agentic-devtools 0.2.148__tar.gz → 0.2.149__tar.gz

{agentic_devtools-0.2.148 → agentic_devtools-0.2.149}/.github/workflows/README.md

@@ -113,30 +113,27 @@ Reviews with this marker from trusted users (`acmarsnik`) are recognized by
 
 ### speckit-issue-trigger.yml
 
-**SpecKit Issue to Specification Automation (Phase 1 — Specify)**
+**SpecKit Issue Trigger — Thin Dispatcher (Phase 1)**
 
 - Runs on:
   - Issues labeled event (when `speckit` or configured label is added)
   - Manual workflow dispatch
-- Purpose: Generates the initial feature specification (`spec.md`) from a GitHub issue — Phase 1 of the SpecKit per-phase pipeline
-- Outputs: Creates Phase 1 branch (`speckit/<issue>/phase-1-specify`), spec file, and pull request labeled `speckit:phase-1`
-- Scripts: Uses helper scripts in `.github/scripts/speckit-trigger/`
-- **Sequence Diagram**: See
-  [Workflow Sequence Diagram](../../specs/002-github-action-speckit-trigger/workflow-sequence-diagram.md)
-  for the original workflow design
-  (note: the diagram predates the per-phase PR progression and may not reflect the current split pipeline)
+- Purpose: Dispatches Phase 1 (Specify) to the unified `speckit-phase-progression.yml` workflow via `workflow_dispatch` with `phase=1`
+- Does NOT perform generation, commit, or PR creation directly — delegates all logic to the progression workflow
+- Retains per-issue concurrency group, processing label management, and failure handling
 
 ### speckit-phase-progression.yml
 
-**SpecKit Phase Progression (Phases 2–5)**
+**SpecKit Phase Progression (Phases 1–5)**
 
 - Runs on:
   - Pull request closed (merged) events with `speckit:phase-N` labels
   - Manual `workflow_dispatch` with inputs:
     - `issue_number` (required): The GitHub issue number to progress
-    - `phase` (required): The phase to generate (2–5)
-- Purpose: Automatically progresses the SpecKit pipeline when a phase PR is merged.
-  Generates the next phase's artifacts and creates a new PR.
+    - `phase` (required): The phase to generate (1–5)
+- Purpose: Unified workflow that handles all SpecKit pipeline phases.
+  Generates phase artifacts and creates PRs using human-identity tokens
+  (`SPECKIT_PR_TOKEN` or `COPILOT_GITHUB_TOKEN`).
   The `workflow_dispatch` trigger allows operators to recover or retry phases
   when the merge trigger fails or a PR is missing the `speckit:phase-N` label.
 - Phase flow: specify → clarify → plan → tasks → analyze

{agentic_devtools-0.2.148 → agentic_devtools-0.2.149}/.github/workflows/speckit-issue-trigger.yml

@@ -5,26 +5,21 @@ on:
     types: [labeled]
   workflow_dispatch: { inputs: { issue_number: { description: 'Issue number to process (for manual testing)', required: true, type: number } } }
 
-permissions: { contents: write, issues: write, pull-requests: write }
-
-env:
-  AGDT_USE_PYTHON_ORCHESTRATOR: "1"
+permissions: { actions: write, issues: write }
 
 concurrency:
   group: speckit-trigger-${{ github.event.issue.number || inputs.issue_number }}
   cancel-in-progress: false
 
 jobs:
-  speckit-trigger:
+  dispatch-phase-1:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 5
     if: >-
       github.event_name == 'workflow_dispatch' ||
       github.event.label.name == vars.SPECKIT_TRIGGER_LABEL ||
       github.event.label.name == 'speckit'
     steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
       - name: Add Processing Label
         uses: actions/github-script@v7
         with:
@@ -36,86 +31,25 @@ jobs:
             }
             try { await github.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: issueNumber, labels: ['speckit:processing'] }); }
             catch (error) { core.warning(`Failed to add speckit:processing label to issue #${issueNumber}: ${error.message}`); }
-      - uses: actions/setup-python@v5
-        with: { python-version: '3.12' }
-      - run: |
-          python -m pip install --upgrade pip
-          python -m pip install github-copilot-sdk
-          python -m pip install . --no-deps
-      - id: generate
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
-          SPECKIT_TRIGGER_LABEL: ${{ vars.SPECKIT_TRIGGER_LABEL || 'speckit' }}
-        run: agdt-speckit-trigger
-      - name: Add ai-auto-merge-allowed label to Phase 1 PR
-        if: success() && vars.SPECKIT_AUTO_MERGE_ALLOWED_LABEL == 'true'
-        env:
-          ISSUE_NUMBER: ${{ github.event.issue.number || inputs.issue_number }}
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const issueNumber = Number(process.env.ISSUE_NUMBER);
-            if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
-              core.warning('Could not determine issue number for speckit phase-1 PR lookup');
-              return;
-            }
 
-            try {
-              const query = `repo:${context.repo.owner}/${context.repo.repo} is:pr is:open head:speckit/${issueNumber}/phase-1-specify`;
-              const search = await github.rest.search.issuesAndPullRequests({
-                q: query,
-                per_page: 1,
-              });
-              const speckit1Pr = search.data.items?.[0];
-              if (!speckit1Pr) {
-                core.warning(`Could not find speckit phase-1 PR for issue #${issueNumber} to label`);
-                return;
-              }
-              await github.rest.issues.addLabels({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: speckit1Pr.number,
-                labels: ['ai-auto-merge-allowed'],
-              });
-              core.info(`Added ai-auto-merge-allowed to PR #${speckit1Pr.number}`);
-            } catch (e) {
-              core.warning(`Could not add ai-auto-merge-allowed label: ${e.message}`);
-            }
-
-      - name: Agent Fallback on Structural Failure
-        id: agent-fallback
-        if: failure()
-        uses: actions/github-script@v7
+      - name: Dispatch Phase Progression
         env:
