ace-hitl 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 96a4def785b91ef54a793fc989a19dc9e716dbf806129d82351bcf487245383c
+  data.tar.gz: 8f611901bbe6fc4ebf003baab73f0dff2de801c98f260011ceeeb4b655465af3
+SHA512:
+  metadata.gz: 7a84118d6cbdd5fed6e868e0b2eff28dcdcc8cc41692feea61dfcd79bd37e84cc42f81d4dd63af122a42007770995cc85b0fbf29d6408d83cf5668997f803052
+  data.tar.gz: 857c322f44dab838002765b159112906d42f7708a308037fb5f5618c47cc21b5cd6547fec3b55e23ed7fc7306b583c8b17e9b94e71d822929290054c2bf612b3

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

@@ -0,0 +1,3 @@
+hitl:
+  root_dir: .ace-local/hitl
+  default_kind: clarification

data/.ace-defaults/nav/protocols/skill-sources/ace-hitl.yml

@@ -0,0 +1,13 @@
+---
+# Skill Sources Protocol Configuration for ace-hitl gem
+# This enables canonical skill discovery from the installed ace-hitl gem
+
+name: ace-hitl
+type: gem
+description: Canonical skills from ace-hitl gem
+priority: 10
+
+config:
+  relative_path: handbook/skills
+  pattern: "*/SKILL.md"
+  enabled: true

data/.ace-defaults/nav/protocols/wfi-sources/ace-hitl.yml

@@ -0,0 +1,13 @@
+---
+# WFI Sources Protocol Configuration for ace-hitl gem
+# This enables workflow discovery from the installed ace-hitl gem
+
+name: ace-hitl
+type: gem
+description: HITL workflow instructions from ace-hitl gem
+priority: 10
+
+config:
+  relative_path: handbook/workflow-instructions
+  pattern: "*.wf.md"
+  enabled: true

