ace-assign 0.57.1 → 0.60.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64ca0ab83e21423599cccecfdc9b20e7dfc4c62b0e262e40bf82dc96ba68e0e0
-  data.tar.gz: 5515ff2144574af8f820437a1423106925ec6f8674f5838921249445c8547f3b
+  metadata.gz: 3a8f387dd91c6da87ca5eb3712cb5fb71051a0326dfa13cf0d9d91e054c1cc00
+  data.tar.gz: 4698ad04a950a1401caec3387ef085e8c66512a07e9dd5af168446d80e7d89eb
 SHA512:
-  metadata.gz: 42b4a978e165872d2bb9c89e6ab9cd6ddc6698c2664d054c0c6fde53de2b18981288dde5f6760e2f4ca2fe6b41811deeafb1435b9071b80a36fe211a2abeeb00
-  data.tar.gz: f6c97237effc40614bcceb08b25a577a70fe0bc0d034791df6f90a8cf0050d9e9adf935bf89834bfd0a7641b2c3f5c5787bd8b73941e9784b04bcb479a0c61d9
+  metadata.gz: 89c8df3b2e0823c195dfc3d3b59fbcc58e79c97b3978e0db2e4395c83e86307e8d450a637e633b9aa947efeb79ff94ba78307bc24de577effb8cb55b53e9b8f5
+  data.tar.gz: dd2e0a73591ea2e646c9c8164cb56269ff6353860005acdfb57bc268ca8e2d5c89b77b3a19af8a1b895dcfa8716199ae0272a1705387dc4c5f5bda424c062668

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,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.60.0] - 2026-10-01
+
+### Fixed
+- Preserve task/project attachment when the public assignment creation path archives its source configuration, so managed attempts retain immutable journal authority.
+- Cache-free evidence lookup handles a seed-only journal ref without creating a checkout or treating an absent attempt as a corrupt journal.
+
+### Added
+- `attempt evidence --kind review-approval` validates accepted independent approval separately from collection; retained collection/approval receipts support explicit historical-head validation without granting current check authority.
+- Bind campaign check names to accepted executed operations and review collection to accepted `review-collect` artifacts, through `attempt evidence` purpose checks.
+
+- `ace-assign attempt evidence` exposes read-only coordinator-accepted current-head check proof. Journal reads use immutable Git objects without writing cache/audit checkout state.
+- Review receipts may consume a durable ace-review campaign result. The existing coordinator still validates authority, live head, independent reviewer, executed checks and artifact digests; stale or conflicting campaign snapshots are rejected.
+
+## [0.59.0] - 2026-09-29
+
+### Added
+- Durable lifecycle exclusion (`Ace::Assign::Molecules::LifecycleExclusion`): prune holds the exclusive side from final evidence reads through removal while every supported start path -- attempt registration, fork/driver session launch, and worktree provisioning -- holds the shared side. Locks live outside every deletion target (sandbox-aware cache base or the shared Git common dir) so they survive removal of the target, and a `removed` marker makes post-prune starts fail closed instead of recreating a deleted identity.
+
+### Changed
+- `AttemptCoordinator#start` and `ForkSessionLauncher#launch` now participate in the prune exclusion: a concurrent prune blocks new writers for the identity, and a start targeting a pruned assignment raises a conflict instead of writing into a recreated path.
+
+## [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
@@ -490,7 +524,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Unified dynamic step default instructions under a single `AssignmentExecutor::DEFAULT_DYNAMIC_STEP_INSTRUCTIONS` source.
 - Limited canonical batch expansion to explicit `workflow`, `skill`, or declared `sub_steps` inputs, preserving prior numbering behavior for plain flat batch inserts.
 - Updated usage, getting-started, and handbook docs to cover the new `add --from` workflow.
