ace-handbook 0.34.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bac5cea7762cdf27f71764a6d79f8149763f83d6fc001157db3b869f0313869
-  data.tar.gz: 3062b5aa4e48907c9eeb26cc81d713ad8ccecdc948a9270e6324ea7e1eccd596
+  metadata.gz: 363ae1e6cd89c714512860b8ca79d36d845dfe197b039b2bcedcf60c77548000
+  data.tar.gz: 077205f8a16622b6972759fa7038cf4fca5a8dcd866ba048f5aebc5bcd2d2ba1
 SHA512:
-  metadata.gz: 0fa6aa552edbfae44a919b680f396adf7dff0b1dfd4c7e26d5c9c9eae183719ec169604bebe58591e9854a1eafa41a700e676d9c1378bed14e7718283a676fb9
-  data.tar.gz: 6e61af1f361bcb6909fccbda5281a0342793ba0a79fd02369befdc29aa21ef5d30b2477725165e31bcbdf018c131ae17ab8a6cab740672c1f786e7a5d3d6ca66
+  metadata.gz: 8b32ee617623055b732bb731531d5039f6f1da1ea5a413cf3828e02ab38c08b93f6ce5bb18a97cfbbe29c9dc041adae39f3a370a205749ae791e404ed8266b19
+  data.tar.gz: 1de4da539f049133b9672cedb3575679b26089b6d3cbb2fb126aa9ddb4639391313e4bc4964a70699f7ae89df5e4cd5633c19d835c7c94e6b88bf38a2e66e1d0

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.35.0] - 2026-10-08
+
+### Changed
+
+- Document standalone and protected delivery, current canonical campaign round/result handoff and scoped publication prerequisites. Keep source verification separate from installed Lab acceptance.
+
+- Route unavailable publication prerequisites through the original assignment failure/status owners without claiming protected publication or retry authority.
+
+- Route protected delivery through original worker merge request, canonical status and exact result consumption while preserving ordinary delivery and unresolved protected PR policy.
+
 ## [0.34.0] - 2026-10-05
 
 ### Changed

data/handbook/workflow-instructions/handbook/perform-delivery.wf.md

@@ -42,6 +42,22 @@ is recorded, inspect it with
 (or `--default-server`, otherwise remote resolution). Inside ACE use source
 `bin/ace-*` commands. Load the relevant implementation and test instructions.
 
+## Coordinating parallel delivery
+
+The coordinating agent owns the review and integration queue as well as dispatch.
+Before opening another scope, review completed candidates and integrate those
+whose executed checks and independent verdict permit it. If a candidate cannot
+integrate, record its exact blocker and owner in the existing task checklist;
+continue independent work only when it advances the same delivery objective.
+Do not become a review bottleneck by repeatedly starting unrelated work while
+finished candidates wait for your decision.
+
+After integration, verify the actual main and requested remote refs and update
+the current checklist. Distinguish committed in a worktree, accepted by review,
+integrated locally, pushed and released. A partial merge is useful incremental
+work, not task completion. Keep the remaining producer/consumer join explicit
+and test it on the combined candidate before declaring that result delivered.
+
 ## Standalone delivery
 
 Implement and commit the requested local task/inline scope using existing task
@@ -77,7 +93,118 @@ and merge evidence is accepted. Preparation after a completed delivery is a
 separate follow-up candidate/scope and must obtain its own required evidence.
 Publication remains separately authorized and gated, including OTP when required.
 
