ace-hitl 0.25.1 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a02c62f4939a60bf11cecc65e359987ef263fe520191bf42ac806326eb9cebaf
-  data.tar.gz: 998d00803a4a9b88e3f92bdd506288e4ca536339dd9cb328a9d79568be689e79
+  metadata.gz: b03d376ceb86f080d28d686be092bc972d05fa6a03037ba45181ad4bcef124ba
+  data.tar.gz: eebcbcc9d94d2c4f929eb4a0e6559812170bc2c45c9c2da67fb4ed7fc7eaf2d9
 SHA512:
-  metadata.gz: c5745f91860ee25c500cecdbaff63efec395c4588cd064fa0df225a8844abdadf4a3f8ab10ba8fde9a83817212a3924a799b2909b79ea244a68c4d7df2dbb46f
-  data.tar.gz: 64a33f6d3de1f218fd60702a0c37072b95688fef66c853b8c8c02f1936108ff156e79f8761a70bb4e9b6c263288de77a7b2478469ce494be53d7198351adad7e
+  metadata.gz: 219f51b837aa9f69beb1faaaafdea4327bce68203e9a3fbcdce9d02d85d1c503984abe6d2855ad1643b94f3fdc115142718410f47dd031a98dfeb19d489a4a64
+  data.tar.gz: d149583ddc5c607e45b15bab620ae41716ebb764fb0e90807252747647edd6e3df1c1d935f171772ea28db1ca9d7bd7a78aaadfffb32a9ea6e0be7bcedce52fa

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-11-12
+
+### Changed
+
+- Close applied decisions with an atomic lesson and expose consistent semantic report revisions.
+- Include the recipient in semantic observation for cross-project ownership filtering.
+
+
+## [0.26.0] - 2026-11-12
+
+### Added
+
+- Expose canonical local case cancellation through `cancel --case --reason`, preserving audited reasons and idempotence without fabricating human answers or contacting relay services.
+
 ## [0.25.1] - 2026-11-10
 
 ### Fixed

data/handbook/workflow-instructions/hitl.wf.md

@@ -165,3 +165,16 @@ Canonical lifecycle namespace: `hitl.event.*`
 - Blockers always produce canonical `HITL: <id> <path>` failure reason.
 - Human-required completion handoffs generate approval HITL events.
 - Resolved HITL events are archived only after successful resume dispatch.
+
+## Withdraw an obsolete local question
+
+If the reason for an unanswered or unapplied question no longer exists, cancel
+the exact local case with the evidence. Do not manufacture a human answer:
+
+```bash
+ace-hitl cancel <case-id> --case --reason "Obsolete: verified new review commit and active next round"
+```
+
+This records terminal cancellation in the canonical case. Repetition is a no-op;
+an applied effect must be closed instead. Without `--case`, cancel addresses the
+relay request owner; it never guesses a different owner on lookup failure.

data/lib/ace/hitl/cli/commands/cancel.rb

@@ -14,16 +14,29 @@ module Ace
           include Ace::Support::Cli::Base
           include LifecycleCommand
 
-          desc "Cancel one HITL relay request with an audited reason"
+          desc "Cancel a relay request or an explicit local case with an audited reason"
 
           argument :id, required: true, desc: "HITL relay request id"
 
+          option :case, type: :boolean, desc: "Cancel an exact local case instead of a relay request; requires --reason"
+
           option :reason, type: :string, desc: "Audited reason recorded in the public lifecycle record"
 
           option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
 
           def call(id:, **options)
-            emit(lifecycle_client.cancel(id, reason: options[:reason] || ""))
+            if options[:case]
+              reason = options[:reason].to_s.strip
+              raise Ace::Support::Cli::Error.new("local case cancellation requires --reason") if reason.empty?
+              state = Organisms::HitlManager.new.cancel_case(id, reason: reason)
+              emit({"case" => id, "state" => state.to_s})
+            else
+              emit(lifecycle_client.cancel(id, reason: options[:reason] || ""))
+            end
+          rescue Organisms::HitlManager::UnknownCaseError,
+            Organisms::HitlManager::AmbiguousReferenceError,
+            Organisms::HitlManager::LifecycleTransitionError => e
+            raise_lifecycle_error("not cancelled: #{e.message}")
           rescue Lifecycle::Error, Providers::ProviderUnavailableError => e
             raise_lifecycle_error(e.message)
           end

data/lib/ace/hitl/cli/commands/close.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "yaml"
 
 module Ace
   module Hitl
@@ -20,14 +21,17 @@ module Ace
 
           argument :case_id, required: true, desc: "Exact HITL case id"
 
+          option :lesson_file, desc: "YAML lesson: by, relation, takeaway, optional refs"
           option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
 
-          def call(case_id:, **)
-            state = Ace::Hitl::Organisms::HitlManager.new.close_case(case_id)
+          def call(case_id:, lesson_file: nil, **)
+            lesson = lesson_file ? YAML.safe_load_file(lesson_file, aliases: false) : nil
+            state = Ace::Hitl::Organisms::HitlManager.new.close_case(case_id, lesson: lesson)
             puts JSON.generate({"case" => case_id, "state" => state.to_s})
           rescue Ace::Hitl::Organisms::HitlManager::UnknownCaseError,
             Ace::Hitl::Organisms::HitlManager::AmbiguousReferenceError,