data/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+All notable changes to `ace-hitl` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.8.0] - 2026-04-02
+
+### Changed
+
+- Changed `ace-hitl list` default status behavior to include all statuses in the selected folder scope when `--status` is omitted (instead of implicitly filtering to `pending`).
+- Updated list row rendering to task-like compact output with leading status icons for each HITL event.
+
+### Technical
+
+- Updated list command/docs/workflow wording and command-level tests to reflect explicit pending filtering (`--status pending`) and icon-led row assertions.
+
+## [0.7.0] - 2026-04-02
+
+### Changed
+
+- Renamed the canonical HITL object terminology from "item" to "event" across CLI help/output, package docs, and workflow instructions.
+- Performed immediate API/contract cutover for `HitlManager` resolution payloads from `:item` to `:event`.
+
+### Added
+
+- Added a list-output stats footer (`HITL Events: ...`) for `ace-hitl list`, including empty-result output and filtered `X of Y` summaries.
+- Added explicit lifecycle event naming contract documentation under the `hitl.event.*` namespace.
+
+## [0.6.0] - 2026-04-02
+
+### Changed
+
+- Switched the default HITL runtime root from `.ace-hitl` to `.ace-local/hitl` to align with ACE local-artifact layout conventions.
+
+### Technical
+
+- Updated scope and status test fixtures that embedded legacy `.ace-hitl` paths to use `.ace-local/hitl`.
+
+## [0.5.0] - 2026-04-02
+
+### Added
+
+- Added `ace-hitl wait <id>` polling support with per-event lease metadata (`waiter_*`) so agents wait only on their own HITL question IDs by default.
+- Added requester session metadata capture (`requester_provider`, `requester_model`, `requester_session_id`) from assignment session traces during HITL creation.
+- Added resume fallback dispatch plumbing for answered items through provider session resume and command fallback paths.
+
+### Changed
+
+- Extended `ace-hitl update` with `--resume` to dispatch answer handoff only when no active waiter lease is detected.
+- Updated HITL workflow and usage docs to make polling the default reliability path and resume dispatch the explicit fallback path.
+
+### Technical
+
+- Added CLI/manager regression coverage for wait timeout/success paths and resume dispatch skip/dispatch behavior.
+
+## [0.4.3] - 2026-04-02
+
+### Changed
+
+- Switched `ace-hitl` configuration loading to ACE shared namespace resolution (`Ace::Support::Config`), with defaults fallback behavior for resilience.
+- Added a package-owned `handbook/` skeleton (`agents/`, `guides/`, `skills/`, `templates/`, `workflow-instructions/`) for architectural consistency.
+
+### Fixed
+
+- Collapsed combined `ace-hitl update` metadata and answer mutations into one locked read/mutate/write cycle to avoid double write passes.
+
+### Technical
+
+- Added `ace-support-config` as a runtime dependency in `ace-hitl.gemspec`.
+
+## [0.4.2] - 2026-04-01
+
+### Fixed
+
+- Made `ace-hitl update` honor scoped multi-worktree resolution semantics (`--scope`) consistent with `show`.
+- Prevented duplicate HITL IDs during rapid event creation by regenerating IDs when collisions are detected.
+- Narrowed loader exception handling so programming errors surface instead of being silently treated as not-found.
+
+### Technical
+
+- Added CLI regression coverage for scoped `update` behavior and ID collision avoidance.
+
+## [0.4.1] - 2026-04-01
+
+### Technical
+
+- Updated CLI version contract tests to assert the current `Ace::Hitl::VERSION` (`0.4.0`) after the 0.4.0 release line.
+
+## [0.4.0] - 2026-04-01
+
+### Added
+
+- Added smart multi-worktree scope resolution for `ace-hitl list` and `ace-hitl show` with explicit `--scope current|all`.
+- Added context-aware default scope behavior: linked worktrees default to current scope, main checkout defaults to all-scope operator view.
+- Added strict all-scope ambiguity handling for `show` with candidate path reporting.
+
+### Changed
+
+- Changed `ace-hitl list` default behavior to show only `pending` items when `--status` is omitted.
+- Changed `ace-hitl show` to perform local-first lookup with implicit all-scope fallback only when scope is not explicitly provided.
+- Changed show output to include explicit resolved-location details for cross-worktree item resolution.
+- Updated usage and README documentation to describe local-first HITL semantics versus global `ace-overseer` dashboard usage.
+
+## [0.3.0] - 2026-04-01
+
+### Added
+
+- Implemented full HITL event store behavior with package-owned model/molecules/manager flow.
+- Added complete CLI behavior for `create`, `list`, `show`, and `update` with filtering and mutation options.
+- Added usage documentation for end-to-end item management flows.
+
+### Fixed
+
+- Corrected answer section updates to handle empty `## Answer` blocks and persist answer text reliably.
+- Updated CLI tests to align with current package version and answer-write behavior.
+
+## [0.2.0] - 2026-04-01
+
+### Added
+
+- Initial package skeleton for `ace-hitl`.
+- Root and package executables (`bin/ace-hitl`, `ace-hitl/exe/ace-hitl`).
+- Minimal CLI registry for `list`, `show`, `create`, and `update`.
+- Baseline docs and config scaffold.

data/README.md

@@ -0,0 +1,42 @@
+# ace-hitl
+
+`ace-hitl` manages ACE human-in-the-loop (HITL) events in `.ace-local/hitl/`.
+
+Canonical workflow and skill for agents:
+
+- Workflow: `wfi://hitl`
+- Skill: `as-hitl`
+
+## Commands
+
+- `ace-hitl create` creates a HITL event
+- `ace-hitl list` lists HITL events with filters (`--scope current|all`, all statuses by default)
+- `ace-hitl show` renders event details, path, or raw content (`--scope current|all`)
+- `ace-hitl update` updates frontmatter, answer content, and folder location
+- `ace-hitl wait` polls a specific HITL event until answered (`--poll-every`, `--timeout`)
+
+`ace-hitl` is a blocker-resolution tool, not a global dashboard:
+
+- linked worktree default: local (`--scope current`)
+- main checkout default: operator view (`--scope all`)
+
+Use `ace-overseer status` for a global worktree dashboard.
+
+## Examples
+
+```bash
+ace-hitl list
+ace-hitl list --scope all
+ace-hitl create "Which auth strategy?" --kind decision --question "JWT or sessions?"
+ace-hitl show abc123 --content
+ace-hitl show abc123 --scope current
+ace-hitl update abc123 --answer "Use JWT with server-side refresh tokens."
+ace-hitl wait abc123
+ace-hitl update abc123 --answer "Use JWT with server-side refresh tokens." --resume
+```
+
+## Ownership Boundary
+
+`ace-hitl` owns HITL-specific event semantics and markdown contract.
+
+`ace-support-items` remains generic support infrastructure and should not absorb HITL-specific domain behavior.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

