ace-handbook 0.31.1 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 358264b1f225530c26fd23fcb8528d7e665b927daaa452350536a18c90148e9a
-  data.tar.gz: 776f9919aa44963a4f779ea662d8741e826436aed7ab23c7698a511190dab8ea
+  metadata.gz: a640260822cd7518266797ae62628ae62a4cae9f6a96ca7604ed274245ac2915
+  data.tar.gz: 9f7e5b5515524a15a2547a874f0324961bb6e38489026d16f316bf2358bed2b6
 SHA512:
-  metadata.gz: 90c8229c6064db0967a97d999138395f57b7570c56d5742e31d717a0ccfbbef83e7127d771c095c960017c3ba021bd661196337e445d365821deb6ee01eee7ba
-  data.tar.gz: e30d53307d64883ff5d89a46aab6f4592559f72d1f6014ed4bc174f1554bd7f53a86cde03be5ade43afb85c1ead270b52094085b7dbd6a44fc1bdca632c014f0
+  metadata.gz: b67c9b8c9ad1c7a21121cd2e8694da47bfd545b2142dee84dfbcff70917049a0cb634e2194b938079db3f3a0d128ed3de1ca7e6b65585e97900c669a86ffd1c2
+  data.tar.gz: ad70a65d103696d260014b279073266ef0beab0e79a2d54ac4e575bc3217a5c1d290623a132e9bebce9192e49b7e89c609b34944ea50c47f3889f2d724fafc45

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Provider manifests may declare an optional `prompts_dir`; `ace-handbook sync` now projects canonical prompt templates from `ace-handbook-integration-*` packages (`handbook/prompts/*.md`) into that directory (idempotent writes; prunes only stale files carrying an `ace-handbook-integration-*` provenance marker, leaving user-authored templates untouched). Sync summary output gains a `; prompts <dir> (N prompts, U updated, R removed)` segment when a provider projects prompts.
+- Shipped `wfi://handbook/manage-overrides` (with paired skill `as-handbook-manage-overrides`): canonical override documentation covering all overridable surfaces (workflows, cookbooks, guides), the source-priority resolution rule, skills' non-overridability ("override the workflow the skill calls"), the `.agents/` sync-projection status, and planted-competitor verification probes.
+
 ### Changed
 - Tightened `wfi://release/rubygems-publish` baseline guidance with an OTP-burst publication contract (build all artifacts before OTP; push in ≤5 concurrent waves; defer metadata verification) for project overlays.
 

data/README.md

@@ -36,7 +36,7 @@
 
 **Integrate with resource discovery and context loading** - pair with [ace-nav](../ace-support-nav) for workflow and resource discovery, [ace-bundle](../ace-bundle) for loading complete workflow instructions, and provider integrations (`ace-handbook-integration-*`) that can project canonical handbook skills into harness-native folders on request.
 
-**Sync and inspect skill projections** - run `ace-handbook sync` to project canonical skills into `.agents/skills/` by default, or use `ace-handbook sync --provider PROVIDER` for harness-native folders such as `.codex/skills/`.
+**Sync and inspect skill projections** - run `ace-handbook sync` to project canonical skills into `.agents/skills/` by default, or use `ace-handbook sync --provider PROVIDER` for harness-native folders such as `.codex/skills/`. Providers whose manifest also declares `prompts_dir` additionally receive canonical prompt templates from the matching integration package's `handbook/prompts/*.md` (projected flat into that directory; user-authored templates without an `ace-handbook-integration-*` provenance marker are never pruned).
 
 **Extend handbook content in normal projects** - put project-specific workflows, guides, cookbooks, templates, and skills under `.ace-handbook/` and discover them with protocol URLs (`wfi://`, `guide://`, `cookbook://`, `tmpl://`, `skill://`). See [Usage Guide](docs/usage.md) for path conventions.
 

