ace-coworker 0.6.0

data/lib/ace/coworker/cli/commands/resume.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Coworker
+    module CLI
+      module Commands
+        class Resume < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Assess interrupted work in this worktree and resume it"
+
+          option :config, desc: "Path to coworker config (default: .ace-local/coworker/config.yml)"
+          option :assignment, desc: "Assignment ID (default: config assignment)"
+          option :"dry-run", type: :boolean, desc: "Derive the resume plan without redelivering reports"
+          option :format, default: "table", desc: "Output format (table, json)"
+          option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
+          option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
+
+          def call(**options)
+            orchestrator = Organisms::ResumeOrchestrator.new
+            result = orchestrator.call(
+              config_path: options[:config],
+              assignment: options[:assignment],
+              dry_run: options[:"dry-run"] == true
+            )
+
+            # Render the plan first: on a delegated report failure the
+            # resume guidance still matters; then keep the non-zero exit.
+            unless options[:quiet]
+              if options[:format] == "json"
+                puts JSON.pretty_generate(to_h(result))
+              else
+                puts Atoms::ResumeBriefFormatter.format_table(result.plan, result)
+              end
+            end
+
+            if result.exit_code != 0
+              raise Ace::Support::Cli::Error, result.message
+            end
+          rescue Ace::Coworker::Error => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+
+          private
+
+          def to_h(result)
+            payload = result.plan.to_h
+            payload["message"] = result.message
+            payload
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/cli/commands/roles.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Coworker
+    module CLI
+      module Commands
+        class Roles < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "List the role preset catalog (gem defaults + project overrides)"
+
+          option :format, default: "table", desc: "Output format (table, json)"
+          option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
+          option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
+
+          def initialize(preset_loader: nil)
+            super()
+            @preset_loader = preset_loader
+          end
+
+          # Read-only catalog query; exit 0 for any valid catalog state (an
+          # empty catalog is a state, not an error). An invalid preset file
+          # surfaces as a CLI error (non-zero exit).
+          def call(**options)
+            loader = @preset_loader || begin
+              project_root = Molecules::ProjectRoot.new.resolve
+              Molecules::RolePresetLoader.new(project_root: project_root)
+            end
+            presets = loader.list
+
+            return if options[:quiet]
+
+            if options[:format] == "json"
+              puts JSON.pretty_generate("roles" => presets)
+            else
+              puts render_table(presets)
+            end
+          rescue Ace::Coworker::Error => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+
+          private
+
+          def render_table(presets)
+            return "Coworker roles: none found (gem .ace-defaults/coworker/roles/ and project .ace/coworker/roles/)" if presets.empty?
+
+            lines = ["Coworker roles:"]
+            presets.each do |preset|
+              lines << "  #{preset['name'].ljust(10)} #{preset['source'].ljust(8)} #{preset['description']}"
+              lines << "  #{" " * 10} instructions: #{preset['instructions']}"
+            end
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/cli/commands/rounds.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Coworker
+    module CLI
+      module Commands
+        class Rounds < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Record a review round for an assignment and print the 3/2/10 verdict"
+
+          example [
+            "record --assignment asg01 --type full --status completed",
+            "record --assignment asg01 --type full --status completed \\",
+            "       --confirmed f-1:high,f-2:low --resolved f-3",
+            "record --assignment asg01 --type delta --status aborted"
+          ]
+
+          argument :action, required: true, desc: "Subcommand (record)"
+
+          option :assignment, required: true, desc: "Assignment ID"
+          option :type, required: true, desc: "Round type (full, delta)"
+          option :status, required: true, desc: "Round status (completed, aborted)"
+          option :confirmed, type: :array, default: [], desc: "Confirmed findings as id:severity pairs (e.g. f-1:high)"
+          option :resolved, type: :array, default: [], desc: "Finding ids resolved by this round"
+          option :format, default: "table", desc: "Output format (table, json)"
+          option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
+          option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
+
+          def initialize(store: nil)
+            super()
+            @store = store
+          end
+
+          def call(action:, assignment:, type:, status:, confirmed: [], resolved: [],
+                   format: "table", **options)
+            raise Ace::Support::Cli::Error, "unknown subcommand '#{action}' (expected: record)" unless action == "record"
+
+            store = @store || begin
+              project_root = Molecules::ProjectRoot.new.resolve
+              Molecules::ReviewRoundStore.new(project_root: project_root)
+            end
+            verdict = store.record!(assignment, build_record(type, status, confirmed, resolved))
+
+            return if options[:quiet]
+
+            if format == "json"
+              puts JSON.pretty_generate(json_payload(assignment, verdict))
+            else
+              puts render(assignment, verdict)
+            end
+          rescue Ace::Coworker::Error => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+
+          private
+
+          def build_record(type, status, confirmed, resolved)
+            {
+              "type" => type,
+              "status" => status,
+              "confirmed" => Array(confirmed).map { |pair| parse_finding(pair) },
+              "resolved" => Array(resolved).map(&:to_s)
+            }
+          end
+
+          def parse_finding(pair)
+            id, severity = pair.to_s.split(":", 2)
+            {"id" => id.to_s, "severity" => severity.to_s}
+          end
+
+          def json_payload(assignment, verdict)
+            {
+              "assignment" => assignment,
+              "verdict" => verdict[:verdict].to_s,
+              "full_rounds" => verdict[:full_rounds],
+              "completed_full_rounds" => verdict[:completed_full_rounds],
+              "consecutive_clean" => verdict[:consecutive_clean],
+              "unresolved_high_critical" => verdict[:unresolved_high_critical]
+            }
+          end
+
+          def render(assignment, verdict)
+            lines = ["Coworker rounds record"]
+            lines << "  assignment:             #{assignment}"
+            lines << "  verdict:                #{verdict[:verdict]}"
+            lines << "  full rounds:            #{verdict[:full_rounds]}"
+            lines << "  completed full rounds:  #{verdict[:completed_full_rounds]}"
+            lines << "  consecutive clean:      #{verdict[:consecutive_clean]}"
+            lines << "  unresolved High/Critical: #{verdict[:unresolved_high_critical].join(', ')}"
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/cli/commands/start.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module CLI
+      module Commands
+        class Start < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Validate prepared run config and render the executor brief"
+
+          option :config, desc: "Path to coworker config (default: .ace-local/coworker/config.yml)"
+          option :format, default: "table", desc: "Output format (table, json)"
+          option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
+          option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
+
+          def initialize(orchestrator: nil)
+            super()
+            @orchestrator = orchestrator
+          end
+
+          def call(config: nil, format: "table", **options)
+            orchestrator = @orchestrator || Organisms::StartOrchestrator.new
+            brief = orchestrator.call(config_path: config)
+            return if options[:quiet]
+
+            if format == "json"
+              puts Atoms::BriefFormatter.format_json(brief)
+            else
+              puts Atoms::BriefFormatter.format_table(brief)
+            end
+          rescue Ace::Coworker::Error, StandardError => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/cli/commands/status.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Coworker
+    module CLI
+      module Commands
+        class Status < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Show readiness, identity, and assignment progress"
+
+          option :config, desc: "Path to coworker config (default: .ace-local/coworker/config.yml)"
+          option :assignment, desc: "Show status for a specific assignment ID (default: config assignment)"
+          option :format, default: "table", desc: "Output format (table, json)"
+          option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
+          option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
+
+          def initialize(orchestrator: nil)
+            super()
+            @orchestrator = orchestrator
+          end
+
+          def call(config: nil, assignment: nil, format: "table", **options)
+            orchestrator = @orchestrator || Organisms::StatusOrchestrator.new
+            result = orchestrator.call(config_path: config, assignment: assignment)
+            return if options[:quiet]
+
+            if format == "json"
+              puts JSON.pretty_generate(to_h(result))
+            else
+              puts render_table(result)
+            end
+          rescue Ace::Coworker::Error, StandardError => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+
+          private
+
+          def effective_assignment(result)
+            result.assignment || result.config.assignment
+          end
+
+          def to_h(result)
+            if result.is_a?(Organisms::StatusOrchestrator::NotReady)
+              {"ready" => false, "message" => result.message}
+            else
+              cfg = result.config
+              payload = {
+                "ready" => true,
+                "role" => cfg.role,
+                "task" => cfg.task,
+                "assignment" => effective_assignment(result),
+                "overseer" => cfg.overseer,
+                "on_failure" => cfg.on_failure
+              }
+              if result.snapshot
+                payload["assignment_status"] = result.snapshot.to_h
+              elsif result.probe_error
+                payload["assignment_error"] = result.probe_error
+              end
+              payload
+            end
+          end
+
+          def render_table(result)
+            if result.is_a?(Organisms::StatusOrchestrator::NotReady)
+              return result.message
+            end
+
+            cfg = result.config
+            lines = ["Coworker status"]
+            lines << "  role:        #{cfg.role}"
+            lines << "  task:        #{cfg.task}"
+            lines << "  assignment:  #{effective_assignment(result)}"
+            lines << "  overseer:    #{cfg.overseer}"
+            if result.snapshot
+              snapshot = result.snapshot
+              verdict = snapshot.completion_verdict == :complete ? "complete" : "incomplete"
+              lines << "  state:       #{snapshot.state} (#{snapshot.progress}) — #{verdict}"
+              unless verdict == "complete"
+                reasons = snapshot.incomplete_reasons
+                lines.concat(reasons.map { |r| "    remaining: #{r}" })
+              end
+            elsif result.probe_error
+              lines << "  assignment error: #{result.probe_error}"
+            end
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/cli.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "cli/commands/start"
+require_relative "cli/commands/status"
+require_relative "cli/commands/report"
+require_relative "cli/commands/resume"
+require_relative "cli/commands/prepare"
+require_relative "cli/commands/commission"
+require_relative "cli/commands/roles"
+require_relative "cli/commands/rounds"
+require_relative "cli/commands/gate"
+
+module Ace
+  module Coworker
+    module CLI
+      extend Ace::Support::Cli::RegistryDsl
+
+      PROGRAM_NAME = "ace-coworker"
+
+      REGISTERED_COMMANDS = [
+        ["start", "Validate prepared run config and render the executor brief"],
+        ["status", "Show readiness, identity, and assignment progress"],
+        ["report", "Record the assignment outcome and report it through ace-hitl"],
+        ["resume", "Assess interrupted work in this worktree and resume it"],
+        ["prepare", "Accept a preparation commission and ensure the task worktree"],
+        ["commission", "Instantiate a role preset into the coworker run config"],
+        ["roles", "List the role preset catalog (gem defaults + project overrides)"],
+        ["rounds", "Record a review round for an assignment and print the 3/2/10 verdict"],
+        ["gate", "Evaluate the pre-merge integration gate (:ready | :blocked with reasons)"]
+      ].freeze
+
+      HELP_EXAMPLES = [
+        "ace-coworker start                    # Read .ace-local/coworker/config.yml",
+        "ace-coworker start --config PATH      # Use an explicit config",
+        "ace-coworker status --format json     # Readiness + assignment verdict",
+        "ace-coworker report                   # Record outcome + HITL report",
+        "ace-coworker report --result error --message 'cause'",
+        "ace-coworker resume                   # Resume interrupted work",
+        "ace-coworker resume --dry-run         # Plan only, no redelivery",
+        "ace-coworker prepare --task 148 --roles worker,reviewer",
+        "ace-coworker prepare --task 148 --roles worker --dry-run",
+        "ace-coworker roles                        # List role presets",
+        "ace-coworker commission --role worker --task 148 --assignment abc123 \\",
+        "                    --overseer overseer@lab",
+        "ace-coworker rounds record --assignment abc123 --type full --status completed",
+        "ace-coworker rounds record --assignment abc123 --type full --status completed \\",
+        "                    --confirmed f-1:high --resolved f-2",
+        "ace-coworker gate --candidate-head 1a2b3c4 --review-head 1a2b3c4 \\",
+        "                 --review-verdict accept --tests executed,passed \\",
+        "                 --dep 8xg.t.sbz.4.2=integrated"
+      ].freeze
+
+      register "start", Commands::Start
+      register "status", Commands::Status
+      register "report", Commands::Report
+      register "resume", Commands::Resume
+      register "prepare", Commands::Prepare
+      register "commission", Commands::Commission
+      register "roles", Commands::Roles
+      register "rounds", Commands::Rounds
+      register "gate", Commands::Gate
+
+      version_cmd = Ace::Support::Cli::VersionCommand.build(
+        gem_name: "ace-coworker",
+        version: Ace::Coworker::VERSION
+      )
+      register "version", version_cmd
+      register "--version", version_cmd
+
+      help_cmd = Ace::Support::Cli::HelpCommand.build(
+        program_name: PROGRAM_NAME,
+        version: Ace::Coworker::VERSION,
+        commands: REGISTERED_COMMANDS,
+        examples: HELP_EXAMPLES
+      )
+      register "help", help_cmd
+      register "--help", help_cmd
+      register "-h", help_cmd
+    end
+  end
+end

