ace-hitl 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64cb514390029a16b5a139d1d0db8da63b36c8fc08b21df9525d2f84bb94c1c3
-  data.tar.gz: 20118ea180abf1437a63d32c48c72581ca6e0aa115b79422b83f77aabc9afc04
+  metadata.gz: b03d376ceb86f080d28d686be092bc972d05fa6a03037ba45181ad4bcef124ba
+  data.tar.gz: eebcbcc9d94d2c4f929eb4a0e6559812170bc2c45c9c2da67fb4ed7fc7eaf2d9
 SHA512:
-  metadata.gz: e096433ca99b4cbc9455f21494d42d2cb08bc4dcf305e8e14d1e4c516a470ab8aa6a6e3eb723c3cb142570dc661197695cc30bb088c6c0713698ea6eda390446
-  data.tar.gz: d23bcb8c437f671d91d3661e3f27041939b4b3007acf680e19bb0c2c3315dd13f8250197cc60501786d4f7f875d20913db58c43694a65009f1442341f4a7982b
+  metadata.gz: 219f51b837aa9f69beb1faaaafdea4327bce68203e9a3fbcdce9d02d85d1c503984abe6d2855ad1643b94f3fdc115142718410f47dd031a98dfeb19d489a4a64
+  data.tar.gz: d149583ddc5c607e45b15bab620ae41716ebb764fb0e90807252747647edd6e3df1c1d935f171772ea28db1ca9d7bd7a78aaadfffb32a9ea6e0be7bcedce52fa

data/CHANGELOG.md

@@ -7,6 +7,14 @@ 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

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/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
 
@@ -354,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.26.0"
+    VERSION = "0.27.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Michal Czyz