ace-handbook 0.33.0 → 0.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +16 -0
  3. data/handbook/workflow-instructions/handbook/perform-delivery.wf.md +293 -260
  4. data/lib/ace/handbook/version.rb +1 -1
  5. metadata +2 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: a640260822cd7518266797ae62628ae62a4cae9f6a96ca7604ed274245ac2915
4
- data.tar.gz: 9f7e5b5515524a15a2547a874f0324961bb6e38489026d16f316bf2358bed2b6
3
+ metadata.gz: 363ae1e6cd89c714512860b8ca79d36d845dfe197b039b2bcedcf60c77548000
4
+ data.tar.gz: 077205f8a16622b6972759fa7038cf4fca5a8dcd866ba048f5aebc5bcd2d2ba1
5
5
  SHA512:
6
- metadata.gz: b67c9b8c9ad1c7a21121cd2e8694da47bfd545b2142dee84dfbcff70917049a0cb634e2194b938079db3f3a0d128ed3de1ca7e6b65585e97900c669a86ffd1c2
7
- data.tar.gz: ad70a65d103696d260014b279073266ef0beab0e79a2d54ac4e575bc3217a5c1d290623a132e9bebce9192e49b7e89c609b34944ea50c47f3889f2d724fafc45
6
+ metadata.gz: 8b32ee617623055b732bb731531d5039f6f1da1ea5a413cf3828e02ab38c08b93f6ce5bb18a97cfbbe29c9dc041adae39f3a370a205749ae791e404ed8266b19
7
+ data.tar.gz: 1de4da539f049133b9672cedb3575679b26089b6d3cbb2fb126aa9ddb4639391313e4bc4964a70699f7ae89df5e4cd5633c19d835c7c94e6b88bf38a2e66e1d0
data/CHANGELOG.md CHANGED
@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.35.0] - 2026-10-08
11
+
12
+ ### Changed
13
+
14
+ - Document standalone and protected delivery, current canonical campaign round/result handoff and scoped publication prerequisites. Keep source verification separate from installed Lab acceptance.
15
+
16
+ - Route unavailable publication prerequisites through the original assignment failure/status owners without claiming protected publication or retry authority.
17
+
18
+ - Route protected delivery through original worker merge request, canonical status and exact result consumption while preserving ordinary delivery and unresolved protected PR policy.
19
+
20
+ ## [0.34.0] - 2026-10-05
21
+
22
+ ### Changed
23
+
24
+ - Canonical delivery consumes neutral attempt-bound PR operations, current executed test/independent review receipts and exact authorized merge evidence; optional release preparation remains separate from publication.
25
+
10
26
  ## [0.33.0] - 2026-09-28
11
27
 
12
28
  ### Added
data/handbook/workflow-instructions/handbook/perform-delivery.wf.md CHANGED
@@ -1,272 +1,305 @@
1
1
  ---
2
2
  doc-type: workflow
3
- title: Perform Delivery Workflow
4
- purpose: Coordinate complete task delivery across implementation, review, release, and review cycles.
5
- ace-docs:
6
- last-updated: 2026-03-12
7
- last-checked: 2026-03-21
3
+ title: Perform attempt-bound delivery
4
+ purpose: Coordinate implementation, exact-head review and authorized delivery on the selected forge
8
5
  ---
9
6
 
10
- # Perform Delivery Workflow
7
+ # Perform attempt-bound delivery
11
8
 
12
9
  ## Goal
13
10
 
14
- Execute complete delivery workflow for a task with automatic step tracking, ensuring no steps are lost during complex multi-step execution.
11
+ Deliver one committed candidate in explicit standalone or managed mode, using
12
+ the selected forge and current executed tests and independent review.
15
13
 
16
14
  ## Prerequisites
17
15
 
