agentic-devtools 0.2.59__tar.gz → 0.2.60__tar.gz

{agentic_devtools-0.2.59 → agentic_devtools-0.2.60}/.github/copilot-instructions.md

@@ -1130,6 +1130,7 @@ When creating a new worktree, `.agdt/workflows/` doesn't exist initially (it's g
 | `REQUESTS_CA_BUNDLE` | Standard requests library CA bundle path (fallback) |
 | `AGENTIC_DEVTOOLS_STATE_DIR` | Override default state directory (`.agdt/workflows/_unscoped`) |
 | `AGDT_DRY_RUN` | Set to "1" for dry-run mode globally |
+| `AGDT_PLAN_CONTEXT_BUDGET` | Plan-phase context budget in characters (default: `32000`). If set, oversized spec content is reduced deterministically before calling the LLM |
 
 ### SSL Certificate Handling
 

agentic_devtools-0.2.60/.github/scripts/speckit-trigger/enforce_budget.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""CLI helper for context budget enforcement in SpecKit trigger scripts.
+
+Reads content from stdin or arguments and applies the context budget.
+Prints the budget-compliant content to stdout and diagnostic metadata to stderr.
+
+Usage:
+    echo "$content" | python enforce_budget.py [--budget N]
+    python enforce_budget.py --description "desc" --comments "comm" [--budget N]
+
+Exit Codes:
+    0 - Success (budget-compliant content written to stdout)
+    1 - Permanent failure (budget cannot be met)
+    2 - Setup/usage error (invalid arguments or missing agentic_devtools package)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Enforce context budget on plan-phase content.")
+    parser.add_argument("--budget", type=int, default=None, help="Context budget in characters")
+    parser.add_argument("--description", type=str, default=None, help="Description content")
+    parser.add_argument("--comments", type=str, default="", help="Comments content")
+    args = parser.parse_args()
+
+    # Import here to avoid import errors when the module is not installed
+    try:
+        from agentic_devtools.context_budget import (
+            DEFAULT_CONTEXT_BUDGET,
+            ContextBudgetError,
+            enforce_context_budget,
+        )
+    except ImportError as exc:
+        print(
+            "Error: agentic_devtools.context_budget is unavailable, so budget enforcement "
+            "cannot run. Install the agentic_devtools package in this environment and rerun "
+            "the SpecKit trigger. Refusing to pass through unbudgeted content.",
+            file=sys.stderr,
+        )
+        print(f"Import error detail: {exc}", file=sys.stderr)
+        return 2
+
+    budget = args.budget if args.budget is not None else DEFAULT_CONTEXT_BUDGET
+
+    if budget <= 0:
+        print(f"Warning: Invalid budget {budget}, using default {DEFAULT_CONTEXT_BUDGET}", file=sys.stderr)
+        budget = DEFAULT_CONTEXT_BUDGET
+
+    # Get description content
+    if args.description is not None:
+        description = args.description
+    else:
+        description = sys.stdin.read()
+
+    comments = args.comments
+
+    try:
+        result = enforce_context_budget(description, comments, budget=budget)
+    except ContextBudgetError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    # Assemble output: description + optional separator + comments.
+    # The separator is accounted for in enforce_context_budget()'s budget math,
+    # so final_chars already includes it only when both fields are non-empty.
+    if result.description and result.comments:
+        output = f"{result.description}\n{result.comments}"
+    elif result.comments:
+        output = result.comments
+    else:
+        output = result.description
+
+    # Emit diagnostic metadata to stderr as JSON
+    metadata = {
+        "stage": result.stage.value,
+        "original_chars": result.original_chars,
+        "final_chars": result.final_chars,
+        "budget": result.budget,
+    }
+    print(f"[Context Budget] {json.dumps(metadata)}", file=sys.stderr)
+
+    if result.stage.value != "passthrough":
+        print(
+            f"[Context Budget] Content reduced: {result.original_chars} → {result.final_chars} chars "
+            f"(stage: {result.stage.value})",
+            file=sys.stderr,
+        )
+
+    # Write the budget-compliant content to stdout
+    sys.stdout.write(output)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -20,9 +20,13 @@
 #   COPILOT_TIMEOUT - Seconds to wait for a Copilot SDK response (default: 600).
 #                     Plan, Tasks, and Analyze phases override this to 900.
 #   SPEC_BASE_PATH  - Base path for specs (default: specs)