data/handbook/skills/as-handbook-manage-overrides/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: as-handbook-manage-overrides
+description: Manage project-local overrides of ace-managed docs (workflows, cookbooks, guides) and verify resolution precedence
+# bundle: wfi://handbook/manage-overrides
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-nav:*)
+  - Bash(ace-handbook:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - LS
+argument-hint: "[surface|uri] [action: plan|verify]"
+last_modified: 2026-09-20
+source: ace-handbook
+integration:
+  targets:
+    - claude
+    - codex
+    - gemini
+    - opencode
+    - pi
+  providers: {}
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://handbook/manage-overrides
+---
+
+Load and run `ace-bundle wfi://handbook/manage-overrides` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

data/handbook/workflow-instructions/handbook/manage-cookbooks.wf.md

@@ -60,6 +60,7 @@ Brief description of what this cookbook accomplishes.
 
 - Package-owned cookbooks (inside `ace-handbook`): `ace-handbook/handbook/cookbooks/`
 - Project-local cookbooks (outside package scope): `.ace-handbook/cookbooks/`
+- Project-local document overrides (workflows, cookbooks, guides) and resolution precedence are governed canonically by `wfi://handbook/manage-overrides`
 
 ## Process Steps
 

data/handbook/workflow-instructions/handbook/manage-overrides.wf.md

@@ -0,0 +1,142 @@
+---
+doc-type: workflow
+name: manage-overrides
+title: Manage Project-Local Overrides
+description: Canonical reference for ace-managed document override surfaces, resolution precedence, and verification probes
+purpose: Documentation for ace-handbook/handbook/workflow-instructions/handbook/manage-overrides.wf.md
+allowed-tools:
+  - Bash(ace-nav:*)
+  - Bash(ace-bundle:*)
+  - Bash(ace-handbook:*)
+  - Read
+  - Write
+  - Edit
+ace-docs:
+  last-updated: 2026-09-20
+  last-checked: 2026-09-20
+---
+
+# Manage Project-Local Overrides
+
+## Goal
+
+Answer, from shipped documentation and tooling, the three override questions: which ace-managed documents can this
+project override, where do the project-local files live, and who wins when a project-local file and a gem file share
+the same name. This workflow is the canonical reference; `ace-nav resolve --why` makes the same precedence observable
+per URI.
+
+## Prerequisites
+
+- Understanding of handbook asset conventions (workflows, cookbooks, guides, skills)
+- `ace-nav` and `ace-handbook` available in the project bundle
+
+## Override Surfaces
+
+| Surface | Protocol | Project-local location | Overridable? | Winner of duplicates (shipped defaults) |
+|---------|----------|------------------------|--------------|------------------------------------------|
+| Workflows | `wfi://` | `.ace-handbook/workflow-instructions/<ns>/<name>.wf.md` | Yes | Project-local, when its source priority is lower than the gem source's (e.g. the shipped `local` source at priority 5 vs gem at 10) |
+| Cookbooks | `cookbook://` | `.ace-handbook/cookbooks/<name>.cookbook.md` | Yes | The candidate from the source with the lower priority number. The shipped project-local default registers priority 20 and the gem source 10, so **the gem wins by default**; register a project cookbook source with priority < 10 to make project-local win |
+| Guides | `guide://` | `handbook/guides/<name>.g.md` | Yes, with registration | Requires a project source registration (`.ace/nav/protocols/guide-sources/local.yml` → `handbook/guides`); with priority < 10 the project-local guide wins. Without registration the gem wins |
+| Skills | `skill://` | none | **No** | Always the gem. Skills are thin layers; override the workflow the skill calls instead |
+| `.agents/skills/` projection | — | written by `ace-handbook sync` | Never edit | Not a resolution source. Neutral `agents`-provider mirror regenerated (and stale entries pruned) on every sync; it does not ship |
+
+## Resolution Rule
+
+Sources for a protocol are scanned in ascending priority order (lower number = higher precedence); the first source
+containing the resource wins and remaining duplicates are ignored. Registration defaults: project sources 10, user
+sources 50, gem defaults 100 — an individual source registration may pin another value (this is why the shipped
+`local` workflow source at priority 5 beats the gem at 10, while the shipped project-local cookbook source at 20 loses
+to the gem at 10).
+
+To answer "why did this candidate win?" for a concrete URI without planting probe files:
+
+```bash
+ace-nav resolve wfi://release/publish --why
+# uri: wfi://release/publish
+# rule: Candidates are tried in ascending source-priority order ...
+# candidates (resolution order):
+#   1. [priority 5]  @local (project) → ...   ← winner
+#   2. [priority 10] @ace-handbook (gem-default) → ...
+```
+
+## Skills Are Not Overridable
+
+Skills (`skill://`) are thin launch layers that load and execute a workflow; they carry no logic worth overriding.
+Consequently no project-local skill source exists: competitors planted in `.ace-handbook/skills/` or `.agents/skills/`
+are ignored and resolution always returns the gem file. The design rule is: **override the workflow the skill calls**
+(under `.ace-handbook/workflow-instructions/`), not the skill. To change a skill's own wording, change the canonical
+`handbook/skills/<name>/SKILL.md` in the owning gem and run `ace-handbook sync`.
+
+## Process Steps
+
+1. **Identify the surface** you need to override (workflow, cookbook, or guide) and its canonical gem path.
+2. **Create the project-local file** at the surface's project-local location (see table), keeping the canonical
+   frontmatter and structure so tools keep resolving it.
+3. **Ensure the source registration makes your file win:**
+   - workflows: keep `.ace/nav/protocols/wfi-sources/local.yml` priority below the gem source (shipped default: 5).
+   - cookbooks: register `.ace/nav/protocols/cookbook-sources/local.yml` with priority < 10 (the shipped
+     project-local default of 20 loses to the gem's 10).
+   - guides: register `.ace/nav/protocols/guide-sources/local.yml` pointing at `handbook/guides` with priority < 10;
+     without a registration the project-local file is never the winner.
+4. **Verify precedence with `ace-nav resolve <uri> --why`:** your file must be listed first and marked
+   `← winner`. For a list of all duplicate candidates use `ace-nav list '<protocol>://<name>'`.
+5. **Never override skills or the `.agents/` projection.** Point the skill at an overridden workflow, or edit the
+   canonical skill in its gem.
+6. **Document the override** in the project's own agent guidance so maintainers know the file shadows a gem asset and
+   should be re-checked on gem upgrades.
+
+## Success Criteria
+
+- [ ] Each project-local override file lives at the canonical project-local path for its surface.
+- [ ] `ace-nav resolve <uri> --why` shows the project-local candidate first, marked `← winner` (or, for skills, shows
+      the gem candidate only).
+- [ ] No files were planted in `.ace-handbook/skills/` or `.agents/skills/` expecting resolution changes.
+- [ ] `ace-handbook sync` runs clean after any canonical skill change.
+
+## Validation Commands
+
+```bash
+ace-bundle wfi://handbook/manage-overrides
+ace-nav resolve wfi://release/publish --why
+ace-nav list 'cookbook://setup-starting-a-multi-ruby-gem-monorepo-with-ace'
+ace-handbook sync
+```
+
+## Planted-Competitor Verification Probes
+
+Executed against ace-handbook 0.31.1 / ace-support-nav 0.28.6 (2026-09-20). Plant a project-local competitor file,
+run the resolve, inspect the first line of the winner, then remove the plant:
+
+```bash
+# Workflows: project-local WINS
+mkdir -p .ace-handbook/workflow-instructions/handbook
+printf '# OVERRIDE\n' > .ace-handbook/workflow-instructions/handbook/manage-cookbooks.wf.md
+ace-nav resolve wfi://handbook/manage-cookbooks        # → .ace-handbook/... (project-local)
+rm .ace-handbook/workflow-instructions/handbook/manage-cookbooks.wf.md
+
+# Cookbooks: with shipped defaults the GEM wins (project-local source priority 20 > gem 10)
+mkdir -p .ace-handbook/cookbooks
+printf '# OVERRIDE\n' > .ace-handbook/cookbooks/setup-starting-a-multi-ruby-gem-monorepo-with-ace.cookbook.md
+ace-nav resolve cookbook://setup-starting-a-multi-ruby-gem-monorepo-with-ace   # → ace-handbook/handbook/... (gem)
+ace-nav list 'cookbook://setup-starting-a-multi-ruby-gem-monorepo-with-ace'    # both candidates listed
+rm .ace-handbook/cookbooks/setup-starting-a-multi-ruby-gem-monorepo-with-ace.cookbook.md
+
+# Skills: gem WINS even with competitors in both overlay locations
+mkdir -p .ace-handbook/skills/as-review-pr .agents/skills/as-review-pr
+printf '# OVERRIDE\n' > .ace-handbook/skills/as-review-pr/SKILL.md
+printf '# OVERRIDE\n' > .agents/skills/as-review-pr/SKILL.md
+ace-nav resolve skill://as-review-pr                   # → ace-review/handbook/skills/... (gem)
+rm .ace-handbook/skills/as-review-pr/SKILL.md
+rmdir .ace-handbook/skills/as-review-pr .ace-handbook/skills
+ace-handbook sync                                      # regenerates .agents/skills/ and prunes the plant
+```
+
+## Error Handling
+
+- **Override silently loses:** inspect `ace-nav resolve <uri> --why`; the losing candidate's source priority is too
+  high — lower it in the source registration.
+- **Guide override not discovered at all:** no project guide source is registered; add
+  `.ace/nav/protocols/guide-sources/local.yml` (see Process Step 3).
+- **Skill edit appears to do nothing:** skills are not overridable; override the workflow the skill calls.
+- **`.agents/skills/` edits keep disappearing:** expected — `ace-handbook sync` regenerates the projection and prunes
+  stale entries; edit canonical skills in the owning gem.

data/lib/ace/handbook/atoms/provider_registry.rb

@@ -34,6 +34,19 @@ module Ace
           manifest(provider).fetch("output_dir")
         end
 
+        def prompts_dir(provider)
+          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

@@ -22,9 +22,12 @@ module Ace
             return if quiet
 
             results.each do |result|
-              puts "synced #{result[:provider]} -> #{result[:relative_output_dir]} " \
-                   "(#{result[:projected_skills]} skills, #{result[:updated_files]} updated, " \
-                   "#{result[:removed_entries]} removed)"
+              line = "synced #{result[:provider]} -> #{result[:relative_output_dir]} " \
+                     "(#{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)
           rescue => e
@@ -33,6 +36,18 @@ module Ace
 
           private
 
+          def format_prompts_summary(result)
+            "; prompts #{result[:relative_prompts_dir]} " \
+              "(#{result[:projected_prompts]} prompts, #{result[:updated_prompt_files]} updated, " \
+              "#{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/models/prompt_template.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Ace
+  module Handbook
+    module Models
+      class PromptTemplate
+        attr_reader :provider, :source_path, :frontmatter, :content
+
+        def initialize(provider:, source_path:, frontmatter:, content:)
+          @provider = provider
+          @source_path = source_path
+          @frontmatter = frontmatter
+          @content = content
+        end
+
+        def name
+          File.basename(source_path, ".md")
+        end
+
+        def source
+          frontmatter["source"].to_s
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Handbook
+    module Organisms
+      # Discovers canonical provider prompt templates shipped by integration packages.
+      #
+      # Each integration package owns its provider's prompt templates in
+      # handbook/prompts/*.md; they project into the provider manifest's prompts_dir.
+      class PromptTemplateInventory
+        FRONTMATTER_PATTERN = /\A---\s*\n(.*?)\n---\s*\n?(.*)\z/m
+        PACKAGE_GLOB = "ace-handbook-integration-*"
+        GEM_NAME_PREFIX = "ace-handbook-integration-"
+
+        attr_reader :project_root
+
+        def initialize(project_root: Ace::Handbook.project_root, gem_roots: nil)
+          @project_root = project_root
+          @gem_roots = gem_roots
+        end
+
+        def all
+          package_roots.filter_map { |root, provider| parse_templates(root, provider) }
+                       .each_with_object({}) do |(provider, templates), index|
+            index[provider] = (index[provider] || []).concat(templates)
+          end
+        end
+
+        def for_provider(provider)
+          all.fetch(provider.to_s, [])
+        end
+
+        private
+
+        def package_roots
+          (local_package_roots + installed_package_roots).sort.uniq.filter_map do |root|
+            provider = package_provider(root)
+            next if provider.nil? || provider.empty?
+
+            [root, provider]
+          end
+        end
+
+        def local_package_roots
+          Dir.glob(File.join(project_root, PACKAGE_GLOB)).select { |path| File.directory?(path) }
+        end
+
+        def installed_package_roots
+          return @gem_roots unless @gem_roots.nil?
+
+          Gem::Specification.find_all
+                            .select { |spec| spec.name.start_with?(GEM_NAME_PREFIX) }
+                            .map(&:full_gem_path)
+        end
+
+        def package_provider(root)
+          manifests = Dir.glob(File.join(root, ".ace-defaults", "handbook", "providers", "*.yml")).sort
+          return nil if manifests.empty?
+
+          data = YAML.safe_load_file(manifests.first, permitted_classes: [Date, Time], aliases: true) || {}
+          data["provider"].to_s
+        rescue StandardError
+          nil
+        end
+
+        def parse_templates(root, provider)
+          templates = Dir.glob(File.join(root, "handbook", "prompts", "*.md")).sort.filter_map do |path|
+            match = File.read(path).match(FRONTMATTER_PATTERN)
+            frontmatter = match ? parse_frontmatter(match[1]) : {}
+            Models::PromptTemplate.new(provider: provider, source_path: path, frontmatter: frontmatter, content: File.read(path))
+          end
+          [provider, templates]
+        end
+
+        def parse_frontmatter(raw)
+          YAML.safe_load(raw, permitted_classes: [Date, Time], aliases: true) || {}
+        rescue StandardError
+          {}
+        end
+      end
+    end
+  end
+end

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

@@ -1,22 +1,31 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "json"
+require "pathname"
+require "tempfile"
+require "yaml"
 
 module Ace
   module Handbook
     module Organisms
       class ProviderSyncer
-        attr_reader :project_root, :registry, :inventory, :config
+        PROJECTION_SOURCE_PREFIX = "ace-handbook-integration-"
+        EXTENSION_RECEIPT_NAME = ".ace-handbook-projection.json"
+
+        attr_reader :project_root, :registry, :inventory, :prompt_inventory, :config
 
         def initialize(
           project_root: Ace::Handbook.project_root,
           registry: nil,
           inventory: nil,
+          prompt_inventory: nil,
           config: nil
         )
           @project_root = project_root
           @registry = registry || Atoms::ProviderRegistry.new(project_root: project_root)
           @inventory = inventory || SkillInventory.new(project_root: project_root)
+          @prompt_inventory = prompt_inventory || PromptTemplateInventory.new(project_root: project_root)
           @config = config || Ace::Handbook.config.resolve_namespace("handbook").to_h
         end
 
@@ -31,6 +40,15 @@ module Ace
         private
 
         def sync_provider(provider, skills:, source_breakdown:)
+          result = sync_skills(provider, skills: skills, source_breakdown: source_breakdown)
+          prompts_result = sync_prompts(provider)
+          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:)
           output_dir = File.join(project_root, registry.output_dir(provider))
           prepare_output_dir(output_dir)
 
@@ -64,6 +82,35 @@ module Ace
           }
         end
 