18
- * Task reference (e.g., `215.03`) OR detailed inline instructions
19
- * Clean git working directory (or staged changes ready for commit)
20
- * Understanding of the standard delivery workflow steps
21
- * Access to the relevant ACE CLI tools and workflows
22
-
23
- ## Project Context Loading
24
-
25
- * Load task context via `ace-task show <ref>` if task reference provided
26
- * Load git status: `git status`
27
- * Load PR status: `gh pr view` (if PR exists)
28
-
29
- ## High-Level Execution Plan
30
-
31
- ### Phase 0: Externalize Workflow (CRITICAL - DO FIRST)
32
-
33
- * [ ] Parse input to identify delivery scope
34
- * [ ] Create TodoWrite entry for EVERY delivery step BEFORE starting work
35
- * [ ] Confirm todo list is complete before proceeding
36
-
37
- ### Phase 1: Implementation
38
-
39
- * [ ] Enter plan mode if implementation required
40
- * [ ] Execute implementation via `ace-bundle wfi://task/work` or inline instructions
41
- * [ ] Commit all changes (`ace-git-commit`)
42
- * [ ] Release modified packages (`ace-bundle wfi://release/local` if applicable)
43
- * [ ] Mark task done and push to remote
44
-
45
- ### Phase 2: PR & Initial Review
46
-
47
- * [ ] Create or update PR (`ace-bundle wfi://github/pr/create`)
48
- * [ ] Run initial review (`ace-bundle wfi://review/pr`)
49
- * [ ] Implement HIGH/CRITICAL feedback immediately
50
-
51
- ### Phase 3: Deep Review Cycle
52
-
53
- * [ ] Run deep code review (`ace-bundle wfi://review/pr`, using the `code-deep` preset)
54
- * [ ] Implement MEDIUM+ severity feedback
55
- * [ ] Run test suite (`ace-test-suite`)
56
- * [ ] Commit fixes (`ace-git-commit`)
57
- * [ ] Repeat review cycle if needed
58
-
59
- ## Process Steps
60
-
61
- ### Phase 0: Externalize Workflow (CRITICAL - DO FIRST)
62
-
63
- **BEFORE reading any detailed content or starting implementation:**
64
-
65
- 1. **Parse Input:**
66
- * Identify if input is a task reference (e.g., `215.03`) or inline instructions
67
- * Determine scope: full delivery vs. partial (implementation only, review only, etc.)
68
-
69
- 2. **Create Session Todo List IMMEDIATELY:**
70
- * Use TodoWrite to create entries for ALL delivery steps
71
- * This MUST be the FIRST action before any other work
72
- * Do not read implementation details until todo list is created
73
-
74
- **Standard Delivery Steps to Add:**
75
-
76
- ```
77
- 1. Implement task (via `ace-bundle wfi://task/work` or inline)
78
- 2. Commit all changes (`ace-git-commit`)
79
- 3. Release modified packages (`ace-bundle wfi://release/local`)
80
- 4. Mark task done and push to remote
81
- 5. Create/update PR (`ace-bundle wfi://github/pr/create`)
82
- 6. Initial review (`ace-bundle wfi://review/pr`)
83
- 7. Implement HIGH/CRITICAL feedback
84
- 8. Deep review (`ace-bundle wfi://review/pr` with `code-deep`)
85
- 9. Implement MEDIUM+ feedback
86
- 10. Run test suite and commit fixes
87
- ```
88
-
89
- 3. **Confirm Before Proceeding:**
90
- * Output: "Session todo list created with N delivery steps"
91
- * Only proceed to Phase 1 after todo list is confirmed
92
-
93
- ### Phase 1: Implementation
94
-
95
- 1. **Load Task Context (if task reference provided):**
96
- * Load `ace-bundle wfi://task/work`, then follow it with the task reference
97
- * If inline instructions provided, use those directly
98
-
99
- 2. **Enter Plan Mode (if implementation required):**
100
- * Prepare detailed implementation plan
101
- * Get user approval before proceeding
102
-
103
- 3. **Execute Implementation:**
104
- * Follow the implementation plan
105
- * Track progress using TodoWrite for sub-tasks
106
-
107
- 4. **Commit Changes:**
108
- * Run `ace-git-commit` to commit all changes
109
- * Use descriptive commit message
110
-
111
- 5. **Release Packages (if applicable):**
112
- * Load `ace-bundle wfi://release/local` when a release is required
113
- * Follow versioning conventions
114
-
115
- 6. **Complete Task:**
116
- * Mark task as done: `ace-task done <ref>`
117
- * Push to remote: `git push`
118
-
119
- ### Phase 2: PR & Initial Review
120
-
121
- 1. **Create or Update PR:**
122
- * Load `ace-bundle wfi://github/pr/create` to prepare the pull request flow
123
- * Include task reference and summary
124
-
125
- 2. **Run Initial Review:**
126
- * Load `ace-bundle wfi://review/pr`
127
- * Review the feedback output
128
-
129
- 3. **Implement Critical Feedback:**
130
- * Address all HIGH and CRITICAL severity items
131
- * Commit fixes with descriptive messages
132
-
133
- ### Phase 3: Deep Review Cycle
134
-
135
- 1. **Run Deep Code Review:**
136
- * Load `ace-bundle wfi://review/pr` and use the `code-deep` preset
137
- * This provides more thorough analysis
138
-
139
- 2. **Implement Feedback:**
140
- * Address MEDIUM severity and above items
141
- * Consider LOW severity items for future improvements
142
-
143
- 3. **Run Test Suite:**
144
- * Run `ace-test-suite` to verify all tests pass
145
- * Fix any failing tests
146
-
147
- 4. **Commit Fixes:**
148
- * Run `ace-git-commit` to commit all fixes
149
-
150
- 5. **Repeat Review Cycle (if needed):**
151
- * If significant changes were made, run another review
152
- * Continue until no HIGH/CRITICAL items remain
153
-
154
- ## Checkpoint Protocol
155
-
156
- **After completing EACH numbered todo item:**
157
-
158
- 1. Mark the todo as COMPLETED using TodoWrite
159
- 2. Output checkpoint message:
160
-
161
- ```
162
- ✓ Step N complete: [step description]
163
- → Next: Step N+1 - [next step description]
16
+ - A reviewed task or an explicit implementation scope and project.
17
+ - For managed delivery, a managed assignment and an active scoped attempt for each
18
+ delivery action; use the actual assignment and
19
+ attempt IDs from the execution boundary, never caller-invented actor identity.
20
+ - For remote delivery, a pushed candidate and explicit fork/canonical provenance:
21
+ mode, head_repository_url, head_ref, base_repository_url and base_ref.
22
+ - An applicable authorization for each effect. Transport credentials do not grant
23
+ permission to merge, publish, deploy or synchronize.
24
+
25
+ Choose standalone mode for ordinary local task/inline implementation, tests, review
26
+ and optional requested version/changelog preparation without a managed assignment.
27
+ Choose managed mode when the request supplies an assignment or requires its
28
+ canonical attempt/receipt boundary. Standalone output cannot satisfy managed or
29
+ protected acceptance. Local-only implementation needs no forge selection or
30
+ scoped attempt. If remote delivery is requested,
31
+ use forge_server or forge_default: true, mutually exclusive; otherwise use the
32
+ repository remote. Preserve the first resolved server/repository/PR identity
33
+ throughout the assignment. Missing service or authorization yields a specific
34
+ blocker; this workflow does not invent grants or impersonate an integrator.
35
+
36
+ ## Project context loading
37
+
38
+ Read the task or inline scope and actual committed diff. In managed mode also
39
+ read assignment status, current attempt and retained delivery parameters. If a PR
40
+ is recorded, inspect it with
41
+ `ace-git pr show IDENTIFIER --format json --server NAME` using the retained selection
42
+ (or `--default-server`, otherwise remote resolution). Inside ACE use source
43
+ `bin/ace-*` commands. Load the relevant implementation and test instructions.
44
+
45
+ ## Coordinating parallel delivery
46
+
47
+ The coordinating agent owns the review and integration queue as well as dispatch.
48
+ Before opening another scope, review completed candidates and integrate those
49
+ whose executed checks and independent verdict permit it. If a candidate cannot
50
+ integrate, record its exact blocker and owner in the existing task checklist;
51
+ continue independent work only when it advances the same delivery objective.
52
+ Do not become a review bottleneck by repeatedly starting unrelated work while
53
+ finished candidates wait for your decision.
54
+
55
+ After integration, verify the actual main and requested remote refs and update
56
+ the current checklist. Distinguish committed in a worktree, accepted by review,
57
+ integrated locally, pushed and released. A partial merge is useful incremental
58
+ work, not task completion. Keep the remaining producer/consumer join explicit
59
+ and test it on the combined candidate before declaring that result delivered.
60
+
61
+ ## Standalone delivery
62
+
63
+ Implement and commit the requested local task/inline scope using existing task
64
+ and Git tools. Execute appropriate tests and independent review, retain their
65
+ actual artifact references and candidate SHA, and record unfinished criteria.
66
+ No managed assignment, protected service receipt or canonical qjl acceptance is
67
+ claimed by this route. Local scope may end here.
68
+
69
+ For an explicitly authorized standalone remote scope, use existing neutral
70
+ primitives on the chosen base repository/forge. Record actual head/base
71
+ repository URLs and refs; canonical provenance means matching repositories,
72
+ while fork provenance requires its explicit source URL. A pushed source ref must
73
+ match the candidate SHA. Draft creation defaults to true:
74
+
75
+ `ace-git pr create --server NAME --head HEAD-REF --head-repo HEAD-REPOSITORY-URL --base BASE-REF --expected-head CANDIDATE-SHA --title TITLE --body-file DESCRIPTION --format json`
76
+
77
+ Read the returned exact PR identity. Update with
78
+ `ace-git pr update IDENTIFIER --server NAME --expected-head CANDIDATE-SHA --body-file DESCRIPTION --format json`.
79
+ Use the retained default/remote selection instead of `--server NAME` when
80
+ applicable. Review through the existing neutral review workflow with the same
81
+ selection. Before readiness or merge, require passed executed tests and accepted
82
+ independent review for that exact candidate and the actual operation authorization;
83
+ the low-level PR command does not establish these gates itself. Readiness uses
84
+ `ace-git pr ready IDENTIFIER --server NAME --expected-head CANDIDATE-SHA --format json`.
85
+ Only an actually authorized standalone integrator may call
86
+ `ace-git pr merge IDENTIFIER --server NAME --expected-head CANDIDATE-SHA --method METHOD --format json`.
87
+ This is not a worker fallback when a managed/protected service is unavailable.
88
+ Remote errors or uncertain effects remain explicit unresolved outcomes; use
89
+ authoritative reads and existing provider reconciliation, never blind replay.
90
+
91
+ Perform any requested local version/changelog changes before final test/review
92
+ and merge evidence is accepted. Preparation after a completed delivery is a
93
+ separate follow-up candidate/scope and must obtain its own required evidence.
94
+ Publication remains separately authorized and gated, including OTP when required.
95
+
96
+ ## Protected worker PR operations and status
97
+
98
+ An installed protected worker uses its original prepared assignment, attempt,
99
+ mapping and hierarchical scope. A role charter or selector is not an authority
100
+ capability: the public owners authenticate the actual worker descendant and
101
+ original birth. Other installed participants must delegate to the provisioned
102
+ worker/executor; they cannot select local delivery. Do not run the ordinary
103
+ managed delivery commands below from this protected route. Draft create/update
104
+ may precede independent review, through the same configured receiver. Ready and
105
+ merge require executed checks, current accepted independent review and the exact
106
+ operation authorization. See `wfi://git/pr/create` and `wfi://git/pr/update` for
107
+ the bounded draft input; credentials do not grant those operations.
108
+
109
+ 1. Retain the exact accepted candidate head and candidate generation, original
110
+ assignment/attempt/mapping/scope, configured receiver ID, authorization and
111
+ request ID. Use the reviewed retained delivery parameters, explicit authorized
112
+ merge method and exact PR URL. Accepted independent review for this candidate
113
+ remains a canonical authority gate; local report files cannot replace it.
114
+ 2. Before the first claim, read
115
+ `ace-assign authority status --mapping MAPPING --assignment ID --attempt ATTEMPT`.
116
+ Its `generation` is the current authority generation and
117
+ `result_candidate_generation` is the candidate generation. They are distinct;
118
+ never increment or substitute one for the other. Verify the candidate generation
119
+ matches the accepted candidate. Unavailable or changed selection blocks the
120
+ request. Keep the exact returned generation for this invocation; a conflict
121
+ is not permission to refresh it and resend.
122
+ 3. Select `create`, `update`, `ready` or `merge`. Save one nonsecret input file:
123
+ create/update contain exactly `target`, `delivery`, `title`, `body`; ready
124
+ contains `target`, `delivery`; merge contains `target`, `delivery`, `method`.
125
+ A create target is the selected base repository URL; other operations use
126
+ the exact PR URL. Target contains that URL as `resource` and nullable
127
+ `artifact_digest`; delivery is the retained `forge_server`/`forge_default` and
128
+ complete `pr_provenance` mapping. Method is explicitly squash, merge or rebase.
129
+ The maintained owner reads one unchanged bounded regular file and computes its
130
+ canonical input digest. It does not accept a caller-supplied digest for request.
131
+
132
+ ```json
133
+ {"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"}
164
134
  ```
