ace-handbook 0.36.2 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7e0dbdef987c766d7465a9d825e42109f9e0cca131cbd72cbe86fd722ab3788
-  data.tar.gz: ebb309bf73b17f5fe41cdcf0ffeb7ecab58fee5f8b1034b4e8465a1921eb567d
+  metadata.gz: 9985cf345994f51d958a0d848c532a7e7cb4f98baa3dac71d9de06e2cff578f7
+  data.tar.gz: aba7c5dc35f70aa7edf202bdf2ebe76ac65936c2ed44fbaa596675e79399afbe
 SHA512:
-  metadata.gz: 62494535cfe334c728174675f69529e16a768875ca05876693a20a8e48e502f1a0c4ae8f575c48e7fa718f4435dbd6816b4a0dd5067eb132e6134d576053b152
-  data.tar.gz: 56b1fe6f7c586f89b294c267ab0125a3e528fcba74135d75b314027f54f611f6a0d173be3c77bdcdb7e957e9c86a6ea48d9e472b6af0c9707612bc2d7ddfabf9
+  metadata.gz: ba495d1f76e1997a523c998c41471ba5750f0e852e8ac2fdd84b3b7d27b96da6b8c084a07854e32be0349caf10a19d48ff69aff05862d6331982a18ec1e08418
+  data.tar.gz: cd38950c60eeb374135da2e02395211f0d023e3f8f568ae59b3a0b4aacd343adbb76b5a39219850fa555b8c8f3e68b8838ddf2f912c1e84dd647ed00bbfdc4cf

data/CHANGELOG.md

@@ -5,7 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.37.0] - 2026-10-30
+
+### Fixed (review rounds 3/3b)
+
+- `resolve_named_package` raises a typed `UnresolvableExtensionsPackageError`
+  in auto mode when a configured `extensions_package` resolves nowhere;
+  installed mode keeps its fallback rule.
+
+### Added
+
+- `wfi://release/publisher` (task 8xs.t.pu0.9): the publisher coworker role —
+  existing release workflows, ace-lab auth access, OTP as a secret HITL ask,
+  resume that recognizes already-published artifacts by version+digest, and
+  the hand-off to install/verify/record.
+- `wfi://release/cycle-record`: the delivery-cycle evidence record contract
+  (task/cycle, source HEAD, bound review/test evidence, publish
+  versions+digests, runtime paths and outcome) through a normal record-only
+  PR that never triggers a release by itself.
+- Provider manifests can declare `extensions_package`: extension assets project
+  from the named asset package (local sibling directory first, installed gem
+  second), enabling gem-backed extension shipping such as `ace-wake` for the pi
+  provider (task 8xs.t.pu0.0); in `ACE_TOOLCHAIN=installed` mode the packaged
+  extension source is always the installed gem, never the checkout directory.
 
 ## [0.36.2] - 2026-10-27
 

data/handbook/workflow-instructions/release/cycle-record.wf.md