-          WORKSPACE_FILE: ${{ github.workspace }}/validation-errors.json
-          ISSUE_NUMBER_ENV: ${{ github.event.issue.number || inputs.issue_number || '0' }}
-          ISSUE_TITLE_ENV: ${{ github.event.issue.title || '' }}
-          ISSUE_BODY_ENV: ${{ github.event.issue.body || '' }}
-          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
-          SPECKIT_AGENT_FALLBACK: ${{ vars.SPECKIT_AGENT_FALLBACK || '' }}
-          SPECKIT_REFERENCE_SPEC_PATH: ${{ vars.SPECKIT_REFERENCE_SPEC_PATH || '' }}
-          SPECKIT_COMMENT_ON_ISSUE: ${{ vars.SPECKIT_COMMENT_ON_ISSUE || '' }}
-        with:
-          script: |
-            const fallback = require('./.github/scripts/speckit-trigger/agent-fallback.js');
-            await fallback.run({
-              github,
-              context,
-              core,
-              phase: 1,
-              validationErrors: '',
-              workspaceFile: process.env.WORKSPACE_FILE,
-              issueNumber: Number(process.env.ISSUE_NUMBER_ENV) || 0,
-              issueTitle: process.env.ISSUE_TITLE_ENV,
-              issueBody: process.env.ISSUE_BODY_ENV,
-              token: process.env.COPILOT_GITHUB_TOKEN,
-              killSwitch: process.env.SPECKIT_AGENT_FALLBACK,
-              referenceSpecPath: process.env.SPECKIT_REFERENCE_SPEC_PATH,
-            });
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          ISSUE_NUMBER="${{ github.event.issue.number || inputs.issue_number }}"
+          if [[ -z "$ISSUE_NUMBER" || "$ISSUE_NUMBER" == "0" ]]; then
+            echo "::error::Could not determine issue number"
+            exit 1
+          fi
+          gh api \
+            --method POST \
+            "/repos/${{ github.repository }}/actions/workflows/speckit-phase-progression.yml/dispatches" \
+            -f ref=main \
+            -f "inputs[issue_number]=$ISSUE_NUMBER" \
+            -f "inputs[phase]=1"
 
       - name: Handle Failure (Comment + Label)
-        if: failure() && steps['agent-fallback'].outputs.handled != 'true'
+        if: failure()
         uses: actions/github-script@v7
         env:
           ISSUE_NUMBER_INPUT: ${{ inputs.issue_number || '' }}
@@ -127,20 +61,20 @@ jobs:
             if (!issueNumber) return;
             const triggerLabel = process.env.TRIGGER_LABEL || 'speckit';
             const retriggerLabelInstructions = triggerLabel === 'speckit'
-              ? `3. You can re-trigger by removing the \`speckit:failed\` label and re-adding the \`speckit\` label, or use the **workflow_dispatch** trigger on the [SpecKit Issue Trigger workflow](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/workflows/speckit-issue-trigger.yml)`
-              : `3. You can re-trigger by removing the \`speckit:failed\` label and re-adding the \`${triggerLabel}\` label (legacy: \`speckit\`), or use the **workflow_dispatch** trigger on the [SpecKit Issue Trigger workflow](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/workflows/speckit-issue-trigger.yml)`;
+              ? `3. You can re-trigger by removing the \`speckit:failed\` label and re-adding the \`speckit\` label, or use the **workflow_dispatch** trigger on the [SpecKit Phase Progression workflow](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/workflows/speckit-phase-progression.yml)`
+              : `3. You can re-trigger by removing the \`speckit:failed\` label and re-adding the \`${triggerLabel}\` label (legacy: \`speckit\`), or use the **workflow_dispatch** trigger on the [SpecKit Phase Progression workflow](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/workflows/speckit-phase-progression.yml)`;
 
             const body = [
               '## ❌ SpecKit: Trigger Failed',
               '',
-              'An error occurred while running the SpecKit trigger workflow.',
+              'An error occurred while dispatching the SpecKit Phase 1 workflow.',
               '',
               `**Workflow Run**: [View logs](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId})`,
               '',
               '### Troubleshooting',
               '',
               '1. Check the workflow logs for detailed error messages',
-              '2. Verify that the COPILOT_GITHUB_TOKEN secret is configured with repo permissions',
+              '2. Verify that the workflow has `permissions: actions: write`, that Actions are enabled in repository settings, and that the target workflow file name/path is correct',
               retriggerLabelInstructions,
               '',
               '---',

{agentic_devtools-0.2.148 → agentic_devtools-0.2.149}/.github/workflows/speckit-phase-progression.yml

@@ -10,10 +10,11 @@ on:
         required: true
         type: number
       phase:
-        description: 'The phase to generate (2-5)'
+        description: 'The phase to generate (1-5)'
         required: true
         type: choice
         options:
+          - '1'
           - '2'
           - '3'
           - '4'
@@ -264,7 +265,7 @@ jobs:
               }
             }
 
-      # For phases 2-5, proceed with generating next phase artifacts
+      # For phases 1-5, proceed with generating phase artifacts
       - name: Checkout Repository (Post-Merge Main)
         if: steps.extract.outcome == 'success' && steps.extract.outputs.next_phase != '6' && steps.extract.outputs.next_phase != '0'
         uses: actions/checkout@v4
