agentic-devtools 0.2.66__tar.gz → 0.2.67__tar.gz

{agentic_devtools-0.2.66 → agentic_devtools-0.2.67}/.github/workflows/speckit-copilot-review-request.yml

@@ -47,6 +47,16 @@ jobs:
       issues: write
 
     steps:
+      - name: Validate Copilot Token
+        env:
+          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+        run: |
+          if [[ -z "$COPILOT_GITHUB_TOKEN" ]]; then
+            echo "::error::COPILOT_GITHUB_TOKEN secret is not configured. Add a fine-grained PAT with 'Pull requests: Write' permission, or a classic PAT with 'repo' scope. The token owner must be a repository collaborator with Copilot access."
+            exit 1
+          fi
+          echo "✓ COPILOT_GITHUB_TOKEN is configured"
+
       # Idempotency guard: avoid re-requesting the reviewer when Copilot is
       # already a requested reviewer or has already reviewed this PR. This
       # makes repeated `labeled` events safe.
@@ -55,6 +65,7 @@ jobs:
         continue-on-error: true
         uses: actions/github-script@v7
         with:
+          github-token: ${{ secrets.COPILOT_GITHUB_TOKEN }}
           script: |
             const prNumber = context.payload.pull_request.number;
             const copilotLogin = 'copilot-pull-request-reviewer[bot]';
@@ -101,6 +112,7 @@ jobs:
         continue-on-error: true
         uses: actions/github-script@v7
         with:
+          github-token: ${{ secrets.COPILOT_GITHUB_TOKEN }}
           script: |
             const prNumber = context.payload.pull_request.number;
             try {

{agentic_devtools-0.2.66 → agentic_devtools-0.2.67}/.github/workflows/speckit-issue-trigger.yml

@@ -235,7 +235,7 @@ jobs:
           COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
         run: |
           if [[ -z "$COPILOT_GITHUB_TOKEN" ]]; then
-            echo "::error::COPILOT_GITHUB_TOKEN secret is not configured. Add a fine-grained PAT with 'Copilot Requests: Read' permission."
+            echo "::error::COPILOT_GITHUB_TOKEN secret is not configured. Add a fine-grained PAT with 'Pull requests: Write' and 'Copilot Requests: Read' permissions, or a classic PAT with 'repo' scope. The token owner must be a repository collaborator with Copilot access."
             exit 1
           fi
           echo "✓ COPILOT_GITHUB_TOKEN is configured"
@@ -342,6 +342,7 @@ jobs:
         continue-on-error: true
         uses: actions/github-script@v7
         with:
+          github-token: ${{ secrets.COPILOT_GITHUB_TOKEN }}
           script: |
             const prNumber = parseInt('${{ steps.create-pr.outputs.pr_number }}', 10);
             const reviewerLogin = 'copilot-pull-request-reviewer';

{agentic_devtools-0.2.66 → agentic_devtools-0.2.67}/.github/workflows/speckit-phase-progression.yml

@@ -457,7 +457,7 @@ jobs:
           COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
         run: |
           if [[ -z "$COPILOT_GITHUB_TOKEN" ]]; then
-            echo "::error::COPILOT_GITHUB_TOKEN secret is not configured."
+            echo "::error::COPILOT_GITHUB_TOKEN secret is not configured. Add a fine-grained PAT with 'Pull requests: Write' and 'Copilot Requests: Read' permissions, or a classic PAT with 'repo' scope. The token owner must be a repository collaborator with Copilot access."
             exit 1
           fi
           echo "✓ COPILOT_GITHUB_TOKEN is configured"
@@ -593,6 +593,7 @@ jobs:
         continue-on-error: true
         uses: actions/github-script@v7
         with:
+          github-token: ${{ secrets.COPILOT_GITHUB_TOKEN }}
           script: |
             const prNumber = parseInt('${{ steps.create-pr.outputs.pr_number }}', 10);
             const reviewerLogin = 'copilot-pull-request-reviewer';

{agentic_devtools-0.2.66 → agentic_devtools-0.2.67}/.gitignore

@@ -57,7 +57,9 @@ htmlcov/
 *.log
 state-out.txt
 poll-output.txt
+poll-output.json
 poll*.txt
+poll*.json
 _poll_output.txt
 
 # Workflow artifacts (ad-hoc, not source files)

{agentic_devtools-0.2.66 → agentic_devtools-0.2.67}/PKG-INFO

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

{agentic_devtools-0.2.66 → agentic_devtools-0.2.67}/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.66'
-__version_tuple__ = version_tuple = (0, 2, 66)
+__version__ = version = '0.2.67'
+__version_tuple__ = version_tuple = (0, 2, 67)
 
 __commit_id__ = commit_id = None

{agentic_devtools-0.2.66 → agentic_devtools-0.2.67}/specs/1195-speckit-clarification-step-overwrites/checklists/requirements.md

@@ -7,7 +7,8 @@
 
 ## Content Quality
 
-- [ ] CHK001 Each referenced user story (User Story 2 backup-write-failure, User Story 3 atomic-replace) is written in "As a … I want … so that …" format and focuses on user/developer value, not implementation
+- [ ] CHK001 Each referenced user story (User Story 2 backup-write-failure, User Story 3 atomic-replace) is written in "As a … I want … so that …" format and focuses on user/developer value, not
+  implementation
   mechanics
 - [ ] CHK002 All functional requirements (FR-002, FR-006, FR-012) and non-functional requirement NFR-005 include an explicit priority assignment (for example, `Priority: P1/P2/P3` or equivalent
   implementation-criticality wording)

agentic_devtools-0.2.67/specs/1195-speckit-clarification-step-overwrites/plan.md

@@ -0,0 +1,295 @@
+# Implementation Plan: SpecKit Clarification Step — Content-Preserving Augmentation
+
+**Issue**: [#1195](https://github.com/ayaiayorg/agentic-devtools/issues/1195)
+**Branch**: `speckit/1195/phase-3-plan`
+
+## Technical Context
+
+### Technology Stack
+
+- **Shell**: `generate-spec-from-issue.sh` — 2084-line Bash script orchestrating the SpecKit pipeline (phases 1–5 + markdownlint)
+- **Python**: `agentic_devtools` package — CLI commands, speckit agent prompt rendering, context budget enforcement
+- **CI/CD**: GitHub Actions workflows (`speckit-issue-trigger.yml`, `speckit-phase-progression.yml`)
+- **LLM**: Copilot SDK via `copilot_generate.py` (model: `claude-opus-4.6`, timeout: 600s)
+- **Testing**: `agdt-test` / `agdt-task-wait` and related `agdt-test-*` commands (100% coverage required where applicable), shell integration tests, 1:1:1 test structure under `tests/unit/`
+
+### Key Dependencies
+
+- `copilot_generate.py` — LLM invocation wrapper
+- `strip_llm_preamble`, `ensure_heading_start`, `append_model_footer` — existing post-processing helpers
+- `check-idempotency.sh` — phase 2 idempotency checks (already looks for `## Clarifications` section)
+- `speckit.clarify.agent.md` — interactive agent (already implements incremental augmentation correctly)
+
+### Architecture Decisions
+
+The defect is in `run_clarify_phase()` and `run_checklist_phase()` in `generate-spec-from-issue.sh` (lines 1255–1397). Both functions:
+
+1. Read the existing file content
+2. Send it to the LLM with instructions to output the "COMPLETE updated specification"
+3. **Destructively overwrite** the file with the LLM response (`printf '%s\n' "$result" > "$SPEC_DIR/spec.md"`)
+
+There is **no backup**, **no validation**, and **no atomic replace**. The fix must be surgical — adding safeguards around the existing write path without rearchitecting the pipeline.
+
+## Research Summary
+
+Detailed decisions for this fix are:
+
+- **Backup naming convention** — `spec.md.bak` with `.bak.N` collision avoidance
+- **Validation strategy** — section heading + requirement count comparison in Bash
+- **Atomic replacement** — `mv` (POSIX rename) from `.tmp` staging file
+- **Shared validation contract** — shell functions reusable by both CI and future Python validation
+- **Prompt augmentation** — explicit preservation instructions added to LLM prompt
+
+## Design Overview
+
+### Three-Layer Protection Model
+
+```text
+┌─────────────────────────────────────────────┐
+│ Layer 1: PREVENTION — Improved LLM Prompt   │
+│ Explicit instructions to preserve all        │
+│ sections and content, not just summarize     │
+└────────────────────┬────────────────────────┘
+                     │
+┌────────────────────▼────────────────────────┐
+│ Layer 2: DETECTION — Structural Validation  │
+│ Compare staged output against original:      │
+│ • Mandatory section headings present         │
+│ • All original section headings preserved    │
+│ • Requirement entry count ≥95% retained      │
+│ • Checklist item count 100% retained         │
+└────────────────────┬────────────────────────┘
+                     │
+┌────────────────────▼────────────────────────┐
+│ Layer 3: RECOVERY — Backup + Restore        │
+│ Pre-write backup with collision avoidance    │
+│ Atomic rename from .tmp staging file         │
+│ Automatic restore on post-replace failure    │
+└─────────────────────────────────────────────┘
+```
+
+### Modified Clarify Phase Flow
+
+```text
+run_clarify_phase():
+  1. Assert spec.md exists and is non-empty (FR-009)
+  2. Warn if spec.md ≥ 50KB (FR-012)
+  3. Create backup: spec.md.bak[.N] (FR-002)
+  4. Read spec content, count sections + requirements
+  5. Send to LLM with augmented prompt (FR-001, FR-003, FR-004)
+  6. Write LLM output to spec.md.tmp (FR-006)
+  7. Validate staged output against original baseline (FR-006):
+     a. All mandatory sections present
+     b. All original sections present
+     c. Requirement count ≥95% of original
+  8. On validation pass → mv spec.md.tmp spec.md (atomic replace)
+  9. On validation fail → leave spec.md unchanged, report errors (FR-007)
+```
+
+### New Shell Functions
+
+| Function | Purpose | Location |
+|---|---|---|
+| `create_backup` | Create backup with collision-avoidance naming | `generate-spec-from-issue.sh` |
+| `restore_from_backup` | Restore original from backup file | `generate-spec-from-issue.sh` |
+| `count_requirement_entries` | Count `FR-###`/`NFR-###` entries in a file | `generate-spec-from-issue.sh` |
+| `count_checklist_items` | Count `- [ ]`/`- [x]` items in a file | `generate-spec-from-issue.sh` |
+| `extract_section_headings` | Extract all `## ...` headings from a file | `generate-spec-from-issue.sh` |
+| `validate_structural_integrity` | Compare staged output vs original | `generate-spec-from-issue.sh` |
+| `safe_write_with_validation` | Orchestrate backup → stage → validate → replace | `generate-spec-from-issue.sh` |
+
+## Implementation Phases
+
+### Phase 1: Shell Utility Functions (Foundation)
+
+**Deliverables**: Backup, counting, and validation helper functions
+
+1. **`create_backup <filepath>`** — Create `<filepath>.bak`, with `.bak.N` suffix when collisions exist. Abort with OS-level error on write failure (FR-002). Return the backup path on stdout.
+
+2. **`restore_from_backup <filepath> <backup_path>`** — Copy backup over the original. Used when post-replace validation fails (FR-007).
+
+3. **`count_requirement_entries <filepath>`** — Count lines matching `^-\s+\*\*(FR|NFR)-[0-9]+\*\*:` in a file.
+   Use a single `grep -cE` pattern so only valid `FR-###` or `NFR-###` requirement entries are counted. Return count on stdout.
+
+4. **`count_checklist_items <filepath>`** — Count lines matching `^- \[(x| )\]` pattern (Markdown task list items per the Checklist Item Count Definition). Return count on stdout.
+
+5. **`extract_section_headings <filepath>`** — Extract `## ...` headings, normalize by stripping trailing `*(mandatory)*` annotations and trimming whitespace. Return one heading per line on stdout.
+
+6. **`validate_structural_integrity <original_file> <candidate_file> [--type spec|checklist]`** — Compare:
+   - Mandatory sections present (for `--type spec`): `## Problem Statement`, `## User Scenarios & Testing`, `## Requirements`, `## Success Criteria`
+   - All original section headings preserved
+   - Requirement entry retention for `--type spec` must satisfy `retained_count >= ceil(0.95 * original_count)`; checklist item retention for `--type checklist` remains `retained_count = original_count`
+   - Skip the retention check only when `original_count` is zero
+   - Print specific failure reasons to stderr (NFR-002)
+   - Return 0 on pass, 1 on fail
+
+7. **`safe_write_with_validation <original_file> <candidate_content> [--type spec|checklist]`** — Orchestrate the full flow:
+   - Create backup
+   - Write candidate to `.tmp`
+   - Run `validate_structural_integrity`
+   - On pass: `mv .tmp original` (atomic replace)
+   - On fail: remove `.tmp`, leave original unchanged, report errors
+   - Return 0 on success, 1 on validation failure
+
+### Phase 2: Modified Clarify Phase
+
+**Deliverables**: Updated `run_clarify_phase()` with all safeguards
+
+1. **Pre-flight checks** (FR-009):
+   - Assert `spec.md` exists: `[[ -f "$SPEC_DIR/spec.md" ]]`
+   - Assert non-empty: `[[ -s "$SPEC_DIR/spec.md" ]]`
+   - Fail with clear, actionable error messages on either condition
+
+2. **File size warning** (FR-012):
+   - Check `stat -c%s` (or `wc -c`) of `spec.md`
+   - If ≥50,000 bytes, emit warning to stderr (non-blocking)
+
+3. **Augmented LLM prompt** (FR-001, FR-003, FR-004, FR-005, FR-011):
+   - Add explicit preservation instructions at the top of the prompt:
+
+     ```text
+     CRITICAL PRESERVATION RULES:
+     - You MUST output the COMPLETE specification with ALL sections intact
+     - Do NOT summarize, truncate, or omit any section
+     - Every section heading from the input MUST appear in your output
+     - Every FR-### and NFR-### entry MUST be preserved unless explicitly merged
+     - Replace [NEEDS CLARIFICATION] markers in-place with resolved answers
+     - Append a ## Clarifications section (or add to existing) with session Q&A
+     ```
+
+   - Add the original section heading list and requirement count as a "checklist" in the prompt for the LLM to cross-reference
+
+4. **Replace destructive write with `safe_write_with_validation`**:
+   - Replace `printf '%s\n' "$result" > "$SPEC_DIR/spec.md"` with call to `safe_write_with_validation`
+   - Pass `--type spec`
+
+### Phase 3: Modified Checklist Phase
+
+**Deliverables**: Updated `run_checklist_phase()` with same safeguards
+
+1. **Pre-flight checks**: Assert `checklists/requirements.md` exists when updating (skip for initial creation during first phase 2 run — the checklist may not exist yet)
+
+2. **Conditional safeguards**: Only apply backup/validation when the file already exists (initial creation skips validation since there's no baseline)
+
+3. **Augmented LLM prompt**: Add preservation instructions for checklist items
+
+4. **Replace destructive write with `safe_write_with_validation`**:
+   - Pass `--type checklist`
+   - 100% checklist item retention required
+
+### Phase 4: Clarification Audit Trail
+
+**Deliverables**: `## Clarifications` section guaranteed in output (FR-005)
+
+1. **Post-validation augmentation**: After successful write, verify `## Clarifications` section exists in the output. If not (LLM omitted it despite instructions), append a minimal session entry:
+
+   ```markdown
+   ## Clarifications
+
+   ### Session YYYY-MM-DD
+
+   - Autonomous clarification pass completed. See inline updates for details.
+   ```
+
+2. **`[NEEDS CLARIFICATION]` marker handling** (FR-011): The LLM prompt already instructs replacement. Add a post-write check counting remaining markers and logging a warning if any survive.
+
+### Phase 5: Shell Integration Tests
+
+**Deliverables**: Shell-script-level tests for all new functions
+
+Create `test_content_preservation.sh` in `.github/scripts/speckit-trigger/` (alongside existing `test_markdownlint_validation.sh` and `test_sc004_regression.sh`):
+
+1. **Test `create_backup`**:
+   - Creates `.bak` file with correct content
+   - Uses `.bak.1`, `.bak.2` suffixes on collision
+   - Returns non-zero on write failure (simulate with read-only directory)
+
+2. **Test `count_requirement_entries`**:
+   - Counts `FR-###` and `NFR-###` entries correctly
+   - Returns 0 for file with no requirements
+   - Ignores non-requirement bullets
+
+3. **Test `count_checklist_items`**:
+   - Counts `- [ ]` and `- [x]` items
+   - Ignores plain bullets `- ...`
+   - Returns 0 for empty file
+
+4. **Test `validate_structural_integrity`**:
+   - Passes when all sections retained and counts match
+   - Fails when mandatory section missing
+   - Fails when original section heading missing
+   - Fails when requirement count drops below 95%
+   - Passes when original has 0 requirements (skip check)
+   - Strips `*(mandatory)*` annotations before matching
+
+5. **Test `safe_write_with_validation`**:
+   - Successful write: original replaced, backup retained
+   - Failed validation: original unchanged, backup exists, `.tmp` cleaned up
+   - Backup write failure: aborts without touching original
+
+6. **Test `run_clarify_phase` integration**:
+   - Missing `spec.md` → clear error
+   - Empty `spec.md` → clear error
+   - Truncated LLM response → validation rejects, original preserved
+   - Successful augmentation → original replaced, backup retained
+
+7. **Test `run_checklist_phase` integration**:
+   - Existing checklist preserved when LLM truncates
+   - New checklist created without validation (no baseline)
+
+### Phase 6: Python Unit Tests
+
+**Deliverables**: Python tests verifying the no-content-loss invariant
+
+New test files under `tests/unit/` following the 1:1:1 policy. Since the core logic is in shell, the Python tests focus on:
+
+1. **Validation logic tests** (if we extract any Python validation helpers):
+   - `tests/unit/cli/speckit/validation/` — if a shared Python validation module is created for NFR-004 (parity)
+
+2. **Prompt augmentation tests**:
+   - Verify the preservation instructions are present in the clarify prompt
+   - Verify section headings and counts are injected into the prompt
+
+3. **Integration with existing speckit tests**:
+   - Extend `tests/unit/cli/speckit/commands/test_speckit_clarify.py` if the Python command layer changes
+
+### Phase 7: CI Workflow Updates
+
+**Deliverables**: Updated workflow configurations
+
+1. **`speckit-phase-progression.yml`**: No changes expected — the workflow calls `generate-spec-from-issue.sh --phase 2` which internally runs the updated functions
+
+2. **Add shell test execution**: Add a step in CI to run `test_content_preservation.sh` (follow pattern of existing `test_markdownlint_validation.sh`)
+
+3. **Idempotency check update**: Verify `check-idempotency.sh` phase 2 detection still works (it checks for `## Clarifications` section, which will now always be present)
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| LLM ignores preservation instructions despite prompt augmentation | Medium | Low (caught by Layer 2 validation) | Validation is the safety net; prompt is defense-in-depth |
+| Validation false positive (rejects valid output due to counting edge cases) | Medium | Medium | Comprehensive test suite for counting logic; skip check when baseline is 0 |
+| `mv` fails on non-POSIX filesystem | Low | Low | GitHub Actions runners use ext4; add error handling regardless |
+| Backup disk space on large specs | Very Low | Low | Backups are tiny (KB); retained for audit per FR-010 |
+| Shell function complexity increases maintenance burden | Medium | Medium | Keep functions small and well-documented; add thorough tests |
+| Validation overhead exceeds 5s NFR-001 threshold | Very Low | Low | All operations are local file I/O + `grep`; sub-second expected |
+| Checklist phase has no baseline on first run | N/A | N/A | Skip validation when file doesn't exist (conditional safeguards) |
+
+## Dependencies
+
+### Internal
+
+- `generate-spec-from-issue.sh` — primary modification target
+- `copilot_generate.py` — no changes needed (LLM invocation unchanged)
+- `check-idempotency.sh` — verify compatibility with always-present `## Clarifications`
+- `speckit-phase-progression.yml` — verify phase 2 step still works
+- Existing shell tests (`test_markdownlint_validation.sh`, `test_sc004_regression.sh`) — follow same patterns
+
+### External
+
+- GitHub Actions runner environment (Bash 5.x, GNU coreutils for `stat`, `mv`, `grep`)
+- `markdownlint-cli2` (already installed in CI; unaffected by changes)
+- Copilot SDK / LLM API (unchanged interface; only prompt content changes)
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*

agentic_devtools-0.2.67/specs/1199-speckit-pipeline-validate-all/checklists/requirements.md

@@ -0,0 +1,45 @@
+# Specification Quality Checklist: SpecKit pipeline: Validate all spec FRs have corresponding tasks
+
+**Purpose**: Validate specification completeness before proceeding to planning
+**Created**: 2026-04-23
+**Feature**: [spec.md](../spec.md)
+**Source Issue**: #1199
+
+## Content Quality
+
+- [ ] CHK001 Spec contains a Summary section describing the FR-to-task validation pipeline purpose and user value
+- [ ] CHK002 User stories US2 (auto-retry prompt mechanism), US3 (human-readable CLI output), and US4 (analysis report enrichment) are written in "As a … I want … so that …" format with explicit
+  priority labels
+- [ ] CHK003 All referenced functional requirements (FR-004, FR-006, FR-007, FR-013) have priority assignments (P1/P2/P3)
+- [ ] CHK004 FR-013 (analysis report enrichment) describes observable user outcomes, not internal implementation details like file paths or module names
+
+## Requirement Completeness
+
+- [ ] CHK005 US2 scenario 1 (auto-retry prompt mechanism) includes a concrete Given/When/Then acceptance scenario that is testable without inspecting implementation internals
+- [ ] CHK006 Retry failure handling and stale FR coverage data scenarios are fully documented with trigger conditions, expected system behavior, and recovery paths
+- [ ] CHK007 Acceptance scenarios for US3 (human-readable CLI output) and US4 (analysis report enrichment with FR coverage data) follow a structured Given/When/Then format
+- [ ] CHK008 Measurable non-functional requirements (e.g., NFR-001 runtime threshold and success metrics) define explicit numeric targets or pass/fail thresholds in the spec body
+- [ ] CHK009 Scope section defines explicit in-scope and out-of-scope boundaries — particularly whether the validation step runs before or after the analyze phase (as discussed in FR-006 and
+  related pipeline-ordering sections of the spec)
+- [ ] CHK010 The spec documents the dependency on an existing `tasks.md` file and, in the appropriate sections, defines the expected coverage-data schema and the relationship between the validation
+  step and the existing SpecKit analyze phase
+
+## Feature Readiness
+
+- [ ] CHK011 Each functional requirement (FR-004 human-readable output, FR-006 pipeline ordering, FR-007 auto-retry, FR-013 report enrichment) has at least one acceptance criterion with pass/fail
+  conditions
+- [ ] CHK012 User scenario coverage includes the happy path (all FRs mapped to tasks), partial coverage (some FRs missing tasks), zero coverage (no tasks.md exists), and retry exhaustion behavior
+  covered by FR-007
+- [ ] CHK013 Success criteria section defines measurable outcomes such as percentage of FRs that must be mapped, maximum acceptable false-positive rate for unmapped FR detection, and CLI output
+  parseability
+- [ ] CHK014 Key design decision in §5 describes deterministic validation behavior in implementation-agnostic terms and does not prescribe internal module names, file structure, or placement
+
+## Notes
+
+- This checklist was generated from the current specification content for issue #1199
+- The spec.md includes the full specification body, including sections such as Summary, Scope, User Stories, Functional Requirements, Non-Functional Requirements, Edge Cases, Acceptance Criteria,
+  and Success Metrics, in addition to the clarification changelog and addendum notes
+- Items marked incomplete indicate areas where the existing spec may need clarification, stronger acceptance detail, or more measurable wording before proceeding to planning
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*