-- Updated `record-demo` step instructions to require diagnosis before skipping on failure — agents must check config, available fonts, and spike findings before reporting a non-blocking skip.
+- Updated `record-demo` step instructions to require diagnosis before skipping on failure -- agents must check config, available fonts, and spike findings before reporting a non-blocking skip.
 - Added `decision_notes.non_blocking_policy` to `record-demo` step catalog entry clarifying that "non-blocking" means "diagnose and retry before skipping," not "skip on first failure."
 
 ### Technical
@@ -946,7 +980,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.20.0] - 2026-03-05
 
 ### Added
-- Provider-specific session detection fallback in `ForkSessionLauncher` — when a provider doesn't return a native `session_id`, scans local session storage via `SessionFinder` to detect the forked session by prompt matching.
+- Provider-specific session detection fallback in `ForkSessionLauncher` -- when a provider doesn't return a native `session_id`, scans local session storage via `SessionFinder` to detect the forked session by prompt matching.
 - Session metadata file (`<root>-session.yml`) written for every fork run, capturing `session_id`, `provider`, `model`, and `completed_at` for traceability.
 - Stall error messages now include `Session: <id>` when session metadata is available, enabling direct trace to agent session.
 
@@ -1031,14 +1065,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.16.1] - 2026-03-04
 
 ### Fixed
-- Correct `.agents/skills` typo to `.agent/skills` in default config and `SkillAssignSourceResolver` — skill discovery now uses the canonical provider-neutral path
+- Correct `.agents/skills` typo to `.agent/skills` in default config and `SkillAssignSourceResolver` -- skill discovery now uses the canonical provider-neutral path
 
 ## [0.16.0] - 2026-03-04
 
 ### Added
-- New `onboard-base` catalog step — loads base project context via `ace-bundle project-base`
-- New `task-load` catalog step — loads task behavioral spec via `ace-bundle task://<taskref>`
-- Taskref placeholder substitution in catalog step descriptions — `<taskref>` in step descriptions is replaced with actual task reference during child instruction building
+- New `onboard-base` catalog step -- loads base project context via `ace-bundle project-base`
+- New `task-load` catalog step -- loads task behavioral spec via `ace-bundle task://<taskref>`
+- Taskref placeholder substitution in catalog step descriptions -- `<taskref>` in step descriptions is replaced with actual task reference during child instruction building
 
 ### Changed
 - Default assignment presets updated to use ace-task
@@ -1052,7 +1086,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.15.1] - 2026-03-01
 
 ### Added
-- Fork-run crash recovery protocol in drive workflow — detection, commit partial work, progress report, inject recovery steps, re-fork pattern for partial completion scenarios
+- Fork-run crash recovery protocol in drive workflow -- detection, commit partial work, progress report, inject recovery steps, re-fork pattern for partial completion scenarios
 
 ## [0.15.0] - 2026-02-28
 
@@ -1209,7 +1243,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.12.14] - 2026-02-22
 
 ### Added
-- Subtree guard step in drive workflow — driver reviews all fork report files before continuing to next step
+- Subtree guard step in drive workflow -- driver reviews all fork report files before continuing to next step
 - Report review instruction in split-subtree-root step template for fork context
 
 ## [0.12.13] - 2026-02-22
@@ -1282,13 +1316,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.12.1] - 2026-02-19
 
 ### Fixed
-- `reflect-verify-cycle` pair changed from `sequential` to `conditional` — prevents overriding optional strength of reflect-and-refactor
+- `reflect-verify-cycle` pair changed from `sequential` to `conditional` -- prevents overriding optional strength of reflect-and-refactor
 - Renamed `max_recursion` to `max_reruns` in replan config for clarity
 
 ## [0.12.0] - 2026-02-19
 
 ### Added
-- New `reflect-and-refactor` step in catalog — analyzes implementation against ATOM principles and executes targeted refactoring before PR creation
+- New `reflect-and-refactor` step in catalog -- analyzes implementation against ATOM principles and executes targeted refactoring before PR creation
 - Composition rules for reflect-and-refactor: ordering (after verify, before mark-done/release/retro), pairs (verify cycle, fix cycle, replan cycle), and conditional suggestion
 - `create-retro` step now consumes `findings-report` from reflect-and-refactor as recommended prerequisite
 - `implement-with-pr` recipe updated to include optional reflect-and-refactor step after work-on-task