@@ -455,13 +456,20 @@ jobs:
         if: steps.extract.outcome == 'success' && steps.extract.outputs.next_phase != '6' && steps.extract.outputs.next_phase != '0' && steps.idempotency.outputs.skipped != 'true'
         env:
           COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+          SPECKIT_PR_TOKEN: ${{ secrets.SPECKIT_PR_TOKEN }}
         run: |
           if [[ -z "$COPILOT_GITHUB_TOKEN" ]]; then
-            echo "::error::COPILOT_GITHUB_TOKEN secret is not set. This PAT is required for Copilot SDK authentication and PR creation. Configure the COPILOT_GITHUB_TOKEN secret with a PAT that has Copilot API access and repo permissions."
+            echo "::error::COPILOT_GITHUB_TOKEN secret is not set. This PAT is required for Copilot SDK authentication. For PR creation, SPECKIT_PR_TOKEN is preferred and COPILOT_GITHUB_TOKEN is the fallback. Configure COPILOT_GITHUB_TOKEN with a PAT that has Copilot API access and repo permissions."
             exit 1
           fi
           echo "✓ COPILOT_GITHUB_TOKEN is set"
 
+          if [[ -n "$SPECKIT_PR_TOKEN" ]]; then
+            echo "✓ SPECKIT_PR_TOKEN is set (will be used for PR creation)"
+          else
+            echo "✓ SPECKIT_PR_TOKEN is not set; COPILOT_GITHUB_TOKEN will be used for PR creation"
+          fi
+
       - name: Set up Python
         if: steps.extract.outcome == 'success' && steps.extract.outputs.next_phase != '6' && steps.extract.outputs.next_phase != '0' && steps.idempotency.outputs.skipped != 'true'
         uses: actions/setup-python@v5

{agentic_devtools-0.2.148 → agentic_devtools-0.2.149}/PKG-INFO

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

{agentic_devtools-0.2.148 → agentic_devtools-0.2.149}/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.148'
-__version_tuple__ = version_tuple = (0, 2, 148)
+__version__ = version = '0.2.149'
+__version_tuple__ = version_tuple = (0, 2, 149)
 
 __commit_id__ = commit_id = None

agentic_devtools-0.2.149/agentic_devtools/cli/ci/commands.py

@@ -0,0 +1,127 @@
+"""CLI entry points for CI orchestration commands.
+
+Provides ``agdt-ai-pr-loop`` and ``agdt-speckit-trigger`` commands
+that read event data from environment variables and invoke the
+appropriate orchestrator functions.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import sys
+
+from agentic_devtools.cli.ci.exceptions import MalformedEventError
+from agentic_devtools.cli.ci.github_provider import GitHubActionsProvider
+from agentic_devtools.cli.ci.guards import check_edit_relevance
+from agentic_devtools.cli.ci.logging_config import setup_logging
+from agentic_devtools.cli.ci.orchestrator import run_ai_pr_loop
+from agentic_devtools.cli.ci.pipeline.command import run_ai_pr_loop_v2
+from agentic_devtools.cli.ci.speckit_trigger import DEPRECATION_MESSAGE
+
+
+def _python_orchestrator_enabled() -> bool:
+    """Return True when the Python CI orchestrator path is enabled."""
+    return os.environ.get("AGDT_USE_PYTHON_ORCHESTRATOR", "").lower() in ("1", "true")
+
+
+def _pipeline_v2_enabled() -> bool:
+    """Return True when the idempotent pipeline v2 is enabled."""
+    return os.environ.get("AGDT_USE_PIPELINE_V2", "").lower() in ("1", "true")
+
+
+def ai_pr_loop_command() -> None:
+    """CLI entry point for the AI PR loop orchestrator.
+
+    Reads event data from ``GITHUB_EVENT_PATH`` and ``GITHUB_EVENT_NAME``
+    environment variables, constructs a GitHub Actions provider, and
+    invokes the appropriate orchestrator or pipeline.
+
+    Routing is controlled by two feature flags, evaluated in order:
+
+    1. ``AGDT_USE_PYTHON_ORCHESTRATOR`` must be ``"1"`` or ``"true"`` to
+       activate any Python-side processing.  When absent/false the function
+       exits with code 0 so the legacy YAML path handles the run.
+
+    2. ``AGDT_USE_PIPELINE_V2`` (requires flag 1 to be set): when ``"1"``
+       or ``"true"``, routes to the idempotent action-evaluator pipeline
+       (``run_ai_pr_loop_v2``).  Otherwise routes to the event-branching
+       orchestrator (``run_ai_pr_loop``).
+
+    Exit codes:
+        0: Success or deferred to legacy path
+        1: Guard blocked
+        2: Malformed event
+        3: Merge blocked
+        4: Metadata resolution failed
+        5: Repair dispatched
+        10: Missing dependency or configuration
+    """
+    # Feature flag check
+    if not _python_orchestrator_enabled():
+        # Legacy path — let the YAML handle it
+        sys.exit(0)
+
+    setup_logging()
+
+    # Check gh CLI dependency
+    if shutil.which("gh") is None:
+        print("Error: 'gh' CLI not found on PATH. Install GitHub CLI to use agdt-ai-pr-loop.", file=sys.stderr)
+        sys.exit(10)
+
+    # Read event data
+    event_path = os.environ.get("GITHUB_EVENT_PATH", "")
+    event_name = os.environ.get("GITHUB_EVENT_NAME", "")
+
+    if not event_path or not event_name:
+        print("Error: GITHUB_EVENT_PATH and GITHUB_EVENT_NAME must be set.", file=sys.stderr)
+        sys.exit(10)
+
+    try:
+        with open(event_path, encoding="utf-8") as f:
+            raw_payload = json.load(f)
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"Error: Failed to read event payload: {exc}", file=sys.stderr)
+        sys.exit(10)
+
+    # Determine repository
+    repo = os.environ.get("GITHUB_REPOSITORY", "")
+
+    # Create provider and run orchestrator
+    provider = GitHubActionsProvider(repo=repo)
+
+    try:
+        event_payload = provider.parse_event(raw_payload, event_name)
+    except MalformedEventError as exc:
+        json.dump({"error": "malformed_event", "event_name": exc.event_name, "reason": exc.reason}, sys.stderr)
+        sys.stderr.write("\n")
+        sys.exit(2)
+
+    # Edit-relevance preflight — skip body-only edits before orchestrator calls
+    should_skip, skip_reason = check_edit_relevance(event_payload)
+    if should_skip:
+        logger = logging.getLogger(__name__)
+        logger.info("PR #%d: %s", event_payload.pr_number, skip_reason)
+        sys.exit(0)
+
+    if _pipeline_v2_enabled():
+        exit_code = run_ai_pr_loop_v2(provider, event_payload)
+    else:
+        exit_code = run_ai_pr_loop(provider, event_payload)
+    sys.exit(exit_code)
+
+
+def speckit_trigger_command() -> None:
+    """CLI entry point for the SpecKit trigger handler — DEPRECATED.
+
+    This command is deprecated. Phase 1 is now handled by the unified
+    ``speckit-phase-progression.yml`` workflow. The ``speckit-issue-trigger.yml``
+    workflow dispatches to it directly via ``workflow_dispatch``.
+
+    Exit codes:
+        1: Always exits with 1 to indicate deprecation
+    """
+    print(f"Error: {DEPRECATION_MESSAGE}", file=sys.stderr)
+    sys.exit(1)

agentic_devtools-0.2.149/agentic_devtools/cli/ci/speckit_trigger.py

@@ -0,0 +1,30 @@
+"""SpecKit trigger orchestration — DEPRECATED.
+
+This module previously handled Phase 1 (Specify) orchestration for issues
+label events. The logic has been consolidated into the unified
+``speckit-phase-progression.yml`` workflow which handles all phases 1–5.
+
+The ``speckit-issue-trigger.yml`` workflow is now a thin dispatcher that
+triggers ``speckit-phase-progression.yml`` via ``workflow_dispatch``.
+
+See: https://github.com/ayaiayorg/agentic-devtools/issues/1527
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+EXIT_SUCCESS = 0
+EXIT_FAILED = 1
+EXIT_MALFORMED_EVENT = 2
+EXIT_MISSING_CONFIG = 10
+
+DEPRECATION_MESSAGE = (
+    "agdt-speckit-trigger is deprecated. "
+    "Phase 1 is now handled by speckit-phase-progression.yml. "
+    "Use workflow_dispatch with phase=1 on speckit-phase-progression.yml instead."
+)
+
+_DEPRECATION_MESSAGE = DEPRECATION_MESSAGE