data/lib/ace/coworker/errors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Coworker
+    class Error < Ace::Support::Cli::Error
+    end
+  end
+end

data/lib/ace/coworker/models/assignment_snapshot.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Models
+      # Pure view of `ace-assign status --format json` for one assignment.
+      class AssignmentSnapshot
+        Step = Struct.new(:number, :name, :status, keyword_init: true) do
+          def done?
+            status == "done"
+          end
+        end
+
+        attr_reader :id, :name, :state, :steps, :progress
+
+        def initialize(id:, name:, state:, steps:, progress:)
+          @id = id.freeze
+          @name = name.freeze
+          @state = state.freeze
+          @steps = steps.map { |s| Step.new(number: s[:number], name: s[:name], status: s[:status]) }.freeze
+          @progress = progress.freeze
+        end
+
+        def self.from_status_json(payload)
+          assignment = payload["assignment"] || {}
+          steps = (payload["steps"] || []).map { |s| {number: s["number"], name: s["name"], status: s["status"]} }
+          new(
+            id: assignment["id"].to_s,
+            name: assignment["name"].to_s,
+            state: assignment["state"].to_s,
+            steps: steps,
+            progress: payload["progress"].to_s
+          )
+        end
+
+        # Deterministic completion verdict: complete only when the assignment
+        # state is completed, the plan is non-empty, and every step is done.
+        # Empty plans, failed steps, or pending/active steps are not complete.
+        def completion_verdict
+          return :complete if state == "completed" && !steps.empty? && steps.all?(&:done?)
+
+          :incomplete
+        end
+
+        def incomplete_reasons
+          reasons = []
+          reasons << "assignment state is '#{state}' (not completed)" if state != "completed"
+          reasons << "assignment plan is empty" if steps.empty?
+          reasons << "#{steps.count { |s| s.status == 'failed' }} failed step(s)" if steps.any? { |s| s.status == "failed" }
+          pending = steps.count { |s| s.status == "pending" }
+          active = steps.count { |s| s.status == "active" }
+          reasons << "#{pending} pending step(s)" if pending.positive?
+          reasons << "#{active} active step(s)" if active.positive?
+          reasons
+        end
+
+        def to_h
+          {"id" => id, "name" => name, "state" => state, "progress" => progress,
+           "steps" => steps.map { |s| {"number" => s.number, "name" => s.name, "status" => s.status} },
+           "complete" => completion_verdict == :complete}
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/models/brief.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Models
+      # Executor brief rendered by `ace-coworker start`.
+      class Brief
+        attr_reader :config, :instructions_source, :task_path, :assignment_snapshot, :project_root
+
+        def initialize(config:, instructions_source:, task_path:, assignment_snapshot:, project_root:)
+          @config = config
+          @instructions_source = instructions_source.freeze
+          @task_path = task_path.freeze
+          @assignment_snapshot = assignment_snapshot
+          @project_root = project_root.freeze
+        end
+
+        def to_h
+          {
+            "role" => config.role,
+            "instructions" => config.instructions,
+            "instructions_source" => instructions_source,
+            "start_prompt" => config.start_prompt,
+            "task" => config.task,
+            "task_path" => task_path,
+            "assignment" => config.assignment,
+            "assignment_state" => assignment_snapshot&.state,
+            "assignment_progress" => assignment_snapshot&.progress,
+            "overseer" => config.overseer,
+            "reporting_channel" => config.reporting_channel,
+            "on_failure" => config.on_failure,
+            "project_root" => project_root
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/models/config.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Models
+      # Immutable validated coworker run configuration.
+      class Config
+        attr_reader :role, :instructions, :start_prompt, :start_prompt_file, :task, :assignment,
+          :overseer, :reporting_channel, :on_failure, :source_path
+
+        def initialize(role:, instructions:, start_prompt:, task:, assignment:, overseer:,
+          start_prompt_file: nil, reporting_channel: "hitl", on_failure: "report", source_path: nil)
+          @role = role.freeze
+          @instructions = instructions.freeze
+          @start_prompt = start_prompt.freeze
+          @start_prompt_file = start_prompt_file.freeze
+          @task = task.freeze
+          @assignment = assignment.freeze
+          @overseer = overseer.freeze
+          @reporting_channel = reporting_channel.freeze
+          @on_failure = on_failure.freeze
+          @source_path = source_path.freeze
+        end
+
+        # A copy with a different assignment, e.g. a --assignment CLI
+        # override threaded through report/resume. Single place so new
+        # fields can never drift between the two identities.
+        def with(assignment:)
+          return self if assignment == @assignment
+
+          self.class.new(role: role, instructions: instructions,
+            start_prompt: start_prompt, start_prompt_file: start_prompt_file,
+            task: task, assignment: assignment, overseer: overseer,
+            reporting_channel: reporting_channel, on_failure: on_failure,
+            source_path: source_path)
+        end
+
+        def to_h
+          {
+            "role" => role,
+            "instructions" => instructions,
+            "start_prompt" => start_prompt,
+            "start_prompt_file" => start_prompt_file,
+            "task" => task,
+            "assignment" => assignment,
+            "overseer" => overseer,
+            "reporting" => {"channel" => reporting_channel},
+            "errors" => {"on_failure" => on_failure}
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/models/outcome.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Models
+      # Immutable derived outcome of one reporting run.
+      class Outcome
+        StepRef = Struct.new(:number, :name, keyword_init: true)
+
+        attr_reader :result, :verdict, :cause, :step, :unfinished_steps, :evidence, :snapshot
+
+        def initialize(result:, verdict:, cause: nil, step: nil, unfinished_steps: [], evidence: {}, snapshot: nil)
+          @result = result.freeze
+          @verdict = verdict
+          @cause = cause.freeze
+          @step = step
+          @unfinished_steps = unfinished_steps.map(&:freeze).freeze
+          @evidence = evidence.freeze
+          @snapshot = snapshot
+        end
+
+        def success?
+          result == "success"
+        end
+
+        def to_h
+          {
+            "result" => result,
+            "verdict" => verdict.to_s,
+            "cause" => cause,
+            "step" => step && {"number" => step.number, "name" => step.name},
+            "unfinished_steps" => unfinished_steps,
+            "evidence" => evidence
+          }
+        end
+      end
+    end
+  end
+end