data/docs/demo/ace-hitl-scope-and-answer.tape.yml

@@ -0,0 +1,37 @@
+---
+description: Showcase ace-hitl scope-aware CLI surface and answer markdown preservation regression coverage
+tags:
+- ace-hitl
+- feature-demo
+- scope
+settings:
+  font_size: 16
+  width: 1100
+  height: 620
+  format: gif
+setup:
+- sandbox
+- copy-fixtures
+scenes:
+- name: Demo context
+  commands:
+  - type: cat fixtures/demo-context.md
+    sleep: 4s
+- name: Show scope-aware list/show CLI flags
+  commands:
+  - type: clear
+    sleep: 1s
+  - type: ace-hitl list --help
+    sleep: 5s
+  - type: ace-hitl show --help
+    sleep: 5s
+- name: Verify ambiguity and heading-preservation behavior
+  commands:
+  - type: clear
+    sleep: 1s
+  - type: ace-test test/commands/hitl_cli_test.rb --filter test_show_scope_all_errors_on_ambiguous_ref_with_candidates
+    sleep: 5s
+  - type: ace-test test/commands/hitl_cli_test.rb --filter test_update_answer_preserves_markdown_headings_in_answer_body
+    sleep: 5s
+teardown:
+- cleanup

data/docs/demo/fixtures/demo-context.md

@@ -0,0 +1,7 @@
+# ace-hitl scope + answer integrity demo
+
+This demo highlights two user-facing outcomes from PR #275:
+- `ace-hitl list/show` expose explicit scope controls for multi-worktree reads.
+- Answer updates preserve markdown headings inside `## Answer` content.
+
+Verification commands in the demo run focused CLI-contract tests.

data/docs/usage.md

@@ -0,0 +1,112 @@
+---
+doc-type: user
+title: ace-hitl Usage Guide
+purpose: Practical CLI usage reference for ace-hitl event creation, triage, and resolution
+  flows.
+ace-docs:
+  last-updated: '2026-04-02'
+  last-checked: '2026-04-02'
+---
+
+# ace-hitl Usage
+
+Canonical handbook resources:
+
+- Workflow: `wfi://hitl`
+- Skill: `as-hitl`
+
+Runtime store default: `.ace-local/hitl/` (legacy `.ace-hitl/` is no longer used as default).
+
+## Create
+
+```bash
+ace-hitl create "Which auth strategy?" \
+  --kind decision \
+  --question "JWT or sessions?" \
+  --question "Refresh token storage?" \
+  --assignment 8qr5kx \
+  --step 020 \
+  --step-name implement-auth \
+  --resume "/as-assign-drive 8qr5kx"
+```
+
+Common completion-attention handoff:
+
+```bash
+ace-hitl create "Review completed assignment results" \
+  --kind approval \
+  --question "Please confirm next action for 8qr5kx." \
+  --assignment 8qr5kx \
+  --step completion \
+  --step-name assignment-complete \
+  --resume "/as-assign-drive 8qr5kx"
+```
+
+## List
+
+`ace-hitl list` is local-first by default:
+
+- in a linked worktree: behaves like `--scope current`
+- in the main checkout: behaves like `--scope all`
+- if `--status` is omitted: includes all statuses in the selected folder scope
+
+```bash
+ace-hitl list
+ace-hitl list --scope current
+ace-hitl list --scope all
+ace-hitl list --status pending
+ace-hitl list --kind decision
+ace-hitl list --kind clarification --status pending
+ace-hitl list --tags auth,security
+ace-hitl list --in archive
+```
+
+## Show
+
+`ace-hitl show` also accepts `--scope current|all`.
+Without `--scope`, lookup is local-first; if not found and smart scope is active, it retries across all worktrees.
+When lookup resolves outside the current worktree, output includes an explicit `Resolved Location:` line.
+When using `--scope all`, ambiguous matches return an error with candidate paths so the operator can select the intended event explicitly.
+
+```bash
+ace-hitl show abc123
+ace-hitl show abc123 --scope current
+ace-hitl show abc123 --scope all
+ace-hitl show abc123 --path
+ace-hitl show abc123 --content
+```
+
+## Update
+
+```bash
+ace-hitl update abc123 --set status=in-progress
+ace-hitl update abc123 --add tags=reviewed
+ace-hitl update abc123 --remove tags=stale
+ace-hitl update abc123 --answer "Use JWT with server-side refresh tokens."
+ace-hitl update abc123 --move-to archive
+ace-hitl update abc123 --move-to next
+ace-hitl update abc123 --answer "close the assignment" --resume
+```
+
+## Wait (Polling Default)
+
+Wait only for a specific HITL id. This is the default reliability path for the requester agent.
+
+```bash
+ace-hitl wait abc123
+ace-hitl wait abc123 --poll-every 600 --timeout 14400
+ace-hitl wait abc123 --scope current
+```
+
+## Lifecycle Event Names
+
+Canonical namespace for HITL lifecycle signaling:
+
+- `hitl.event.created`
+- `hitl.event.answered`
+- `hitl.event.wait_started`
+- `hitl.event.wait_timed_out`
+- `hitl.event.resume_dispatched`
+- `hitl.event.resume_skipped_waiter_active`
+- `hitl.event.resume_failed`
+- `hitl.event.archived`