{agentic_devtools-0.2.148 → agentic_devtools-0.2.149}/specs/1527-consolidate-speckit-issue-trigger/tasks.md

@@ -16,24 +16,24 @@
 
 ## Phase 1: Setup & Analysis
 
-- [ ] T001 Verify existing `speckit-phase-progression.yml` extract step handles `phase=1` correctly (outputs `completed_phase=0`, `next_phase=1`, `next_phase_name=specify`) (FR-001) —
+- [x] T001 Verify existing `speckit-phase-progression.yml` extract step handles `phase=1` correctly (outputs `completed_phase=0`, `next_phase=1`, `next_phase_name=specify`) (FR-001) —
   `.github/workflows/speckit-phase-progression.yml`
-- [ ] T002 Verify existing "Create Pull Request" step already uses `SPECKIT_PR_TOKEN || COPILOT_GITHUB_TOKEN` via `GH_TOKEN` env for all phases (FR-002, FR-014) — `.github/workflows/speckit-phase-progression.yml`
-- [ ] T003 Verify feature flags (`SPECKIT_CREATE_BRANCH`, `SPECKIT_CREATE_PR`, `SPECKIT_CRITICAL_GATE_MODE`) already apply universally (no phase-gating) (FR-015) —
+- [x] T002 Verify existing "Create Pull Request" step already uses `SPECKIT_PR_TOKEN || COPILOT_GITHUB_TOKEN` via `GH_TOKEN` env for all phases (FR-002, FR-014) — `.github/workflows/speckit-phase-progression.yml`
+- [x] T003 Verify feature flags (`SPECKIT_CREATE_BRANCH`, `SPECKIT_CREATE_PR`, `SPECKIT_CRITICAL_GATE_MODE`) already apply universally (no phase-gating) (FR-015) —
   `.github/workflows/speckit-phase-progression.yml`
-- [ ] T004 Verify existing `speckit:phase-1` label in PR merge trigger condition for Phase 2 progression (FR-012) — `.github/workflows/speckit-phase-progression.yml` line 45
+- [x] T004 Verify existing `speckit:phase-1` label in PR merge trigger condition for Phase 2 progression (FR-012) — `.github/workflows/speckit-phase-progression.yml` line 45
 
 ## Phase 2: Foundational — Extend Progression Workflow for Phase 1
 
