aidp 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 724d07296380ad69a72b1f9d6bf4dd44d77cf35f994eb35e1e0d224ed32e93a0
-  data.tar.gz: f54213c88e3e532205852f8dfbedcc0c264a446a65a1110ddf7de524f10e64d5
+  metadata.gz: d4fbf6c86d50426f952b62da4b353cce6560aa5321c33d641a972a3af5989456
+  data.tar.gz: da684c72ccdc0d4770d3029a0977f592a9f9baf8e1ce4c14df47ccfbda559b38
 SHA512:
-  metadata.gz: f8788f4f8af45642b276e350f7d64e2413ae1532cbe02fe29c95c06c8fcbf84ecd66c35cb73e5b16637b6780f52ba77991b255d78f5f2464200a5db6acce262b
-  data.tar.gz: 2cd95f1e5369205332ad1f87d313b6dc99801d7bdb6f13d0b661cfbba4a771a9e8277e6e8f43e8234a2bea1a6ba23cc73ef54e480f2cf73788bc6dd17aa8de74
+  metadata.gz: bf57b96f9393e533508624fabe2ca3bdc8e49a241a68f6404c144d124ab0c19c4f3cea415e8e8e2f4a7d3145e06e23f86f2207e61414b8397ea929304ae29f96
+  data.tar.gz: f15ca608bda7e5ed3358c9b633b7d415ce943e99d9a10a74f114de3e31373daec0d4ae52d01000bbb42c6950b252e50ad13daa176c4d32932a6f98b2153a678b

data/lib/aidp/cli/issue_importer.rb

@@ -4,20 +4,30 @@ require "json"
 require "net/http"
 require "uri"
 require "open3"
+require "timeout"
 
 module Aidp
   # Handles importing GitHub issues into AIDP work loops
   class IssueImporter
     include Aidp::MessageDisplay
 
+    COMPONENT = "issue_importer"
+
     # Initialize the importer
     #
     # @param gh_available [Boolean, nil] (test-only) forcibly sets whether gh CLI is considered
     #   available. When nil (default) we auto-detect. This enables deterministic specs without
     #   depending on developer environment.
     def initialize(gh_available: nil, enable_bootstrap: true)
-      @gh_available = gh_available.nil? ? gh_cli_available? : gh_available
+      disabled_via_env = ENV["AIDP_DISABLE_GH_CLI"] == "1"
+      @gh_available = if disabled_via_env
+        false
+      else
+        gh_available.nil? ? gh_cli_available? : gh_available
+      end
       @enable_bootstrap = enable_bootstrap
+      Aidp.log_debug(COMPONENT, "Initialized importer", gh_available: @gh_available, enable_bootstrap: @enable_bootstrap, disabled_via_env: disabled_via_env)
+      Aidp.log_debug(COMPONENT, "GitHub CLI disabled via env flag") if disabled_via_env
     end
 
     def import_issue(identifier)
@@ -81,16 +91,28 @@ module Aidp
       return nil unless match
 
       owner, repo, number = match[1], match[2], match[3]
+      Aidp.log_debug(COMPONENT, "Fetching issue data", owner: owner, repo: repo, number: number, via: (@gh_available ? "gh_cli" : "api"))
 
       # First try GitHub CLI if available (works for private repos)
       if @gh_available
         display_message("🔍 Fetching issue via GitHub CLI...", type: :info)
+        Aidp.log_debug(COMPONENT, "Attempting GitHub CLI fetch", owner: owner, repo: repo, number: number)
         issue_data = fetch_via_gh_cli(owner, repo, number)
-        return issue_data if issue_data
+        if issue_data
+          Aidp.log_debug(COMPONENT, "GitHub CLI fetch succeeded", owner: owner, repo: repo, number: number)
+          return issue_data
+        end
+        Aidp.log_debug(COMPONENT, "GitHub CLI fetch failed, falling back to API", owner: owner, repo: repo, number: number)
       end
 
       # Fallback to public API
       display_message("🔍 Fetching issue via GitHub API...", type: :info)
