ace-handbook 0.32.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e70a71fff6e61cbaa6724591eb965481b3b92153aed554c5fd6ad8b51f3e01e
-  data.tar.gz: 99db5b08f74300bfbc87b71f2621a0bcee70934d92a89d7a142884adb8a2e434
+  metadata.gz: 6bac5cea7762cdf27f71764a6d79f8149763f83d6fc001157db3b869f0313869
+  data.tar.gz: 3062b5aa4e48907c9eeb26cc81d713ad8ccecdc948a9270e6324ea7e1eccd596
 SHA512:
-  metadata.gz: 34c7119d2d01e4ad2ff58a6b91bc5b4b092fb42a575abc33319d3ee6f4c7e237058f1135c19ab560565ff3fa91a696e39a9b92e27b6b839f855de0bf20de0c64
-  data.tar.gz: c1b28858004960a5ef381e50bde467910b6694bfb29179e7cdd7014d45d25a2eb47ece9d75996cef92e35c30892705ca7687a6340f169b86e07781a287f8e499
+  metadata.gz: 0fa6aa552edbfae44a919b680f396adf7dff0b1dfd4c7e26d5c9c9eae183719ec169604bebe58591e9854a1eafa41a700e676d9c1378bed14e7718283a676fb9
+  data.tar.gz: 6e61af1f361bcb6909fccbda5281a0342793ba0a79fd02369befdc29aa21ef5d30b2477725165e31bcbdf018c131ae17ab8a6cab740672c1f786e7a5d3d6ca66

data/CHANGELOG.md

@@ -7,6 +7,17 @@ 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
+- Provider manifests may declare an optional `extensions_dir`; `ace-handbook sync` now projects extension assets from `ace-handbook-integration-*` packages (`handbook/extensions/**`) into that directory (idempotent copies; prunes only stale paths recorded in the `.ace-handbook-projection.json` receipt, leaving user-authored extensions untouched). Destinations are validated before anything is written; a failed projection rolls back overwritten **and** pruned assets so the previous installation stays complete and loadable, and the retry needs no manual cleanup. Sync summary output gains a `; extensions <dir> (N files, U updated, R removed)` segment when a provider projects extensions. `ProviderRegistry` exposes `extensions_dir(provider)` and `package_root(provider)`.
+
 ## [0.32.0] - 2026-09-27
 
 ### 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/atoms/provider_registry.rb

@@ -38,6 +38,15 @@ module Ace
           manifest(provider)["prompts_dir"]
         end
 
+        def extensions_dir(provider)
+          manifest(provider)["extensions_dir"]
+        end
+
+        def package_root(provider)
+          manifest_dir = File.dirname(manifest(provider).fetch("_manifest_path"))
+          File.expand_path("../../..", manifest_dir)
+        end
+
         def manifests
           @manifests ||= begin
             all_paths = local_manifest_paths + installed_manifest_paths

data/lib/ace/handbook/cli/commands/sync.rb

@@ -26,6 +26,7 @@ module Ace
                      "(#{result[:projected_skills]} skills, #{result[:updated_files]} updated, " \
                      "#{result[:removed_entries]} removed)"
               line += format_prompts_summary(result) if result.key?(:relative_prompts_dir)
+              line += format_extensions_summary(result) if result.key?(:relative_extensions_dir)
               puts line
             end
             print_inventory_summary(results)
@@ -41,6 +42,12 @@ module Ace
               "#{result[:removed_prompt_entries]} removed)"
           end
 
+          def format_extensions_summary(result)
+            "; extensions #{result[:relative_extensions_dir]} " \
+              "(#{result[:projected_extensions]} files, #{result[:updated_extension_files]} updated, " \
+              "#{result[:removed_extension_entries]} removed)"
+          end
+
           def print_inventory_summary(results)
             source_breakdown = results.first&.fetch(:source_breakdown, {})
             return if source_breakdown.nil? || source_breakdown.empty?

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

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "json"
+require "pathname"
+require "tempfile"
 require "yaml"
 
 module Ace