-            Ace::Hitl::Organisms::HitlManager::LifecycleTransitionError => e
+            Ace::Hitl::Organisms::HitlManager::LifecycleTransitionError,
+            Ace::Hitl::Organisms::HitlManager::LessonRefusedError, Psych::Exception, SystemCallError => e
             raise Ace::Support::Cli::Error.new("not closed: #{e.message}")
           end
         end

data/lib/ace/hitl/cli.rb

@@ -47,7 +47,7 @@ module Ace
         ["wait", "Wait for an answer on a specific HITL event"],
         ["deliver", "Deliver an answer (stdin) to a pending HITL relay request"],
         ["consume", "Wait for and consume the answer of one own HITL relay request"],
-        ["cancel", "Cancel one HITL relay request with an audited reason"],
+        ["cancel", "Cancel a relay request or explicit local case (--case)"],
         ["pending", "List answerable HITL relay requests (transport)"],
         ["states", "List public HITL lifecycle projections (transport)"],
         ["duty", "Project pending and escalated HITL requests (transport)"],

data/lib/ace/hitl/molecules/event_observation.rb

@@ -15,19 +15,23 @@ module Ace
 
         def call(scope: "current", limit: 500, owner: nil, in_folder: "next")
           events = incoming_events(scope: scope, limit: limit, owner: owner, in_folder: in_folder)
-          rows = events.map do |event|
-            semantic = [event.id, event.type, event.status, event.result, event.kind,
-              event.title, event.content, event.answer, event.questions,
-              Array(event.tags).sort, canonical(event.recipient), canonical(event.reply_to),
-              event.metadata.values_at("task", "assignment", "step", "step_name", "resume_instructions")]
-            {"key" => Digest::SHA256.hexdigest(event.file_path.to_s),
-             "id" => event.id, "revision" => Digest::SHA256.hexdigest(JSON.generate(canonical(semantic))),
-             "type" => event.type, "status" => event.status, "result" => event.result,
-             "task" => event.metadata["task"], "assignment" => event.metadata["assignment"]}
-          end
+          rows = events.map { |event| project(event) }
           {"schema" => "ace.hitl.observation/v1", "events" => rows.sort_by { |row| row["key"] }}
         end
 
+        # Project the same immutable event read by the report consumer.
+        def project(event)
+          semantic = [event.id, event.type, event.status, event.result, event.kind,
+            event.title, event.content, event.answer, event.questions,
+            Array(event.tags).sort, canonical(event.recipient), canonical(event.reply_to),
+            event.metadata.values_at("task", "assignment", "role", "step", "step_name", "resume_instructions")]
+          {"key" => Digest::SHA256.hexdigest(event.file_path.to_s),
+           "id" => event.id, "revision" => Digest::SHA256.hexdigest(JSON.generate(canonical(semantic))),
+           "type" => event.type, "status" => event.status, "result" => event.result,
+           "task" => event.metadata["task"], "assignment" => event.metadata["assignment"],
+           "recipient" => event.recipient}
+        end
+
         # Shared read boundary for observation and report consumers. Preserve
         # strict enumeration and recipient ownership in both paths.
         def incoming_events(scope: "current", limit: 500, owner: nil, in_folder: "next")

data/lib/ace/hitl/organisms/hitl_manager.rb

@@ -238,27 +238,27 @@ module Ace
         # close is a no-op; a close without the applied proof fails —
         # exactly-once belongs to the EFFECT, never to the close itself.
         # @return [Symbol] :closed or :duplicate
-        def close_case(ref, scope: nil)
+        def close_case(ref, scope: nil, lesson: nil)
           event = exact_case(ref, scope: scope)
-          ensure_answered!(event)
-
-          transition(event.file_path) do |frontmatter, _body|
+          rewrite_case(event.file_path) do |frontmatter, body|
             application = frontmatter["application"] || {}
-            case application["state"].to_s
-            when "", "pending"
+            next [:duplicate, nil, nil] if application["state"] == "closed"
+            unless frontmatter["answered"] == true && application["state"] == "applied"
               raise LifecycleTransitionError,
-                "case '#{event.id}' has no applied effect; close only after the " \
-                  "applied proof (ace-hitl apply CASE --ref OWNER_REF)"
-            when "applied"
-              frontmatter["application"] = application.merge("state" => "closed",
-                "closed_at" => timestamp)
-              :closed
-            when "closed"
-              :duplicate
-            else
-              raise LifecycleTransitionError,
-                "case '#{event.id}' is #{application["state"]}; it cannot be closed"
+                "case '#{event.id}' has no applied effect from a human decision; close only after ace-hitl apply CASE --ref OWNER_REF"
             end