+      Aidp.log_debug(COMPONENT, "Fetching issue via GitHub API", owner: owner, repo: repo, number: number)
+      fixture = test_fixture(owner, repo, number)
+      if fixture
+        Aidp.log_debug(COMPONENT, "Using test fixture for issue fetch", owner: owner, repo: repo, number: number, status: fixture["status"])
+        return handle_test_fixture(fixture, owner, repo, number)
+      end
       fetch_via_api(owner, repo, number)
     end
 
@@ -101,9 +123,12 @@ module Aidp
         "--json", "title,body,labels,milestone,comments,state,assignees,number,url"
       ]
 
-      stdout, stderr, status = Open3.capture3(*cmd)
+      Aidp.log_debug(COMPONENT, "Running gh cli", owner: owner, repo: repo, number: number, command: cmd.join(" "))
+      stdout, stderr, status = capture3_with_timeout(*cmd, timeout: gh_cli_timeout)
+      Aidp.log_debug(COMPONENT, "Completed gh cli", owner: owner, repo: repo, number: number, exitstatus: status.exitstatus)
 
       unless status.success?
+        Aidp.log_warn(COMPONENT, "GitHub CLI fetch failed", owner: owner, repo: repo, number: number, exitstatus: status.exitstatus, error: stderr.strip)
         display_message("⚠️ GitHub CLI failed: #{stderr.strip}", type: :warn)
         return nil
       end
@@ -112,9 +137,14 @@ module Aidp
         data = JSON.parse(stdout)
         normalize_gh_cli_data(data)
       rescue JSON::ParserError => e
+        Aidp.log_warn(COMPONENT, "GitHub CLI response parse failed", owner: owner, repo: repo, number: number, error: e.message)
         display_message("❌ Failed to parse GitHub CLI response: #{e.message}", type: :error)
         nil
       end
+    rescue Timeout::Error
+      Aidp.log_warn(COMPONENT, "GitHub CLI timed out", owner: owner, repo: repo, number: number, timeout: gh_cli_timeout)
+      display_message("⚠️ GitHub CLI timed out after #{gh_cli_timeout}s, falling back to API", type: :warn)
+      nil
     end
 
     def fetch_via_api(owner, repo, number)
@@ -281,6 +311,103 @@ module Aidp
       false
     end
 
+    def capture3_with_timeout(*cmd, timeout:)
+      stdout_str = +""
+      stderr_str = +""
+      status = nil
+      wait_thr = nil
+
+      Timeout.timeout(timeout) do
+        Open3.popen3(*cmd) do |stdin, stdout_io, stderr_io, thread|
+          wait_thr = thread
+          stdin.close
+          stdout_str = stdout_io.read
+          stderr_str = stderr_io.read
+          status = thread.value
+        end
+      end
+
+      [stdout_str, stderr_str, status]
+    rescue Timeout::Error
+      terminate_process(wait_thr)
+      raise
+    end
+
+    def terminate_process(wait_thr)
+      return unless wait_thr&.alive?
+
+      begin
+        Process.kill("TERM", wait_thr.pid)
+      rescue Errno::ESRCH
+        return
+      end
+
+      begin
+        wait_thr.join(1)
+      rescue
+        nil
+      end
+
+      return unless wait_thr.alive?
+
+      begin
+        Process.kill("KILL", wait_thr.pid)
+      rescue Errno::ESRCH
+        return
+      end
+
+      begin
+        wait_thr.join(1)
+      rescue
+        nil
+      end
+    end
+
+    def gh_cli_timeout
+      Integer(ENV.fetch("AIDP_GH_CLI_TIMEOUT", 5))
+    rescue ArgumentError, TypeError
+      5
+    end
+
+    def test_fixture(owner, repo, number)
+      fixtures_raw = ENV["AIDP_TEST_ISSUE_FIXTURES"]
+      return nil unless fixtures_raw
+
+      fixtures = JSON.parse(fixtures_raw)
+      fixtures["#{owner}/#{repo}##{number}"]
+    rescue JSON::ParserError => e
+      Aidp.log_warn(COMPONENT, "Invalid issue fixtures JSON", error: e.message)
+      nil
+    end
+
+    def handle_test_fixture(fixture, owner, repo, number)
+      status = fixture["status"].to_i
+      case status
+      when 200
+        data = fixture.fetch("data", {})
+        Aidp.log_debug(COMPONENT, "Returning fixture issue data", owner: owner, repo: repo, number: number)
+        normalize_api_data(stringify_keys(data))
+      when 404
+        Aidp.log_warn(COMPONENT, "Fixture indicates issue not found", owner: owner, repo: repo, number: number)
+        display_message("❌ Issue not found (may be private)", type: :error)
+        nil
+      when 403
+        Aidp.log_warn(COMPONENT, "Fixture indicates API rate limit", owner: owner, repo: repo, number: number)
+        display_message("❌ API rate limit exceeded", type: :error)
+        nil
+      else
+        Aidp.log_warn(COMPONENT, "Fixture indicates API error", owner: owner, repo: repo, number: number, status: status)
+        display_message("❌ GitHub API error: #{status}", type: :error)
+        nil
+      end
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) do |(k, v), result|
+        result[k.to_s] = v
+      end
+    end
+
     def perform_bootstrap(issue_data)
       return if ENV["AIDP_DISABLE_BOOTSTRAP"] == "1"
       return unless @enable_bootstrap

