ace-assign 0.57.1 → 0.60.0

data/lib/ace/assign/cli/commands/attempt/reconcile.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+
+module Ace
+  module Assign
+    module CLI
+      module Commands
+        module Attempt
+          # Classify interruptions and resolve uncertainty against verified,
+          # boundary-attributed receipts. Never replays external effects.
+          class Reconcile < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+            include Attempt::Base
+
+            desc "Reconcile an interrupted or uncertain attempt"
+
+            option :attempt, desc: "Attempt ID"
+            option :receipt, desc: "Path to the receipt JSON file (required to resolve uncertainty)"
+
+            def call(**options)
+              attempt_id = require_option(options, :attempt, "reconcile --attempt ID [--receipt FILE]")
+              receipt = options[:receipt].to_s.strip
+
+              result = build_coordinator.reconcile(
+                attempt_id: attempt_id,
+                receipt_path: receipt.empty? ? nil : receipt
+              )
+
+              emit_json(result.projection)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/cli/commands/attempt/start.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+
+module Ace
+  module Assign
+    module CLI
+      module Commands
+        module Attempt
+          # Bind an immutable attempt to an assignment step/subtree.
+          #
+          # Identity is derived from the execution boundary; a repeated
+          # identical start returns the active attempt, and a conflicting
+          # binding fails without launching a second writer.
+          class Start < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+            include Attempt::Base
+
+            desc "Start a scoped attempt for an assignment step"
+
+            option :assignment, desc: "Assignment ID"
+            option :step, desc: "Step or subtree scope (e.g. 010 or 010.01)"
+            option :project, desc: "Project ID the attempt executes in"
+
+            def call(**options)
+              usage = "start --assignment ID --step STEP --project ID"
+              assignment = require_option(options, :assignment, usage)
+              step = require_option(options, :step, usage)
+              project = require_option(options, :project, usage)
+
+              attempt = build_coordinator.start(
+                assignment_id: assignment,
+                step: step,
+                project_id: project
+              )
+
+              emit_json(attempt.projection)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/cli/commands/attempt/status.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+
+module Ace
+  module Assign
+    module CLI
+      module Commands
+        module Attempt
+          # Show attempt state, binding facts, and evidence references.
+          # JSON output carries only state, binding, references, and digests
+          # — never credentials or receipt bytes.
+          class Status < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+            include Attempt::Base
+
+            desc "Show attempt status for an assignment"
+
+            option :assignment, desc: "Assignment ID"
+            option :format, desc: "Output format (json, text)", default: "json"
+
+            def call(**options)
+              assignment = require_option(options, :assignment, "status --assignment ID --format json")
+              projection = build_coordinator.status(assignment)
+
+              if options[:format] == "text"
+                print_text(assignment, projection)
+              else
+                emit_json(projection || {"attempt" => nil})
+              end
+            end
+
+            private
+
+            def print_text(assignment, projection)
+              return puts "No attempts recorded for #{assignment}" if projection.nil?
+
+              puts "Attempt: #{projection['attempt_id']} #{projection['state']} (#{projection['scope']})"
+              puts "Recovery: #{projection['recovery_mode']}"
+              puts "Base head: #{projection['base_head']}"
+              puts "Candidate head: #{projection['candidate_head'] || 'unpinned'}"
+              puts "Evidence ref: #{projection['evidence_git_ref'] || 'local-only'}"
+              puts "Journal commit: #{projection['journal_commit'] || 'none'}"
+              return unless projection["unresolved_effects"].any?
+
+              puts "Unresolved effects: #{projection['unresolved_effects'].join(', ')}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -88,7 +88,10 @@ module Ace
             preset_name = Ace::Assign::Molecules::PresetInferrer.infer_from_assignment(assignment)
             auto_merge = true if preset_name && preset_name.start_with?("work-on-task-auto-merge")
 
