ace-handbook 0.33.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a640260822cd7518266797ae62628ae62a4cae9f6a96ca7604ed274245ac2915
-  data.tar.gz: 9f7e5b5515524a15a2547a874f0324961bb6e38489026d16f316bf2358bed2b6
+  metadata.gz: 6bac5cea7762cdf27f71764a6d79f8149763f83d6fc001157db3b869f0313869
+  data.tar.gz: 3062b5aa4e48907c9eeb26cc81d713ad8ccecdc948a9270e6324ea7e1eccd596
 SHA512:
-  metadata.gz: b67c9b8c9ad1c7a21121cd2e8694da47bfd545b2142dee84dfbcff70917049a0cb634e2194b938079db3f3a0d128ed3de1ca7e6b65585e97900c669a86ffd1c2
-  data.tar.gz: ad70a65d103696d260014b279073266ef0beab0e79a2d54ac4e575bc3217a5c1d290623a132e9bebce9192e49b7e89c609b34944ea50c47f3889f2d724fafc45
+  metadata.gz: 0fa6aa552edbfae44a919b680f396adf7dff0b1dfd4c7e26d5c9c9eae183719ec169604bebe58591e9854a1eafa41a700e676d9c1378bed14e7718283a676fb9
+  data.tar.gz: 6e61af1f361bcb6909fccbda5281a0342793ba0a79fd02369befdc29aa21ef5d30b2477725165e31bcbdf018c131ae17ab8a6cab740672c1f786e7a5d3d6ca66

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.34.0] - 2026-10-05
+
+### Changed
+
+- 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.
+
 ## [0.33.0] - 2026-09-28
 
 ### Added

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

@@ -1,272 +1,158 @@
 ---
 doc-type: workflow
-title: Perform Delivery Workflow
-purpose: Coordinate complete task delivery across implementation, review, release, and review cycles.
-ace-docs:
-  last-updated: 2026-03-12
-  last-checked: 2026-03-21
+title: Perform attempt-bound delivery
+purpose: Coordinate implementation, exact-head review and authorized delivery on the selected forge
 ---
 
-# Perform Delivery Workflow
+# Perform attempt-bound delivery
 
 ## Goal
 
-Execute complete delivery workflow for a task with automatic step tracking, ensuring no steps are lost during complex multi-step execution.
+Deliver one committed candidate in explicit standalone or managed mode, using
+the selected forge and current executed tests and independent review.
 
 ## Prerequisites
 