data/exe/ace-hitl

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ace/hitl"
+
+args = ARGV.empty? ? ["--help"] : ARGV
+
+trap("INT") { exit 130 }
+
+begin
+  Ace::Hitl::HitlCLI.start(args)
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit(e.exit_code)
+rescue ArgumentError => e
+  warn "Error: #{e.message}"
+  exit(1)
+end

data/handbook/README.md

@@ -0,0 +1,14 @@
+# ace-hitl Handbook
+
+Package-owned handbook skeleton for HITL workflows, skills, and guides.
+
+- `agents/`: package-local agent definitions
+- `workflow-instructions/`: canonical HITL workflows (`.wf.md`)
+- `skills/`: canonical skill definitions (`SKILL.md`)
+- `guides/`: package-specific guidance docs (`.g.md`)
+- `templates/`: reusable prompt/doc templates
+
+Current canonical entries:
+
+- `wfi://hitl`
+- `as-hitl`

data/handbook/skills/as-hitl/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: as-hitl
+description: Manage human-attention blockers and completion handoffs with ace-hitl
+# bundle: wfi://hitl
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-hitl:*)
+  - Bash(ace-assign:*)
+  - Bash(ace-bundle:*)
+  - Read
+argument-hint: "[create|list|show|update] [options]"
+last_modified: 2026-04-02
+source: ace-hitl
+integration:
+  targets:
+    - claude
+    - codex
+    - gemini
+    - opencode
+    - pi
+  providers: {}
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://hitl
+---
+
+Load and run `ace-bundle wfi://hitl` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

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

@@ -0,0 +1,110 @@
+---
+doc-type: workflow
+title: HITL Workflow
+purpose: Standardize human-attention handling for blocked and completed work using ace-hitl events.
+ace-docs:
+  last-updated: '2026-04-02'
+  last-checked: '2026-04-02'
+---
+
+# HITL Workflow
+
+## Goal
+
+Use `ace-hitl` as the canonical contract whenever agent flow needs explicit human attention.
+
+## When To Use HITL
+
+Create a HITL event in exactly two cases:
+
+1. **Blocker requiring human judgment** (ambiguity, product decision, policy/approval gate).
+2. **Work is complete but explicit user attention is required** before follow-up actions.
+
+Do not create HITL events for routine status updates that do not require user action.
+
+## Commands
+
+### 1) Create a blocker HITL
+
+```bash
+ace-hitl create "Need product decision" \
+  --kind decision \
+  --question "Should retries be visible?" \
+  --assignment <assignment-id> \
+  --step <step-number> \
+  --step-name <step-name> \
+  --resume "/as-assign-drive <assignment-id>"
+```
+
+If the active assignment step is blocked, fail it using canonical format:
+
+```bash
+ace-assign fail --message "HITL: <hitl-id> <hitl-path>" --assignment "<assignment-id>"
+```
+
+### 2) Create a completion-attention HITL
+
+```bash
+ace-hitl create "Review completed assignment results" \
+  --kind approval \
+  --question "Please confirm next action for <assignment-id>." \
+  --assignment <assignment-id> \
+  --step completion \
+  --step-name assignment-complete \
+  --resume "/as-assign-drive <assignment-id>"
+```
+
+### 3) Discover HITL work
+
+```bash
+ace-hitl list
+ace-hitl list --scope current
+ace-hitl list --scope all
+ace-hitl list --status pending
+```
+
+### 4) Resolve and archive
+
+```bash
+ace-hitl show <hitl-id>
+ace-hitl update <hitl-id> --answer "<human decision>"
+```
+
+Polling is the default reliability path for the requesting agent:
+
+```bash
+ace-hitl wait <hitl-id>
+```
+
+If the waiter is no longer active, operator fallback can dispatch resume:
+
+```bash
+ace-hitl update <hitl-id> --answer "<human decision>" --resume
+```
+
+## Completion Contract
+
+After answer is applied:
+
+- Continue normal assignment retry/resume flow.
+- Keep `ace-assign` mechanics unchanged (no paused assignment state).
+- Archive HITL event after resolution.
+
+## Event Names
+
+Canonical lifecycle namespace: `hitl.event.*`
+
+- `hitl.event.created`
+- `hitl.event.answered`
+- `hitl.event.wait_started`
+- `hitl.event.wait_timed_out`
+- `hitl.event.resume_dispatched`
+- `hitl.event.resume_skipped_waiter_active`
+- `hitl.event.resume_failed`
+- `hitl.event.archived`
+
+## Success Criteria
+
+- 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.