@@ -0,0 +1,61 @@
+---
+name: release-cycle-record
+description: Write the integrated delivery-cycle evidence record into .ace-tasks/_records through a normal reviewed record-only PR
+allowed-tools: Bash, Read
+doc-type: workflow
+title: Delivery Cycle Record Workflow
+purpose: Bind the record contract — one reviewed document per delivery cycle naming task/cycle, source HEAD, review/test evidence, publish versions and digests, runtime paths and the runtime outcome — without starting a new release or a recursive record.
+ace-docs:
+  last-updated: '2026-10-30'
+  last-checked: '2026-10-30'
+---
+# Delivery Cycle Record Workflow
+
+## Goal
+
+Close a delivery cycle with a durable, reviewed Git record of the WHOLE path:
+sources, integration, publication, installation, runtime outcome (task
+8xs.t.pu0.9). The record is evidence, not a control queue: the live cycle
+state stays in its task/assignment until the record is integrated.
+
+## Instructions
+
+### 1) Gather facts from the owners — never from memory
+
+Every value comes from evidence produced by the owners:
+
+- task/cycle reference and the managing assignment;
+- source HEAD (the merged candidate) and the merge proof;
+- review/test evidence: the independent reviewer verdict, the executed test
+  commands with their results, and the HEAD each was bound to
+  (`ace-coworker gate` inputs);
+- publication: package versions and artifact digests from the artifact
+  repository (checked, not assumed — an interrupted publish must have been
+  reconciled first);
+- runtime: the installed gem/CLI/extension paths and versions the target
+  account actually ran, and the acceptance result.
+
+Do not fabricate identifiers, SHAs, or version endings. If a fact is
+missing, the cycle is NOT complete — say so in the task and stop.
+
+### 2) Write the record
+
+Place one document under `.ace-tasks/_records/<dated-cycle-slug>/` with the
+sections: Goal, Source (HEAD, PR), Review & Tests (bound heads, verdicts,
+commands), Publication (versions + digests), Installation & Runtime
+(paths, versions, acceptance under the target account), Outcome (closed or
+explicitly open with the blocking reason and resume point).
+
+### 3) Integrate through a normal review
+
+The record goes through a record-only PR with the ordinary review/integration
+gate. It does NOT trigger another release (no product change) and requires no
+recursive record of its own merge. After the record's integration, mark the
+task done (`ace-task update <ref> --set status=done` — archive per the task
+family's convention).
+
+## Boundaries
+
+- No secrets, OTP values, or tokens in the record.
+- A failed or partially deployed cycle keeps the task open with a resumable
+  blocking state; the record documents the stage truthfully instead.

data/handbook/workflow-instructions/release/publisher.wf.md

@@ -0,0 +1,90 @@
+---
+name: release-publisher
+description: Publisher coworker role — deliver a merged change through release inventory, bumps, build, publication (OTP via a secret HITL ask), and hand off to install/verify
+allowed-tools: Bash, Read
+doc-type: workflow
+title: Release Publisher Workflow
+purpose: Bind the publisher role's delivery pass: existing release workflows, short-lived access via ace-lab auth, OTP as a secret HITL case whose wake never carries the value, resume that recognizes already-published artifacts, and the cycle record contract.
+ace-docs:
+  last-updated: '2026-10-30'
+  last-checked: '2026-10-30'
+---
+# Release Publisher Workflow
+
+## Goal
+
+Deliver a MERGED change to the installed runtime and hand the cycle to
+install/verify and the record (task 8xs.t.pu0.9). You are the publisher
+coworker: you run the project's existing release workflows — never a private
+variant.
+
+## Instructions
+
+Run the loaded workflow as the source of truth and execute it end-to-end
+instead of only summarizing it.
+
+### 1) Access
+
+Request the publisher profile through `ace-lab auth` (task 8xs.t.pu0.7):
+
+```bash
+ace-lab auth request --profile <publisher-profile> --role publisher \
+  --task <task> --assignment <assignment> --repo <repo>
+```
+
+Verify principal, repo, scope and use-until before each operation. Static env
+profiles expose process-scoped values only and are never proof of remote
+expiry. If a wait needs a paused access window, do NOT extend it — request a
+fresh lease after the answer.
+
+### 2) Release preparation
+
+Use the existing release workflows exactly: inventory the modified packages,
+version bumps, changelogs, and the coordinated release commit
+(`ace-bundle wfi://release/local` in ACE-style repos). Do not close the task
+at merge when runtime delivery is still required.
+
+### 3) OTP through HITL — a SECRET ask
+
+When publication needs an OTP, ask with the explicit secret flag:
+
+```bash
+ace-hitl ask "OTP for gem push" --to captain --kind approval --secret \
+  --task <task> --question "One-time code for <publisher step>"
+```
+
+`--secret` marks the case AT CREATION (no title heuristics): the armed wake
+carries the CASE REFERENCE ONLY — the value never passes through the model.
+End the turn after asking; there is no deadline on the Captain's answer and
+waiting is never a model loop. Read the value from the case file through the
+existing wrapper (the publishing tool consumes it via env/stdin, never argv).
+A rejected or expired OTP needs a NEW case — never replay an old value.
+
+### 4) Publication and resume
+
+Publish through the project's existing publication queue. If publication was
+interrupted, first check the artifact repository: a matching version AND
+digest means ALREADY PUBLISHED — continue with the missing steps only; a
+version/digest conflict BLOCKS (never overwrite a version, never bump around
+a conflict as a workaround). A failed publication leaves an explicit,
+resumable state — never pretend a partially deployed cycle is complete.
+
+### 5) Install, verify, record
+
+After publication, the lab side runs `ace-lab install` convergence (manifest,
+gem versions, dependency closure, extension projections) and the runtime
+acceptance under the target account — separately evidenced from source and
+integration. The cycle's evidence record then goes to
+`.ace-tasks/_records/` through a normal reviewed record-only PR
+(`ace-bundle wfi://release/cycle-record`). The record-only PR does not
+trigger another release without a product change and needs no recursive
+record of its own merge. The task closes only after the successful runtime
+acceptance AND the integrated record.
+
+## Boundaries
+
+- Source work happens on the host; the lab installs published artifacts.
+- Secrets (API keys, OTP) live only in the allowed wrapper/env and the secret
+  HITL case — never in prompts, reports, argv, or the wake.
+- The live cycle state stays in the existing task/assignment; `_records` is
+  the final reviewed evidence write-up, not a control queue.

data/lib/ace/handbook/atoms/provider_registry.rb

@@ -2,6 +2,7 @@
 
 require "date"
 require "yaml"
+require "ace/support/cli/toolchain"
 
 module Ace
   module Handbook
@@ -42,6 +43,23 @@ module Ace
           manifest(provider)["extensions_dir"]
         end
 
+        # Source root for a provider's extension assets: the package the
+        # manifest names through `extensions_package` (an asset package
+        # such as ace-wake that is NOT an integration package). The named
+        # package resolves like every other package: the sibling package
+        # directory in the local project first, the installed gem second
+        # — so a monorepo checkout projects the working tree and an
+        # installed lab projects the exact installed gem (task
+        # 8xs.t.pu0.0). In auto mode an unresolvable package raises; in
+        # installed mode the manifest's own package root is the fallback
+        # (the installed-mode rule).
+        def extensions_source_root(provider)
+          package = manifest(provider)["extensions_package"]
+          return package_root(provider) if package.nil? || package.to_s.strip.empty?
+
+          resolve_named_package(package.to_s.strip) || package_root(provider)
+        end
+
         def package_root(provider)
           manifest_dir = File.dirname(manifest(provider).fetch("_manifest_path"))
           File.expand_path("../../..", manifest_dir)
@@ -63,6 +81,55 @@ module Ace
 
         private
 
+        # A package named through `extensions_package` resolves like the
+        # registry's own packages: the sibling directory inside the
+        # local project first (monorepo checkout), the installed gem
+        # second. In installed mode (ACE_TOOLCHAIN=installed) the
+        # checkout directory is project DATA, never the runtime source:
+        # the package must come from an installed gem, and only an
+        # installed spec counts. Only a package that actually carries
+        # handbook/extensions counts. In auto mode a configured package
+        # that resolves nowhere is a hard error: an unresolvable
+        # extensions_package must never be treated as "no extensions",
+        # which would prune every receipt-owned file from the target.
+        def resolve_named_package(name)
+          return installed_package(name) if Ace::Support::Cli::Toolchain.installed?
+
+          local = File.join(project_root, name)
+          return local if File.directory?(File.join(local, "handbook", "extensions"))
+
+          spec = Gem::Specification.find_by_name(name)
+          return spec.full_gem_path if File.directory?(File.join(spec.full_gem_path, "handbook", "extensions"))
+
+          raise_unresolvable_extensions_package(name,
+            "the installed gem carries no handbook/extensions tree")
+        rescue Gem::LoadError, ArgumentError => e
+          raise_unresolvable_extensions_package(name, e.message)
+        end
+
+        # A typed contract for an unresolvable extensions_package: callers
+        # (syncers, tests) rescue this precisely, never bare StandardError.
+        class UnresolvableExtensionsPackageError < StandardError; end
+
+        def raise_unresolvable_extensions_package(name, detail)
+          raise UnresolvableExtensionsPackageError,
+            "the configured extensions_package '#{name}' cannot be resolved (#{detail}): " \
+            "neither a sibling package directory under #{project_root} nor an installed gem " \
+            "carries the extension assets. Install the package or fix the provider manifest — " \
+            "an unresolvable extensions_package must never be treated as 'no extensions'."
+        end
+
+        # Installed mode: the packaged extension source must be the
+        # installed gem (max version), never the checkout directory.
+        def installed_package(name)
+          spec = Gem::Specification.find_all
+            .select { |candidate| candidate.name == name && Ace::Support::Cli::Toolchain.installed_spec?(candidate) }
+            .max_by(&:version)
+          return nil if spec.nil? || !File.directory?(File.join(spec.full_gem_path, "handbook", "extensions"))
+
+          spec.full_gem_path
+        end
+
         def local_manifest_paths
           LOCAL_MANIFEST_GLOBS.flat_map do |glob|
             Dir.glob(File.join(project_root, glob))

data/lib/ace/handbook/organisms/provider_syncer.rb

@@ -184,7 +184,7 @@ module Ace
           extensions_dir = registry.extensions_dir(provider)
           return nil if extensions_dir.nil? || extensions_dir.to_s.empty?
 
-          source_dir = File.join(registry.package_root(provider), "handbook", "extensions")
+          source_dir = File.join(registry.extensions_source_root(provider), "handbook", "extensions")
           expected = extension_source_files(source_dir)
           output_dir = File.join(project_root, extensions_dir)
           FileUtils.mkdir_p(output_dir)

data/lib/ace/handbook/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Handbook
-    VERSION = "0.36.2"
+    VERSION = "0.37.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-handbook
 version: !ruby/object:Gem::Version
-  version: 0.36.2
+  version: 0.37.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-28 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -201,8 +201,10 @@ files:
 - handbook/workflow-instructions/handbook/synthesize-research.wf.md
 - handbook/workflow-instructions/handbook/update-docs.wf.md
 - handbook/workflow-instructions/release/bump-version.wf.md
+- handbook/workflow-instructions/release/cycle-record.wf.md
 - handbook/workflow-instructions/release/local.wf.md
 - handbook/workflow-instructions/release/publish.wf.md
+- handbook/workflow-instructions/release/publisher.wf.md
 - handbook/workflow-instructions/release/rubygems-publish.wf.md
 - handbook/workflow-instructions/release/update-changelog.wf.md
 - lib/ace/handbook.rb