@@ -8,6 +11,7 @@ module Ace
     module Organisms
       class ProviderSyncer
         PROJECTION_SOURCE_PREFIX = "ace-handbook-integration-"
+        EXTENSION_RECEIPT_NAME = ".ace-handbook-projection.json"
 
         attr_reader :project_root, :registry, :inventory, :prompt_inventory, :config
 
@@ -36,11 +40,12 @@ module Ace
         private
 
         def sync_provider(provider, skills:, source_breakdown:)
-          skills_result = sync_skills(provider, skills: skills, source_breakdown: source_breakdown)
+          result = sync_skills(provider, skills: skills, source_breakdown: source_breakdown)
           prompts_result = sync_prompts(provider)
-          return skills_result if prompts_result.nil?
-
-          skills_result.merge(prompts_result)
+          result = result.merge(prompts_result) unless prompts_result.nil?
+          extensions_result = sync_extensions(provider)
+          result = result.merge(extensions_result) unless extensions_result.nil?
+          result
         end
 
         def sync_skills(provider, skills:, source_breakdown:)
@@ -171,6 +176,258 @@ module Ace
           stale.size
         end
 
+        # Extension assets project from a package's handbook/extensions/ tree
+        # into the provider manifest's extensions_dir. The target directory may
+        # hold user-authored extensions, so pruning is receipt-based: only files
+        # recorded in the projection receipt from a previous sync are removed.
+        def sync_extensions(provider)
+          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")
+          expected = extension_source_files(source_dir)
+          output_dir = File.join(project_root, extensions_dir)
+          FileUtils.mkdir_p(output_dir)
+
+          receipt = read_projection_receipt(output_dir, provider)
+          # Ownership requires a valid receipt from this projection explicitly
+          # listing the path. A missing, symlinked, or corrupt receipt leaves
+          # ownership unknown: any conflicting destination file is refused so
+          # user-authored extensions can never be overwritten on a guess.
+          owned_paths = receipt&.fetch("files", []) || []
+          reject_unowned_collisions(output_dir, expected.keys, owned_paths)
+
+          # Pruning happens only after the replacement projection committed:
+          # a failed upgrade must leave the previous installation usable.
+          stale_paths = receipt&.fetch("files", [])&.-(expected.keys) || []
+          updated_files = 0
+
+          # Resolve and validate every destination before writing anything: a
+          # failure mid-copy must never leave half a projection behind (files
+          # written before a later validation error would be unowned and wedge
+          # every retry).
+          output_paths = expected.each_with_object({}) do |(relative_path, source_path), map|
+            map[relative_path] = validate_projection_destination(output_dir, relative_path, extensions_dir)
+          end
+
+          newly_created = []
+          saved_originals = {}
+          failed_prunes = []
+          begin
+            output_paths.each do |relative_path, output_path|
+              source_path = expected.fetch(relative_path)
+              FileUtils.mkdir_p(File.dirname(output_path))
+              created = !File.exist?(output_path)
+              # Register before copying: a copy that fails partway (disk
+              # exhaustion) must still roll back the partial file. Overwritten
+              # files are receipt-owned, so rollback restores their previous
+              # content instead of deleting them.
+              saved_originals[output_path] = File.binread(output_path) unless created
+              newly_created << output_path if created
+              next if !created && FileUtils.compare_file(source_path, output_path)
+
+              FileUtils.cp(source_path, output_path)
+              updated_files += 1
+            end
+
+            removed_entries = prune_stale_extension_files(output_dir, stale_paths, failed_prunes, saved_originals)
+            # Stale files whose removal failed keep their ownership until a
+            # later sync manages to delete them.
+            write_projection_receipt(output_dir, provider, expected.keys + failed_prunes)
+          rescue
+            # Roll back so a retry never finds its own partial installation
+            # standing in the way as an unowned collision, and restore the
+            # previous content of overwritten and pruned files — the previous
+            # installation must stay complete and loadable.
+            newly_created.each do |path|
+              FileUtils.rm_f(path)
+            rescue
+              nil
+            end
+            saved_originals.each do |path, content|
+              # Pruned assets restore after pruning emptied and removed their
+              # directories; a path swapped to a symlink mid-sync is never
+              # written through.
+              next if File.symlink?(path)
+
+              FileUtils.mkdir_p(File.dirname(path))
+              File.binwrite(path, content)
+            rescue
+              nil
+            end
+            newly_created.each do |path|
+              remove_empty_parent_dirs(File.dirname(path), output_dir)
+            end
+            raise
+          end
+
+          {
+            relative_extensions_dir: extensions_dir,
+            projected_extensions: expected.size,
+            updated_extension_files: updated_files,
+            removed_extension_entries: removed_entries
+          }
+        end
+
+        # The destination directory may hold user-authored extensions, so a
+        # destination file that exists before the first ACE projection (or one
+        # the receipt does not own) is never overwritten: the sync fails with
+        # a visible error instead of destroying user files.
+        def reject_unowned_collisions(output_dir, expected_relative_paths, owned_paths)
+          expected_relative_paths.each do |relative_path|
+            next if owned_paths.include?(relative_path)
+
+            candidate = safe_projection_path(output_dir, relative_path)
+            next if candidate.nil? || !File.exist?(candidate)
+
+            raise StandardError,
+              "refusing to overwrite existing file #{candidate}; it is not claimed by a valid projection receipt " \
+              "(missing, symlinked, or corrupt receipts claim nothing). Move or remove the file — or repair or remove " \
+              "#{File.join(output_dir, EXTENSION_RECEIPT_NAME)} — then rerun `ace-handbook sync`."
+          end
+        end
+
+        # Resolve and fully validate a destination before any file is
+        # written: every ancestor must be a directory or creatable (no
+        # regular files, no symlinks), so a mid-copy failure can never leave
+        # a half-installed projection that wedges retries.
+        def validate_projection_destination(output_dir, relative_path, extensions_dir)
+          segments = relative_path.split(File::SEPARATOR)
+          if segments.empty? || segments.any? { |segment| segment.empty? || segment == "." || segment == ".." }
+            raise StandardError, "cannot project #{relative_path.inspect}: invalid destination path"
+          end
+
+          current = Pathname.new(File.realpath(output_dir))
+          segments.each do |segment|
+            current = current.join(segment)
+            if File.symlink?(current.to_s)
+              raise StandardError,
+                "cannot project #{relative_path} into #{extensions_dir}: a symlinked path component would escape the projection directory"
+            end
+            next if segments.last == segment
+
+            if !current.directory? && File.exist?(current.to_s)
+              raise StandardError,
+                "cannot project #{relative_path} into #{extensions_dir}: #{current} exists and is not a directory"
+            end
+          end
+          if File.directory?(current.to_s)
+            # Receipt ownership of a path never authorizes writing through a
+            # directory planted at that path — cp would reinterpret the
+            # destination as a container and overwrite unowned content.
+            raise StandardError,
+              "cannot project #{relative_path} into #{extensions_dir}: #{current} exists and is a directory"
+          end
+          current.to_s
+        rescue Errno::ENOENT
+          raise StandardError, "cannot project #{relative_path} into #{extensions_dir}: projection directory vanished"
+        end
+
+        def extension_source_files(source_dir)
+          return {} unless Dir.exist?(source_dir)
+
+          source_root = Pathname.new(source_dir)
+          Dir.glob(File.join(source_dir, "**", "*"))
+            .select { |path| File.file?(path) }
+            .to_h { |path| [Pathname.new(path).relative_path_from(source_root).to_s, path] }
+        end
+
+        def prune_stale_extension_files(output_dir, stale_relative_paths, failed_prunes, rollback_ledger)
+          stale = stale_relative_paths
+          removed = 0
+          stale.each do |relative_path|
+            contained = safe_projection_path(output_dir, relative_path)
+            next if contained.nil?
+            next unless File.file?(contained)
+
+            begin
+              # Each pruned asset joins the rollback ledger before deletion:
+              # if publication later fails, restoring only overwritten files
+              # would leave the retained previous entrypoint importing a
+              # module that no longer exists.
+              rollback_ledger[contained] = File.binread(contained)
+              FileUtils.rm(contained)
+              removed += 1
+              remove_empty_parent_dirs(File.dirname(contained), output_dir)
+            rescue
+              # Keep ownership of the undeletable file: the next sync retries
+              # the removal instead of forgetting the file belongs to ACE.
+              failed_prunes << relative_path
+            end
+          end
+          removed
+        end
+
+        # Receipt files are projected data, so treat them as untrusted, and
+        # destination paths are resolved on the real filesystem: only plain
+        # relative paths whose every component stays inside output_dir — with
+        # no symlinked component, which could point anywhere — may be written
+        # or pruned.
+        def safe_projection_path(output_dir, relative_path)
+          return nil unless relative_path.is_a?(String)
+          return nil if relative_path.include?("\0")
+
+          segments = relative_path.split(File::SEPARATOR)
+          return nil if segments.empty? || segments.any? { |segment| segment.empty? || segment == "." || segment == ".." }
+
+          current = Pathname.new(File.realpath(output_dir))
+          segments.each do |segment|
+            current = current.join(segment)
+            return nil if File.symlink?(current.to_s)
+          end
+          current.to_s
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def read_projection_receipt(output_dir, provider)
+          receipt_path = File.join(output_dir, EXTENSION_RECEIPT_NAME)
+          return nil if File.symlink?(receipt_path)
+          return nil unless File.file?(receipt_path)
+
+          receipt = JSON.parse(File.read(receipt_path))
+          return nil unless receipt.is_a?(Hash) && receipt["files"].is_a?(Array)
+          # A receipt from another projector (or without provenance) claims
+          # nothing: only our own source marker authorizes overwrites and
+          # pruning.
+          return nil unless receipt["source"] == "#{PROJECTION_SOURCE_PREFIX}#{provider}"
+
+          receipt
+        rescue JSON::ParserError
+          nil
+        end
+
+        def write_projection_receipt(output_dir, provider, relative_paths)
+          receipt_path = File.join(output_dir, EXTENSION_RECEIPT_NAME)
+          # Create the temp file exclusively in the destination directory: a
+          # predictable, plainly-opened temp path could follow a planted
+          # symlink and truncate a file outside the projection. The rename
+          # then replaces any symlink at the receipt path itself.
+          temp = Tempfile.create([".ace-handbook-projection", ".tmp"], output_dir)
+          begin
+            temp.write(JSON.pretty_generate(
+              "source" => "#{PROJECTION_SOURCE_PREFIX}#{provider}",
+              "files" => relative_paths.sort
+            ))
+            temp.close
+            File.rename(temp.path, receipt_path)
+          ensure
+            temp.close
+            FileUtils.rm_f(temp.path)
+          end
+        end
+
+        def remove_empty_parent_dirs(dir, stop_dir)
+          until dir == stop_dir
+            FileUtils.rmdir(dir)
+            dir = File.dirname(dir)
+          end
+        rescue Errno::ENOTEMPTY, Errno::ENOENT
+          # Surviving siblings (or a vanished ancestor) stop the ascent; the
+          # sync must continue writing remaining assets and the receipt.
+          nil
+        end
+
         # The prompts dir is shared with user-authored templates, so only files
         # carrying an ACE integration provenance marker are ever pruned.
         def prune_stale_prompt_files(output_dir, expected_template_names)
@@ -189,7 +446,7 @@ module Ace
 
           frontmatter = YAML.safe_load(match[1], permitted_classes: [Date, Time], aliases: true)
           frontmatter.is_a?(Hash) ? frontmatter["source"].to_s : ""
-        rescue StandardError
+        rescue
           ""
         end
       end

data/lib/ace/handbook/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Handbook
-    VERSION = "0.32.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.32.0
+  version: 0.34.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-27 00:00:00.000000000 Z
+date: 2026-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config