data/lib/aidp/harness/config_schema.rb

@@ -1110,6 +1110,9 @@ module Aidp
 
       # Apply defaults to configuration
       def self.apply_defaults(config)
+        # Guard against non-hash config (e.g., when YAML parsing fails)
+        return config unless config.is_a?(Hash)
+
         result = deep_dup(config)
 
         # Apply harness defaults

data/lib/aidp/harness/config_validator.rb

@@ -279,6 +279,7 @@ module Aidp
 
       def fix_validation_issues
         return unless @config
+        return unless @config.is_a?(Hash)
 
         # Fix common issues that can be automatically corrected
 

data/lib/aidp/harness/provider_manager.rb

@@ -108,10 +108,16 @@ module Aidp
         # Last resort: try any available provider
         next_provider = find_any_available_provider
         if next_provider
-          success = set_current_provider(next_provider, reason, context)
-          if success
-            log_provider_switch(old_provider, next_provider, reason, context)
-            return next_provider
+          # Only attempt switch if it's actually a different provider
+          if next_provider != old_provider
+            success = set_current_provider(next_provider, reason, context)
+            if success
+              log_provider_switch(old_provider, next_provider, reason, context)
+              return next_provider
+            end
+          else
+            # Same provider - no switch possible
+            Aidp.logger.debug("provider_manager", "Only provider available is current provider", provider: next_provider)
           end
         end
 
@@ -132,6 +138,14 @@ module Aidp
           # Treat capacity/resource exhaustion like rate limit for fallback purposes
           Aidp.logger.warn("provider_manager", "Resource/quota exhaustion detected", classified_from: error_type)
           switch_provider("rate_limit", error_details.merge(classified_from: error_type))
+        when "empty_response"
+          # Empty response indicates provider failure, try next provider
+          Aidp.logger.warn("provider_manager", "Empty response from provider", classified_from: error_type)
+          switch_provider("provider_failure", error_details.merge(classified_from: error_type))
+        when "provider_error"
+          # Generic provider error, try next provider
+          Aidp.logger.warn("provider_manager", "Provider error detected", classified_from: error_type)
+          switch_provider("provider_failure", error_details.merge(classified_from: error_type))
         when "authentication"
           switch_provider("authentication_error", error_details)
         when "network"
@@ -1504,7 +1518,13 @@ module Aidp
 
       # Log provider switch
       def log_provider_switch(from_provider, to_provider, reason, context)
-        display_message("🔄 Provider switch: #{from_provider} → #{to_provider} (#{reason})", type: :info)
+        if from_provider == to_provider
+          # Same provider - this indicates no fallback was possible
+          display_message("⚠️  Provider switch failed: #{from_provider} → #{to_provider} (#{reason})", type: :warning)
+          display_message("   No alternative providers available", type: :warning)
+        else
+          display_message("🔄 Provider switch: #{from_provider} → #{to_provider} (#{reason})", type: :info)
+        end
         if context.any?
           display_message("   Context: #{context.inspect}", type: :muted)
         end
@@ -1513,7 +1533,31 @@ module Aidp
       # Log no providers available
       def log_no_providers_available(reason, context)
         display_message("❌ No providers available for switching (#{reason})", type: :error)
