ace-assign 0.57.0 → 0.58.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ae38e39385e77c124bb67fc25b8ae8f1f5eef5e79d4779e8b40f1047bae52b6
-  data.tar.gz: 323a3390bf57c7543443ba3c49b1d67483436cff03c5cfcebcb2aec2c8f99bc0
+  metadata.gz: c66fd1fc72e1bb186537931c960477dc7f9405ce3bc0f41c195a4b6601aa9bd1
+  data.tar.gz: fef52c4c68bbb1435499d7cb0468d09919b5b330d9d7226b4c676c54c12ff9ad
 SHA512:
-  metadata.gz: '02824e0e864c5694a606c11e10c68259bbc4d31741e934dfe89c99ef643f8a501d7126beba2fc85230732653e930d82c9ec2cdbb58662e077df6b4e3a0b0e88c'
-  data.tar.gz: 5e602ed50ddf6f34bfc5ee73a1808a507901d36f9d469063759482c9334ff1a2f08494c3243d997ce2deda876671b6353619ea9494881dd6da62cf18ec7722c0
+  metadata.gz: 8e31f4379b900c7906be0b15b92768c904d57bf3fcfccbaf284ca972168413be443907281e1f1b939dff66337daf2835f32fc27c27fc802738dbe19238f220c4
+  data.tar.gz: f77a7e04992fddf9b8ddf99e57243759e1ec8ccbd7502fbae9836e32bd749a60b5feb7d7c4a63017f92b384efdce49654547b7ecb1d18fb29c66cab644dad18a

data/.ace-defaults/assign/config.yml

@@ -28,6 +28,19 @@ execution:
   timeout: 1800
   launch_mode: auto # auto | headless | tmux
 
+# Attempt evidence persistence (managed attempts)
+attempt:
+  # Dedicated Git ref holding accepted execution evidence, outside the
+  # deliverable candidate branch; journal paths are execution/<assignment-id>/
+  evidence_git_ref: "refs/ace/execution"
+  # Disposable isolated audit checkout root (relative to project root)
+  evidence_checkout_root: ".ace-local/assign/evidence-checkout"
+  # Trusted execution-boundary identity adapter: local (interactive
+  # coordinator) or service (identity supplied by a trusted service executor
+  # via service_identity_env). Unknown identity fails closed.
+  identity_adapter: "local"
+  service_identity_env: "ACE_ASSIGN_SERVICE_IDENTITY"
+
 # Subtree execution behavior
 subtree:
   pre_commit_review: true

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.58.0] - 2026-09-28
+
+### Added
+- Durable assignment attempts: `ace-assign attempt start|status|finish|reconcile` bind an immutable attempt ID to an assignment step/subtree, project, boundary-derived actor identity, and `base_head`, with a `reserved -> running -> succeeded/failed/stopped/uncertain` lifecycle and conservative reconciliation of interruptions (no automatic replay of merge/publish/deploy).
+- Managed attempts journal accepted execution evidence to the configured evidence Git ref (default `refs/ace/execution`) through an isolated audit checkout with flock serialization and expected-old-value `git update-ref` compare-and-swap; `refs/ace/execution` never advances the deliverable candidate branch.
+- Structured execution receipts: verifiable artifact digests, executed checks, executed independent reviewer verdicts for the exact current head, and rejection of credentials/terminal output in accepted evidence.
+- `ace-assign status` (JSON) now includes the active attempt, `base_head`, `candidate_head`, `evidence_git_ref`, `journal_commit`, and unresolved effects.
+
+### Changed
+- BREAKING: delivery evidence is derived exclusively from accepted, current-head journal receipts. The previous interpretation that a current `.ace-local/review`/`.ace-local/release` report plus hardcoded `terminal` feedback authorizes merge is removed; `merge_decision` is now `authorized` or `approval-required` (never `report-only`). Existing `EvidenceCalculator` consumers must read evidence from attempts.
+- BREAKING: taskless assignments persist attempts locally (`recovery_mode: local_only`), never claim Git-backed recovery, and cannot record external effects until attached to a source task.
+- New `attempt` error family exits with code 5 (conflict, rejected receipt, unauthorized identity, unavailable evidence, illegal attempt state).
+
+## [0.57.1] - 2026-09-27
+
+### Technical
+- Stop depending on the removed review-fit preset step in tests.
+
 ## [0.57.0] - 2026-09-24
 
 ### Changed

data/docs/exit-codes.md