-- [ ] T005 Add `'1'` to `workflow_dispatch.inputs.phase.options` list (FR-001) — `.github/workflows/speckit-phase-progression.yml` line 16–20
-- [ ] T006 Update "Validate Tokens" step to check `SPECKIT_PR_TOKEN || COPILOT_GITHUB_TOKEN` with explicit failure if both missing;
-  MUST NOT fall back to `GITHUB_TOKEN` (FR-002, FR-014) — `.github/workflows/speckit-phase-progression.yml` lines 454–463
-- [ ] T007 Verify that the "Add Processing Label" step already fires for phase 1 (condition: `next_phase != '0' && next_phase != '6'`) — confirms FR-013 coverage —
+- [x] T005 Add `'1'` to `workflow_dispatch.inputs.phase.options` list (FR-001) — `.github/workflows/speckit-phase-progression.yml` line 16–20
+- [x] T006 Update "Validate Tokens" step to require `COPILOT_GITHUB_TOKEN` for Copilot SDK auth and to report whether `SPECKIT_PR_TOKEN` is set (preferred for PR creation);
+  MUST NOT fall back to `GITHUB_TOKEN` (FR-002, FR-014) — `.github/workflows/speckit-phase-progression.yml` lines 455–472
+- [x] T007 Verify that the "Add Processing Label" step already fires for phase 1 (condition: `next_phase != '0' && next_phase != '6'`) — confirms FR-013 coverage —
   `.github/workflows/speckit-phase-progression.yml` line 172–188
-- [ ] T008 Verify the "Push Branch" step condition includes phase 1 (not gated on phase number) and respects `SPECKIT_CREATE_BRANCH` (FR-003, FR-015) —
+- [x] T008 Verify the "Push Branch" step condition includes phase 1 (not gated on phase number) and respects `SPECKIT_CREATE_BRANCH` (FR-003, FR-015) —
   `.github/workflows/speckit-phase-progression.yml` line 532–536
-- [ ] T009 Verify the "Check Phase Idempotency" step works for phase 1 (passes `--phase 1` from `next_phase` output) (FR-007) — `.github/workflows/speckit-phase-progression.yml` line 303–310
-- [ ] T010 Verify the "Add ai-auto-merge-allowed label" step fires for phase 1 (condition: `next_phase != '0' && next_phase != '6'` and `next_phase_name != 'clarify'`) (FR-008) —
+- [x] T009 Verify the "Check Phase Idempotency" step works for phase 1 (passes `--phase 1` from `next_phase` output) (FR-007) — `.github/workflows/speckit-phase-progression.yml` line 303–310
+- [x] T010 Verify the "Add ai-auto-merge-allowed label" step fires for phase 1 (condition: `next_phase != '0' && next_phase != '6'` and `next_phase_name != 'clarify'`) (FR-008) —
   `.github/workflows/speckit-phase-progression.yml` line 602–629
 
 ## Phase 3: User Story 1 — Phase 1 PRs Created with Human Identity Token (P1)
@@ -41,74 +41,74 @@
 - [ ] T011 [US1] Write integration test verifying `SPECKIT_PR_TOKEN || COPILOT_GITHUB_TOKEN` is used for PR creation step when `phase=1` (not `GITHUB_TOKEN`) — `tests/unit/cli/ci/` (new test)
 - [ ] T012 [US1] Write test: when both `SPECKIT_PR_TOKEN` and `COPILOT_GITHUB_TOKEN` are unset, token validation fails before PR creation (FR-014) — `tests/unit/cli/ci/` (new test)
 - [ ] T013 [US1] Write happy-path test: when `SPECKIT_PR_TOKEN` is unset but `COPILOT_GITHUB_TOKEN` is set, fallback works gracefully (FR-002) — `tests/unit/cli/ci/` (new test)
-- [ ] T014 [US1] Update the "Validate Tokens" step to add `SPECKIT_PR_TOKEN` to environment and check
+- [x] T014 [US1] Update the "Validate Tokens" step to add `SPECKIT_PR_TOKEN` to environment and check
   `SPECKIT_PR_TOKEN || COPILOT_GITHUB_TOKEN` resolution with clear error message (FR-002, FR-014) — `.github/workflows/speckit-phase-progression.yml`
 
 ## Phase 4: User Story 2 — Single Workflow Handles All Phases 1–5 (P1)
 
-- [ ] T015 [US2] Confirm extract step produces correct outputs for `phase=1` dispatch: `completed_phase=0`, `next_phase=1`, `next_phase_name=specify` (FR-011) —
+- [x] T015 [US2] Confirm extract step produces correct outputs for `phase=1` dispatch: `completed_phase=0`, `next_phase=1`, `next_phase_name=specify` (FR-011) —
   `.github/workflows/speckit-phase-progression.yml`
 - [ ] T016 [US2] Verify `generate-spec-from-issue.sh` supports `--phase 1` and generates `spec.md` + empty `checklists/` + empty `contracts/` — happy-path success scenario (FR-003) —
   `.github/scripts/speckit-trigger/generate-spec-from-issue.sh`
-- [ ] T017 [US2] Verify the commit step message format works for phase 1: `spec(specify): Phase 1 artifacts for issue #N` (FR-003) — `.github/workflows/speckit-phase-progression.yml` lines 500–530
-- [ ] T018 [US2] Verify PR creation step invokes `create-spec-pr.sh` with `--phase-number 1 --phase-name specify` (FR-003) — `.github/workflows/speckit-phase-progression.yml` lines 538–600
-- [ ] T019 [US2] Verify PR merge of `speckit:phase-1` labeled PR triggers Phase 2 dispatch (FR-012 non-regression) — `.github/workflows/speckit-phase-progression.yml` lines 39–50
-- [ ] T020 [US2] Confirm `SPECKIT_CREATE_BRANCH`, `SPECKIT_CREATE_PR`, `SPECKIT_CRITICAL_GATE_MODE` apply to phase 1 (FR-015) — `.github/workflows/speckit-phase-progression.yml`
+- [x] T017 [US2] Verify the commit step message format works for phase 1: `spec(specify): Phase 1 artifacts for issue #N` (FR-003) — `.github/workflows/speckit-phase-progression.yml` lines 500–530
+- [x] T018 [US2] Verify PR creation step invokes `create-spec-pr.sh` with `--phase-number 1 --phase-name specify` (FR-003) — `.github/workflows/speckit-phase-progression.yml` lines 538–600
+- [x] T019 [US2] Verify PR merge of `speckit:phase-1` labeled PR triggers Phase 2 dispatch (FR-012 non-regression) — `.github/workflows/speckit-phase-progression.yml` lines 39–50
+- [x] T020 [US2] Confirm `SPECKIT_CREATE_BRANCH`, `SPECKIT_CREATE_PR`, `SPECKIT_CRITICAL_GATE_MODE` apply to phase 1 (FR-015) — `.github/workflows/speckit-phase-progression.yml`
 
 ## Phase 5: User Story 3 — Thin Dispatcher for Label-Based Triggering (P2)
 