165
135
 
166
- 3. Read todo list to confirm next step
167
- 4. Continue IMMEDIATELY to next step (no user prompt needed unless blocked)
168
-
169
- **On Failure:**
170
-
171
- 1. Mark the current todo as blocked (keep as in_progress)
172
- 2. Output failure message:
173
-
174
- ```
175
- ✗ Step N failed: [step description]
176
- → Error: [error description]
177
- → Action needed: [what user needs to do]
178
- ```
179
-
180
- 3. Ask user for guidance using AskUserQuestion
181
- 4. Resume workflow after issue is resolved
182
-
183
- ## Auto-Continue Protocol
184
-
185
- **CRITICAL:** This workflow should AUTO-CONTINUE between steps without waiting for user input.
186
-
187
- The only times to pause and ask the user:
188
-
189
- * Plan mode approval (Phase 1)
190
- * Step failure requiring user intervention
191
- * Ambiguous instructions requiring clarification
192
- * External blockers (CI failures, merge conflicts, etc.)
193
-
194
- For all other transitions, immediately proceed to the next step after checkpoint.
195
-
196
- ## Scope Variations
197
-
198
- ### Full Delivery (default)
199
-
200
- All steps from implementation through review cycles. Load `ace-bundle wfi://handbook/perform-delivery`.
201
-
202
- ### Implementation Only
203
-
204
- Skip PR and review phases (useful for WIP branches). Load `ace-bundle wfi://handbook/perform-delivery`.
205
-
206
- ### Review Only
207
-
208
- Skip implementation, start from PR creation. Load `ace-bundle wfi://handbook/perform-delivery`.
209
-
210
- ### Custom Instructions
211
-
212
- Provide inline instructions instead of task reference. Load `ace-bundle wfi://handbook/perform-delivery`.
213
-
214
- ## Success Criteria
215
-
216
- * All todo items marked as completed
217
- * No skipped or forgotten steps
218
- * All commits pushed to remote
219
- * PR created (if applicable)
220
- * All HIGH/CRITICAL review feedback addressed
221
- * Test suite passing
222
- * Task marked as done in taskflow
223
-
224
- ## Error Handling
225
-
226
- **Step Fails to Complete:**
227
-
228
- * Keep todo item as in_progress
229
- * Log the error with context
230
- * Ask user for guidance
231
- * Resume from failed step after resolution
232
-
233
- **User Interruption:**
234
-
235
- * Save current state (which step is in progress)
236
- * Allow resume from interruption point
237
- * Maintain todo list across session
238
-
239
- **External Tool Failure:**
240
-
241
- * Report which tool failed and the error
242
- * Suggest manual alternatives if available
243
- * Wait for user guidance before proceeding
244
-
245
- ## Usage Examples
246
-
247
- ### Full Task Delivery
248
-
249
- > "Perform delivery for task 215.03"
250
-
251
- This will:
252
- 1. Load task context
253
- 2. Implement the task
254
- 3. Commit, release, mark done
255
- 4. Create PR
256
- 5. Review and iterate
257
-
258
- ### Review Cycle Only
259
-
260
- > "Perform delivery for task 215.03 --scope review"
261
-
262
- This will:
263
- 1. Create/update PR
264
- 2. Review and implement feedback
265
- 3. Run test suite
266
- 4. Iterate until clean
267
-
268
- ### Custom Workflow
269
-
270
- > "Perform delivery: implement the dark mode feature, commit, create PR, and run one review cycle"
271
-
272
- This will parse the custom instructions and create a todo list matching the requested steps.
136
+ 4. Invoke the existing configured receiver through
137
+ `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`.
138
+ No dry-run or standalone fallback exists here. Retain the returned original
139
+ `selection` from either `data` or `error`: it includes input_digest and target.
140
+ `service_claim_accepted` acknowledges a durable claim, not operation completion.
141
+ `service_claim_unconfirmed` requires inspection of this original request;
142
+ neither uncertainty nor a timeout authorizes automatic resubmission.
143
+ 5. Read exact canonical status without an effect:
144
+ `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`.
145
+ Use the original returned selection; omit `--artifact-digest` for null, or
146
+ supply its exact original SHA256 when present. Status does not use a refreshed
147
+ expected generation and never repairs or restarts an uncertain service.
148
+ Missing receiver, review, authorization or installed owner stays a routed
149
+ blocker. A caller-local journal or remote PR observation is not canonical proof.
150
+ 6. Only after canonical succeeded status, consume the exact completed result:
151
+ `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`.
152
+ Apply the same nullable artifact flag rule. Do not supply local `--tests`,
153
+ `--review`, title/body or parameters. The authority has already verified the
154
+ original review, completion receipt/import and exact input association, and
155
+ atomically published the delivery event. Worker consumption verifies that
156
+ event; it neither appends evidence nor invokes the provider again.
157
+ 7. Preserve the original request and result references on resume. Exact read-only
158
+ status is safe; an explicit identical request may only return its retained
159
+ canonical claim/result and must not refresh selectors. Never retry an unknown
160
+ effect to obtain a receipt. Publication, deployment and synchronization still
161
+ require their separate authorization, evidence and OTP where applicable.
162
+
163
+ ## Protected campaign result before readiness or merge
164
+
165
+ When the original protected parent registers `review_campaign`, finish the existing
166
+ R1/R2/R3 review policy through its linked, canonically settled collection/check/
167
+ approval children. Follow the protected handoff in `wfi://review/pr`; ordinary
168
+ `ace-review campaign` output and `ace-assign attempt finish` are not substitutes.
169
+ Draft create/update above may run before independent review. Ready and merge wait
170
+ for the current canonical parent campaign result, executed checks and independent
171
+ review acceptance.
172
+
173
+ 1. Upload the documented R1 round input using the closed envelope
174
+ `{"version":1,"round":ROUND_OBJECT,"artifacts":[{"path":"report.md","sha256":"SHA256"}]}`.
175
+ Keep the original parent selectors, pinned head/base/scopes and registered
176
+ campaign/requirements/policy. The round attempt_id equals its stable mutation.
177
+ `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`
178
+ supplies ordered immutable artifact bytes, not authority-readable worker paths.
179
+ Repeat the artifact flag in envelope order; settled child receipts establish
180
+ execution and approval, not editable reports alone.
181
+ 2. After policy acceptance, download its verified exact bytes:
182
+ `ace-assign campaign-export-result --mapping MAPPING --assignment ID --attempt ATTEMPT --head SHA --candidate-generation N --output RESULT.json`.
183
+ Retain exported sha256/result_identity/journal_commit. The authority owns the
184
+ campaign store and validates the accepted immutable candidate; the output file
185
+ is a transfer artifact, not permission to change or bypass policy.
186
+ 3. Keep the original parent's succeeded review receipt, independent actors and
187
+ executed checks. Add `campaign: {id: REGISTERED-CAMPAIGN, result: {path:
188
+ RESULT.json, sha256: EXPORTED-SHA256}}` and the identical reference in its
189
+ ordered artifacts. Upload exact exported bytes in that artifact slot with
190
+ `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`.
191
+ Supply any other receipt artifacts in their declared order. Submission imports
192
+ evidence; the original reviewer/finish owner still owns acceptance and release.
193
+ G is persisted authority generation; N is candidate generation, never G.
194
+
195
+ Restart retains original mutations, envelope/receipt bytes, ordered artifacts and
196
+ selectors. Exact replay preserves the existing round/result; re-export only accepts
197
+ an identical existing file. Changed candidate, policy or missing canonical child
198
+ settlement rejects current acceptance without erasing history. Ready/merge service
199
+ admission rechecks the canonical parent campaign result. Route a missing producer
200
+ to its owner, keeping delivery unfinished; do not build a new receipt generator,
201
+ refresh conflicting generations or use ordinary commands as a protected fallback.
202
+
203
+ ## Ordinary managed delivery steps
204
+
205
+ These steps retain the existing nonprotected managed workflow. They are not a
206
+ fallback for an installed protected participant or a blocked protected operation.
207
+
208
+
209
+ 1. Record the requested delivery steps and their owners before implementation.
210
+ Follow the existing task-work plan. Commit the implementation and run appropriate
211
+ package tests. If requested, perform local version/changelog preparation with
212
+ `ace-bundle wfi://release/local` before final evidence and merge; it does not
213
+ publish. Keep unfinished task criteria open; a bounded source checkpoint
214
+ cannot mark an entire installed task done.
215
+ 2. For remote delivery, prepare a concrete title and description from the changes
216
+ and executed validation. Load `ace-bundle wfi://git/pr/create` and use the actual
217
+ managed assignment and active delivery attempt. The executable operation is
218
+ `ace-assign delivery --assignment ID --attempt ATTEMPT --operation create --title TITLE --body-file DESCRIPTION`.
219
+ Provide `--parameters FILE` if required for the assignment's explicit delivery
220
+ mapping. Creation defaults to a draft. Record its returned server, repositories,
221
+ refs, PR number/URL and exact candidate_head.
222
+ 3. Execute the independent review workflow `ace-bundle wfi://review/pr` against that
223
+ exact PR and retained forge selection. Preserve its actual round completion rule,
224
+ findings and reviewer identities. Fix confirmed blocking findings and rerun
225
+ affected tests. Every new committed candidate, including task-only edits,
226
+ invalidates prior ready/merge evidence. Historical approval remains history.
227
+ 4. Obtain coordinator-accepted current-head test and independent review receipts
228
+ through the existing assignment boundary. File existence, fabricated approval,
229
+ exit zero or a worker claim cannot replace acceptance. Distinguish base_head,
230
+ candidate_head, evidence_git_ref and journal_commit; evidence commits do not
231
+ advance the deliverable branch. CI status is visible and advisory; failed
232
+ executed tests, stale evidence or unresolved review findings still block.
233
+ 5. Prepare the final PR body with the concrete behavior, executed checks,
234
+ independent verdict and remaining limitations. Load
235
+ `ace-bundle wfi://git/pr/update` and execute
236
+ `ace-assign delivery --assignment ID --attempt ATTEMPT --operation update --body-file DESCRIPTION`.
237
+ Mark ready only with accepted exact-head reference files:
238
+ `ace-assign delivery --assignment ID --attempt ATTEMPT --operation ready --tests TEST-REF --review REVIEW-REF`.
239
+ Each reference file contains only attempt_id and receipt_digest.
240
+ 6. Hand off merge only to the existing authorized integrator/service for the exact
241
+ PR, candidate and operation. Its executor uses the neutral provider merge with
242
+ both required values:
243
+ `ace-git pr merge IDENTIFIER --server NAME --expected-head CANDIDATE-SHA --method METHOD --format json`.
244
+ METHOD is the authorized squash, merge or rebase choice, never an implicit
245
+ default. The assignment worker consumes a completed verified service receipt:
246
+ `ace-assign delivery --assignment ID --attempt ATTEMPT --operation merge --tests TEST-REF --review REVIEW-REF --service-request REQUEST`.
247
+ This command does not dispatch or execute its own pending merge. If no actual
248
+ configured executor or valid receipt is available, retain the routed blocker.
249
+ 7. Local version/changelog preparation is optional requested work from step1.
250
+ It must be included before final exact-head evidence and merge. Preparation
251
+ requested after a completed merge starts a separate follow-up candidate/scope;
252
+ the old merge does not accept its amended content.
253
+ Publication, deployment and synchronization are distinct operations with their
254
+ own valid authorization, executed technical evidence and any required OTP.
255
+ Authorized merge does not authorize them. Do not add an unnecessary proposal
256
+ for an already authorized operation or fabricate an unavailable proposal API.
257
+ 8. Record the exact delivered scope, candidate, receipt references, review verdict
258
+ and remaining gates. A requested delivery-only scope can finish after its
259
+ authorized merge; publication is not mandatory. Keep the task in progress until
260
+ all of its actual acceptance criteria are satisfied.
261
+
262
+ ## Unavailable publication prerequisite
263
+
264
+ Requested publication is a separate step, never a consequence of merge success.
265
+ Use the existing configured service policy and publisher prerequisites; an absent
266
+ publisher or unavailable required OTP is a routed blocker, not permission to run
267
+ an alternate command/account. The ordinary tested publisher's precondition
268
+ failure is ordinary source evidence only; it does not supply a protected
269
+ publication receipt or positive scoped OTP capability.
270
+
271
+ If the requested step cannot proceed, record its value-free cause through the
272
+ existing assignment failure owner:
273
+ `ace-assign fail --assignment ID@SCOPE --attempt ATTEMPT --mapping MAPPING --message "publication blocked: prerequisite unavailable"`.
274
+ Use the actual original protected selectors; ordinary assignments omit protected
275
+ selectors and use their existing target. Read `ace-assign status` for that same
276
+ scope afterward. The step remains failed/unfinished, with no publication receipt
277
+ or task completion. Preserve an uncertain service request separately: a failure
278
+ report must not claim a definitive denial or effect absence from a lost reply.
279
+ Protected recovery requires the reviewed new prepared version/attempt; never
280
+ finish the failed step or retry publication to manufacture success.
281
+
282
+ ## Uncertainty and resume
283
+
284
+ In managed mode, read assignment status and retained qjl delivery events before
285
+ resuming. Repeat read/check operations safely. On interrupted create, update or readiness, use the
286
+ same delivery command for exact-selector reconciliation. One matching draft may
287
+ be adopted; zero remains unresolved and multiple matches conflict. A different
288
+ requested effect cannot be reported complete merely because an earlier effect
289
+ was recovered.
290
+
291
+ Unknown merge/publication remains unknown pending its existing owner's
292
+ reconciliation. Never blindly replay an effect, substitute a generic PR result
293
+ for a service receipt or translate a blocker into direct gh/fj commands.
294
+
295
+ ## Success criteria
296
+
297
+ - The requested scope has real artifact, current test and independent review
298
+ evidence for its exact candidate.
299
+ - Remote identity and explicit provenance remain fixed with honest unresolved
300
+ outcomes preserved; managed mode records them in the existing attempt journal.
301
+ - Readiness and authorized integration consume current evidence; managed merge
302
+ additionally consumes exact service receipts. Standalone output cannot satisfy
303
+ managed/protected acceptance. CI alone neither grants nor vetoes acceptance.
304
+ - Optional publication remains separately authorized and unfinished installed
305
+ criteria remain visible.
data/lib/ace/handbook/version.rb CHANGED
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Ace
4
4
  module Handbook
5
- VERSION = "0.33.0"
5
+ VERSION = "0.35.0"
6
6
  end
7
7
  end
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ace-handbook
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.33.0
4
+ version: 0.35.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Michal Czyz
8
8
  bindir: exe
9
9
  cert_chain: []
10
- date: 2026-09-29 00:00:00.000000000 Z
10
+ date: 2026-10-08 00:00:00.000000000 Z
11
11
  dependencies:
12
12
  - !ruby/object:Gem::Dependency
13
13
  name: ace-support-config