+#   AGDT_PLAN_CONTEXT_BUDGET - Context budget in characters for the plan phase
+#                              (default: 32000).  If the spec content exceeds this
+#                              limit, deterministic reduction is applied before
+#                              calling the LLM.
 #
 # Outputs:
-#   GITHUB_OUTPUT: branch_name, spec_file, feature_num, spec_dir
+#   GITHUB_OUTPUT: branch_name, spec_file, issue_number, spec_dir
 
 set -euo pipefail
 
@@ -41,20 +45,36 @@ SPEC_BASE_PATH="${SPEC_BASE_PATH:-specs}"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
 
+# ---------------------------------------------------------------------------
+# Validate ISSUE_NUMBER is a positive integer (FR-011)
+# ---------------------------------------------------------------------------
+if [[ ! "$ISSUE_NUMBER" =~ ^[1-9][0-9]*$ ]]; then
+    echo "Error: ISSUE_NUMBER must be a positive integer (got '$ISSUE_NUMBER')" >&2
+    exit 1
+fi
+
 echo "=== SpecKit: Generating Full Planning Artifact Suite ==="
 echo "Issue: #$ISSUE_NUMBER - $ISSUE_TITLE"
 echo "Model: $COPILOT_MODEL"
 
-# Function to get the next feature number
+# Function to get the next feature number (legacy autoincrement, kept for
+# potential fallback use).  Only counts directories/branches that match the
+# legacy 3-digit prefix pattern ^[0-9]{3}- so that issue-numbered directories
+# with non-3-digit prefixes (e.g. 42-foo, 1176-bar) do not inflate the
+# autoincrement counter (FR-007).  Note: 3-digit issue numbers (100–999) will
+# still match the legacy pattern and be counted — this is an accepted overlap
+# since the autoincrement function is only used as a fallback.
 get_next_feature_number() {
     local highest=0
 
-    # Check existing specs directories
+    # Check existing specs directories — only legacy 3-digit prefixed dirs
     if [[ -d "$REPO_ROOT/$SPEC_BASE_PATH" ]]; then
         for dir in "$REPO_ROOT/$SPEC_BASE_PATH"/*; do
             [[ -d "$dir" ]] || continue
             dirname=$(basename "$dir")
-            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
+            # Only match legacy 3-digit prefixed directories (FR-007)
+            echo "$dirname" | grep -q '^[0-9]\{3\}-' || continue
+            number=$(echo "$dirname" | grep -o '^[0-9]\{3\}')
             number=$((10#$number))
             if [[ $number -gt $highest ]]; then
                 highest=$number
@@ -62,7 +82,7 @@ get_next_feature_number() {
         done
     fi
 
-    # Check branches
+    # Check branches — already correctly filters ^[0-9]{3}-
     branches=$(git branch -a 2>/dev/null || echo "")
     if [[ -n "$branches" ]]; then
         while IFS= read -r branch; do
@@ -80,12 +100,67 @@ get_next_feature_number() {
     echo $((highest + 1))
 }
 
-# Get next feature number
-FEATURE_NUM=$(get_next_feature_number)
-FEATURE_NUM_PADDED=$(printf "%03d" "$FEATURE_NUM")
-BRANCH_NAME="${FEATURE_NUM_PADDED}-${SHORT_NAME}"
-SPEC_DIR="$REPO_ROOT/$SPEC_BASE_PATH/$BRANCH_NAME"
-SPEC_FILE="$SPEC_BASE_PATH/$BRANCH_NAME/spec.md"
+# ---------------------------------------------------------------------------
+# Collision detection & directory reuse (FR-004, FR-012, FR-015)
+#
+# Use the GitHub issue number directly as the spec directory prefix instead
+# of autoincrementing.  If a directory for this issue already exists, reuse
+# it (even if the issue title — and therefore SHORT_NAME — has changed).
+# ---------------------------------------------------------------------------
+EXISTING_DIRS=()
+
+shopt -s nullglob
+for dir in "$REPO_ROOT/$SPEC_BASE_PATH"/${ISSUE_NUMBER}-*; do
+    if [[ -d "$dir" ]]; then
+        EXISTING_DIRS+=("$dir")
+    fi
+done
+shopt -u nullglob
+
+if (( ${#EXISTING_DIRS[@]} > 1 )); then
+    echo "Error: Found multiple existing spec directories for issue #$ISSUE_NUMBER:" >&2
+    for dir in "${EXISTING_DIRS[@]}"; do
+        echo "  - $(basename "$dir")" >&2
+    done
+    echo "Refusing to choose one directory non-deterministically. Remove or rename the extra directories and retry." >&2
+    exit 1
+fi
+
+EXISTING_DIR=""
+if (( ${#EXISTING_DIRS[@]} == 1 )); then
+    EXISTING_DIR="${EXISTING_DIRS[0]}"
+fi
+
+if [[ -n "$EXISTING_DIR" ]]; then
+    # FR-015: For 3-digit issue numbers (100-999), the prefix overlaps with
+    # the legacy ^[0-9]{3}- namespace.  Verify that the candidate directory
+    # actually belongs to this issue by checking for a Source Issue marker.
+    if [[ ${#ISSUE_NUMBER} -eq 3 ]]; then
+        SOURCE_ISSUE_FOUND=false
+        for artifact in "$EXISTING_DIR/checklists/requirements.md" "$EXISTING_DIR/spec.md"; do
+            if [[ -f "$artifact" ]] && grep -Eq "\*\*Source Issue\*\*.*#${ISSUE_NUMBER}([^0-9]|$)" "$artifact"; then
+                SOURCE_ISSUE_FOUND=true
+                break
+            fi
+        done
+        if [[ "$SOURCE_ISSUE_FOUND" != "true" ]]; then
+            echo "Error: Found existing directory '$(basename "$EXISTING_DIR")' but it does not contain a matching Source Issue marker for #$ISSUE_NUMBER." >&2
+            echo "This may be an unrelated legacy directory. Refusing to reuse." >&2
+            exit 1
+        fi
+    fi
+
+    # Reuse existing directory (FR-012: stable identity even if title changed)
+    EXISTING_DIRNAME=$(basename "$EXISTING_DIR")
+    BRANCH_NAME="$EXISTING_DIRNAME"
+    SPEC_DIR="$EXISTING_DIR"
+    echo "Reusing existing spec directory: $EXISTING_DIRNAME"
+else
+    # Create new directory with raw issue number prefix (FR-001)
+    BRANCH_NAME="${ISSUE_NUMBER}-${SHORT_NAME}"
+    SPEC_DIR="$REPO_ROOT/$SPEC_BASE_PATH/$BRANCH_NAME"
+fi
+SPEC_FILE="$SPEC_BASE_PATH/$(basename "$SPEC_DIR")/spec.md"
 
 echo "Branch: $BRANCH_NAME"
 echo "Spec Directory: $SPEC_DIR"
@@ -371,11 +446,58 @@ $spec_content"
 #
 # Generates plan.md and optional artifacts (research.md, data-model.md,
 # contracts/*, quickstart.md) using artifact delimiters.
+#
+# Context budget enforcement: before calling the LLM, the spec content is
+# passed through the Python budget module to ensure it fits within the
+# configured context budget (default: 32,000 chars, override via
+# AGDT_PLAN_CONTEXT_BUDGET).  If the content is too large, deterministic
+# reduction stages are applied (strip markdown → remove images → collapse
+# whitespace → hard truncate → summary-only).
 # ---------------------------------------------------------------------------
 run_plan_phase() {
     local spec_content
     spec_content=$(strip_model_footer "$(cat "$SPEC_DIR/spec.md")")
 
+    # --- Context budget enforcement ---
+    local budget_args=()
+    local budget_value="${AGDT_PLAN_CONTEXT_BUDGET:-}"
+    if [[ -n "$budget_value" ]]; then
+        # Validate that the value is a positive integer (strip leading zeros to avoid octal)
+        if [[ "$budget_value" =~ ^[0-9]+$ ]] && (( 10#$budget_value > 0 )); then
+            budget_args+=(--budget "$budget_value")
+        else
+            echo "Warning: AGDT_PLAN_CONTEXT_BUDGET='$budget_value' is not a valid positive integer. Using default." >&2
+        fi
+    fi
+
+    local budget_stderr_file
+    budget_stderr_file=$(mktemp /tmp/budget_stderr.XXXXXX) || {
+        echo "Error: Failed to create temp file for budget stderr capture." >&2
+        return 1
+    }
+    local budget_content=""
+    local budget_exit_code=0
+    budget_content=$(printf '%s' "$spec_content" | python "$SCRIPT_DIR/enforce_budget.py" "${budget_args[@]}" 2>"$budget_stderr_file") || budget_exit_code=$?
+    local budget_stderr=""
+    budget_stderr=$(cat "$budget_stderr_file" 2>/dev/null || echo "")
+    rm -f "$budget_stderr_file"
+
+    if [[ $budget_exit_code -ne 0 ]]; then
+        echo "Error: Context budget enforcement failed for plan phase." >&2
+        if [[ -n "$budget_stderr" ]]; then
+            echo "$budget_stderr" >&2
+        fi
+        return 1
+    fi
+
+    # Emit budget diagnostics
+    if [[ -n "$budget_stderr" ]]; then
+        echo "$budget_stderr" >&2
+    fi
+
+    # Use budget-compliant content for the prompt
+    spec_content="$budget_content"
+
     local prompt
     prompt="You are a technical implementation planner. Based on the following feature specification, produce a comprehensive implementation plan.
 
@@ -702,7 +824,7 @@ fi
 SPEC_DIR_REL="${SPEC_DIR_REL#/}"
 echo "branch_name=$BRANCH_NAME" >> "${GITHUB_OUTPUT:-/dev/stdout}"
 echo "spec_file=$SPEC_FILE" >> "${GITHUB_OUTPUT:-/dev/stdout}"
-echo "feature_num=$FEATURE_NUM_PADDED" >> "${GITHUB_OUTPUT:-/dev/stdout}"
+echo "issue_number=$ISSUE_NUMBER" >> "${GITHUB_OUTPUT:-/dev/stdout}"
 echo "spec_dir=$SPEC_DIR_REL" >> "${GITHUB_OUTPUT:-/dev/stdout}"
 
 echo ""

{agentic_devtools-0.2.59 → agentic_devtools-0.2.60}/.github/workflows/speckit-issue-trigger.yml

@@ -274,8 +274,16 @@ jobs:
 
           BRANCH_NAME="${{ steps.generate.outputs.branch_name }}"
 
-          # Create and checkout new branch
-          git checkout -b "$BRANCH_NAME"
+          # Fetch the remote branch so the remote-tracking ref is current, but do not
+          # check out origin/$BRANCH_NAME after artifacts have been generated because
+          # untracked generated files can cause checkout to fail on reruns (FR-013).
+          if git ls-remote --exit-code --heads origin "$BRANCH_NAME" >/dev/null 2>&1; then
+            echo "Branch '$BRANCH_NAME' already exists on remote — fetching and resetting local branch from current HEAD"
+            git fetch origin "refs/heads/$BRANCH_NAME:refs/remotes/origin/$BRANCH_NAME"
+            git checkout -B "$BRANCH_NAME"
+          else
+            git checkout -b "$BRANCH_NAME"
+          fi
 
           # Add all generated artifacts in the spec directory
           SPEC_DIR="${{ steps.generate.outputs.spec_dir }}"
@@ -302,7 +310,7 @@ jobs:
         if: steps.validate-label.outputs.label_matches == 'true' && steps.idempotency.outputs.skipped != 'true' && vars.SPECKIT_CREATE_BRANCH != 'false'
         run: |
           BRANCH_NAME="${{ steps.generate.outputs.branch_name }}"
-          git push -u origin "$BRANCH_NAME"
+          git push --force-with-lease -u origin "$BRANCH_NAME"
 
       - name: Create Pull Request
         if: steps.validate-label.outputs.label_matches == 'true' && steps.idempotency.outputs.skipped != 'true' && vars.SPECKIT_CREATE_PR != 'false'

{agentic_devtools-0.2.59 → agentic_devtools-0.2.60}/.specify/scripts/bash/common.sh

@@ -72,9 +72,11 @@ check_feature_branch() {
         return 0
     fi
 
-    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
+    # Accept both legacy 3-digit prefixes (001-feature) and issue-number
+    # prefixes of any length (42-feature, 1176-feature) — FR-014
+    if [[ ! "$branch" =~ ^[0-9]+- ]]; then
         echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
-        echo "Feature branches should be named like: 001-feature-name" >&2
+        echo "Feature branches should be named like: 001-feature-name or 42-feature-name" >&2
         return 1
     fi
 
@@ -85,13 +87,14 @@ get_feature_dir() { echo "$1/specs/$2"; }
 
 # Find feature directory by numeric prefix instead of exact branch match
 # This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
+# Supports both legacy 3-digit prefixes and issue-number prefixes of any length (FR-014)
 find_feature_dir_by_prefix() {
     local repo_root="$1"
     local branch_name="$2"
     local specs_dir="$repo_root/specs"
 
-    # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
-    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
+    # Extract numeric prefix from branch (e.g., "004" from "004-whatever" or "1176" from "1176-feature")
+    if [[ ! "$branch_name" =~ ^([0-9]+)- ]]; then
         # If branch doesn't have numeric prefix, fall back to exact match
         echo "$specs_dir/$branch_name"
         return
@@ -117,10 +120,10 @@ find_feature_dir_by_prefix() {
         # Exactly one match - perfect!
         echo "$specs_dir/${matches[0]}"
     else
-        # Multiple matches - this shouldn't happen with proper naming convention
+        # Multiple matches — fail hard so callers don't silently mkdir a new dir
         echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
         echo "Please ensure only one spec directory exists per numeric prefix." >&2
-        echo "$specs_dir/$branch_name"  # Return something to avoid breaking the script
+        return 1
     fi
 }
 
@@ -133,8 +136,16 @@ get_feature_paths() {
         has_git_repo="true"
     fi
 
-    # Use prefix-based lookup to support multiple branches per spec
-    local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch")
+    # This helper is consumed by callers using `eval $(get_feature_paths)`.
+    # A non-zero exit status inside command substitution is not reliably
+    # fatal under `set -e`, so emit a failing command for eval to execute
+    # when path resolution fails. The underlying error text is already
+    # written to stderr by find_feature_dir_by_prefix.
+    local feature_dir
+    if ! feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch"); then
+        echo "false"
+        return 0
+    fi
 
     cat <<EOF
 REPO_ROOT='$repo_root'

{agentic_devtools-0.2.59 → agentic_devtools-0.2.60}/PKG-INFO

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

{agentic_devtools-0.2.59 → agentic_devtools-0.2.60}/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.59'
-__version_tuple__ = version_tuple = (0, 2, 59)
+__version__ = version = '0.2.60'
+__version_tuple__ = version_tuple = (0, 2, 60)
 
 __commit_id__ = commit_id = None