+            if lesson
+              unless lesson.is_a?(Hash) && (lesson.keys.map(&:to_s) - %w[by relation takeaway refs]).empty?
+                raise LessonRefusedError, "lesson must contain by, relation, takeaway and optional refs"
+              end
+              fields = lesson.transform_keys(&:to_sym)
+              body = lesson_body(event.id, frontmatter, body, **fields)
+            end
+            if body.include?("## Suggestion") && !body.include?("## Lesson")
+              raise LessonRefusedError, "case '#{event.id}' has a suggestion; supply a lesson before closing"
+            end
+            frontmatter["application"] = application.merge("state" => "closed", "closed_at" => timestamp)
+            [:closed, frontmatter, body]
           end
         end
 
@@ -267,7 +267,7 @@ module Ace
         # Only from the not-yet-applied states — an applied effect is
         # history and is closed, not cancelled.
         # @return [Symbol] :cancelled or :duplicate
-        def cancel_case(ref, scope: nil)
+        def cancel_case(ref, scope: nil, reason: nil)
           event = exact_case(ref, scope: scope)
 
           transition(event.file_path) do |frontmatter, _body|
@@ -276,6 +276,7 @@ module Ace
             when "", "pending"
               frontmatter["application"] = {"state" => "cancelled",
                 "cancelled_at" => timestamp}
+              frontmatter["application"]["reason"] = reason.to_s.strip unless reason.to_s.strip.empty?
               :cancelled
             when "cancelled"
               :duplicate
@@ -353,40 +354,33 @@ module Ace
         # @return [Symbol] :written or :duplicate
         def add_lesson(ref, by:, relation:, takeaway:, refs: [], scope: nil)
           event = exact_case(ref, scope: scope)
-
           rewrite_case(event.file_path) do |frontmatter, body|
             refuse_terminal!(frontmatter, event.id)
-            unless body.include?("## Suggestion")
-              raise LessonRefusedError,
-                "case '#{event.id}' carries no suggestion; there is nothing to compare"
-            end
-            unless frontmatter["answered"] == true
-              raise LessonRefusedError,
-                "case '#{event.id}' has no accepted human decision to learn from"
-            end
-
-            if body.include?("## Lesson")
-              next [:duplicate, nil, nil] if lesson_matches?(body, by, takeaway)
-
-              raise LessonRefusedError,
-                "case '#{event.id}' already carries a lesson; reprocessing does not multiply them"
-            end
-
-            unless %w[accepted rejected modified].include?(relation.to_s)
-              raise LessonRefusedError,
-                "relation must be accepted, rejected or modified (got '#{relation}')"
-            end
-
-            decision_refs = ["case:#{event.id}", "suggestion:#{event.id}-s1"]
-            decision_refs << "decision:#{frontmatter["answered_at"]}" if frontmatter["answered_at"]
-            lesson = {"id" => "#{event.id}-l1", "author" => by.to_s,
-              "relation" => relation.to_s, "takeaway" => takeaway.to_s.strip,
-              "refs" => Array(refs).map(&:to_s).reject(&:empty?).push(*decision_refs).uniq,
-              "at" => timestamp}
-            updated = Molecules::HitlLessonEditor.apply(body, lesson)
+            updated = lesson_body(event.id, frontmatter, body,
+              by: by, relation: relation, takeaway: takeaway, refs: refs)
+            updated == body ? [:duplicate, nil, nil] : [:written, frontmatter, updated]
+          end
+        end
 
-            [:written, frontmatter, updated]
+        private def lesson_body(id, frontmatter, body, by: nil, relation: nil, takeaway: nil, refs: [])
+          unless body.include?("## Suggestion") && frontmatter["answered"] == true
+            raise LessonRefusedError, "case '#{id}' has no suggestion or no accepted human decision"
+          end
+          unless %w[accepted rejected modified].include?(relation.to_s) &&
+              !by.to_s.strip.empty? && !takeaway.to_s.strip.empty? && refs.is_a?(Array)
+            raise LessonRefusedError, "lesson requires by, takeaway, relation accepted/rejected/modified and an array of refs"
+          end
+          if body.include?("## Lesson")
+            return body if lesson_matches?(body, by, takeaway) &&
+              body_section(body, "Lesson").match?(/^relation: #{Regexp.escape(relation.to_s)}$/)
+            raise LessonRefusedError, "case '#{id}' already carries a lesson; reprocessing does not multiply them"
           end
+          decision_refs = ["case:#{id}", "suggestion:#{id}-s1"]
+          decision_refs << "decision:#{frontmatter['answered_at']}" if frontmatter["answered_at"]
+          lesson = {"id" => "#{id}-l1", "author" => by.to_s,
+            "relation" => relation.to_s, "takeaway" => takeaway.to_s.strip,
+            "refs" => refs.map(&:to_s).reject(&:empty?).push(*decision_refs).uniq, "at" => timestamp}
+          Molecules::HitlLessonEditor.apply(body, lesson)
         end
 
         # Decision history for the advisory agent's NEXT suggestion (task

data/lib/ace/hitl/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Hitl
-    VERSION = "0.25.1"
+    VERSION = "0.27.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.25.1
+  version: 0.27.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-11-10 00:00:00.000000000 Z
+date: 2026-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-hitl-contract