-        display_message("   All providers are rate limited, unhealthy, or circuit breaker open", type: :warning)
+
+        # Check if we have any fallback providers configured
+        harness_fallbacks = if @configuration.respond_to?(:fallback_providers)
+          Array(@configuration.fallback_providers).compact
+        else
+          []
+        end
+
+        all_providers = configured_providers
+
+        if harness_fallbacks.empty? && all_providers.size <= 1
+          display_message("   No fallback providers configured in aidp.yml", type: :warning)
+          display_message("   💡 Add fallback providers to enable automatic failover:", type: :info)
+          display_message("      harness:", type: :muted)
+          display_message("        fallback_providers:", type: :muted)
+          display_message("          - anthropic", type: :muted)
+          display_message("          - gemini", type: :muted)
+          display_message("   Run 'aidp config --interactive' to configure providers", type: :info)
+        else
+          display_message("   All providers are rate limited, unhealthy, or circuit breaker open", type: :warning)
+          if harness_fallbacks.any?
+            display_message("   Configured fallbacks: #{harness_fallbacks.join(", ")}", type: :muted)
+          end
+        end
+
         if context.any?
           display_message("   Context: #{context.inspect}", type: :muted)
         end

data/lib/aidp/init/doc_generator.rb

@@ -112,6 +112,12 @@ module Aidp
 
           ---
           Generated from template `planning/generate_llm_style_guide.md` with repository-aware adjustments.
+
+          **Note**: For comprehensive AIDP projects, consider creating both:
+          1. `STYLE_GUIDE.md` - Detailed explanations with examples and rationale
+          2. `LLM_STYLE_GUIDE.md` - Quick reference with `STYLE_GUIDE:line-range` cross-references
+
+          See `planning/generate_llm_style_guide.md` for the two-guide approach.
         GUIDE
 
         File.write(File.join(@project_dir, STYLE_GUIDE_PATH), content)

data/lib/aidp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Aidp
-  VERSION = "0.20.0"
+  VERSION = "0.21.0"
 end

data/lib/aidp/watch/repository_client.rb

@@ -209,6 +209,7 @@ module Aidp
           number: raw["number"],
           title: raw["title"],
           body: raw["body"] || "",
+          author: raw.dig("author", "login") || raw["author"],
           comments: Array(raw["comments"]).map { |comment| normalize_comment(comment) },
           labels: Array(raw["labels"]).map { |label| label.is_a?(Hash) ? label["name"] : label },
           state: raw["state"],
@@ -223,6 +224,7 @@ module Aidp
           number: raw["number"],
           title: raw["title"],
           body: raw["body"] || "",
+          author: raw.dig("user", "login"),
           comments: Array(raw["comments"]).map { |comment| normalize_comment(comment) },
           labels: Array(raw["labels"]).map { |label| label["name"] },
           state: raw["state"],