@@ -20,6 +20,7 @@ This document describes the exit codes returned by the `ace-assign` CLI.
 | 2 | Assignment error | No active assignment or assignment not found |
 | 3 | Configuration not found | Config file does not exist |
 | 4 | Step not found | Referencing a step that does not exist |
+| 5 | Attempt error | Attempt conflict, rejected receipt, unauthorized identity, unavailable evidence, or illegal attempt state |
 
 ## Exit Code Details
 
@@ -55,6 +56,15 @@ The requested step reference does not exist in the target assignment:
 - `retry` with unknown step number
 - Commands that target a specific missing step
 
+### Exit Code 5: Attempt Error
+An attempt, receipt, identity, or evidence problem rejected the operation:
+- `attempt start` with a conflicting binding for an owned subtree
+- `attempt finish`/`attempt reconcile` with a receipt that fails verification (wrong binding, stale head, digest mismatch, self-approval, forbidden fields)
+- Worker-identity attempts to accept a succeeded verdict
+- Unknown or missing execution-boundary identity
+- Reconciling a terminal attempt, or resolving uncertainty without a receipt
+- Unavailable or unwritable evidence storage blocking a managed effect
+
 ## See Also
 
 - [Usage Guide](usage.md) for full command reference

data/docs/usage.md

@@ -85,6 +85,38 @@ ace-assign add --step review-pr --after 100 --child
 ace-assign add --yaml .ace-local/assign/jobs/add-task.yml --after 010 --child
 ```
 
+## Attempt Evidence
+
+Execution evidence lives in assignment attempts, not in reports. An attempt binds an immutable ID to an assignment, step/subtree scope, project, boundary-derived actor/role/runtime, source task, and `base_head`; the deliverable `candidate_head` is pinned only when accepted evidence is submitted, and the evidence journal commit is tracked separately from both.
+
+### Attempt lifecycle
+
+```bash
+ace-assign attempt start --assignment ASSIGNMENT --step STEP --project PROJECT
+ace-assign attempt status --assignment ASSIGNMENT --format json
+ace-assign attempt finish --attempt ATTEMPT --receipt receipt.json
+ace-assign attempt reconcile --attempt ATTEMPT --receipt receipt.json
+```
+
+- `attempt start` returns a JSON projection of the attempt (ID, state, binding facts, evidence references, digests). A repeated identical start returns the same attempt; a conflicting start exits 5 without launching a second writer.
+- `attempt status` exposes only state, binding, references, and digests -- never credentials or receipt bytes.
+- `attempt finish` accepts a structured receipt: operation, attributed producer, exact tested/reviewed head, verdict, artifact paths with SHA-256 digests, executed checks, and -- for review operations -- an executed independent reviewer verdict for that head.
+- `attempt reconcile` classifies interrupted attempts (`stopped` before process start, `uncertain` when an effect cannot be proven either way, still `running` only for verifiably live processes) and resolves uncertainty only against a verified receipt attributed to the recorded execution boundary. Merge, publish, and deploy effects are never replayed automatically.
+
+### State machine
+
+`reserved -> running -> succeeded | failed | stopped | uncertain`; reconciliation may resolve `uncertain -> succeeded | failed`. Terminal attempts accept no new effects, and accepted history is append-only.
+
+### Evidence storage and recovery modes
+
+- Task-attached (managed) attempts journal accepted evidence to the configured evidence Git ref (default `refs/ace/execution`) through an isolated, disposable audit checkout, outside the deliverable candidate branch. Journal commits never advance or exempt the reviewed candidate.
+- Taskless assignments persist attempts under `.ace-local/assign` with `recovery_mode: local_only`. This path never claims Git-backed recovery and cannot record external effects (`merge`, `publish`, `deploy`, `release`); attach the assignment to a source task before managed delivery.
+- Actor identity always comes from the execution boundary (OS login for local use, or the trusted service executor's identity). Unknown identity fails closed; flags never grant identity or authority.
+
+### status integration
+
+`ace-assign status --format json` includes the active attempt, `base_head`, `candidate_head`, `evidence_git_ref`, `journal_commit`, and unresolved effects. Feedback state is derived from accepted current-head evidence: `terminal` (accepted evidence at the current head), `open` (attempts without a terminal outcome), `uncertain` (unresolved interruptions), or `unknown` (no attempts). Merge authorization requires an executed independent review verdict for the current head plus an independent release receipt when relevant; report files, exit codes, and prose never authorize a merge.
+
 ## Commands
 
 ### `ace-assign create`

data/handbook/workflow-instructions/assign/drive.wf.md

@@ -657,21 +657,71 @@ Follow the instructions directly, performing the described work:
 
 ### 4. External Action Rule (Attempt-First)
 
-For external-facing steps (for example PR/review/release/push/update lifecycle steps):
+Every external-facing step (implement, verify, review, merge, publish, deploy, release) runs inside a scoped attempt. The attempt -- not the report and not exit status -- is the delivery record.
 
-- Attempt the step command(s) first.
-- If blocked, capture concrete evidence:
+**Step 1: Start the attempt before executing the step.** Actor identity is derived from the execution boundary; never pass actor flags.
 
-  - command attempted
-  - exact error output
-  - why the step cannot proceed
+```bash
+ATTEMPT_JSON=$(ace-assign attempt start --assignment "$ASSIGNMENT_ID" --step "$STEP_NUMBER" --project "$PROJECT_ID")
+echo "$ATTEMPT_JSON"
+```
+
+- A repeated identical start returns the same attempt; a conflicting start fails (exit 5). Never launch a second writer for an owned subtree.
+- `base_head` is captured exactly once at start. Record the `attempt_id`.
+
+**Step 2: Execute the step command(s).** If blocked, capture concrete evidence:
+
+- command attempted
+- exact error output
+- why the step cannot proceed
 
-- Mark step failed with evidence (do not report synthetic completion).
+Mark the step failed with evidence (do not report synthetic completion):
 
 ```bash
 ace-assign fail --message "Command failed: <cmd>. Error: <exact stderr>" --assignment "$ASSIGNMENT_TARGET"
 ```
 
+**Step 3: Submit a structured receipt -- never prose -- to close the attempt.**
+
+```bash
+cat > /tmp/attempt-receipt.json << 'EOF'
+{
+  "attempt_id": "<ATTEMPT_ID>",
+  "assignment_id": "<ASSIGNMENT_ID>",
+  "project_id": "<PROJECT_ID>",
+  "scope": "<STEP_NUMBER>",
+  "operation": "implement",
+  "producer": {"actor": "<boundary-actor>", "role": "worker", "runtime": "<boundary-runtime>"},
+  "head": "<exact tested/reviewed HEAD sha>",
+  "verdict": "succeeded",
+  "artifacts": [{"path": "report.md", "sha256": "<sha256>"}],
+  "checks": [{"name": "ace-test", "verdict": "passed"}],
+  "review": {"reviewer": {"actor": "<independent-reviewer>", "runtime": "<reviewer-runtime>"}, "verdict": "approved", "head": "<same HEAD sha>"}
+}
+EOF
+
+ace-assign attempt finish --attempt "$ATTEMPT_ID" --receipt /tmp/attempt-receipt.json
+```
+
+Receipt rules enforced by the coordinator:
+
+- `succeeded` verdicts require verifiable artifact digests, passing checks, and trusted coordinator/service authority; worker runtimes may submit attributable results but cannot self-approve.
+- Review approval requires an executed independent reviewer verdict for the exact current head; same author/reviewer and report-only existence are rejected.
+- Receipts carrying credentials, environment dumps, or terminal output are rejected outright.
+- External effects (`merge`, `publish`, `deploy`, `release`) additionally require an accepted independent review receipt for the current head. Taskless assignments cannot record external effects.
+
+**Step 4: Handle interruptions by classifying and reconciling -- never by assuming.**
+
+```bash
+ace-assign attempt status --assignment "$ASSIGNMENT_ID" --format json
+ace-assign attempt reconcile --attempt "$ATTEMPT_ID"
+ace-assign attempt reconcile --attempt "$ATTEMPT_ID" --receipt /tmp/attempt-receipt.json
+```
+
+- A lost receipt after a possible effect is `uncertain`; it resolves only against a verified receipt attributed to the recorded execution boundary.
+- Running attempts stay running only while their recorded process is verifiably live; anything else becomes `stopped` or `uncertain`.
+- Never replay `merge`, `publish`, or `deploy` automatically. Reconciliation records evidence; it never re-executes effects.
+
 ### Human-in-the-Loop (HITL) Stall Protocol
 
 Canonical source of truth: `wfi://hitl`.