-## Managed delivery steps
+## Protected worker PR operations and status
+
+An installed protected worker uses its original prepared assignment, attempt,
+mapping and hierarchical scope. A role charter or selector is not an authority
+capability: the public owners authenticate the actual worker descendant and
+original birth. Other installed participants must delegate to the provisioned
+worker/executor; they cannot select local delivery. Do not run the ordinary
+managed delivery commands below from this protected route. Draft create/update
+may precede independent review, through the same configured receiver. Ready and
+merge require executed checks, current accepted independent review and the exact
+operation authorization. See `wfi://git/pr/create` and `wfi://git/pr/update` for
+the bounded draft input; credentials do not grant those operations.
+
+1. Retain the exact accepted candidate head and candidate generation, original
+   assignment/attempt/mapping/scope, configured receiver ID, authorization and
+   request ID. Use the reviewed retained delivery parameters, explicit authorized
+   merge method and exact PR URL. Accepted independent review for this candidate
+   remains a canonical authority gate; local report files cannot replace it.
+2. Before the first claim, read
+   `ace-assign authority status --mapping MAPPING --assignment ID --attempt ATTEMPT`.
+   Its `generation` is the current authority generation and
+   `result_candidate_generation` is the candidate generation. They are distinct;
+   never increment or substitute one for the other. Verify the candidate generation
+   matches the accepted candidate. Unavailable or changed selection blocks the
+   request. Keep the exact returned generation for this invocation; a conflict
+   is not permission to refresh it and resend.
+3. Select `create`, `update`, `ready` or `merge`. Save one nonsecret input file:
+   create/update contain exactly `target`, `delivery`, `title`, `body`; ready
+   contains `target`, `delivery`; merge contains `target`, `delivery`, `method`.
+   A create target is the selected base repository URL; other operations use
+   the exact PR URL. Target contains that URL as `resource` and nullable
+   `artifact_digest`; delivery is the retained `forge_server`/`forge_default` and
+   complete `pr_provenance` mapping. Method is explicitly squash, merge or rebase.
+   The maintained owner reads one unchanged bounded regular file and computes its
+   canonical input digest. It does not accept a caller-supplied digest for request.
+
+   ```json
+   {"target":{"resource":"https://forge.example/team/repo/pulls/25","artifact_digest":null},"delivery":{"forge_server":"forge-lab","forge_default":false,"pr_provenance":{"mode":"canonical","head_repository_url":"https://forge.example/team/repo","head_ref":"work","base_repository_url":"https://forge.example/team/repo","base_ref":"main"}},"method":"squash"}
+   ```
+
+4. Invoke the existing configured receiver through
+   `ace-lab service request --project PROJECT --assignment ID --attempt ATTEMPT --mapping MAPPING --scope SCOPE --service SERVICE --candidate-head SHA --candidate-generation CANDIDATE-GENERATION --expected-generation AUTHORITY-GENERATION --operation OPERATION --authorization AUTHORIZATION --request-id REQUEST --input INPUT.json`.
+   No dry-run or standalone fallback exists here. Retain the returned original
+   `selection` from either `data` or `error`: it includes input_digest and target.
+   `service_claim_accepted` acknowledges a durable claim, not operation completion.
+   `service_claim_unconfirmed` requires inspection of this original request;
+   neither uncertainty nor a timeout authorizes automatic resubmission.
+5. Read exact canonical status without an effect:
+   `ace-lab service status --request REQUEST --project PROJECT --assignment ID --attempt ATTEMPT --mapping MAPPING --scope SCOPE --candidate-head SHA --candidate-generation CANDIDATE-GENERATION --input-digest INPUT-DIGEST --target ORIGINAL-TARGET`.
+   Use the original returned selection; omit `--artifact-digest` for null, or
+   supply its exact original SHA256 when present. Status does not use a refreshed
+   expected generation and never repairs or restarts an uncertain service.
+   Missing receiver, review, authorization or installed owner stays a routed
+   blocker. A caller-local journal or remote PR observation is not canonical proof.
+6. Only after canonical succeeded status, consume the exact completed result:
+   `ace-assign delivery --assignment ID --attempt ATTEMPT --mapping MAPPING --scope SCOPE --operation OPERATION --service-request REQUEST --candidate-head SHA --candidate-generation CANDIDATE-GENERATION --input-digest INPUT-DIGEST --target ORIGINAL-TARGET`.
+   Apply the same nullable artifact flag rule. Do not supply local `--tests`,
+   `--review`, title/body or parameters. The authority has already verified the
+   original review, completion receipt/import and exact input association, and
+   atomically published the delivery event. Worker consumption verifies that
+   event; it neither appends evidence nor invokes the provider again.
+7. Preserve the original request and result references on resume. Exact read-only
+   status is safe; an explicit identical request may only return its retained
+   canonical claim/result and must not refresh selectors. Never retry an unknown
+   effect to obtain a receipt. Publication, deployment and synchronization still
+   require their separate authorization, evidence and OTP where applicable.
+
+## Protected campaign result before readiness or merge
+
+When the original protected parent registers `review_campaign`, finish the existing
+R1/R2/R3 review policy through its linked, canonically settled collection/check/
+approval children. Follow the protected handoff in `wfi://review/pr`; ordinary
+`ace-review campaign` output and `ace-assign attempt finish` are not substitutes.
+Draft create/update above may run before independent review. Ready and merge wait
+for the current canonical parent campaign result, executed checks and independent
+review acceptance.
+
+1. Upload the documented R1 round input using the closed envelope
+   `{"version":1,"round":ROUND_OBJECT,"artifacts":[{"path":"report.md","sha256":"SHA256"}]}`.
+   Keep the original parent selectors, pinned head/base/scopes and registered
+   campaign/requirements/policy. The round attempt_id equals its stable mutation.
+   `ace-assign campaign-record-round --mapping MAPPING --assignment ID --attempt ATTEMPT --head SHA --candidate-generation N --mutation ROUND-ATTEMPT --input ROUND-ENVELOPE.json --artifact REPORT-BYTES`
+   supplies ordered immutable artifact bytes, not authority-readable worker paths.
+   Repeat the artifact flag in envelope order; settled child receipts establish
+   execution and approval, not editable reports alone.
+2. After policy acceptance, download its verified exact bytes:
+   `ace-assign campaign-export-result --mapping MAPPING --assignment ID --attempt ATTEMPT --head SHA --candidate-generation N --output RESULT.json`.
+   Retain exported sha256/result_identity/journal_commit. The authority owns the
+   campaign store and validates the accepted immutable candidate; the output file
+   is a transfer artifact, not permission to change or bypass policy.
+3. Keep the original parent's succeeded review receipt, independent actors and
+   executed checks. Add `campaign: {id: REGISTERED-CAMPAIGN, result: {path:
+   RESULT.json, sha256: EXPORTED-SHA256}}` and the identical reference in its
+   ordered artifacts. Upload exact exported bytes in that artifact slot with
+   `ace-assign submit-result --mapping MAPPING --assignment ID --attempt ATTEMPT --head SHA --candidate-generation N --expected-generation G --mutation RESULT-MUTATION --receipt PARENT-RECEIPT.json --artifact RESULT.json`.
+   Supply any other receipt artifacts in their declared order. Submission imports
+   evidence; the original reviewer/finish owner still owns acceptance and release.
+   G is persisted authority generation; N is candidate generation, never G.
+
+Restart retains original mutations, envelope/receipt bytes, ordered artifacts and
+selectors. Exact replay preserves the existing round/result; re-export only accepts
+an identical existing file. Changed candidate, policy or missing canonical child
+settlement rejects current acceptance without erasing history. Ready/merge service
+admission rechecks the canonical parent campaign result. Route a missing producer
+to its owner, keeping delivery unfinished; do not build a new receipt generator,
+refresh conflicting generations or use ordinary commands as a protected fallback.
+
+## Ordinary managed delivery steps
+
+These steps retain the existing nonprotected managed workflow. They are not a
+fallback for an installed protected participant or a blocked protected operation.
+
 
 1. Record the requested delivery steps and their owners before implementation.
    Follow the existing task-work plan. Commit the implementation and run appropriate