data/lib/aidp/watch/repository_safety_checker.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "open3"
+require_relative "../message_display"
+
+module Aidp
+  module Watch
+    # Validates watch mode safety requirements for public repositories
+    # and enforces author allowlists to prevent untrusted input execution.
+    class RepositorySafetyChecker
+      include Aidp::MessageDisplay
+
+      class UnsafeRepositoryError < StandardError; end
+      class UnauthorizedAuthorError < StandardError; end
+
+      def initialize(repository_client:, config: {})
+        @repository_client = repository_client
+        @config = config
+        @repo_visibility_cache = {}
+      end
+
+      # Check if watch mode is safe to run for this repository
+      # @param force [Boolean] Skip safety checks (dangerous!)
+      # @return [Boolean] true if safe, raises error otherwise
+      def validate_watch_mode_safety!(force: false)
+        Aidp.log_debug("repository_safety", "validate watch mode safety",
+          repo: @repository_client.full_repo,
+          force: force)
+
+        # Skip checks if forced (user takes responsibility)
+        if force
+          display_message("⚠️  Watch mode safety checks BYPASSED (--force)", type: :warning)
+          return true
+        end
+
+        # Check repository visibility
+        unless repository_safe_for_watch_mode?
+          raise UnsafeRepositoryError, unsafe_repository_message
+        end
+
+        # Check if running in safe environment
+        unless safe_environment?
+          display_message("⚠️  Watch mode running outside container/sandbox", type: :warning)
+          display_message("   Consider using a containerized environment for additional safety", type: :muted)
+        end
+
+        display_message("✅ Watch mode safety checks passed", type: :success)
+        true
+      end
+
+      # Check if an issue author is allowed to trigger automated work
+      # @param issue [Hash] Issue data with :author or :assignees
+      # @return [Boolean] true if authorized
+      def author_authorized?(issue)
+        author = extract_author(issue)
+        return false unless author
+
+        # If no allowlist configured, allow all (backward compatible)
+        return true if author_allowlist.empty?
+
+        # Check if author is in allowlist
+        authorized = author_allowlist.include?(author)
+
+        Aidp.log_debug("repository_safety", "check author authorization",
+          author: author,
+          authorized: authorized,
+          allowlist_size: author_allowlist.size)
+
+        authorized
+      end
+
+      # Check if an issue should be processed based on author authorization
+      # @param issue [Hash] Issue data
+      # @param enforce [Boolean] Raise error if unauthorized
+      # @return [Boolean] true if should process
+      def should_process_issue?(issue, enforce: true)
+        unless author_authorized?(issue)
+          author = extract_author(issue)
+          if enforce && author_allowlist.any?
+            raise UnauthorizedAuthorError,
+              "Issue ##{issue[:number]} author '#{author}' not in allowlist. " \
+              "Add to watch.safety.author_allowlist in aidp.yml to allow."
+          end
+
+          display_message("⏭️  Skipping issue ##{issue[:number]} - author '#{author}' not authorized",
+            type: :muted)
+          return false
+        end
+
+        true
+      end
+
+      private
+
+      def repository_safe_for_watch_mode?
+        # Check if repository is private
+        return true if repository_private?
+
+        # Public repositories require explicit opt-in
+        if public_repos_allowed?
+          display_message("⚠️  Watch mode enabled for PUBLIC repository", type: :warning)
+          display_message("   Ensure you trust all contributors and have proper safety measures", type: :muted)
+          return true
+        end
+
+        false
+      end
+
+      def repository_private?
+        # Cache visibility check to avoid repeated API calls
+        return @repo_visibility_cache[:private] if @repo_visibility_cache.key?(:private)
+
+        is_private = if @repository_client.gh_available?
+          check_visibility_via_gh
+        else
+          check_visibility_via_api
+        end
+
+        @repo_visibility_cache[:private] = is_private
+        Aidp.log_debug("repository_safety", "repository visibility check",
+          repo: @repository_client.full_repo,
+          private: is_private)
+
+        is_private
+      end
+
+      def check_visibility_via_gh
+        cmd = ["gh", "repo", "view", @repository_client.full_repo, "--json", "visibility"]
+        stdout, stderr, status = Open3.capture3(*cmd)
+
+        unless status.success?
+          Aidp.log_warn("repository_safety", "failed to check repo visibility via gh",
+            error: stderr.strip)
+          # Assume public if we can't determine (safer default)
+          return false
+        end
+
+        data = JSON.parse(stdout)
+        data["visibility"]&.downcase == "private"
+      rescue JSON::ParserError => e
+        Aidp.log_error("repository_safety", "failed to parse gh repo response", error: e.message)
+        false # Assume public on error
+      end
+
+      def check_visibility_via_api
+        uri = URI("https://api.github.com/repos/#{@repository_client.full_repo}")
+        response = Net::HTTP.get_response(uri)
+
+        unless response.code == "200"
+          Aidp.log_warn("repository_safety", "failed to check repo visibility via API",
+            status: response.code)
+          # Assume public if we can't determine
+          return false
+        end
+
+        data = JSON.parse(response.body)
+        data["private"] == true
+      rescue => e
+        Aidp.log_error("repository_safety", "failed to check repo visibility", error: e.message)
+        false # Assume public on error
+      end
+
+      def public_repos_allowed?
+        @config.dig(:safety, :allow_public_repos) == true
+      end
+
+      def author_allowlist
+        @author_allowlist ||= Array(@config.dig(:safety, :author_allowlist)).compact.map(&:to_s)
+      end
+
+      def safe_environment?
+        # Check if running in a container
+        in_container? || @config.dig(:safety, :require_container) == false
+      end
+
+      def in_container?
+        # Check for container indicators
+        File.exist?("/.dockerenv") ||
+          File.exist?("/run/.containerenv") ||
+          ENV["AIDP_ENV"] == "development" # devcontainer
+      end
+
+      def extract_author(issue)
+        # Try different author fields
+        issue[:author] ||
+          issue.dig(:assignees, 0) ||
+          issue["author"] ||
+          issue.dig("assignees", 0)
+      end
+
+      def unsafe_repository_message
+        <<~MSG
+          🛑 Watch mode is DISABLED for public repositories by default.
+
+          Running automated code execution on untrusted public input is dangerous!
+
+          To enable watch mode for this public repository, add to your aidp.yml:
+
+            watch:
+              safety:
+                allow_public_repos: true
+                author_allowlist:  # Only these users can trigger automation
+                  - trusted_maintainer
+                  - another_admin
+                require_container: true  # Require sandboxed environment
+
+          Alternatively, use --force to bypass this check (NOT RECOMMENDED).
+        MSG
+      end
+    end
+  end
+end