@@ -717,7 +767,7 @@ For a blocked step:
 
 ### 5. Write Report (Only After Real Execution)
 
-After completing the step work, write a brief report summarizing what was accomplished:
+After the attempt accepted a receipt (or the step was failed with evidence), write a brief report summarizing what was accomplished. The report advances the queue; the accepted attempt receipt carries the delivery evidence:
 
 ```bash
 # Write report content to a temp file
@@ -737,6 +787,12 @@ EOF
 ace-assign finish --message /tmp/step-report.md --assignment "$ASSIGNMENT_TARGET"
 ```
 
+Prohibited:
+
+- Advancing a step when its attempt has no accepted receipt (or recorded failure evidence).
+- Treating a written report, exit 0, or prose as proof of completion. Check `ace-assign attempt status --assignment "$ASSIGNMENT_ID" --format json` for accepted evidence and unresolved effects.
+- Reporting `uncertain` attempts as complete; reconcile them first.
+
 ### 6. Verify State Transition (Required)
 
 After each `ace-assign finish --message` or `ace-assign fail`, verify queue state:

data/lib/ace/assign/atoms/assignment_scope.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure validation and canonicalization of attempt scopes.
+      #
+      # An attempt scope is the step/subtree an attempt owns, expressed as a
+      # step number ("010", "010.01"). Scopes are canonicalized before they
+      # key ownership locks, journal paths, or binding comparisons so that
+      # cosmetic differences cannot create a second writer.
+      module AssignmentScope
+        SCOPE_PATTERN = /\A\d+(?:\.\d+)*\z/.freeze
+
+        # Canonicalize and validate a step/subtree scope.
+        #
+        # @param step [String] Step or subtree root number
+        # @return [String] Canonical scope
+        # @raise [Ace::Assign::AttemptErrors::InvalidScope] if blank or malformed
+        def self.canonicalize(step)
+          scope = step.to_s.strip
+          if scope.empty? || !scope.match?(SCOPE_PATTERN)
+            raise Ace::Assign::AttemptErrors::InvalidScope,
+              "Invalid attempt scope '#{step}': expected a step number such as 010 or 010.01"
+          end
+
+          scope
+        end
+
+        # Filesystem-safe token for an assignment/scope pair, used to key
+        # active-attempt ownership records.
+        #
+        # @param assignment_id [String] Assignment ID
+        # @param scope [String] Canonical scope
+        # @return [String] Ownership key token
+        def self.ownership_key(assignment_id, scope)
+          "#{assignment_id}-#{canonicalize(scope)}.json"
+        end
+
+        # Compare two scopes for binding identity.
+        #
+        # @param left [String] First scope
+        # @param right [String] Second scope
+        # @return [Boolean] True if both canonicalize to the same scope
+        def self.equal?(left, right)
+          canonicalize(left) == canonicalize(right)
+        rescue Ace::Assign::AttemptErrors::InvalidScope
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/atoms/attempt_state_machine.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure state machine for assignment attempt lifecycles.
+      #
+      # Legal transitions:
+      # - reserved -> running
+      # - running  -> succeeded | failed | stopped | uncertain
+      # - uncertain -> succeeded | failed (only via reconciliation)
+      #
+      # Terminal states are succeeded, failed, and stopped. Terminal attempts
+      # never accept new transitions, effects, or receipts; accepted history is
+      # immutable. A stop is never success, and an uncertain attempt must be
+      # resolved through explicit reconciliation, never automatic replay.
+      module AttemptStateMachine
+        STATES = %w[reserved running succeeded failed stopped uncertain].freeze
+        TERMINAL_STATES = %w[succeeded failed stopped].freeze
+        RESOLVED_STATES = %w[succeeded failed].freeze
+
+        TRANSITIONS = {
+          "reserved" => %w[running].freeze,
+          "running" => %w[succeeded failed stopped uncertain].freeze,
+          "uncertain" => RESOLVED_STATES.freeze
+        }.freeze
+
+        # @return [Array<String>] All known attempt states
+        def self.states
+          STATES
+        end
+
+        # @param state [String] State to inspect
+        # @return [Boolean] True if the state is terminal (no further transitions)
+        def self.terminal?(state)
+          TERMINAL_STATES.include?(state.to_s)
+        end
+
+        # @param state [String] State to inspect
+        # @return [Boolean] True if the state awaits reconciliation
+        def self.uncertain?(state)
+          state.to_s == "uncertain"
+        end
+
+        # Check whether a transition is legal without raising.
+        #
+        # @param from [String] Current state
+        # @param to [String] Requested next state
+        # @return [Boolean] True if the transition is legal
+        def self.can_transition?(from, to)
+          TRANSITIONS.fetch(from.to_s, []).include?(to.to_s)
+        end
+
+        # Return the legal next states for a state.
+        #
+        # @param from [String] Current state
+        # @return [Array<String>] Legal next states (empty for unknown/terminal)
+        def self.next_states(from)
+          TRANSITIONS.fetch(from.to_s, [])
+        end
+
+        # Validate a transition.
+        #
+        # @param from [String] Current state
+        # @param to [String] Requested next state
+        # @raise [Ace::Assign::AttemptErrors::InvalidTransition] if illegal
+        def self.transition!(from, to)
+          return to.to_s if can_transition?(from, to)
+
+          raise Ace::Assign::AttemptErrors::InvalidTransition,
+            "Illegal attempt transition #{from} -> #{to} (legal from #{from}: #{next_states(from).join(', ')})"
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/atoms/evidence_digest.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure canonical digest helpers for attempt evidence.
+      #
+      # Every accepted evidence record (events, receipts, artifacts) carries a
+      # SHA-256 digest over a canonical JSON serialization (sorted keys, no
+      # insignificant whitespace) so records remain comparable across writers
+      # and reloads. Digests are over non-secret metadata only.
+      module EvidenceDigest
+        # Canonical JSON serialization of an object.
+        #
+        # Sorts hash keys recursively and strips insignificant whitespace so
+        # semantically equal payloads produce byte-identical output.
+        #
+        # @param object [Object] JSON-serializable object
+        # @return [String] Canonical JSON string
+        def self.canonical_json(object)
+          JSON.generate(sort_keys(object))
+        end
+
+        # SHA-256 hex digest over the canonical JSON of an object.
+        #
+        # @param object [Object] JSON-serializable object
+        # @return [String] 64-character hex digest
+        def self.digest(object)
+          digest_string(canonical_json(object))
+        end
+
+        # SHA-256 hex digest over raw bytes.
+        #
+        # @param bytes [String] Raw byte content
+        # @return [String] 64-character hex digest
+        def self.digest_string(bytes)
+          Digest::SHA256.hexdigest(bytes)
+        end
+
+        # SHA-256 hex digest of a file's contents.
+        #
+        # @param path [String] File path
+        # @return [String] 64-character hex digest
+        # @raise [Errno::ENOENT] if the file does not exist
+        def self.digest_file(path)
+          digest_string(File.read(path))
+        end
+
+        # Short digest prefix for file naming (collision-resistant enough for
+        # append-only event filenames; full digests remain in the payload).
+        #
+        # @param object [Object] JSON-serializable object
+        # @return [String] 12-character hex prefix
+        def self.short_digest(object)
+          digest(object)[0, 12]
+        end
+
+        class << self
+          private
+
+          def sort_keys(value)
+            case value
+            when Hash
+              value.sort.to_h.transform_values { |v| sort_keys(v) }
+            when Array
+              value.map { |item| sort_keys(item) }
+            else
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Assign
+    module CLI
+      module Commands
+        # Public `ace-assign attempt` command namespace (interface contract:
+        # start, status, finish, reconcile).
+        module Attempt
+          # Shared coordinator construction, option validation, and JSON output.
+          module Base
+            private
+
+            def build_coordinator
+              Organisms::AttemptCoordinator.new
+            end
+
+            def require_option(options, key, usage)
+              value = options[key].to_s.strip
+              raise Ace::Support::Cli::Error, "Missing --#{key}: usage: ace-assign attempt #{usage}" if value.empty?
+
+              value
+            end
+
+            def emit_json(payload)
+              puts JSON.generate(payload)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+
+module Ace
+  module Assign
+    module CLI
+      module Commands
+        module Attempt
+          # Accept a structured execution receipt and record the outcome.
+          # Terminal and uncertain attempts refuse new receipts.
+          class Finish < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+            include Attempt::Base
+
+            desc "Finish an attempt with a structured execution receipt"
+
+            option :attempt, desc: "Attempt ID"
+            option :receipt, desc: "Path to the receipt JSON file"
+
+            def call(**options)
+              attempt_id = require_option(options, :attempt, "finish --attempt ID --receipt FILE")
+              receipt = require_option(options, :receipt, "finish --attempt ID --receipt FILE")
+
+              result = build_coordinator.finish(attempt_id: attempt_id, receipt_path: receipt)
+
+              emit_json(result.projection)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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