aidp 0.43.0 → 0.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 013dc044889cc320404776d0691d2091f3cddda0d9ba854dc0afb92312396336
-  data.tar.gz: bb1c57bf8e7d87dfa7d7b169d69646ac76c0cb14fe2f72c70ef02b8543b43494
+  metadata.gz: d898c7dea670e05503b8777e0907e0d0f975d398fd3cf80d9ddc659e8806070c
+  data.tar.gz: c25d8e50f56ce0e89f93c3e5fea9d4fb0ca6d540c19ac5fd3d2710d38be57290
 SHA512:
-  metadata.gz: c7ea760cd1d62424ada60f64acc356cdf4a82db6e2166c203d9d41c489fed936a704afaee17e9a20d588fbf0ead8ebd816a991a3fa01d87644939c872b104b12
-  data.tar.gz: 9c3b34d7474a2f9e899bf50d9b61d1edcb67a1b4a7b41d78abf810517db8cb2082fe889ec7b1fda5266276b6f1406e577644f2ddca16142bcf66e66e79b1e338
+  metadata.gz: ec307da67468acc15043f72c0295f443a7650a4312d1767f12629fbf582d02354a76cf2476081a313cb434c48eb63f5ec06d6d7d90f39d00d972342725d0dbe5
+  data.tar.gz: 7bbb9cbfff2543d753b56ca940c19745b0b4678d9e4825c418639c5ec2cbeeac99069de846e75e8c8ef05a8d83b825d13d7e99b056a462e07a89c1f56a2cb96a

data/lib/aidp/config.rb

@@ -197,7 +197,9 @@ module Aidp
         polling_interval: 30,
         labels: {
           plan_trigger: "aidp-plan",
+          project_trigger: "aidp-project",
           build_trigger: "aidp-build",
+          blocked_trigger: "aidp-blocked",
           review_trigger: "aidp-review",
           fix_ci_trigger: "aidp-fix-ci",
           change_request_trigger: "aidp-request-changes",

data/lib/aidp/setup/wizard.rb

@@ -1649,6 +1649,11 @@ module Aidp
           existing[:plan_trigger] || "aidp-plan"
         )
 
+        project_trigger = ask_with_default(
+          "Label to trigger project planning",
+          existing[:project_trigger] || "aidp-project"
+        )
+
         needs_input = ask_with_default(
           "Label for plans needing user input",
           existing[:needs_input] || "aidp-needs-input"
@@ -1664,6 +1669,11 @@ module Aidp
           existing[:build_trigger] || "aidp-build"
         )
 