-            evidence = Ace::Assign::Molecules::EvidenceCalculator.calculate(auto_merge: auto_merge)
+            evidence = Ace::Assign::Molecules::EvidenceCalculator.calculate(
+              auto_merge: auto_merge,
+              assignment_id: assignment.id
+            )
 
             payload = {
               assignment: {
@@ -132,6 +135,10 @@ module Ace
             lines = []
             lines.concat(compact_summary_lines(view.assignment, view.scoped_state, view.active_steps, view.next_step))
 
+            if (attempt_line = compact_attempt_line(view.assignment.id))
+              lines.insert(1, attempt_line)
+            end
+
             unless target.assignment_id
               other_line = compact_other_assignments_line(view.assignment.id, include_completed: include_completed)
               lines << other_line if other_line
@@ -140,6 +147,22 @@ module Ace
             puts lines.take(10).join("\n")
           end
 
+          # Active attempt summary projected from the coordinator authority.
+          def compact_attempt_line(assignment_id)
+            projection = Organisms::AttemptCoordinator.new.status(assignment_id)
+            return nil unless projection
+
+            base = projection["base_head"].to_s[0, 7]
+            candidate = projection["candidate_head"].to_s[0, 7]
+            line = "Attempt: #{projection['attempt_id']} #{projection['state']}"
+            line += " | base:#{base}" unless base.to_s.empty?
+            line += " | cand:#{candidate.empty? ? 'none' : candidate}"
+            line += " | unresolved: #{projection['unresolved_effects'].join(',')}" if projection["unresolved_effects"].any?
+            line
+          rescue Ace::Assign::Error, Ace::Support::Cli::Error
+            nil
+          end
+
           def compact_summary_lines(assignment, state, active_steps, next_step)
             lines = [
               compact_assignment_line(assignment, state, active_steps, next_step),

data/lib/ace/assign/cli.rb

@@ -9,6 +9,10 @@ require_relative "models/assignment"
 require_relative "models/step"
 require_relative "models/queue_state"
 require_relative "models/assignment_info"
+require_relative "models/attempt_binding"
+require_relative "models/attempt"
+require_relative "models/execution_receipt"
+require_relative "models/evidence_event"
 
 # Atoms
 require_relative "atoms/step_numbering"
@@ -22,9 +26,14 @@ require_relative "atoms/catalog_loader"
 require_relative "atoms/composition_rules"
 require_relative "atoms/assign_frontmatter_parser"
 require_relative "atoms/tree_formatter"
+require_relative "atoms/attempt_state_machine"
+require_relative "atoms/evidence_digest"
+require_relative "atoms/assignment_scope"
 
 # Molecules
+require_relative "molecules/lifecycle_exclusion"
 require_relative "molecules/assignment_manager"
+require_relative "molecules/attempt_store"
 require_relative "molecules/assignment_discoverer"
 require_relative "molecules/queue_scanner"
 require_relative "molecules/step_writer"
@@ -34,9 +43,14 @@ require_relative "molecules/fork_session_launcher"
 require_relative "molecules/tmux_control_surface_runner"
 require_relative "molecules/preset_inferrer"
 require_relative "molecules/evidence_calculator"
+require_relative "molecules/evidence_journal"
+require_relative "molecules/execution_identity_resolver"
+require_relative "molecules/receipt_verifier"
+require_relative "molecules/attempt_reconciler"
 
 # Organisms
 require_relative "organisms/assignment_executor"
+require_relative "organisms/attempt_coordinator"
 
 # Commands
 require_relative "cli/commands/create"
@@ -52,6 +66,12 @@ require_relative "cli/commands/list"
 require_relative "cli/commands/select"
 require_relative "cli/commands/fork_run"
 require_relative "cli/commands/fork_session"
+require_relative "cli/commands/attempt/base"
+require_relative "cli/commands/attempt/start"
+require_relative "cli/commands/attempt/status"
+require_relative "cli/commands/attempt/finish"
+require_relative "cli/commands/attempt/reconcile"
+require_relative "cli/commands/attempt/evidence"
 
 module Ace
   module Assign
@@ -73,7 +93,12 @@ module Ace
         ["retry", "Retry failed step"],
         ["list", "List all assignments"],
         ["select", "Select active assignment"],
-        ["fork-run", "Run subtree in forked process"]
+        ["fork-run", "Run subtree in forked process"],
+        ["attempt start", "Start a scoped attempt for an assignment step"],
+        ["attempt status", "Show attempt status for an assignment"],
+        ["attempt evidence", "Read accepted current-head check evidence"],
+        ["attempt finish", "Finish an attempt with a structured execution receipt"],
+        ["attempt reconcile", "Reconcile an interrupted or uncertain attempt"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -83,7 +108,9 @@ module Ace
         "ace-assign start                      # Start next workable step",
         "ace-assign finish --message done.md    # Complete active step",
         "cat report.md | ace-assign finish     # Complete step via stdin",
-        "ace-assign fork-run 010.01            # Run subtree in subprocess"
+        "ace-assign fork-run 010.01            # Run subtree in subprocess",
+        "ace-assign attempt start --assignment ID --step 010 --project ID",
+        "ace-assign attempt finish --attempt ID --receipt receipt.json"
       ].freeze
 
       # Captured command exit code from last run
@@ -131,6 +158,11 @@ module Ace
       register "select", wrap_command(Commands::Select)
       register "fork-run", wrap_command(Commands::ForkRun)
       register "fork-session", wrap_command(Commands::ForkSession)
+      register "attempt start", wrap_command(Commands::Attempt::Start)
+      register "attempt status", wrap_command(Commands::Attempt::Status)
+      register "attempt evidence", wrap_command(Commands::Attempt::Evidence)
+      register "attempt finish", wrap_command(Commands::Attempt::Finish)
+      register "attempt reconcile", wrap_command(Commands::Attempt::Reconcile)
 
       # Register version command
       version_cmd = Ace::Support::Cli::VersionCommand.build(

data/lib/ace/assign/models/assignment.rb

@@ -19,7 +19,8 @@ module Ace
       # NOTE: Could be refactored to use Data.define in Ruby 3.2+ for reduced boilerplate,
       # but tests would need to be updated to provide all required fields.
       class Assignment
-        attr_reader :id, :name, :description, :created_at, :updated_at, :source_config, :cache_dir, :parent
+        attr_reader :id, :name, :description, :created_at, :updated_at, :source_config, :cache_dir, :parent,
+          :task_id, :project_id
 
         # @param id [String] Unique assignment ID (6-char compact timestamp)
         # @param name [String] Human-readable assignment name
@@ -29,7 +30,10 @@ module Ace
         # @param source_config [String] Path to source configuration file
         # @param cache_dir [String, nil] Assignment cache directory
         # @param parent [String, nil] Parent assignment ID for hierarchy linking
-        def initialize(id:, name:, created_at:, source_config:, description: nil, updated_at: nil, cache_dir: nil, parent: nil)
+        # @param task_id [String, nil] Source task ID attached to this assignment (nil = taskless)
+        # @param project_id [String, nil] Project ID this assignment executes in
+        def initialize(id:, name:, created_at:, source_config:, description: nil, updated_at: nil, cache_dir: nil,
+          parent: nil, task_id: nil, project_id: nil)
           @id = id.freeze
           @name = name.freeze
           @description = description&.freeze
@@ -38,6 +42,15 @@ module Ace
           @source_config = source_config.freeze
           @cache_dir = cache_dir&.freeze
           @parent = parent&.freeze
+          @task_id = task_id&.freeze
+          @project_id = project_id&.freeze
+        end
+
+        # @return [Boolean] True when a source task is attached; taskless
+        #   assignments persist attempts locally only and never claim
+        #   Git-backed recovery
+        def managed?
+          !task_id.nil? && !task_id.to_s.strip.empty?
         end
 
         # Convert to hash for YAML serialization
@@ -50,7 +63,9 @@ module Ace
             "created_at" => created_at.iso8601,
             "updated_at" => updated_at.iso8601,
             "source_config" => source_config,
-            "parent" => parent
+            "parent" => parent,
+            "task_id" => task_id,
+            "project_id" => project_id
           }.compact
         end
 
@@ -67,7 +82,9 @@ module Ace
             updated_at: parse_time(data["updated_at"]),
             source_config: data["source_config"],
             cache_dir: cache_dir,
-            parent: data["parent"]
+            parent: data["parent"],
+            task_id: data["task_id"],
+            project_id: data["project_id"]
           )
         end
 

data/lib/ace/assign/models/attempt.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/attempt_state_machine"
+require_relative "attempt_binding"
+
+module Ace
+  module Assign
+    module Models
+      # Mutable derived state of an assignment attempt.
+      #
+      # The binding is immutable; an Attempt carries the derived execution
+      # state: the current state-machine state, the pinned candidate head,
+      # the latest evidence journal commit, accepted receipts (by digest),
+      # recorded effects, and the append-only local event trail for
+      # taskless attempts. `base_head` (binding) and `candidate_head`
+      # (deliverable) are always tracked separately.
+      class Attempt
+        attr_reader :binding, :state, :candidate_head, :journal_commit,
+          :accepted_receipts, :effects, :events, :updated_at
+
+        # @param binding [Models::AttemptBinding] Immutable start-time binding
+        # @param state [String] State-machine state
+        # @param candidate_head [String, nil] Pinned deliverable head
+        # @param journal_commit [String, nil] Latest evidence journal commit SHA
+        # @param accepted_receipts [Array<Hash>] Accepted receipt payloads (digests included)
+        # @param effects [Array<Hash>] Recorded effects with intent/receipt linkage
+        # @param events [Array<Hash>] Local event trail (taskless attempts only)
+        # @param updated_at [Time] Last state change
+        def initialize(binding:, state: "reserved", candidate_head: nil, journal_commit: nil,
+          accepted_receipts: [], effects: [], events: [], updated_at: nil)
+          @binding = binding
+          @state = state.to_s
+          @candidate_head = candidate_head
+          @journal_commit = journal_commit
+          @accepted_receipts = accepted_receipts.dup.freeze
+          @effects = effects.dup.freeze
+          @events = events.dup.freeze
+          @updated_at = updated_at || binding.created_at
+        end
+
+        # @return [String] Immutable attempt ID
+        def attempt_id
+          binding.attempt_id
+        end
+
+        # @return [Boolean] True if no further transitions or effects are allowed
+        def terminal?
+          Atoms::AttemptStateMachine.terminal?(state)
+        end
+
+        # @return [Boolean] True if the attempt awaits reconciliation
+        def uncertain?
+          state == "uncertain"
+        end
+
+        # @return [Boolean] True if the attempt owns an active subtree slot
+        def active?
+          %w[reserved running uncertain].include?(state)
+        end
+
+        # @return [String] "git" or "local_only" recovery mode
+        def recovery_mode
+          binding.recovery_mode
+        end
+
+        # @return [Boolean] True when managed evidence-ref journaling applies
+        def managed?
+          binding.managed?
+        end
+
+        # Effects whose intent was recorded but whose accepted receipt is missing.
+        #
+        # @return [Array<Hash>] Unresolved effect records
+        def unresolved_effects
+          effects.reject { |effect| effect["receipt_digest"] }
+        end
+
+        # Return a new Attempt with the state transitioned.
+        #
+        # @param to [String] Target state (validated against the state machine)
+        # @param at [Time] Transition time
+        # @return [Attempt] New attempt instance
+        # @raise [Ace::Assign::AttemptErrors::InvalidTransition] if illegal
+        def transition(to, at: Time.now.utc)
+          Atoms::AttemptStateMachine.transition!(state, to)
+          with(state: to.to_s, updated_at: at)
+        end
+
+        # Return a new Attempt with updated derived fields. The binding is
+        # never replaced.
+        #
+        # @param attrs [Hash] Fields to override (state, candidate_head,
+        #   journal_commit, accepted_receipts, effects, events, updated_at)
+        # @return [Attempt] New attempt instance
+        def with(**attrs)
+          Attempt.new(
+            binding: binding,
+            state: attrs.fetch(:state, state),
+            candidate_head: attrs.fetch(:candidate_head, candidate_head),
+            journal_commit: attrs.fetch(:journal_commit, journal_commit),
+            accepted_receipts: attrs.fetch(:accepted_receipts, accepted_receipts),
+            effects: attrs.fetch(:effects, effects),
+            events: attrs.fetch(:events, events),
+            updated_at: attrs.fetch(:updated_at, Time.now.utc)
+          )
+        end
+
+        # Convert to a hash for canonical serialization.
+        # @return [Hash] Attempt data with string keys
+        def to_h
+          {
+            "binding" => binding.to_h,
+            "state" => state,
+            "candidate_head" => candidate_head,
+            "journal_commit" => journal_commit,
+            "accepted_receipts" => accepted_receipts,
+            "effects" => effects,
+            "events" => events,
+            "updated_at" => updated_at.iso8601
+          }
+        end
+
+        # JSON projection exposed by public commands. Contains attempt
+        # ID, state, binding facts, references and digests only — never
+        # credentials, receipt bytes, or terminal output.
+        #
+        # @return [Hash] Redacted projection
+        def projection
+          {
+            "attempt_id" => attempt_id,
+            "state" => state,
+            "assignment_id" => binding.assignment_id,
+            "scope" => binding.scope,
+            "project_id" => binding.project_id,
+            "task_id" => binding.task_id,
+            "actor" => binding.actor,
+            "role" => binding.role,
+            "runtime" => binding.runtime,
+            "base_head" => binding.base_head,
+            "candidate_head" => candidate_head,
+            "evidence_git_ref" => binding.evidence_git_ref,
+            "journal_commit" => journal_commit,
+            "recovery_mode" => recovery_mode,
+            "accepted_receipt_digests" => accepted_receipts.map { |receipt| receipt["digest"] },
+            "unresolved_effects" => unresolved_effects.map { |effect| effect["operation"] },
+            "created_at" => binding.created_at.iso8601,
+            "updated_at" => updated_at.iso8601
+          }
+        end
+
+        # Rebuild an attempt from serialized data.
+        #
+        # @param data [Hash] Serialized attempt (string keys)
+        # @return [Attempt] Rebuilt attempt
+        def self.from_h(data)
+          new(
+            binding: AttemptBinding.from_h(data["binding"]),
+            state: data["state"],
+            candidate_head: data["candidate_head"],
+            journal_commit: data["journal_commit"],
+            accepted_receipts: data["accepted_receipts"] || [],
+            effects: data["effects"] || [],
+            events: data["events"] || [],
+            updated_at: parse_time(data["updated_at"])
+          )
+        end
+
+        def self.parse_time(value)
+          return nil if value.nil?
+          return value if value.is_a?(Time)
+          require "time"
+          Time.parse(value)
+        end
+        private_class_method :parse_time
+      end
+    end
+  end
+end

data/lib/ace/assign/models/attempt_binding.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Models
+      # Immutable start-time facts for an assignment attempt.
+      #
+      # A binding freezes exactly what an attempt owns: the immutable attempt
+      # ID, the assignment and step/subtree scope, the project, the
+      # authenticated actor/role and runtime identity resolved at the
+      # execution boundary, the source task ID, the base head captured once at
+      # start, and the configured evidence ref. Bindings are never mutated;
+      # changes require a new attempt.
+      class AttemptBinding
+        attr_reader :attempt_id, :assignment_id, :scope, :project_id, :task_id,
+          :actor, :role, :runtime, :base_head, :evidence_git_ref, :created_at
+
+        # @param attempt_id [String] Immutable attempt ID (ace-b36ts)
+        # @param assignment_id [String] Owning assignment ID
+        # @param scope [String] Canonical step/subtree scope
+        # @param project_id [String] Project the attempt executes in
+        # @param actor [String] Authenticated actor from the execution boundary
+        # @param role [String] Trusted role (coordinator, service, worker)
+        # @param runtime [String] Runtime identity of the executing boundary
+        # @param base_head [String] Git HEAD captured exactly once at start
+        # @param task_id [String, nil] Source task ID (nil for taskless assignments)
+        # @param evidence_git_ref [String, nil] Evidence ref for managed attempts
+        # @param created_at [Time] Binding creation time
+        def initialize(attempt_id:, assignment_id:, scope:, project_id:, actor:, role:, runtime:, base_head:,
+          task_id: nil, evidence_git_ref: nil, created_at:)
+          @attempt_id = attempt_id.freeze
+          @assignment_id = assignment_id.freeze
+          @scope = scope.freeze
+          @project_id = project_id.freeze
+          @task_id = task_id&.freeze
+          @actor = actor.freeze
+          @role = role.freeze
+          @runtime = runtime.freeze
+          @base_head = base_head.freeze
+          @evidence_git_ref = evidence_git_ref&.freeze
+          @created_at = created_at
+        end
+
+        # @return [Boolean] True when the attempt is bound to a source task and
+        #   eligible for managed evidence-ref delivery
+        def managed?
+          !task_id.nil? && !task_id.to_s.strip.empty?
+        end
+
+        # Recovery mode implied by task attachment: git-backed journaling for
+        # task-attached attempts, disposable local state otherwise.
+        #
+        # @return [String] "git" or "local_only"
+        def recovery_mode
+          managed? ? "git" : "local_only"
+        end
+
+        # Identity facts repeated by receipts must match the binding exactly.
+        #
+        # @param other [AttemptBinding] Binding to compare
+        # @return [Boolean] True if both bindings own the same attempt identity
+        def same_identity?(other)
+          attempt_id == other.attempt_id &&
+            assignment_id == other.assignment_id &&
+            scope == other.scope &&
+            project_id == other.project_id
+        end
+
+        # Convert to a hash for canonical serialization.
+        # @return [Hash] Binding data with string keys
+        def to_h
+          {
+            "attempt_id" => attempt_id,
+            "assignment_id" => assignment_id,
+            "scope" => scope,
+            "project_id" => project_id,
+            "task_id" => task_id,
+            "actor" => actor,
+            "role" => role,
+            "runtime" => runtime,
+            "base_head" => base_head,
+            "evidence_git_ref" => evidence_git_ref,
+            "created_at" => created_at.iso8601
+          }
+        end
+
+        # Rebuild a binding from serialized data.
+        #
+        # @param data [Hash] Serialized binding (string keys)
+        # @return [AttemptBinding] Rebuilt binding
+        def self.from_h(data)
+          new(
+            attempt_id: data["attempt_id"],
+            assignment_id: data["assignment_id"],
+            scope: data["scope"],
+            project_id: data["project_id"],
+            task_id: data["task_id"],
+            actor: data["actor"],
+            role: data["role"],
+            runtime: data["runtime"],
+            base_head: data["base_head"],
+            evidence_git_ref: data["evidence_git_ref"],
+            created_at: parse_time(data["created_at"])
+          )
+        end
+
+        def self.parse_time(value)
+          return value if value.is_a?(Time)
+          require "time"
+          Time.parse(value)
+        end
+        private_class_method :parse_time
+      end
+    end
+  end
+end