ace-handbook 0.34.0 → 0.35.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bac5cea7762cdf27f71764a6d79f8149763f83d6fc001157db3b869f0313869
-  data.tar.gz: 3062b5aa4e48907c9eeb26cc81d713ad8ccecdc948a9270e6324ea7e1eccd596
+  metadata.gz: 265fcff8879eef3a62977ecf5ac29dda8e252f06b5cb18f654da4064e6bb7de9
+  data.tar.gz: 7edd597cda3730560bfbf34ea456c02a230f10850da5c312a26d946926825dc6
 SHA512:
-  metadata.gz: 0fa6aa552edbfae44a919b680f396adf7dff0b1dfd4c7e26d5c9c9eae183719ec169604bebe58591e9854a1eafa41a700e676d9c1378bed14e7718283a676fb9
-  data.tar.gz: 6e61af1f361bcb6909fccbda5281a0342793ba0a79fd02369befdc29aa21ef5d30b2477725165e31bcbdf018c131ae17ab8a6cab740672c1f786e7a5d3d6ca66
+  metadata.gz: 39ff2ee4d8a19b8329fd3588c7a78cc222cc139cb5017cb8cc53579867bf270fcb3bf754777b9cadfabca1046268989e8bfa379a54f392ae3ef1bfaaf687f5e1
+  data.tar.gz: 82491f08d0331566b9e42539e40d402668ed510cc89dcdecc4f3850575de3f8d8717b94babae38f2505c876091d9dd671341867d535000b36424b3719b76853b

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.35.1] - 2026-10-10
+
+### Technical
+
+- Clarify guide candidate discovery and the scope of this monorepo's checked-in priority-5 workflow source in `wfi://handbook/manage-overrides`.
+
+## [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/manage-overrides.wf.md

@@ -34,7 +34,7 @@ per URI.
 
 | Surface | Protocol | Project-local location | Overridable? | Winner of duplicates (shipped defaults) |
 |---------|----------|------------------------|--------------|------------------------------------------|
-| Workflows | `wfi://` | `.ace-handbook/workflow-instructions/<ns>/<name>.wf.md` | Yes | Project-local, when its source priority is lower than the gem source's (e.g. the shipped `local` source at priority 5 vs gem at 10) |
+| Workflows | `wfi://` | `.ace-handbook/workflow-instructions/<ns>/<name>.wf.md` | Yes | Project-local, when its source priority is lower than the gem source's (e.g. this monorepo's checked-in `local` source at priority 5 vs gem at 10) |
 | Cookbooks | `cookbook://` | `.ace-handbook/cookbooks/<name>.cookbook.md` | Yes | The candidate from the source with the lower priority number. The shipped project-local default registers priority 20 and the gem source 10, so **the gem wins by default**; register a project cookbook source with priority < 10 to make project-local win |
 | Guides | `guide://` | `handbook/guides/<name>.g.md` | Yes, with registration | Requires a project source registration (`.ace/nav/protocols/guide-sources/local.yml` → `handbook/guides`); with priority < 10 the project-local guide wins. Without registration the gem wins |
 | Skills | `skill://` | none | **No** | Always the gem. Skills are thin layers; override the workflow the skill calls instead |
@@ -44,9 +44,9 @@ per URI.
 
 Sources for a protocol are scanned in ascending priority order (lower number = higher precedence); the first source
 containing the resource wins and remaining duplicates are ignored. Registration defaults: project sources 10, user
-sources 50, gem defaults 100 — an individual source registration may pin another value (this is why the shipped
-`local` workflow source at priority 5 beats the gem at 10, while the shipped project-local cookbook source at 20 loses
-to the gem at 10).
+sources 50, gem defaults 100 — an individual source registration may pin another value. In this monorepo, the checked-in
+`.ace/nav/protocols/wfi-sources/local.yml` sets priority 5 and beats the gem at 10; downstream projects must register
+their own local workflow source. The shipped project-local cookbook source at 20 loses to the gem at 10.
 
 To answer "why did this candidate win?" for a concrete URI without planting probe files:
 
@@ -73,7 +73,8 @@ are ignored and resolution always returns the gem file. The design rule is: **ov
 2. **Create the project-local file** at the surface's project-local location (see table), keeping the canonical
    frontmatter and structure so tools keep resolving it.
 3. **Ensure the source registration makes your file win:**
-   - workflows: keep `.ace/nav/protocols/wfi-sources/local.yml` priority below the gem source (shipped default: 5).
+   - workflows: register `.ace/nav/protocols/wfi-sources/local.yml` with priority below the gem source; this monorepo's
+     checked-in registration uses 5, but downstream projects do not receive that project-local source by default.
    - cookbooks: register `.ace/nav/protocols/cookbook-sources/local.yml` with priority < 10 (the shipped
      project-local default of 20 loses to the gem's 10).
    - guides: register `.ace/nav/protocols/guide-sources/local.yml` pointing at `handbook/guides` with priority < 10;
@@ -135,8 +136,10 @@ ace-handbook sync                                      # regenerates .agents/ski
 
 - **Override silently loses:** inspect `ace-nav resolve <uri> --why`; the losing candidate's source priority is too
   high — lower it in the source registration.
-- **Guide override not discovered at all:** no project guide source is registered; add
-  `.ace/nav/protocols/guide-sources/local.yml` (see Process Step 3).
+- **Guide override does not win:** a planted guide may be discovered as a losing candidate through the
+  `@ace-support-nav` gem-default example source (`./handbook/guides`, priority 100), or it may be absent from the
+  candidates, depending on source registration. Register `.ace/nav/protocols/guide-sources/local.yml` with priority
+  below the gem source (see Process Step 3), then confirm the project candidate wins with `ace-nav resolve --why`.
 - **Skill edit appears to do nothing:** skills are not overridable; override the workflow the skill calls.
 - **`.agents/skills/` edits keep disappearing:** expected — `ace-handbook sync` regenerates the projection and prunes
   stale entries; edit canonical skills in the owning gem.

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.1"
   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.1
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config