-- [ ] T021 [US3] Replace `speckit-issue-trigger.yml` job body with thin dispatcher: remove Python setup, pip install, `agdt-speckit-trigger` call, and "Add ai-auto-merge-allowed" step (FR-004) —
+- [x] T021 [US3] Replace `speckit-issue-trigger.yml` job body with thin dispatcher: remove Python setup, pip install, `agdt-speckit-trigger` call, and "Add ai-auto-merge-allowed" step (FR-004) —
   `.github/workflows/speckit-issue-trigger.yml`
-- [ ] T022 [US3] Remove `AGDT_USE_PYTHON_ORCHESTRATOR` env var from dispatcher workflow (FR-004) — `.github/workflows/speckit-issue-trigger.yml` line 11
-- [ ] T023 [US3] Change permissions to `actions: write, issues: write` (drop `contents: write`, `pull-requests: write`) (FR-004) — `.github/workflows/speckit-issue-trigger.yml` line 8
-- [ ] T024 [US3] Add dispatch step using `gh api` or `actions/github-script` to POST `workflow_dispatch` to `speckit-phase-progression.yml` with
+- [x] T022 [US3] Remove `AGDT_USE_PYTHON_ORCHESTRATOR` env var from dispatcher workflow (FR-004) — `.github/workflows/speckit-issue-trigger.yml` line 11
+- [x] T023 [US3] Change permissions to `actions: write, issues: write` (drop `contents: write`, `pull-requests: write`) (FR-004) — `.github/workflows/speckit-issue-trigger.yml` line 8
+- [x] T024 [US3] Add dispatch step using `gh api` or `actions/github-script` to POST `workflow_dispatch` to `speckit-phase-progression.yml` with
   `{"ref":"main","inputs":{"issue_number":"N","phase":"1"}}` using `GITHUB_TOKEN` (FR-004) — `.github/workflows/speckit-issue-trigger.yml`
-- [ ] T025 [US3] Retain per-issue concurrency group `speckit-trigger-${{ github.event.issue.number || inputs.issue_number }}`
+- [x] T025 [US3] Retain per-issue concurrency group `speckit-trigger-${{ github.event.issue.number || inputs.issue_number }}`
   with `cancel-in-progress: false` (FR-005) — `.github/workflows/speckit-issue-trigger.yml` lines 13–15
-- [ ] T026 [US3] Retain the `speckit` / `SPECKIT_TRIGGER_LABEL` label filter condition (FR-005) — `.github/workflows/speckit-issue-trigger.yml` lines 21–24
-- [ ] T027 [US3] Keep "Add Processing Label" step in dispatcher (or verify progression handles it) — `.github/workflows/speckit-issue-trigger.yml`
-- [ ] T028 [US3] Retain failure handling steps (comment + `speckit:failed` label) for dispatch errors (FR-005) — `.github/workflows/speckit-issue-trigger.yml`
-- [ ] T029 [US3] Verify dispatcher is < 30 lines of workflow logic (excluding failure handling) — `.github/workflows/speckit-issue-trigger.yml`
+- [x] T026 [US3] Retain the `speckit` / `SPECKIT_TRIGGER_LABEL` label filter condition (FR-005) — `.github/workflows/speckit-issue-trigger.yml` lines 21–24
+- [x] T027 [US3] Keep "Add Processing Label" step in dispatcher (or verify progression handles it) — `.github/workflows/speckit-issue-trigger.yml`
+- [x] T028 [US3] Retain failure handling steps (comment + `speckit:failed` label) for dispatch errors (FR-005) — `.github/workflows/speckit-issue-trigger.yml`
+- [x] T029 [US3] Verify dispatcher is < 30 lines of workflow logic (excluding failure handling) — `.github/workflows/speckit-issue-trigger.yml`
 
 ## Phase 6: User Story 4 — Remove Python Orchestrator Commit/Push/PR Logic (P2)
 