-* Task reference (e.g., `215.03`) OR detailed inline instructions
-* Clean git working directory (or staged changes ready for commit)
-* Understanding of the standard delivery workflow steps
-* Access to the relevant ACE CLI tools and workflows
-
-## Project Context Loading
-
-* Load task context via `ace-task show <ref>` if task reference provided
-* Load git status: `git status`
-* Load PR status: `gh pr view` (if PR exists)
-
-## High-Level Execution Plan
-
-### Phase 0: Externalize Workflow (CRITICAL - DO FIRST)
-
-* [ ] Parse input to identify delivery scope
-* [ ] Create TodoWrite entry for EVERY delivery step BEFORE starting work
-* [ ] Confirm todo list is complete before proceeding
-
-### Phase 1: Implementation
-
-* [ ] Enter plan mode if implementation required
-* [ ] Execute implementation via `ace-bundle wfi://task/work` or inline instructions
-* [ ] Commit all changes (`ace-git-commit`)
-* [ ] Release modified packages (`ace-bundle wfi://release/local` if applicable)
-* [ ] Mark task done and push to remote
-
-### Phase 2: PR & Initial Review
-
-* [ ] Create or update PR (`ace-bundle wfi://github/pr/create`)
-* [ ] Run initial review (`ace-bundle wfi://review/pr`)
-* [ ] Implement HIGH/CRITICAL feedback immediately
-
-### Phase 3: Deep Review Cycle
-
-* [ ] Run deep code review (`ace-bundle wfi://review/pr`, using the `code-deep` preset)
-* [ ] Implement MEDIUM+ severity feedback
-* [ ] Run test suite (`ace-test-suite`)
-* [ ] Commit fixes (`ace-git-commit`)
-* [ ] Repeat review cycle if needed
-
-## Process Steps
-
-### Phase 0: Externalize Workflow (CRITICAL - DO FIRST)
-
-**BEFORE reading any detailed content or starting implementation:**
-
-1. **Parse Input:**
-   * Identify if input is a task reference (e.g., `215.03`) or inline instructions
-   * Determine scope: full delivery vs. partial (implementation only, review only, etc.)
-
-2. **Create Session Todo List IMMEDIATELY:**
-   * Use TodoWrite to create entries for ALL delivery steps
-   * This MUST be the FIRST action before any other work
-   * Do not read implementation details until todo list is created
-
-   **Standard Delivery Steps to Add:**
-
-   ```
-   1. Implement task (via `ace-bundle wfi://task/work` or inline)
-   2. Commit all changes (`ace-git-commit`)
-   3. Release modified packages (`ace-bundle wfi://release/local`)
-   4. Mark task done and push to remote
-   5. Create/update PR (`ace-bundle wfi://github/pr/create`)
-   6. Initial review (`ace-bundle wfi://review/pr`)
-   7. Implement HIGH/CRITICAL feedback
-   8. Deep review (`ace-bundle wfi://review/pr` with `code-deep`)
-   9. Implement MEDIUM+ feedback
-   10. Run test suite and commit fixes
-   ```
-
-3. **Confirm Before Proceeding:**
-   * Output: "Session todo list created with N delivery steps"
-   * Only proceed to Phase 1 after todo list is confirmed
-
-### Phase 1: Implementation
-
-1. **Load Task Context (if task reference provided):**
-   * Load `ace-bundle wfi://task/work`, then follow it with the task reference
-   * If inline instructions provided, use those directly
-
-2. **Enter Plan Mode (if implementation required):**
-   * Prepare detailed implementation plan
-   * Get user approval before proceeding
-
-3. **Execute Implementation:**
-   * Follow the implementation plan
-   * Track progress using TodoWrite for sub-tasks
-
-4. **Commit Changes:**
-   * Run `ace-git-commit` to commit all changes
-   * Use descriptive commit message
-
-5. **Release Packages (if applicable):**
-   * Load `ace-bundle wfi://release/local` when a release is required
-   * Follow versioning conventions
-
-6. **Complete Task:**
-   * Mark task as done: `ace-task done <ref>`
-   * Push to remote: `git push`
-
-### Phase 2: PR & Initial Review
-
-1. **Create or Update PR:**
-   * Load `ace-bundle wfi://github/pr/create` to prepare the pull request flow
-   * Include task reference and summary
-
-2. **Run Initial Review:**
-   * Load `ace-bundle wfi://review/pr`
-   * Review the feedback output
-
-3. **Implement Critical Feedback:**
-   * Address all HIGH and CRITICAL severity items
-   * Commit fixes with descriptive messages
-
-### Phase 3: Deep Review Cycle
-
-1. **Run Deep Code Review:**
-   * Load `ace-bundle wfi://review/pr` and use the `code-deep` preset
-   * This provides more thorough analysis
-
-2. **Implement Feedback:**
-   * Address MEDIUM severity and above items
-   * Consider LOW severity items for future improvements
-
-3. **Run Test Suite:**
-   * Run `ace-test-suite` to verify all tests pass
-   * Fix any failing tests
-
-4. **Commit Fixes:**
-   * Run `ace-git-commit` to commit all fixes
-
-5. **Repeat Review Cycle (if needed):**
-   * If significant changes were made, run another review
-   * Continue until no HIGH/CRITICAL items remain
-
-## Checkpoint Protocol
-
-**After completing EACH numbered todo item:**
-
-1. Mark the todo as COMPLETED using TodoWrite
-2. Output checkpoint message:
-
-   ```
-   ✓ Step N complete: [step description]
-   → Next: Step N+1 - [next step description]
-   ```
-
-3. Read todo list to confirm next step
-4. Continue IMMEDIATELY to next step (no user prompt needed unless blocked)
-
-**On Failure:**
-
-1. Mark the current todo as blocked (keep as in_progress)
-2. Output failure message:
-
-   ```
-   ✗ Step N failed: [step description]
-   → Error: [error description]
-   → Action needed: [what user needs to do]
-   ```
-
-3. Ask user for guidance using AskUserQuestion
-4. Resume workflow after issue is resolved
-
-## Auto-Continue Protocol
-
-**CRITICAL:** This workflow should AUTO-CONTINUE between steps without waiting for user input.
-
-The only times to pause and ask the user:
-
-* Plan mode approval (Phase 1)
-* Step failure requiring user intervention
-* Ambiguous instructions requiring clarification
-* External blockers (CI failures, merge conflicts, etc.)
-
-For all other transitions, immediately proceed to the next step after checkpoint.
-
-## Scope Variations
-
-### Full Delivery (default)
-
-All steps from implementation through review cycles. Load `ace-bundle wfi://handbook/perform-delivery`.
-
-### Implementation Only
-
-Skip PR and review phases (useful for WIP branches). Load `ace-bundle wfi://handbook/perform-delivery`.
-
-### Review Only
-
-Skip implementation, start from PR creation. Load `ace-bundle wfi://handbook/perform-delivery`.
-
-### Custom Instructions
-
-Provide inline instructions instead of task reference. Load `ace-bundle wfi://handbook/perform-delivery`.
-
-## Success Criteria
-
-* All todo items marked as completed
-* No skipped or forgotten steps
-* All commits pushed to remote
-* PR created (if applicable)
-* All HIGH/CRITICAL review feedback addressed
-* Test suite passing
-* Task marked as done in taskflow
-
-## Error Handling
-
-**Step Fails to Complete:**
-
-* Keep todo item as in_progress
-* Log the error with context
-* Ask user for guidance
-* Resume from failed step after resolution
-
-**User Interruption:**
-
-* Save current state (which step is in progress)
-* Allow resume from interruption point
-* Maintain todo list across session
-
-**External Tool Failure:**
-
-* Report which tool failed and the error
-* Suggest manual alternatives if available
-* Wait for user guidance before proceeding
-
-## Usage Examples
-
-### Full Task Delivery
-
-> "Perform delivery for task 215.03"
-
-This will:
-1. Load task context
-2. Implement the task
-3. Commit, release, mark done
-4. Create PR
-5. Review and iterate
-
-### Review Cycle Only
-
-> "Perform delivery for task 215.03 --scope review"
-
-This will:
-1. Create/update PR
-2. Review and implement feedback
-3. Run test suite
-4. Iterate until clean
-
-### Custom Workflow
-
-> "Perform delivery: implement the dark mode feature, commit, create PR, and run one review cycle"
-
-This will parse the custom instructions and create a todo list matching the requested steps.
+- A reviewed task or an explicit implementation scope and project.
+- For managed delivery, a managed assignment and an active scoped attempt for each
+  delivery action; use the actual assignment and
+  attempt IDs from the execution boundary, never caller-invented actor identity.
+- For remote delivery, a pushed candidate and explicit fork/canonical provenance:
+  mode, head_repository_url, head_ref, base_repository_url and base_ref.
+- An applicable authorization for each effect. Transport credentials do not grant
+  permission to merge, publish, deploy or synchronize.
+
+Choose standalone mode for ordinary local task/inline implementation, tests, review
+and optional requested version/changelog preparation without a managed assignment.
+Choose managed mode when the request supplies an assignment or requires its
+canonical attempt/receipt boundary. Standalone output cannot satisfy managed or
+protected acceptance. Local-only implementation needs no forge selection or
+scoped attempt. If remote delivery is requested,
+use forge_server or forge_default: true, mutually exclusive; otherwise use the
+repository remote. Preserve the first resolved server/repository/PR identity
+throughout the assignment. Missing service or authorization yields a specific
+blocker; this workflow does not invent grants or impersonate an integrator.
+
+## Project context loading
+
+Read the task or inline scope and actual committed diff. In managed mode also
+read assignment status, current attempt and retained delivery parameters. If a PR
+is recorded, inspect it with
+`ace-git pr show IDENTIFIER --format json --server NAME` using the retained selection
+(or `--default-server`, otherwise remote resolution). Inside ACE use source
+`bin/ace-*` commands. Load the relevant implementation and test instructions.
+
+## Standalone delivery
+
+Implement and commit the requested local task/inline scope using existing task
+and Git tools. Execute appropriate tests and independent review, retain their
+actual artifact references and candidate SHA, and record unfinished criteria.
+No managed assignment, protected service receipt or canonical qjl acceptance is
+claimed by this route. Local scope may end here.
+
+For an explicitly authorized standalone remote scope, use existing neutral
+primitives on the chosen base repository/forge. Record actual head/base
+repository URLs and refs; canonical provenance means matching repositories,
+while fork provenance requires its explicit source URL. A pushed source ref must
+match the candidate SHA. Draft creation defaults to true:
+
+`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`
+
+Read the returned exact PR identity. Update with
+`ace-git pr update IDENTIFIER --server NAME --expected-head CANDIDATE-SHA --body-file DESCRIPTION --format json`.
+Use the retained default/remote selection instead of `--server NAME` when
+applicable. Review through the existing neutral review workflow with the same
+selection. Before readiness or merge, require passed executed tests and accepted
+independent review for that exact candidate and the actual operation authorization;
+the low-level PR command does not establish these gates itself. Readiness uses
+`ace-git pr ready IDENTIFIER --server NAME --expected-head CANDIDATE-SHA --format json`.
+Only an actually authorized standalone integrator may call
+`ace-git pr merge IDENTIFIER --server NAME --expected-head CANDIDATE-SHA --method METHOD --format json`.
+This is not a worker fallback when a managed/protected service is unavailable.
+Remote errors or uncertain effects remain explicit unresolved outcomes; use
+authoritative reads and existing provider reconciliation, never blind replay.
+
+Perform any requested local version/changelog changes before final test/review
+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
+
+1. Record the requested delivery steps and their owners before implementation.
+   Follow the existing task-work plan. Commit the implementation and run appropriate
+   package tests. If requested, perform local version/changelog preparation with
+   `ace-bundle wfi://release/local` before final evidence and merge; it does not
+   publish. Keep unfinished task criteria open; a bounded source checkpoint
+   cannot mark an entire installed task done.
+2. For remote delivery, prepare a concrete title and description from the changes
+   and executed validation. Load `ace-bundle wfi://git/pr/create` and use the actual
+   managed assignment and active delivery attempt. The executable operation is
+   `ace-assign delivery --assignment ID --attempt ATTEMPT --operation create --title TITLE --body-file DESCRIPTION`.
+   Provide `--parameters FILE` if required for the assignment's explicit delivery
+   mapping. Creation defaults to a draft. Record its returned server, repositories,
+   refs, PR number/URL and exact candidate_head.
+3. Execute the independent review workflow `ace-bundle wfi://review/pr` against that
+   exact PR and retained forge selection. Preserve its actual round completion rule,
+   findings and reviewer identities. Fix confirmed blocking findings and rerun
+   affected tests. Every new committed candidate, including task-only edits,
+   invalidates prior ready/merge evidence. Historical approval remains history.
+4. Obtain coordinator-accepted current-head test and independent review receipts
+   through the existing assignment boundary. File existence, fabricated approval,
+   exit zero or a worker claim cannot replace acceptance. Distinguish base_head,
+   candidate_head, evidence_git_ref and journal_commit; evidence commits do not
+   advance the deliverable branch. CI status is visible and advisory; failed
+   executed tests, stale evidence or unresolved review findings still block.
+5. Prepare the final PR body with the concrete behavior, executed checks,
+   independent verdict and remaining limitations. Load
+   `ace-bundle wfi://git/pr/update` and execute
+   `ace-assign delivery --assignment ID --attempt ATTEMPT --operation update --body-file DESCRIPTION`.
+   Mark ready only with accepted exact-head reference files:
+   `ace-assign delivery --assignment ID --attempt ATTEMPT --operation ready --tests TEST-REF --review REVIEW-REF`.
+   Each reference file contains only attempt_id and receipt_digest.
+6. Hand off merge only to the existing authorized integrator/service for the exact
+   PR, candidate and operation. Its executor uses the neutral provider merge with
+   both required values:
+   `ace-git pr merge IDENTIFIER --server NAME --expected-head CANDIDATE-SHA --method METHOD --format json`.
+   METHOD is the authorized squash, merge or rebase choice, never an implicit
+   default. The assignment worker consumes a completed verified service receipt:
+   `ace-assign delivery --assignment ID --attempt ATTEMPT --operation merge --tests TEST-REF --review REVIEW-REF --service-request REQUEST`.
+   This command does not dispatch or execute its own pending merge. If no actual
+   configured executor or valid receipt is available, retain the routed blocker.
+7. Local version/changelog preparation is optional requested work from step1.
+   It must be included before final exact-head evidence and merge. Preparation
+   requested after a completed merge starts a separate follow-up candidate/scope;
+   the old merge does not accept its amended content.
+   Publication, deployment and synchronization are distinct operations with their
+   own valid authorization, executed technical evidence and any required OTP.
+   Authorized merge does not authorize them. Do not add an unnecessary proposal
+   for an already authorized operation or fabricate an unavailable proposal API.
+8. Record the exact delivered scope, candidate, receipt references, review verdict
+   and remaining gates. A requested delivery-only scope can finish after its
+   authorized merge; publication is not mandatory. Keep the task in progress until
+   all of its actual acceptance criteria are satisfied.
+
+## Uncertainty and resume
+
+In managed mode, read assignment status and retained qjl delivery events before
+resuming. Repeat read/check operations safely. On interrupted create, update or readiness, use the
+same delivery command for exact-selector reconciliation. One matching draft may
+be adopted; zero remains unresolved and multiple matches conflict. A different
+requested effect cannot be reported complete merely because an earlier effect
+was recovered.
+
+Unknown merge/publication remains unknown pending its existing owner's
+reconciliation. Never blindly replay an effect, substitute a generic PR result
+for a service receipt or translate a blocker into direct gh/fj commands.
+
+## Success criteria
+
+- The requested scope has real artifact, current test and independent review
+  evidence for its exact candidate.
+- Remote identity and explicit provenance remain fixed with honest unresolved
+  outcomes preserved; managed mode records them in the existing attempt journal.
+- Readiness and authorized integration consume current evidence; managed merge
+  additionally consumes exact service receipts. Standalone output cannot satisfy
+  managed/protected acceptance. CI alone neither grants nor vetoes acceptance.
+- Optional publication remains separately authorized and unfinished installed
+  criteria remain visible.

data/lib/ace/handbook/version.rb

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

metadata

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