+        def sync_prompts(provider)
+          prompts_dir = registry.prompts_dir(provider)
+          return nil if prompts_dir.nil? || prompts_dir.to_s.empty?
+
+          output_dir = File.join(project_root, prompts_dir)
+          FileUtils.mkdir_p(output_dir)
+
+          expected = {}
+          updated_files = 0
+
+          prompt_inventory.for_provider(provider).each do |template|
+            output_path = File.join(output_dir, "#{template.name}.md")
+            expected[template.name] = output_path
+            next if File.exist?(output_path) && File.read(output_path) == template.content
+
+            File.write(output_path, template.content)
+            updated_files += 1
+          end
+
+          removed_entries = prune_stale_prompt_files(output_dir, expected.keys)
+
+          {
+            relative_prompts_dir: prompts_dir,
+            projected_prompts: expected.size,
+            updated_prompt_files: updated_files,
+            removed_prompt_entries: removed_entries
+          }
+        end
+
         def summarize_sources(skills)
           skills.each_with_object(Hash.new(0)) do |skill, memo|
             source = skill.source.to_s
@@ -128,6 +175,280 @@ module Ace
           stale.each { |path| FileUtils.rm_rf(path) }
           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)
+          stale = Dir.glob(File.join(output_dir, "*.md")).reject do |path|
+            expected_template_names.include?(File.basename(path, ".md"))
+          end.select do |path|
+            template_source(path).start_with?(PROJECTION_SOURCE_PREFIX)
+          end
+          stale.each { |path| FileUtils.rm(path) }
+          stale.size
+        end
+
+        def template_source(path)
+          match = File.read(path).match(/\A---\s*\n(.*?)\n---/m)
+          return "" unless match
+
+          frontmatter = YAML.safe_load(match[1], permitted_classes: [Date, Time], aliases: true)
+          frontmatter.is_a?(Hash) ? frontmatter["source"].to_s : ""
+        rescue
+          ""
+        end
       end
     end
   end

