ace-coworker 0.6.0

data/lib/ace/coworker/atoms/brief_formatter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Atoms
+      # Renders the executor brief (table or json). Pure formatting.
+      class BriefFormatter
+        def self.format_table(brief)
+          h = brief.to_h
+          lines = []
+          lines << "Coworker brief"
+          lines << "  role:              #{h['role']}"
+          lines << "  instructions:      #{h['instructions']}"
+          lines << "  instructions src:  #{h['instructions_source']}"
+          lines << "  start prompt:      #{h['start_prompt']}"
+          lines << "  task:              #{h['task']} (#{h['task_path']})"
+          lines << "  assignment:        drive with --assignment #{h['assignment']}"
+          lines << "  assignment state:  #{h['assignment_state']} (#{h['assignment_progress']})"
+          lines << "  overseer:          #{h['overseer']} (channel: #{h['reporting_channel']})"
+          lines << "  on failure:        #{h['on_failure']}"
+          lines << "  report with:      ace-coworker report --assignment #{h['assignment']}"
+          lines << "  project root:      #{h['project_root']}"
+          lines.join("\n")
+        end
+
+        def self.format_json(brief)
+          require "json"
+          JSON.pretty_generate(brief.to_h)
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/atoms/config_schema.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Atoms
+      # Pure validation of a raw coworker config hash.
+      #
+      # Produces field-specific errors; no IO, no guesses, no defaults
+      # beyond the documented ones (reporting.channel, errors.on_failure).
+      class ConfigSchema
+        REQUIRED_FIELDS = %w[role instructions task assignment overseer].freeze
+        PROTOCOL_PREFIXES = %w[wfi:// prompt:// tmpl://].freeze
+        CHANNELS = %w[hitl].freeze
+        ON_FAILURE = %w[report stop].freeze
+
+        # @param raw [Hash, nil] parsed config hash
+        # @return [Array<String>] field-specific error messages (empty when valid)
+        def self.errors(raw)
+          return ["config is empty"] if raw.nil? || (!raw.is_a?(Hash) && raw.to_s.strip.empty?)
+          return ["config must be a mapping, got #{raw.class}"] unless raw.is_a?(Hash)
+
+          errors = []
+          REQUIRED_FIELDS.each do |field|
+            value = raw[field]
+            if value.nil? || value.to_s.strip.empty?
+              errors << "missing required field '#{field}'"
+            end
+          end
+
+          errors.concat(prompt_errors(raw))
+          errors.concat(nested_mapping_errors(raw, "reporting"))
+          errors.concat(nested_mapping_errors(raw, "errors"))
+          errors.concat(reporting_errors(raw))
+          errors.concat(error_rules_errors(raw))
+          errors
+        end
+
+        # @param raw [Hash] validated config hash
+        # @return [Hash] normalized hash with defaults applied.
+        #   start_prompt stays literal; the start_prompt_file CONTENT is read
+        #   by the loader (IO does not belong in this pure atom).
+        def self.normalize(raw)
+          {
+            "role" => str(raw["role"]),
+            "instructions" => str(raw["instructions"]),
+            "start_prompt" => str(raw["start_prompt"]),
+            "start_prompt_file" => str(raw["start_prompt_file"]),
+            "task" => str(raw["task"]),
+            "assignment" => str(raw["assignment"]),
+            "overseer" => str(raw["overseer"]),
+            "reporting" => {"channel" => nested_str(raw, "reporting", "channel").empty? ? "hitl" : nested_str(raw, "reporting", "channel")},
+            "errors" => {"on_failure" => nested_str(raw, "errors", "on_failure").empty? ? "report" : nested_str(raw, "errors", "on_failure")}
+          }
+        end
+
+        # Protocol instructions reference an external resource; plain paths
+        # are files resolved against the project root.
+        def self.protocol?(instructions)
+          PROTOCOL_PREFIXES.any? { |prefix| instructions.to_s.start_with?(prefix) }
+        end
+
+        def self.errors_for_field(raw, field)
+          errors(raw).select { |e| e.include?("'#{field}'") }
+        end
+
+        def self.prompt_errors(raw)
+          prompt = str(raw["start_prompt"])
+          prompt_file = str(raw["start_prompt_file"])
+          if prompt.empty? && prompt_file.empty?
+            ["missing required field 'start_prompt' (or 'start_prompt_file')"]
+          elsif !prompt.empty? && !prompt_file.empty?
+            ["'start_prompt' and 'start_prompt_file' are mutually exclusive"]
+          else
+            []
+          end
+        end
+        private_class_method :prompt_errors
+
+        def self.reporting_errors(raw)
+          channel = nested_str(raw, "reporting", "channel")
+          return [] if channel.empty?
+
+          CHANNELS.include?(channel) ? [] : ["reporting.channel '#{channel}' is not one of: #{CHANNELS.join(', ')}"]
+        end
+        private_class_method :reporting_errors
+
+        def self.error_rules_errors(raw)
+          on_failure = nested_str(raw, "errors", "on_failure")
+          return [] if on_failure.empty?
+
+          ON_FAILURE.include?(on_failure) ? [] : ["errors.on_failure '#{on_failure}' is not one of: #{ON_FAILURE.join(', ')}"]
+        end
+        private_class_method :error_rules_errors
+
+        # Nested sections must be mappings (or absent); scalars such as
+        # `reporting: hitl` would raise TypeError in #dig.
+        def self.nested_mapping_errors(raw, section)
+          value = raw[section]
+          return [] if value.nil? || value.is_a?(Hash)
+
+          ["'#{section}' must be a mapping, got #{value.class}"]
+        end
+        private_class_method :nested_mapping_errors
+
+        # TypeError-safe nested string read for validated mappings.
+        def self.nested_str(raw, section, key)
+          value = raw[section]
+          return "" unless value.is_a?(Hash)
+
+          str(value[key])
+        end
+        private_class_method :nested_str
+
+        def self.str(value)
+          value.to_s.strip
+        end
+        private_class_method :str
+      end
+    end
+  end
+end

data/lib/ace/coworker/atoms/integration_gate.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Atoms
+      # Pure pre-merge integration gate (8xg.t.sbz.4.3 / contract): the
+      # integrator merges only a candidate whose (a) dependencies are
+      # integrated predecessors, (b) current head matches the reviewed
+      # head (no drift), (c) tests were executed and passed, and (d) a
+      # fresh independent review verdict accepts the EXACT candidate
+      # head. Any unknown or contradictory fact is a blocking reason -
+      # uncertainty must be verified against the real worktree/reports,
+      # never guessed or retried blind. Explicit :blocked outcome with
+      # reasons, never an exception. No IO, no writes, no merges: the
+      # gate decides readiness only; the role drives git/ace-git.
+      module IntegrationGate
+        ACCEPT_VERDICTS = %w[accept].freeze
+
+        # @param input [Hash] string-keyed facts:
+        #   "candidate_head" => String (current head of the candidate)
+        #   "review" => {"head" => String reviewed head, "verdict" => String}
+        #   "tests" => {"executed" => bool, "passed" => bool}
+        #   "dependencies" => {name => bool (integrated predecessor)}
+        # @return [Hash] {verdict: :ready | :blocked, reasons: [String],
+        #   failed_checks: [:dependencies|:candidate|:review|:tests|:input]}
+        def self.evaluate(input)
+          unless input.is_a?(Hash) && input.keys.all? { |k| k.is_a?(String) }
+            return {verdict: :blocked,
+                    reasons: ["gate input must be a Hash with string keys, got #{input.class}"],
+                    failed_checks: [:input]}
+          end
+
+          reasons = []
+          failed = []
+
+          candidate_head = str(input["candidate_head"])
+          if candidate_head.empty?
+            reasons << "candidate head unknown: verify the actual worktree head instead of guessing"
+            failed << :candidate
+          end
+
+          dependencies = hash(input["dependencies"])
+          unsatisfied = dependencies.reject { |_, integrated| integrated == true }
+          unless unsatisfied.empty?
+            reasons << "dependencies not integrated: #{unsatisfied.keys.sort.join(', ')}"
+            failed << :dependencies
+          end
+
+          review = hash(input["review"])
+          review_head = str(review["head"])
+          verdict = str(review["verdict"]).downcase
+          if review_head.empty?
+            reasons << "review evidence missing: no reviewed head recorded - the verdict covers no verifiable candidate"
+            failed << :review
+          elsif !candidate_head.empty? && review_head.downcase != candidate_head.downcase
+            reasons << "stale review: candidate #{candidate_head} is not the reviewed head #{review_head}"
+            failed << :review
+          end
+          unless ACCEPT_VERDICTS.include?(verdict)
+            reasons << "review verdict is '#{verdict.empty? ? 'unknown' : verdict}', not accept"
+            failed << :review
+          end
+
+          tests = hash(input["tests"])
+          unless tests["executed"] == true
+            reasons << "tests not executed: real executed-test evidence is required before merge"
+            failed << :tests
+          end
+          unless tests["passed"] == true
+            reasons << "tests not passing: executed tests failed or their outcome is unknown"
+            failed << :tests
+          end
+
+          {verdict: reasons.empty? ? :ready : :blocked,
+           reasons: reasons, failed_checks: failed.uniq}
+        end
+
+        class << self
+          private
+
+          def str(value)
+            value.to_s.strip
+          end
+
+          def hash(value)
+            value.is_a?(Hash) ? value : {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/atoms/outcome_planner.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Atoms
+      # Pure derivation of the reporting Outcome from an AssignmentSnapshot.
+      # ace-assign is the only truth: a success report requires a complete
+      # verdict; an error report requires a cause and never claims work done.
+      class OutcomePlanner
+        # @param snapshot [Models::AssignmentSnapshot]
+        # @param explicit_result [String, nil] --result flag
+        # @param message [String, nil] explicit cause
+        # @param step_evidence [String, nil] failed-step report content
+        # @param step_override [String, nil] explicit --step flag
+        # @return [Models::Outcome]
+        # @raise [Coworker::Error] on refused inputs (false success, missing cause)
+        def self.plan(snapshot, explicit_result: nil, message: nil, step_evidence: nil, step_override: nil)
+          if explicit_result && !%w[success error].include?(explicit_result)
+            raise Error, "invalid --result '#{explicit_result}': expected success or error"
+          end
+
+          complete = snapshot.completion_verdict == :complete
+          result = explicit_result || (complete ? "success" : "error")
+
+          if result == "success" && !complete
+            raise Error,
+              "assignment '#{snapshot.id}' is not complete: #{snapshot.incomplete_reasons.join('; ')}; refusing to record work done"
+          end
+
+          if result == "error"
+            return error_outcome(snapshot, message, step_evidence, step_override)
+          end
+
+          success_outcome(snapshot, step_override)
+        end
+
+        def self.success_outcome(snapshot, step_override)
+          step = if step_override
+            Models::Outcome::StepRef.new(number: step_override, name: step_name(snapshot, step_override))
+          else
+            last = snapshot.steps.last
+            Models::Outcome::StepRef.new(number: last&.number, name: last&.name)
+          end
+
+          Models::Outcome.new(result: "success", verdict: :complete, step: step,
+            unfinished_steps: [],
+            evidence: {"progress" => snapshot.progress})
+        end
+
+        def self.error_outcome(snapshot, message, step_evidence, step_override)
+          failed = snapshot.steps.reverse.find { |s| s.status == "failed" } ||
+            snapshot.steps.find { |s| s.status == "active" } ||
+            snapshot.steps.find { |s| s.status == "pending" } ||
+            snapshot.steps.last
+          step = if step_override
+            Models::Outcome::StepRef.new(number: step_override, name: step_name(snapshot, step_override))
+          else
+            Models::Outcome::StepRef.new(number: failed&.number, name: failed&.name)
+          end
+
+          cause = message.to_s.strip
+          cause = step_evidence.to_s.strip if cause.empty?
+          if cause.empty?
+            raise Error,
+              "error outcome for assignment '#{snapshot.id}' needs a cause: pass --message or provide a failed-step report"
+          end
+
+          unfinished = snapshot.steps.reject(&:done?).map { |s| "#{s.number} #{s.name} (#{s.status})" }
+          Models::Outcome.new(result: "error", verdict: :incomplete, cause: cause, step: step,
+            unfinished_steps: unfinished)
+        end
+
+        def self.step_name(snapshot, number)
+          snapshot.steps.find { |s| s.number.to_s == number.to_s }&.name
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/atoms/prepare_decision.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "ace/git/worktree/atoms/task_id_extractor"
+
+module Ace
+  module Coworker
+    module Atoms
+      # Pure disposition rules for the preparation decision procedure.
+      # Inputs are the structured hashes returned by the worktree owner
+      # (ace-git-worktree switch/create results); outputs are dispositions
+      # with reasons. No IO, no writes.
+      module PrepareDecision
+        # @param switch_result [Hash] WorktreeManager#switch result; with the
+        #   real owner, a worktree whose directory is missing never resolves
+        #   here (switch fails with a "directory does not exist" error).
+        # @param expected_task_id [String] id of the task being prepared
+        # @param stale_registration [Hash, nil] association-registered
+        #   worktree for the expected task whose directory is missing on
+        #   disk ({task_id:, worktree_path:, branch:}); recovered via prune
+        #   + recreate instead of a plain create
+        # @return [Hash] {disposition:, reason:, worktree_path:, branch:, task_id:}
+        #   disposition: :reuse | :conflict_mismatch | :stale_recovery | :miss
+        def self.from_switch(switch_result, expected_task_id:, stale_registration: nil)
+          if switch_result[:success]
+            task_id = switch_result[:task_id].to_s
+            base = {worktree_path: switch_result[:worktree_path],
+                    branch: switch_result[:branch], task_id: task_id}
+            if expected_ids(expected_task_id).include?(task_id)
+              base.merge(disposition: :reuse, reason: "worktree already prepared for this task")
+            else
+              base.merge(disposition: :conflict_mismatch,
+                reason: "resolved worktree belongs to task '#{task_id}', not '#{expected_task_id}'")
+            end
+          elsif stale_registration
+            {disposition: :stale_recovery,
+             reason: "worktree metadata resolves to a missing directory: #{stale_registration[:worktree_path]}",
+             worktree_path: stale_registration[:worktree_path],
+             branch: stale_registration[:branch],
+             task_id: stale_registration[:task_id]}
+          else
+            {disposition: :miss, reason: switch_result[:error].to_s,
+             worktree_path: nil, branch: nil, task_id: nil}
+          end
+        end
+
+        # ace-git-worktree stores the worktree association under the task's
+        # short id (e.g. "aaa") while ace-task resolves the full id
+        # ("8xh.t.aaa"); accept every recognized form of the expected id.
+        def self.expected_ids(expected_task_id)
+          full = expected_task_id.to_s
+          [full, Ace::Git::Worktree::Atoms::TaskIDExtractor.short_id(full),
+            Ace::Git::Worktree::Atoms::TaskIDExtractor.normalize(full)].compact.uniq
+        end
+
+        # @param create_result [Hash] WorktreeManager#create_task result
+        # @param occupied_directory [Boolean] whether the task's expected
+        #   worktree directory exists on disk (a foreign occupant when the
+        #   create failed)
+        # @return [Hash] {disposition:, reason:, worktree_path:, branch:}
+        #   disposition: :created | :recovered | :reuse | :conflict_mismatch | :error
+        def self.from_create(create_result, occupied_directory: false)
+          if create_result[:success]
+            disposition = create_result[:existing] ? :reuse : (create_result[:recovered] ? :recovered : :created)
+            return {disposition: disposition, reason: create_result[:message].to_s,
+                    worktree_path: create_result[:worktree_path], branch: create_result[:branch]}
+          end
+
+          disposition = occupied_directory ? :conflict_mismatch : :error
+          {disposition: disposition, reason: create_result[:error].to_s,
+           worktree_path: nil, branch: nil}
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/atoms/prompt_template.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Atoms
+      # Pure start-prompt template rendering. Substitutes the known
+      # placeholders from a context hash; unknown placeholders stay literal.
+      # No IO.
+      class PromptTemplate
+        PLACEHOLDERS = %w[task assignment role overseer].freeze
+        PLACEHOLDER_PATTERN = /\{\{(#{PLACEHOLDERS.map { |p| Regexp.escape(p) }.join('|')})\}\}/.freeze
+
+        # @param template [String] preset start_prompt with {{placeholders}}
+        # @param context [Hash{String => String}] commission identity values
+        # @return [String] rendered prompt
+        def self.render(template, context)
+          # Single pass over PLACEHOLDER_PATTERN: only known placeholders
+          # match, and substituted values are never re-expanded (a value
+          # shaped like a later placeholder stays literal). Block form: the
+          # replacement is treated literally, so values containing
+          # backslashes or gsub escape sequences (\1, \0, \&) interpolate
+          # verbatim.
+          template.to_s.gsub(PLACEHOLDER_PATTERN) { context.fetch(Regexp.last_match(1), "").to_s }.strip
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/atoms/report_record_formatter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Ace
+  module Coworker
+    module Atoms
+      # Pure rendering of the durable task-folder record markdown.
+      class ReportRecordFormatter
+        # @param outcome [Models::Outcome]
+        # @param cfg [Models::Config]
+        # @param extras [Hash] event_id:, delivery:, record_path:
+        # @return [String] markdown document
+        def self.format(outcome, cfg, event_id: nil, delivery: nil, record_path: nil)
+          lines = []
+          lines << "---"
+          lines << "task: #{cfg.task}"
+          lines << "assignment: #{cfg.assignment}"
+          lines << "result: #{outcome.result}"
+          lines << "verdict: #{outcome.verdict}"
+          lines << "event_id: #{event_id}" if event_id
+          # Delivery can carry free-form failure detail ("failed: <cause>");
+          # serialize the value so the frontmatter stays parseable YAML.
+          lines << "delivery: #{delivery.to_s.inspect}" if delivery
+          lines << "updated_at: #{Time.now.utc.iso8601}"
+          lines << "---"
+          lines << ""
+          lines << "# #{outcome.success? ? "Work done" : "Assignment failed"} - #{cfg.task}/#{cfg.assignment}"
+          lines << ""
+          if outcome.success?
+            lines << "Assignment completed (#{outcome.evidence["progress"]})."
+          else
+            lines << "## Cause"
+            lines << ""
+            lines << outcome.cause
+            lines << ""
+            lines << "## Unfinished steps"
+            lines << ""
+            if outcome.unfinished_steps.empty?
+              lines << "- (none recorded)"
+            else
+              outcome.unfinished_steps.each { |step| lines << "- #{step}" }
+            end
+          end
+          lines << ""
+          lines << "## Evidence"
+          lines << ""
+          lines << "- record: #{record_path}" if record_path
+          lines << "- reports: .ace-local/assign/#{cfg.assignment}/reports/"
+          lines << "- event: .ace-local/hitl/ (#{event_id})" if event_id
+          lines << ""
+          lines << "## Delivery"
+          lines << ""
+          lines << (delivery ? "- #{delivery}" : "- (not attempted)")
+          lines.join("\n") + "\n"
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/atoms/resume_brief_formatter.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Atoms
+      # Pure rendering of a ResumePlan (table format). The brief is the
+      # guidance the next role or tool reads to continue safely.
+      class ResumeBriefFormatter
+        # @param plan [Models::ResumePlan]
+        # @param result [Organisms::ResumeOrchestrator::ResumeResult, nil]
+        # @return [String]
+        def self.format_table(plan, result = nil)
+          lines = ["Coworker resume"]
+          if plan.disposition == :report
+            lines << "  assignment complete; report delivery missing"
+            if plan.redeliver_event_id
+              lines << "  resend event:      #{plan.redeliver_event_id} (same ID; retrying delivery never retries the assignment)"
+            end
+            lines << "  #{result.message}" if result.message
+            return lines.join("\n")
+          end
+
+          if plan.disposition == :complete
+            lines << "  assignment complete and delivered; nothing to resume"
+            return lines.join("\n")
+          end
+
+          lines.concat(identity_lines(plan))
+          lines.concat(preserved_lines(plan))
+          lines.concat(remaining_lines(plan))
+          lines.concat(in_flight_lines(plan))
+          lines.concat(local_changes_lines(plan))
+          lines.concat(effect_caution_lines(plan))
+          lines.join("\n")
+        end
+
+        def self.identity_lines(plan)
+          branch = plan.git["branch"] || "(detached)"
+          ["  branch:            #{branch}"]
+        end
+
+        def self.preserved_lines(plan)
+          return [] if plan.preserved_steps.empty?
+
+          ["  preserved steps:"] + plan.preserved_steps.map { |s| "    done: #{s}" }
+        end
+
+        def self.remaining_lines(plan)
+          return [] if plan.remaining_steps.empty?
+
+          ["  remaining work:"] + plan.remaining_steps.map { |s| "    #{s}" }
+        end
+
+        def self.in_flight_lines(plan)
+          return [] unless plan.in_flight
+
+          step = plan.in_flight
+          lines = ["  in-flight step:    #{step["number"]} #{step["name"]} (#{step["status"]})"]
+          lines << "    recorded cause:  #{plan.in_flight_cause}" if plan.in_flight_cause
+          lines << "    step report:     #{plan.step_report_path}" if plan.step_report_path
+          lines << "    verify the effect from the current files/Git state and the step's own report before repeating it; do not reset local changes"
+          lines
+        end
+
+        def self.local_changes_lines(plan)
+          dirty = plan.git["dirty_entries"] || []
+          return [] if dirty.empty?
+
+          ["  local changes (preserved, never reset):"] + dirty.map { |entry| "    #{entry}" }
+        end
+
+        def self.effect_caution_lines(plan)
+          return [] if plan.effect_caution_steps.empty?
+
+          ["  effect caution:    uncertain external effect (merge/publish/deploy/release/push)?"] +
+            plan.effect_caution_steps.map { |s| "    step: #{s}" } +
+            ["    check the actual state with existing tools (e.g. ace-git status, PR evidence) or report a blocker;",
+             "    never replay blindly; same task, assignment and worktree"]
+          # never replay blindly; same task, assignment and worktree
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/atoms/resume_planner.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Atoms
+      # Pure derivation of the resume plan: ace-assign is the only step
+      # truth, the worktree git state is the only change truth, and the
+      # report helper state decides create-vs-resend. Never plans a new
+      # task/assignment/worktree and never plans resetting local changes.
+      class ResumePlanner
+        EFFECT_PATTERN = /merge|publish|deploy|release|push/i.freeze
+
+        # @param snapshot [Models::AssignmentSnapshot]
+        # @param report_state [Hash, nil] .ace-local/coworker/reports/<id>.json
+        # @param git_state [Hash] branch/ahead_behind/dirty_entries/last_commit
+        # @param step_cause [String, nil] recorded error of the in-flight step
+        # @param step_report_path [String, nil] report file of the in-flight step
+        # @return [Models::ResumePlan]
+        def self.plan(snapshot:, report_state: nil, git_state: {},
+          step_cause: nil, step_report_path: nil)
+          if snapshot.completion_verdict == :complete
+            return complete_plan(report_state, git_state)
+          end
+
+          continue_plan(snapshot, report_state, git_state,
+            step_cause: step_cause, step_report_path: step_report_path)
+        end
+
+        # Only a DELIVERED SUCCESS report matches a completed assignment:
+        # a delivered error report describes an outcome the assignment has
+        # since left behind, so resume must still report the success.
+        def self.complete_plan(report_state, git_state)
+          delivered = report_state.is_a?(Hash) &&
+            report_state["result"] == "success" &&
+            report_state["delivery"].to_s.start_with?("delivered")
+          if delivered
+            Models::ResumePlan.new(disposition: :complete, git: git_state)
+          else
+            Models::ResumePlan.new(disposition: :report, git: git_state,
+              redeliver_event_id: report_state.is_a?(Hash) ? report_state["event_id"] : nil)
+          end
+        end
+
+        # Single source of truth for the in-flight step: last active, else
+        # last failed, else first remaining. The orchestrator uses this to
+        # decide whose evidence to read; the planner renders the same step.
+        def self.in_flight_step(snapshot)
+          remaining = snapshot.steps.reject(&:done?)
+          remaining.reverse.find { |s| s.status == "active" } ||
+            remaining.reverse.find { |s| s.status == "failed" } ||
+            remaining.first
+        end
+
+        def self.continue_plan(snapshot, report_state, git_state, step_cause:, step_report_path:)
+          preserved = snapshot.steps.select(&:done?).map { |s| "#{s.number} #{s.name}" }
+          remaining = snapshot.steps.reject(&:done?)
+          in_flight_step = in_flight_step(snapshot)
+
+          remaining_lines = remaining.map { |s| "#{s.number} #{s.name} (#{s.status})" }
+          caution = remaining_lines.select { |line| line.match?(EFFECT_PATTERN) }.uniq
+
+          Models::ResumePlan.new(disposition: :continue,
+            preserved_steps: preserved,
+            remaining_steps: remaining_lines,
+            in_flight: in_flight_step && {
+              "number" => in_flight_step.number, "name" => in_flight_step.name,
+              "status" => in_flight_step.status
+            },
+            in_flight_cause: step_cause,
+            step_report_path: step_report_path,
+            effect_caution_steps: caution,
+            git: git_state,
+            redeliver_event_id: report_state.is_a?(Hash) ? report_state["event_id"] : nil)
+        end
+      end
+    end
+  end
+end