data/lib/aidp/watch/runner.rb

@@ -4,6 +4,7 @@ require "tty-prompt"
 
 require_relative "../message_display"
 require_relative "repository_client"
+require_relative "repository_safety_checker"
 require_relative "state_store"
 require_relative "plan_generator"
 require_relative "plan_processor"
@@ -18,14 +19,19 @@ module Aidp
 
       DEFAULT_INTERVAL = 30
 
-      def initialize(issues_url:, interval: DEFAULT_INTERVAL, provider_name: nil, gh_available: nil, project_dir: Dir.pwd, once: false, use_workstreams: true, prompt: TTY::Prompt.new)
+      def initialize(issues_url:, interval: DEFAULT_INTERVAL, provider_name: nil, gh_available: nil, project_dir: Dir.pwd, once: false, use_workstreams: true, prompt: TTY::Prompt.new, safety_config: {}, force: false)
         @prompt = prompt
         @interval = interval
         @once = once
         @project_dir = project_dir
+        @force = force
 
         owner, repo = RepositoryClient.parse_issues_url(issues_url)
         @repository_client = RepositoryClient.new(owner: owner, repo: repo, gh_available: gh_available)
+        @safety_checker = RepositorySafetyChecker.new(
+          repository_client: @repository_client,
+          config: safety_config
+        )
         @state_store = StateStore.new(project_dir: project_dir, repository: "#{owner}/#{repo}")
         @plan_processor = PlanProcessor.new(
           repository_client: @repository_client,
@@ -41,6 +47,9 @@ module Aidp
       end
 
       def start
+        # Validate safety requirements before starting
+        @safety_checker.validate_watch_mode_safety!(force: @force)
+
         display_message("👀 Watch mode enabled for #{@repository_client.full_repo}", type: :highlight)
         display_message("Polling every #{@interval} seconds. Press Ctrl+C to stop.", type: :muted)
 
@@ -51,6 +60,9 @@ module Aidp
         end
       rescue Interrupt
         display_message("\n⏹️  Watch mode interrupted by user", type: :warning)
+      rescue RepositorySafetyChecker::UnsafeRepositoryError => e
+        display_message("\n#{e.message}", type: :error)
+        raise
       end
 
       private
@@ -66,7 +78,13 @@ module Aidp
           next unless issue_has_label?(issue, PlanProcessor::PLAN_LABEL)
 
           detailed = @repository_client.fetch_issue(issue[:number])
+
+          # Check author authorization before processing
+          next unless @safety_checker.should_process_issue?(detailed, enforce: false)
+
           @plan_processor.process(detailed)
+        rescue RepositorySafetyChecker::UnauthorizedAuthorError => e
+          Aidp.log_warn("watch_runner", "unauthorized issue author", issue: issue[:number], error: e.message)
         end
       end
 
@@ -79,7 +97,13 @@ module Aidp
           next if status["status"] == "completed"
 
           detailed = @repository_client.fetch_issue(issue[:number])
+
+          # Check author authorization before processing
+          next unless @safety_checker.should_process_issue?(detailed, enforce: false)
+
           @build_processor.process(detailed)
+        rescue RepositorySafetyChecker::UnauthorizedAuthorError => e
+          Aidp.log_warn("watch_runner", "unauthorized issue author", issue: issue[:number], error: e.message)
         end
       end
 

data/lib/aidp/workflows/guided_agent.rb

@@ -236,18 +236,28 @@ module Aidp
           result
         rescue => e
           message = e.message.to_s
+
+          # Classify error type for better handling
           classified = if message =~ /resource[_ ]exhausted/i || message =~ /\[resource_exhausted\]/i
             "resource_exhausted"
           elsif message =~ /quota[_ ]exceeded/i || message =~ /\[quota_exceeded\]/i
             "quota_exceeded"
+          elsif /empty response/i.match?(message)
+            "empty_response"
+          else
+            "provider_error"
           end
 
-          if classified && attempts < max_attempts
-            display_message("⚠️  Provider '#{provider_name}' #{classified.tr("_", " ")} – attempting fallback...", type: :warning)
+          # Attempt fallback if we haven't exhausted all providers
+          if attempts < max_attempts
+            display_message("⚠️  Provider '#{provider_name}' failed (#{classified.tr("_", " ")}) – attempting fallback...", type: :warning)
+
             if @provider_manager.respond_to?(:switch_provider_for_error)
+              # Try to switch to fallback provider
               switched = @provider_manager.switch_provider_for_error(classified, stderr: message)
+
               if switched && switched != provider_name
-                display_message("↩️  Switched to provider '#{switched}'", type: :info)
+                display_message("↩️  Switched to provider '#{switched}' – retrying with same prompt", type: :info)
                 retry
               elsif switched == provider_name
                 # ProviderManager could not advance; mark current as rate limited to encourage next attempt to move on.
@@ -256,13 +266,18 @@ module Aidp
                   @provider_manager.mark_rate_limited(provider_name)
                   next_provider = @provider_manager.switch_provider("rate_limit_forced", previous_error: message)
                   if next_provider && next_provider != provider_name
-                    display_message("↩️  Switched to provider '#{next_provider}' (forced)", type: :info)
+                    display_message("↩️  Switched to provider '#{next_provider}' (forced) – retrying with same prompt", type: :info)
                     retry
                   end
                 end
               end
             end
           end
+
+          # If we get here, either we've exhausted all attempts or couldn't switch providers
+          if attempts >= max_attempts
+            display_message("❌ All providers exhausted after #{attempts} attempts", type: :error)
+          end
           raise
         end
       end

data/templates/planning/generate_llm_style_guide.md

@@ -1,6 +1,6 @@
 # Generate LLM Style Guide
 
-Your task is to create a project-specific **LLM_STYLE_GUIDE.md** that will be used by AI agents working on this project. This guide should be concise, actionable, and tailored to this specific codebase.
+Your task is to create a project-specific **LLM_STYLE_GUIDE.md** and **STYLE_GUIDE.md** that will be used by AI agents working on this project. The LLM guide should be concise and actionable, while the full guide provides detailed context and rationale.
 
 ## Context
 
@@ -13,9 +13,27 @@ You have access to the project directory. Examine the codebase to understand:
 - Project structure
 - Dependencies and frameworks
 
-## Requirements
+## Two-Guide Approach
 
-Create a file at `docs/LLM_STYLE_GUIDE.md` with the following sections:
+Create **TWO** complementary guides:
+
+### 1. STYLE_GUIDE.md (Detailed Reference)
+
+- Comprehensive explanations with examples
+- Rationale and context for each guideline
+- Deep dives into patterns and anti-patterns
+- Located at `docs/STYLE_GUIDE.md`
+
+### 2. LLM_STYLE_GUIDE.md (Quick Reference)
+
+- Ultra-concise bullet points for quick scanning
+- Each guideline references back to STYLE_GUIDE.md with line numbers
+- Format: `Guideline text. STYLE_GUIDE:start-end`
+- Located at `docs/LLM_STYLE_GUIDE.md`
+
+## Requirements for LLM_STYLE_GUIDE.md
+
+Create a file at `docs/LLM_STYLE_GUIDE.md` with the following sections, **adding line number references to the detailed guide**:
 
 ### 1. Core Engineering Rules
 
@@ -88,32 +106,97 @@ Create a file at `docs/LLM_STYLE_GUIDE.md` with the following sections:
 
 ## Output Format
 
-The LLM_STYLE_GUIDE.md should be:
+### STYLE_GUIDE.md Format
+
+The detailed guide should be:
+
+- **Comprehensive**: Full explanations with context and rationale
+- **Example-driven**: Show code examples for each pattern
+- **Well-structured**: Clear section headers that can be referenced by line number
+- **Numbered sections**: Use consistent heading levels for easy reference
+
+### LLM_STYLE_GUIDE.md Format
+
+The concise guide should be:
 
 - **Concise**: Use bullet points and tables where possible
+- **Cross-referenced**: Every guideline includes `STYLE_GUIDE:start-end` reference
 - **Specific**: Reference actual code patterns from this project
 - **Actionable**: Provide clear do's and don'ts
 - **Scannable**: Use headers, lists, and formatting for easy reference
 
+## Creating Cross-References
+
+### Step 1: Write STYLE_GUIDE.md first
+
+```markdown
+## Code Organization      # Line 18
+
+### Class Structure       # Line 20
+...detailed explanation...
+
+### File Organization     # Line 45
+...detailed explanation...
+```
+
+### Step 2: Add references to LLM_STYLE_GUIDE.md
+
+For each guideline in the LLM guide, add the line range from STYLE_GUIDE.md:
+
+```markdown
+## 1. Core Engineering Rules
+
+- Small objects, clear roles. Avoid god classes. `STYLE_GUIDE:18-50`
+- Methods: do one thing; extract early. `STYLE_GUIDE:108-117`
+```
+
+### Step 3: Verify line numbers
+
+Use `grep -n "^##" docs/STYLE_GUIDE.md` to find section headers and their line numbers.
+
 ## Example Structure
 
+### STYLE_GUIDE.md
+
+```markdown
+# Project Style Guide
+
+## Code Organization
+
+Detailed explanation of code organization principles...
+
+### Single Responsibility Principle
+
+Detailed explanation with examples...
+
+## Testing Guidelines
+
+Comprehensive testing approach...
+```
+
+### LLM_STYLE_GUIDE.md
+
 ```markdown
-# Project LLM Style Guide
+# Project LLM Style Cheat Sheet
 
-> Concise rules for AI agents working on [Project Name]. Based on [Language/Framework].
+> Ultra-concise rules for automated coding agents.
 
 ## 1. Core Engineering Rules
-- [Specific rule based on this project]
-- [Another specific rule]
 
-## 2. Naming & Structure
-- Classes: [convention]
-- Files: [convention]
-- [etc.]
+- Small objects, clear roles. `STYLE_GUIDE:18-50`
+- Methods: do one thing; extract early. `STYLE_GUIDE:108-117`
+
+## 2. Testing Contracts
 
-[Continue with all sections...]
+- Test public behavior only. `STYLE_GUIDE:1022-1261`
+- Mock external boundaries only. `STYLE_GUIDE:1022-1261`
 ```
 
 ## Deliverable
 
-Create `docs/LLM_STYLE_GUIDE.md` with all the sections above, tailored specifically to this project's codebase, languages, and frameworks.
+Create **BOTH** files:
+
+1. `docs/STYLE_GUIDE.md` - Comprehensive guide with detailed explanations
+2. `docs/LLM_STYLE_GUIDE.md` - Quick reference with line number cross-references to the detailed guide
+
+The guides should work together: AI agents read the concise LLM guide for quick decisions, then reference the detailed STYLE_GUIDE for context and examples when needed.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aidp
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Bart Agapinan
@@ -379,6 +379,7 @@ files:
 - lib/aidp/watch/plan_generator.rb
 - lib/aidp/watch/plan_processor.rb
 - lib/aidp/watch/repository_client.rb
+- lib/aidp/watch/repository_safety_checker.rb
 - lib/aidp/watch/runner.rb
 - lib/aidp/watch/state_store.rb
 - lib/aidp/workflows/definitions.rb