data/lib/ace/hitl/atoms/hitl_file_pattern.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Atoms
+      class HitlFilePattern
+        FILE_EXTENSION = ".hitl.s.md"
+        FILE_GLOB = "*#{FILE_EXTENSION}"
+
+        def self.folder_name(id, slug)
+          slug.nil? || slug.empty? ? id : "#{id}-#{slug}"
+        end
+
+        def self.filename(id, slug)
+          "#{folder_name(id, slug)}#{FILE_EXTENSION}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/atoms/hitl_id_formatter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "ace/b36ts"
+
+module Ace
+  module Hitl
+    module Atoms
+      class HitlIdFormatter
+        def self.generate(time = Time.now.utc)
+          Ace::B36ts.encode(time, format: :"2sec")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        class Create < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Create HITL event"
+
+          argument :title, required: false, desc: "HITL event title"
+
+          option :kind, type: :string, aliases: %w[-k], desc: "Kind: clarification, decision, approval"
+          option :question, type: :string, repeat: true, aliases: %w[-Q], desc: "Question line (repeatable)"
+          option :tags, type: :string, aliases: %w[-T], desc: "Comma-separated tags"
+          option :assignment, type: :string, desc: "Assignment reference"
+          option :step, type: :string, desc: "Step number"
+          option :"step-name", type: :string, desc: "Step name"
+          option :resume, type: :string, desc: "Resume instructions"
+          option :"move-to", type: :string, aliases: %w[-m], desc: "Target folder (archive, next)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(title: nil, **options)
+            unless title && !title.strip.empty?
+              raise Ace::Support::Cli::Error.new("Title required")
+            end
+
+            kind = options[:kind]
+            validate_kind!(kind) if kind
+
+            questions = Array(options[:question]).map(&:strip).reject(&:empty?)
+            tags = parse_tags(options[:tags])
+
+            manager = Ace::Hitl::Organisms::HitlManager.new
+            event = manager.create(
+              title,
+              kind: kind,
+              questions: questions,
+              tags: tags,
+              assignment: options[:assignment],
+              step: options[:step],
+              step_name: options[:"step-name"],
+              resume_instructions: options[:resume],
+              move_to: options[:"move-to"]
+            )
+
+            folder_info = event.special_folder ? " (#{event.special_folder})" : ""
+            puts "HITL event created: #{event.id} #{event.title}#{folder_info}"
+            puts "  Path: #{event.file_path}"
+          end
+
+          private
+
+          def validate_kind!(kind)
+            allowed = %w[clarification decision approval]
+            return if allowed.include?(kind)
+
+            raise Ace::Support::Cli::Error.new("Invalid kind '#{kind}'. Allowed: #{allowed.join(", ")}")
+          end
+
+          def parse_tags(raw)
+            return [] unless raw
+
+            raw.split(",").map(&:strip).reject(&:empty?)
+          end
+        end
+      end
+    end
+  end
+end