-- [ ] T030 [US4] Write test: `speckit_trigger_command()` stub prints migration message and exits with code 1 (FR-006) — `tests/unit/cli/ci/commands/test_speckit_trigger_command.py`
-- [ ] T031 [US4] Delete `_commit_and_push_phase_branch()` from `speckit_trigger.py` (FR-006) — `agentic_devtools/cli/ci/speckit_trigger.py` lines 238–267
-- [ ] T032 [US4] Delete `_create_phase_pull_request()` from `speckit_trigger.py` (FR-006) — `agentic_devtools/cli/ci/speckit_trigger.py` lines 270–285
-- [ ] T033 [US4] Delete `process_speckit_label_event()` and supporting private functions (`_load_issue_context_from_event`, `_set_issue_labels`, `_run_script_with_outputs`, `_parse_key_value_file`,
+- [x] T030 [US4] Write test: `speckit_trigger_command()` stub prints migration message and exits with code 1 (FR-006) — `tests/unit/cli/ci/commands/test_speckit_trigger_command.py`
+- [x] T031 [US4] Delete `_commit_and_push_phase_branch()` from `speckit_trigger.py` (FR-006) — `agentic_devtools/cli/ci/speckit_trigger.py` lines 238–267
+- [x] T032 [US4] Delete `_create_phase_pull_request()` from `speckit_trigger.py` (FR-006) — `agentic_devtools/cli/ci/speckit_trigger.py` lines 270–285
+- [x] T033 [US4] Delete `process_speckit_label_event()` and supporting private functions (`_load_issue_context_from_event`, `_set_issue_labels`, `_run_script_with_outputs`, `_parse_key_value_file`,
   `_run_checked`, `_require_repository`, `_IssueContext`) (FR-006) — `agentic_devtools/cli/ci/speckit_trigger.py`
-- [ ] T034 [US4] Replace `speckit_trigger_command()` in `commands.py` with a stub that prints migration message and exits with code 1 (FR-006) — `agentic_devtools/cli/ci/commands.py` lines 119–180
-- [ ] T035 [US4] Remove `from agentic_devtools.cli.ci.speckit_trigger import process_speckit_label_event` import from `commands.py` (FR-006) — `agentic_devtools/cli/ci/commands.py` line 24
-- [ ] T036 [US4] Remove `_python_orchestrator_enabled()` helper or its usage in `speckit_trigger_command()` (FR-006) — `agentic_devtools/cli/ci/commands.py`
-- [ ] T037 [US4] Update/remove tests for `process_speckit_label_event` (FR-006) — `tests/unit/cli/ci/speckit_trigger/test_process_speckit_label_event.py`
-- [ ] T038 [US4] Retain `agdt-speckit-trigger` entry point in `pyproject.toml` pointing to stub (FR-006) — `pyproject.toml`
+- [x] T034 [US4] Replace `speckit_trigger_command()` in `commands.py` with a stub that prints migration message and exits with code 1 (FR-006) — `agentic_devtools/cli/ci/commands.py` lines 119–180
+- [x] T035 [US4] Remove `from agentic_devtools.cli.ci.speckit_trigger import process_speckit_label_event` import from `commands.py` (FR-006) — `agentic_devtools/cli/ci/commands.py` line 24
+- [x] T036 [US4] Remove `_python_orchestrator_enabled()` helper or its usage in `speckit_trigger_command()` (FR-006) — `agentic_devtools/cli/ci/commands.py`
+- [x] T037 [US4] Update/remove tests for `process_speckit_label_event` (FR-006) — `tests/unit/cli/ci/speckit_trigger/test_process_speckit_label_event.py`
+- [x] T038 [US4] Retain `agdt-speckit-trigger` entry point in `pyproject.toml` pointing to stub (FR-006) — `pyproject.toml`
 - [ ] T039 [US4] Run full test suite to confirm no regressions — `agdt-test`
 
 ## Phase 7: User Story 5 — Feature Parity for Phase 1 (P1)
 
-- [ ] T040 [US5] Verify idempotency step skips PR creation when Phase 1 branch already exists (FR-007) — `.github/workflows/speckit-phase-progression.yml` lines 303–362
-- [ ] T041 [US5] Verify `ai-auto-merge-allowed` label is added for phase 1 (FR-008) — happy-path success when
+- [x] T040 [US5] Verify idempotency step skips PR creation when Phase 1 branch already exists (FR-007) — `.github/workflows/speckit-phase-progression.yml` lines 303–362
+- [x] T041 [US5] Verify `ai-auto-merge-allowed` label is added for phase 1 (FR-008) — happy-path success when
   `SPECKIT_AUTO_MERGE_ALLOWED_LABEL == 'true'` in `.github/workflows/speckit-phase-progression.yml` lines
   602–629
-- [ ] T042 [US5] Add failure handling step to progression workflow for phase 1: post failure comment + apply `speckit:failed` label on error (FR-009) —
+- [x] T042 [US5] Add failure handling step to progression workflow for phase 1: post failure comment + apply `speckit:failed` label on error (FR-009) —
   `.github/workflows/speckit-phase-progression.yml`
-- [ ] T043 [US5] Verify critical gate draft mode: when `SPECKIT_CRITICAL_GATE_MODE == 'draft'` and gate fails, PR is created as draft with critical findings (FR-010) —
+- [x] T043 [US5] Verify critical gate draft mode: when `SPECKIT_CRITICAL_GATE_MODE == 'draft'` and gate fails, PR is created as draft with critical findings (FR-010) —
   `.github/workflows/speckit-phase-progression.yml` lines 552–558
-- [ ] T044 [US5] Verify `speckit:processing` label is added at start and removed on completion/failure for phase 1 (FR-013) — `.github/workflows/speckit-phase-progression.yml`
+- [x] T044 [US5] Verify `speckit:processing` label is added at start and removed on completion/failure for phase 1 (FR-013) — `.github/workflows/speckit-phase-progression.yml`
 
 ## Phase 8: User Story 6 — Workflow Documentation Updated (P3)
 
-- [ ] T045 [P] [US6] Update `.github/workflows/README.md` to describe consolidated single-workflow architecture (Phases 1–5) and thin dispatcher for label events
-- [ ] T046 [P] [US6] Add instructions for manual Phase 1 trigger via `workflow_dispatch` with `phase=1` on `speckit-phase-progression.yml`
-- [ ] T047 [P] [US6] Remove or update references to `speckit-issue-trigger.yml` as a Phase 1 executor in documentation
+- [x] T045 [P] [US6] Update `.github/workflows/README.md` to describe consolidated single-workflow architecture (Phases 1–5) and thin dispatcher for label events
+- [x] T046 [P] [US6] Add instructions for manual Phase 1 trigger via `workflow_dispatch` with `phase=1` on `speckit-phase-progression.yml`
+- [x] T047 [P] [US6] Remove or update references to `speckit-issue-trigger.yml` as a Phase 1 executor in documentation
 
 ## Phase 9: Polish & Cross-Cutting
 
-- [ ] T048 Verify the progression workflow's existing failure handling step covers phase 1 (comment + `speckit:failed` label + `speckit:processing` removal) (FR-009) —
+- [x] T048 Verify the progression workflow's existing failure handling step covers phase 1 (comment + `speckit:failed` label + `speckit:processing` removal) (FR-009) —
   `.github/workflows/speckit-phase-progression.yml`
 - [ ] T049 [US2] Run `agdt-test` full test suite and verify all tests pass
 - [ ] T050 [US4] Run `bash scripts/targeted-checks.sh` for lint, format, type-check, and coverage validation
-- [ ] T051 Verify `speckit-issue-trigger.yml` final line count is minimal (< 30 lines of dispatch logic) (FR-004)
+- [x] T051 Verify `speckit-issue-trigger.yml` final line count is minimal (< 30 lines of dispatch logic) (FR-004)
 - [ ] T052 End-to-end validation: manually dispatch `speckit-phase-progression.yml` with `phase=1` and `issue_number=N` and verify full artifact generation + PR creation (FR-001, FR-003)
 
 ## Dependencies

{agentic_devtools-0.2.148 → agentic_devtools-0.2.149}/specs/1620-runner-not-detect-human/spec.md

@@ -16,7 +16,8 @@
 - Q: When `invoke()` returns `None` or an unexpected type (per the edge case), what specific exit code should the runner use? → A: The runner should exit with code 1 (generic error), consistent with
   the existing `sys.exit(1)` pattern used for other failure conditions in the runner (e.g., workflow execution failures).
 - Q: Should the state inspection logic be extracted into a separate helper function (e.g., `_is_workflow_paused(result)`) for testability, or should it be inline in the existing flow? → A: Extract
-  into a small helper function `_is_workflow_paused(result: dict) -> bool` that returns `True` when `result.get("status") != "completed"`. This improves testability and keeps the net new line count
+  into a small helper function `_is_workflow_paused(result: dict) -> bool` that returns `True` when `result.get("status") != "completed"` and raises `TypeError` for `None`/non-dict inputs. This
+  improves testability and keeps the net new line count
   within SC-005's 5-line budget for the runner itself while the helper lives alongside `_print_pause_message`.
 - Q: For the resume path, the current code in `runner.py` line 90 uses `compiled.invoke(Command(resume=resume_value), config=config)` — should the state inspection apply to the result of this call
   identically (same helper, same logic) as the fresh path? → A: Yes, both paths must call the same `_is_workflow_paused` helper on the returned `result` dictionary. The spec (FR-004) mandates
@@ -55,6 +56,8 @@ message for true terminal states only.
 An AI agent or developer starts a fresh work-on-jira-issue workflow using the LangGraph engine with a persistent checkpointer. The workflow progresses through initiate, setup, and planning nodes, then
 reaches `planning_gate_node` which calls `interrupt()` to wait for human approval. The user expects to see a clear pause message with resume instructions, not a misleading completion message.
 
+**Associated FRs**: FR-001, FR-002, FR-006, FR-007, FR-008
+
 **Why this priority**: This is the primary failure mode described in the issue. Every user who runs the workflow with a checkpointer encounters this bug on their first run. Without fixing this, the
 entire human-in-the-loop UX is broken — users cannot understand what the system is waiting for.
 
@@ -87,6 +90,8 @@ should apply the same post-`invoke()` state inspection to the resume path, so th
 the resumed invocation returns a non-terminal state (`status != "completed"`), it
 prints the pause message instead of the misleading "Workflow completed" message.
 
+**Associated FRs**: FR-004, FR-006
+
 **Why this priority**: The resume path (`compiled.invoke(Command(resume=...))`)
 currently shares the same completion reporting code as the fresh-run path, so it can
 misreport pauses in the same way (including for any future human-in-the-loop gates
@@ -113,6 +118,8 @@ interrupt after resume) and verifying the pause message appears.
 A user has resumed through all gate nodes and the workflow runs all the way through commit, pull request, and completion nodes. The workflow reaches the terminal `completion_node` and the status is
 set to `"completed"`. The user expects to see the legitimate "Workflow completed" message confirming their work is done.
 
+**Associated FRs**: FR-002, FR-003
+
 **Why this priority**: Without this story, a naive fix might suppress the completion message entirely. This story ensures that the completion message still appears for genuinely finished workflows,
 maintaining the UX contract for the happy path.
 
@@ -133,6 +140,8 @@ maintaining the UX contract for the happy path.
 A developer working on the orchestration module needs confidence that future changes to the runner or graph structure do not reintroduce the misleading completion message. Automated regression tests
 must cover both the fresh-run and resume-run paths for pause detection, as well as the true-completion path.
 
+**Associated FRs**: FR-001, FR-005
+
 **Why this priority**: Tests prevent regression and document the intended behavior. They are essential for long-term maintainability but do not directly fix the user-facing bug — they protect the fix
 once it is in place.
 
@@ -203,7 +212,7 @@ purpose.
 
 - **FR-007**: The runner MUST exit with code 0 when a pause is detected (not an error condition), matching the existing behavior when `GraphInterrupt` is caught.
 
-- **FR-008**: The state inspection logic MUST be encapsulated in a helper function `_is_workflow_paused(result: dict | None) -> bool` that returns `True` when `result` is a dict and
+- **FR-008**: The state inspection logic MUST be encapsulated in a helper function `_is_workflow_paused(result: dict) -> bool` that returns `True` when `result` is a dict and
   `result.get("status") != "completed"`, and raises/handles the `None`/unexpected-type case as an error.
 
 ### Non-Functional Requirements