@@ -1302,7 +1336,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- `assignment_state` now checks `completed` before `failed` — assignments where all steps are done/failed correctly report `:completed` instead of `:failed`
+- `assignment_state` now checks `completed` before `failed` -- assignments where all steps are done/failed correctly report `:completed` instead of `:failed`
 
 ### Added
 
@@ -1893,7 +1927,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- CLI `start` command crashes with positional argument (`ace-assign start job.yaml`) because `option :config` requires `--config` flag — renamed command to `create` with `argument :config`
+- CLI `start` command crashes with positional argument (`ace-assign start job.yaml`) because `option :config` requires `--config` flag -- renamed command to `create` with `argument :config`
 - `ace-bundle wfi://prepare-assignment` fails due to missing project-level wfi:// protocol registration
 
 ### Added

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,55 @@ 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.
+
+### Read accepted execution authority
+
+`attempt evidence` reads a managed coordinator-accepted receipt from immutable journal history without transitions, cache writes, or audit checkout creation. Supply the accepted attempt ID and exact canonical receipt digest. The trusted local operator or OS-enforced service verifies the actual executed outcome before accepting its receipt; worker-authored success claims cannot accept themselves. This reader consumes that attestation and does not execute a test or model.
+
+```sh
+ace-assign attempt evidence --attempt ATTEMPT --receipt-digest SHA256 --format json \
+  --kind check --check-name tests
+ace-assign attempt evidence --attempt ATTEMPT --receipt-digest SHA256 --format json \
+  --kind review-collection
+ace-assign attempt evidence --attempt ATTEMPT --receipt-digest SHA256 --format json \
+  --kind review-collection --historical-head EXACT_RECORDED_HEAD
+ace-assign attempt evidence --attempt ATTEMPT --receipt-digest SHA256 --format json \
+  --kind review-approval
+```
+
+A check proof requires the live candidate head, intact accepted artifacts, and the matching executed operation: `tests` uses `test`, other explicit check names use that operation name. Review collection requires an accepted `review-collect` operation with a passed `review-execution` outcome and the retained metadata/report/prompt artifacts. Review approval requires an ordinary accepted `review` operation with the approved independent reviewer verdict, exact head and retained report artifacts; collection proof cannot substitute for approval. Both collection and approval support an exact `--historical-head`. Historical review validation exposes `historical: true` and the recorded head; it preserves accepted source authority across head drift and cannot certify live checks. Unknown receipts, changed artifacts, unaccepted/unmanaged history, wrong purposes and stale current queries fail closed. Retain the configured evidence ref alongside durable review campaigns.
+
+### 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/evidence.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+require_relative "base"
+module Ace
+  module Assign
+    module CLI
+      module Commands
+        module Attempt
+          class Evidence < Ace::Support::Cli::Command
+            include Attempt::Base
+            desc "Read coordinator-accepted live execution or historical review authority"
+            option :attempt, required: true, desc: "Accepted execution attempt ID"
+            option :receipt_digest, required: true, desc: "Accepted receipt digest"
+            option :kind, default: "check", desc: "Evidence purpose: check, review-collection or review-approval"
+            option :check_name, default: "tests", desc: "Required check name (tests binds operation test)"
+            option :historical_head, desc: "Recorded collection/approval head for historical authority only"
+            option :format, default: "json", desc: "JSON evidence projection"
+
+            def call(**options)
+              raise Ace::Support::Cli::Error, "evidence supports --format json" unless options[:format] == "json"
+              emit_json(build_coordinator.evidence(attempt_id: options[:attempt], receipt_digest: options[:receipt_digest],
+                kind: options[:kind], check_name: options[:check_name], historical_head: options[:historical_head]))
+            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