@@ -132,6 +259,26 @@ Publication remains separately authorized and gated, including OTP when required
    authorized merge; publication is not mandatory. Keep the task in progress until
    all of its actual acceptance criteria are satisfied.
 
+## Unavailable publication prerequisite
+
+Requested publication is a separate step, never a consequence of merge success.
+Use the existing configured service policy and publisher prerequisites; an absent
+publisher or unavailable required OTP is a routed blocker, not permission to run
+an alternate command/account. The ordinary tested publisher's precondition
+failure is ordinary source evidence only; it does not supply a protected
+publication receipt or positive scoped OTP capability.
+
+If the requested step cannot proceed, record its value-free cause through the
+existing assignment failure owner:
+`ace-assign fail --assignment ID@SCOPE --attempt ATTEMPT --mapping MAPPING --message "publication blocked: prerequisite unavailable"`.
+Use the actual original protected selectors; ordinary assignments omit protected
+selectors and use their existing target. Read `ace-assign status` for that same
+scope afterward. The step remains failed/unfinished, with no publication receipt
+or task completion. Preserve an uncertain service request separately: a failure
+report must not claim a definitive denial or effect absence from a lost reply.
+Protected recovery requires the reviewed new prepared version/attempt; never
+finish the failed step or retry publication to manufacture success.
+
 ## Uncertainty and resume
 
 In managed mode, read assignment status and retained qjl delivery events before

data/lib/ace/handbook/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Handbook
-    VERSION = "0.34.0"
+    VERSION = "0.35.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-handbook
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.35.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config