+        blocked_trigger = ask_with_default(
+          "Label for blocked project sub-issues",
+          existing[:blocked_trigger] || "aidp-blocked"
+        )
+
         review_trigger = ask_with_default(
           "Label to trigger code review",
           existing[:review_trigger] || "aidp-review"
@@ -1686,9 +1696,11 @@ module Aidp
 
         set(%i[watch labels], {
           plan_trigger: plan_trigger,
+          project_trigger: project_trigger,
           needs_input: needs_input,
           ready_to_build: ready_to_build,
           build_trigger: build_trigger,
+          blocked_trigger: blocked_trigger,
           review_trigger: review_trigger,
           ci_fix_trigger: ci_fix_trigger,
           auto_trigger: auto_trigger,
@@ -1856,9 +1868,11 @@ module Aidp
       def collect_required_labels(labels_config)
         default_colors = {
           plan_trigger: "0E8A16",        # Green
+          project_trigger: "0052CC",     # Deep blue
           needs_input: "D93F0B",         # Red
           ready_to_build: "0075CA",      # Blue
           build_trigger: "5319E7",       # Purple
+          blocked_trigger: "B60205",     # Dark red
           review_trigger: "FBCA04",      # Yellow
           ci_fix_trigger: "D93F0B",      # Red
           auto_trigger: "0C8BD6",        # Blue (distinct from build)

data/lib/aidp/version.rb

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

data/lib/aidp/watch/plan_generator.rb

@@ -27,7 +27,7 @@ module Aidp
       PROMPT
 
       HIERARCHICAL_PROVIDER_PROMPT = <<~PROMPT
-        You are AIDP's planning specialist for large projects. Read the GitHub issue and existing comments.
+        You are AIDP's project planning specialist for large projects. Read the GitHub issue and existing comments.
         This is a LARGE project that should be broken down into independent sub-issues.
 
         Analyze the requirements and break them into logical sub-tasks that can be worked on independently.
@@ -59,6 +59,7 @@ module Aidp
         - Sub-issues should be sized for 1-3 days of work
         - Include 3-8 sub-issues for a large project
         - Be specific about skills needed (avoid generic terms)
+        - Prefer leaf-node tasks first so dependency order is explicit and mechanically executable
         - Only create sub-issues if the project truly warrants it (complexity, multiple components, etc.)
       PROMPT
 

data/lib/aidp/watch/plan_processor.rb

@@ -4,6 +4,8 @@ require_relative "../message_display"
 require_relative "plan_generator"
 require_relative "state_store"
 require_relative "feedback_collector"
+require_relative "projects_processor"
+require_relative "sub_issue_creator"
 
 module Aidp
   module Watch
@@ -12,39 +14,48 @@ module Aidp
     class PlanProcessor
       include Aidp::MessageDisplay
 
+      TrackedSubIssuesRetirementError = Class.new(StandardError)
+
       # Default label names
       DEFAULT_PLAN_LABEL = "aidp-plan"
+      DEFAULT_PROJECT_LABEL = "aidp-project"
       DEFAULT_NEEDS_INPUT_LABEL = "aidp-needs-input"
       DEFAULT_READY_LABEL = "aidp-ready"
       DEFAULT_BUILD_LABEL = "aidp-build"
+      DEFAULT_BLOCKED_LABEL = "aidp-blocked"
 
       COMMENT_HEADER = "## 🤖 AIDP Plan Proposal"
 
-      attr_reader :plan_label, :needs_input_label, :ready_label, :build_label
+      attr_reader :plan_label, :project_label, :needs_input_label, :ready_label, :build_label, :blocked_label
 
-      def initialize(repository_client:, state_store:, plan_generator:, label_config: {})
+      def initialize(repository_client:, state_store:, plan_generator:, label_config: {}, project_config: {})
         @repository_client = repository_client
         @state_store = state_store
         @plan_generator = plan_generator
+        @project_config = project_config
 
         # Load label configuration with defaults
         @plan_label = label_config[:plan_trigger] || label_config["plan_trigger"] || DEFAULT_PLAN_LABEL
+        @project_label = label_config[:project_trigger] || label_config["project_trigger"] || DEFAULT_PROJECT_LABEL
         @needs_input_label = label_config[:needs_input] || label_config["needs_input"] || DEFAULT_NEEDS_INPUT_LABEL
         @ready_label = label_config[:ready_to_build] || label_config["ready_to_build"] || DEFAULT_READY_LABEL
         @build_label = label_config[:build_trigger] || label_config["build_trigger"] || DEFAULT_BUILD_LABEL
+        @blocked_label = label_config[:blocked_trigger] || label_config["blocked_trigger"] || DEFAULT_BLOCKED_LABEL
       end
 
-      def process(issue)
+      def process(issue, trigger_label: @plan_label)
         number = issue[:number]
         existing_plan = @state_store.plan_data(number)
+        project_mode = trigger_label.to_s.casecmp(@project_label).zero?
 
         if existing_plan
           display_message("🔄 Re-planning for issue ##{number} (iteration #{@state_store.plan_iteration_count(number) + 1})", type: :info)
         else
-          display_message("🧠 Generating plan for issue ##{number} (#{issue[:title]})", type: :info)
+          prefix = project_mode ? "🗂️  Generating project plan" : "🧠 Generating plan"
+          display_message("#{prefix} for issue ##{number} (#{issue[:title]})", type: :info)
         end
 
-        plan_data = @plan_generator.generate(issue)
+        plan_data = @plan_generator.generate(issue, hierarchical: project_mode)
 
         # If plan generation failed (all providers unavailable), silently skip
         unless plan_data
@@ -59,7 +70,13 @@ module Aidp
         # If updating existing plan, archive the previous content
         archived_content = existing_plan ? archive_previous_plan(number, existing_plan) : nil
 
-        comment_body = build_comment(issue: issue, plan: plan_data, label_actor: label_actor, archived_content: archived_content)
+        comment_body = build_comment(
+          issue: issue,
+          plan: plan_data,
+          project_mode: project_mode,
+          label_actor: label_actor,
+          archived_content: archived_content
+        )
         comment_body_with_feedback = FeedbackCollector.append_feedback_prompt(comment_body)
         comment_id = nil
 
@@ -91,8 +108,16 @@ module Aidp
         plan_data = plan_data.merge(comment_id: comment_id) if comment_id
         @state_store.record_plan(number, plan_data.merge(comment_body: comment_body, comment_hint: COMMENT_HEADER))
 
+        project_setup = project_mode ? process_project_plan(issue, plan_data) : {status: :not_applicable}
+
         # Update labels: remove plan trigger, add appropriate status label
-        update_labels_after_plan(number, plan_data)
+        update_labels_after_plan(
+          number,
+          plan_data,
+          trigger_label: trigger_label,
+          project_mode: project_mode,
+          project_setup: project_setup
+        )
       end
 
       private
@@ -122,28 +147,34 @@ module Aidp
         archived_parts.join("\n")
       end
 
-      def update_labels_after_plan(number, plan_data)
-        questions = Array(plan_data[:questions])
-        has_questions = questions.any? && !questions.all? { |q| q.to_s.strip.empty? }
-
-        # Determine which label to add based on whether there are questions
-        new_label = has_questions ? @needs_input_label : @ready_label
-        status_text = has_questions ? "needs input" : "ready to build"
+      def update_labels_after_plan(number, plan_data, trigger_label:, project_mode:, project_setup:)
+        new_label, status_text = next_label_for(
+          plan_data,
+          trigger_label: trigger_label,
+          project_mode: project_mode,
+          project_setup: project_setup
+        )
+        old_labels = labels_to_replace(trigger_label, project_mode: project_mode)
+
+        if old_labels == [new_label]
+          display_message("🏷️  Left label '#{trigger_label}' in place (#{status_text})", type: :info)
+          return
+        end
 
         begin
           @repository_client.replace_labels(
             number,
-            old_labels: [@plan_label],
+            old_labels: old_labels,
             new_labels: [new_label]
           )
-          display_message("🏷️  Updated labels: removed '#{@plan_label}', added '#{new_label}' (#{status_text})", type: :info)
+          display_message("🏷️  Updated labels: removed '#{trigger_label}', added '#{new_label}' (#{status_text})", type: :info)
         rescue => e
           display_message("⚠️  Failed to update labels for issue ##{number}: #{e.message}", type: :warn)
           # Don't fail the whole process if label update fails
         end
       end
 
-      def build_comment(issue:, plan:, label_actor: nil, archived_content: nil)
+      def build_comment(issue:, plan:, project_mode:, label_actor: nil, archived_content: nil)
         summary = plan[:summary].to_s.strip
         tasks = Array(plan[:tasks])
         questions = Array(plan[:questions])
@@ -187,7 +218,10 @@ module Aidp
 
         # Add instructions based on whether there are questions
         parts << if has_questions
-          "**Next Steps**: Please reply with answers to the questions above. Once resolved, remove the `#{@needs_input_label}` label and add the `#{@build_label}` label to begin implementation."
+          resume_label = project_mode ? @project_label : @build_label
+          "**Next Steps**: Please reply with answers to the questions above. Once resolved, remove the `#{@needs_input_label}` label and add the `#{resume_label}` label to continue."
+        elsif plan[:should_create_sub_issues]
+          "**Next Steps**: AIDP will create project sub-issues, place them on the active GitHub Project, and dispatch dependency-ready work with `#{@build_label}` while blocked work is held under `#{@blocked_label}`."
         else
           "**Next Steps**: This plan is ready for implementation. Add the `#{@build_label}` label to begin."
         end
@@ -195,6 +229,170 @@ module Aidp
         parts.join("\n")
       end
 
+      def process_project_plan(issue, plan_data)
+        return {status: :not_required} unless plan_data[:should_create_sub_issues]
+
+        sub_issues = Array(plan_data[:sub_issues])
+        if sub_issues.empty?
+          return record_project_setup_failure(issue[:number], "no sub-issues were generated for project planning")
+        end
+
+        project_id = resolve_project_id(issue)
+        return record_project_setup_failure(issue[:number], "unable to resolve a GitHub Project") unless project_id
+
+        projects_processor = ProjectsProcessor.new(
+          repository_client: @repository_client,
+          state_store: @state_store,
+          project_id: project_id,
+          config: @project_config
+        )
+        unless projects_processor.ensure_project_fields
+          return record_project_setup_failure(issue[:number], "unable to configure required GitHub Project fields")
+        end
+
+        creator = SubIssueCreator.new(
+          repository_client: @repository_client,
+          state_store: @state_store,
+          project_id: project_id,
+          build_label: @build_label,
+          blocked_label: @blocked_label
+        )
+        created_issues = existing_sub_issues_for(issue, sub_issues: sub_issues, creator: creator)
+        created_issues = creator.create_sub_issues(issue, sub_issues) if created_issues.empty?
+        if created_issues.empty?
+          return record_project_setup_failure(issue[:number], "unable to create project sub-issues")
+        end
+
+        unless sync_project_issue_statuses(issue[:number], created_issues, projects_processor)
+          return record_project_setup_failure(issue[:number], "unable to sync project issues to the GitHub Project")
+        end
+
+        @state_store.record_project_sync(issue[:number], setup_status: "ready", setup_error: nil, setup_failed_at: nil)
+        {status: :ready}
+      rescue SubIssueCreator::UnresolvedDependenciesError => e
+        Aidp.log_error("plan_processor", "project_sub_issue_dependency_resolution_failed",
+          issue: issue[:number], error: e.message)
+        record_project_setup_failure(issue[:number], e.message)
+      rescue TrackedSubIssuesRetirementError => e
+        Aidp.log_error("plan_processor", "project_sub_issue_retirement_failed",
+          issue: issue[:number], error: e.message)
+        record_project_setup_failure(issue[:number], e.message)
+      end
+
+      def resolve_project_id(issue)
+        configured_project_id = @project_config[:default_project_id] || @project_config["default_project_id"]
+        return configured_project_id if configured_project_id
+
+        saved_project_id = @state_store.project_sync_data(issue[:number])["project_id"]
+        return saved_project_id if saved_project_id
+
+        active_project = @repository_client.find_active_project
+        if active_project
+          @state_store.record_project_sync(
+            issue[:number],
+            project_id: active_project[:id],
+            project_url: active_project[:url],
+            project_title: active_project[:title]
+          )
+          display_message("📊 Reusing active GitHub Project '#{active_project[:title]}'", type: :info)
+          return active_project[:id]
+        end
+
+        title = "AIDP Project ##{issue[:number]}: #{issue[:title]}".slice(0, 100)
+        project = @repository_client.create_project(title: title)
+        @state_store.record_project_sync(issue[:number], project_id: project[:id], project_url: project[:url], project_title: project[:title])
+        display_message("📊 Created GitHub Project '#{project[:title]}'", type: :success)
+        project[:id]
+      rescue => e
+        Aidp.log_error("plan_processor", "project_resolution_failed", issue: issue[:number], error: e.message)
+        display_message("⚠️  Failed to resolve GitHub Project for issue ##{issue[:number]}: #{e.message}", type: :warn)
+        nil
+      end
+
+      def sync_project_issue_statuses(parent_number, created_issues, projects_processor)
+        return false unless projects_processor.sync_issue_to_project(parent_number, status: ProjectsProcessor::STATUS_VALUES[:blocked])
+
+        created_issues.each do |created_issue|
+          status = project_issue_status_for(created_issue)
+          return false unless projects_processor.sync_issue_to_project(created_issue[:number], status: status)
+        end
+
+        true
+      end
+
+      def existing_sub_issues_for(parent_issue, sub_issues:, creator:)
+        parent_number = parent_issue[:number]
+        existing_numbers = @state_store.sub_issues(parent_number)
+        return [] if existing_numbers.empty?
+
+        tracked_issues = existing_numbers.map { |number| fetch_tracked_sub_issue(number) }
+        preserved_issues, remaining_numbers, remaining_sub_issues = preserve_closed_tracked_sub_issues(tracked_issues, sub_issues)
+        preserved_numbers_by_title = issue_numbers_by_title(preserved_issues)
+
+        remaining_issues = if remaining_numbers.empty? && remaining_sub_issues.empty?
+          []
+        elsif reconciliable_sub_issues?(remaining_numbers, remaining_sub_issues)
+          display_message("🔁 Reusing #{existing_numbers.size} tracked sub-issues for ##{parent_number}", type: :info)
+          reconcile_existing_sub_issues(
+            parent_issue,
+            remaining_numbers,
+            remaining_sub_issues,
+            creator,
+            issue_numbers_by_title: preserved_numbers_by_title
+          )
+        else
+          regenerate_open_tracked_sub_issues(
+            parent_issue,
+            parent_number,
+            remaining_numbers,
+            remaining_sub_issues,
+            creator,
+            preserved_numbers_by_title: preserved_numbers_by_title
+          )
+        end
+
+        ordered_issues = order_tracked_sub_issues(sub_issues, preserved_issues + remaining_issues)
+        record_tracked_sub_issue_dependencies(ordered_issues, sub_issues)
+        @state_store.record_sub_issues(parent_number, ordered_issues.map { |tracked_issue| tracked_issue[:number] })
+        ordered_issues
+      end
+
+      def next_label_for(plan_data, trigger_label:, project_mode:, project_setup:)
+        questions = Array(plan_data[:questions])
+        has_questions = questions.any? && !questions.all? { |q| q.to_s.strip.empty? }
+
+        return [@needs_input_label, "needs input"] if has_questions
+        if project_mode && plan_data[:should_create_sub_issues]
+          return [@blocked_label, "project initialized"] if project_setup[:status] == :ready
+
+          return [@needs_input_label, "project setup failed: #{project_setup[:reason]}"]
+        end
+
+        [@ready_label, "ready to build"]
+      end
+
+      def labels_to_replace(trigger_label, project_mode:)
+        return [trigger_label] unless project_mode
+
+        [trigger_label, @plan_label, @build_label].uniq
+      end
+
+      def record_project_setup_failure(issue_number, reason)
+        @state_store.record_project_sync(
+          issue_number,
+          setup_status: "failed",
+          setup_error: reason,
+          setup_failed_at: Time.now.utc.iso8601
+        )
+        {status: :failed, reason: reason}
+      end
+
+      def project_issue_status_for(created_issue)
+        return ProjectsProcessor::STATUS_VALUES[:done] if created_issue[:state].to_s.casecmp("closed").zero?
+
+        created_issue[:dependencies].any? ? ProjectsProcessor::STATUS_VALUES[:blocked] : ProjectsProcessor::STATUS_VALUES[:todo]
+      end
+
       def format_bullets(items, placeholder:)
         if items.empty?
           placeholder
@@ -210,6 +408,262 @@ module Aidp
           items.each_with_index.map { |item, index| "#{index + 1}. #{item}" }.join("\n")
         end
       end
+
+      def reconciliable_sub_issues?(existing_numbers, sub_issues)
+        return false unless sub_issue_count_matches?(existing_numbers, sub_issues)
+        return true if tracked_sub_issues_match_plan?(existing_numbers, sub_issues)
+
+        display_message(
+          "⚠️  Tracked sub-issues no longer match the regenerated plan; regenerating them",
+          type: :warn
+        )
+        false
+      end
+
+      def sub_issue_count_matches?(existing_numbers, sub_issues)
+        return true if existing_numbers.size == sub_issues.size
+
+        display_message(
+          "⚠️  Tracked sub-issues no longer match the regenerated plan (#{existing_numbers.size} tracked, #{sub_issues.size} planned); regenerating them",
+          type: :warn
+        )
+        false
+      end
+
+      def tracked_sub_issues_match_plan?(existing_numbers, sub_issues)
+        tracked_issues = existing_numbers.map { |number| fetch_tracked_sub_issue(number) }
+
+        tracked_titles = tracked_issues.map { |tracked_issue| normalize_sub_issue_title(tracked_issue[:title]) }
+        planned_titles = sub_issues.map { |sub_issue| normalize_sub_issue_title(sub_issue[:title]) }
+
+        tracked_titles == planned_titles
+      rescue => e
+        Aidp.log_warn("plan_processor", "tracked_sub_issue_validation_failed",
+          error: e.message,
+          tracked_issue_numbers: existing_numbers)
+        false
+      end
+
+      def fetch_tracked_sub_issue(number)
+        @repository_client.fetch_issue(number)
+      end
+
+      def normalize_sub_issue_title(title)
+        title.to_s.strip.downcase
+      end
+
+      def preserve_closed_tracked_sub_issues(tracked_issues, sub_issues)
+        remaining_tracked_issues = tracked_issues.dup
+        remaining_sub_issues = sub_issues.dup
+        preserved_issues = []
+
+        tracked_issues.each do |tracked_issue|
+          next unless tracked_issue[:state].to_s.casecmp("closed").zero?
+
+          match_index = remaining_sub_issues.index do |sub_issue|
+            normalize_sub_issue_title(sub_issue[:title]) == normalize_sub_issue_title(tracked_issue[:title])
+          end
+          next unless match_index
+
+          preserved_issues << tracked_issue
+          remaining_tracked_issues.delete(tracked_issue)
+          remaining_sub_issues.delete_at(match_index)
+        end
+
+        return [preserved_issues, remaining_tracked_issues.map { |tracked_issue| tracked_issue[:number] }, remaining_sub_issues] if preserved_issues.empty?
+
+        suffix = if preserved_issues.one?
+          ""
+        else
+          "s"
+        end
+        display_message(
+          "🔒 Preserving #{preserved_issues.size} completed tracked sub-issue#{suffix} during re-plan",
+          type: :info
+        )
+        [preserved_issues, remaining_tracked_issues.map { |tracked_issue| tracked_issue[:number] }, remaining_sub_issues]
+      end
+
+      def reconcile_existing_sub_issues(parent_issue, existing_numbers, sub_issues, creator, issue_numbers_by_title: {})
+        tracked_issues = sub_issues.each_with_index.map do |sub_issue, index|
+          number = existing_numbers.fetch(index)
+          tracked_issue = @repository_client.fetch_issue(number)
+          planned_issue = creator.planned_sub_issue_attributes(parent_issue, sub_issue, index + 1)
+          update_tracked_sub_issue(number, tracked_issue, planned_issue) unless tracked_sub_issue_contract_matches?(tracked_issue, planned_issue)
+
+          {
+            number: number,
+            title: planned_issue[:title].to_s.strip,
+            dependencies: Array(sub_issue[:dependencies]),
+            state: tracked_issue[:state]
+          }
+        end
+
+        issue_numbers_by_title = build_issue_numbers_by_title(tracked_issues, issue_numbers_by_title)
+        tracked_issues.each do |tracked_issue|
+          dependencies, unresolved_dependencies = resolve_tracked_dependencies(
+            tracked_issue[:dependencies],
+            issue_numbers_by_title
+          )
+          if unresolved_dependencies.any?
+            raise SubIssueCreator::UnresolvedDependenciesError,
+              "Unable to resolve dependencies for sub-issue ##{tracked_issue[:number]} (#{tracked_issue[:title]}): #{unresolved_dependencies.join(", ")}"
+          end
+
+          @state_store.record_issue_dependencies(tracked_issue[:number], dependencies)
+          tracked_issue[:dependencies] = dependencies
+        end
+
+        tracked_issues
+      end
+
+      def regenerate_open_tracked_sub_issues(parent_issue, parent_number, existing_numbers, sub_issues, creator, preserved_numbers_by_title:)
+        retire_tracked_sub_issues(parent_number, existing_numbers)
+        return [] if sub_issues.empty?
+
+        creator.create_sub_issues(
+          parent_issue,
+          sub_issues_with_resolved_dependencies(sub_issues, preserved_numbers_by_title)
+        )
+      end
+
+      def order_tracked_sub_issues(sub_issues, tracked_issues)
+        tracked_issue_groups = tracked_issues.group_by { |tracked_issue| normalize_sub_issue_title(tracked_issue[:title]) }
+
+        sub_issues.map do |sub_issue|
+          normalized_title = normalize_sub_issue_title(sub_issue[:title])
+          issue_group = tracked_issue_groups[normalized_title]
+          next issue_group.shift if issue_group&.any?
+
+          raise SubIssueCreator::UnresolvedDependenciesError,
+            "Unable to match tracked sub-issue for planned item '#{sub_issue[:title]}'"
+        end
+      end
+
+      def record_tracked_sub_issue_dependencies(tracked_issues, sub_issues)
+        issue_numbers_by_title = build_issue_numbers_by_title(tracked_issues)
+
+        tracked_issues.zip(sub_issues).each do |tracked_issue, sub_issue|
+          dependencies, unresolved_dependencies = resolve_tracked_dependencies(
+            sub_issue[:dependencies],
+            issue_numbers_by_title
+          )
+          if unresolved_dependencies.any?
+            raise SubIssueCreator::UnresolvedDependenciesError,
+              "Unable to resolve dependencies for sub-issue ##{tracked_issue[:number]} (#{tracked_issue[:title]}): #{unresolved_dependencies.join(", ")}"
+          end
+
+          @state_store.record_issue_dependencies(tracked_issue[:number], dependencies)
+          tracked_issue[:dependencies] = dependencies
+        end
+      end
+
+      def sub_issues_with_resolved_dependencies(sub_issues, issue_numbers_by_title)
+        sub_issues.map do |sub_issue|
+          dependencies = Array(sub_issue[:dependencies]).map do |dependency|
+            issue_number = issue_numbers_by_title[normalize_sub_issue_title(dependency)]
+            issue_number ? "##{issue_number}" : dependency
+          end
+
+          sub_issue.merge(dependencies: dependencies)
+        end
+      end
+
+      def build_issue_numbers_by_title(tracked_issues, seed = {})
+        issue_numbers_by_title = seed.dup
+        duplicate_titles = duplicate_normalized_tracked_titles(tracked_issues)
+        if duplicate_titles.empty?
+          tracked_issues.each do |tracked_issue|
+            normalized_title = normalize_sub_issue_title(tracked_issue[:title])
+            next if normalized_title.empty?
+            next unless issue_numbers_by_title.key?(normalized_title) && issue_numbers_by_title[normalized_title] != tracked_issue[:number]
+
+            duplicate_titles << tracked_issue[:title].to_s.strip
+          end
+          if duplicate_titles.empty?
+            return tracked_issues.each_with_object(issue_numbers_by_title) do |tracked_issue, memo|
+              normalized_title = normalize_sub_issue_title(tracked_issue[:title])
+              memo[normalized_title] = tracked_issue[:number] unless normalized_title.empty?
+            end
+          end
+        end
+
+        raise SubIssueCreator::UnresolvedDependenciesError,
+          "Duplicate sub-issue titles after normalization are not allowed: #{duplicate_titles.join(", ")}"
+      end
+
+      def duplicate_normalized_tracked_titles(tracked_issues)
+        grouped_titles = tracked_issues.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |tracked_issue, memo|
+          normalized_title = normalize_sub_issue_title(tracked_issue[:title])
+          next if normalized_title.empty?
+
+          memo[normalized_title] << tracked_issue[:title].to_s.strip
+        end
+
+        grouped_titles.filter_map do |_normalized_title, titles|
+          next unless titles.size > 1
+
+          titles.uniq.join(" / ")
+        end
+      end
+
+      def issue_numbers_by_title(tracked_issues)
+        tracked_issues.each_with_object({}) do |tracked_issue, memo|
+          normalized_title = normalize_sub_issue_title(tracked_issue[:title])
+          memo[normalized_title] = tracked_issue[:number] unless normalized_title.empty?
+        end
+      end
+
+      def resolve_tracked_dependencies(dependencies, issue_numbers_by_title)
+        Array(dependencies).each_with_object([[], []]) do |dependency, (resolved, unresolved)|
+          text = dependency.to_s.strip
+          match = text.match(/\A#(\d+)\z/)
+          resolved_dependency = match ? match[1].to_i : issue_numbers_by_title[normalize_sub_issue_title(text)]
+          resolved_dependency ? resolved << resolved_dependency : unresolved << dependency
+        end
+      end
+
+      def tracked_sub_issue_contract_matches?(tracked_issue, planned_issue)
+        normalize_sub_issue_title(tracked_issue[:title]) == normalize_sub_issue_title(planned_issue[:title]) &&
+          tracked_issue[:body].to_s == planned_issue[:body] &&
+          normalized_list(tracked_issue[:labels]) == normalized_list(planned_issue[:labels]) &&
+          normalized_list(tracked_issue[:assignees]) == normalized_list(planned_issue[:assignees])
+      end
+
+      def update_tracked_sub_issue(number, tracked_issue, planned_issue)
+        Aidp.log_info("plan_processor", "tracked_sub_issue_updated",
+          issue: number,
+          title_changed: normalize_sub_issue_title(tracked_issue[:title]) != normalize_sub_issue_title(planned_issue[:title]),
+          body_changed: tracked_issue[:body].to_s != planned_issue[:body],
+          labels_changed: normalized_list(tracked_issue[:labels]) != normalized_list(planned_issue[:labels]),
+          assignees_changed: normalized_list(tracked_issue[:assignees]) != normalized_list(planned_issue[:assignees]))
+
+        @repository_client.update_issue(
+          number,
+          title: planned_issue[:title],
+          body: planned_issue[:body],
+          labels: planned_issue[:labels],
+          assignees: planned_issue[:assignees]
+        )
+      end
+
+      def normalized_list(values)
+        Array(values).map { |value| value.to_s.strip }.reject(&:empty?).sort
+      end
+
+      def retire_tracked_sub_issues(parent_number, existing_numbers)
+        display_message("🧹 Retiring #{existing_numbers.size} stale tracked sub-issues for ##{parent_number}", type: :warn)
+
+        existing_numbers.each do |number|
+          @repository_client.close_issue(number)
+        rescue => e
+          raise TrackedSubIssuesRetirementError,
+            "unable to retire stale tracked sub-issue ##{number}: #{e.message}"
+        end
+
+        @state_store.clear_sub_issues(parent_number)
+        []
+      end
     end
   end
 end