data/lib/ace/handbook/version.rb

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

data/lib/ace/handbook.rb

@@ -5,8 +5,10 @@ require "ace/support/config"
 require_relative "handbook/version"
 require_relative "handbook/atoms/provider_registry"
 require_relative "handbook/models/skill_document"
+require_relative "handbook/models/prompt_template"
 require_relative "handbook/molecules/skill_projection"
 require_relative "handbook/organisms/skill_inventory"
+require_relative "handbook/organisms/prompt_template_inventory"
 require_relative "handbook/organisms/provider_syncer"
 require_relative "handbook/organisms/status_collector"
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-handbook
 version: !ruby/object:Gem::Version
-  version: 0.31.1
+  version: 0.33.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -169,6 +169,7 @@ files:
 - handbook/skills/as-handbook-manage-agents/SKILL.md
 - handbook/skills/as-handbook-manage-cookbooks/SKILL.md
 - handbook/skills/as-handbook-manage-guides/SKILL.md
+- handbook/skills/as-handbook-manage-overrides/SKILL.md
 - handbook/skills/as-handbook-manage-workflows/SKILL.md
 - handbook/skills/as-handbook-parallel-research/SKILL.md
 - handbook/skills/as-handbook-perform-delivery/SKILL.md
@@ -188,6 +189,7 @@ files:
 - handbook/workflow-instructions/handbook/manage-agents.wf.md
 - handbook/workflow-instructions/handbook/manage-cookbooks.wf.md
 - handbook/workflow-instructions/handbook/manage-guides.wf.md
+- handbook/workflow-instructions/handbook/manage-overrides.wf.md
 - handbook/workflow-instructions/handbook/manage-workflows.wf.md
 - handbook/workflow-instructions/handbook/parallel-research.wf.md
 - handbook/workflow-instructions/handbook/perform-delivery.wf.md
@@ -207,8 +209,10 @@ files:
 - lib/ace/handbook/cli.rb
 - lib/ace/handbook/cli/commands/status.rb
 - lib/ace/handbook/cli/commands/sync.rb
+- lib/ace/handbook/models/prompt_template.rb
 - lib/ace/handbook/models/skill_document.rb
 - lib/ace/handbook/molecules/skill_projection.rb
+- lib/ace/handbook/organisms/prompt_template_inventory.rb
 - lib/ace/handbook/organisms/provider_syncer.rb
 - lib/ace/handbook/organisms/skill_inventory.rb
 - lib/ace/handbook/organisms/status_collector.rb