ace-handbook 0.31.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 837b9e5d5edbfab28596d94f6e53d3b0a4641451cf43da81899591736a3352ed
-  data.tar.gz: d99a5b04b59b095d60575aac6adc4a7e7bf8009071b0fe42ba7bdb6d342bee3c
+  metadata.gz: 1e70a71fff6e61cbaa6724591eb965481b3b92153aed554c5fd6ad8b51f3e01e
+  data.tar.gz: 99db5b08f74300bfbc87b71f2621a0bcee70934d92a89d7a142884adb8a2e434
 SHA512:
-  metadata.gz: 90654bdde3d8faec5d009c9991091db20aa2f7033615959f82aeec5d7fdaab8a3a38865468f4b5d16c5f3331bbc582ab1fd9ead74f97fba798589cef9ab9a1d1
-  data.tar.gz: fc9dad5f9987207a3ff1c00782df8a4a663d8cba5296d06c3125ce8e0ab17d83506ba06186f91ae1d34f0033c3ef3362cfb80f927d67153edf6b01a5ca9d55b2
+  metadata.gz: 34c7119d2d01e4ad2ff58a6b91bc5b4b092fb42a575abc33319d3ee6f4c7e237058f1135c19ab560565ff3fa91a696e39a9b92e27b6b839f855de0bf20de0c64
+  data.tar.gz: c1b28858004960a5ef381e50bde467910b6694bfb29179e7cdd7014d45d25a2eb47ece9d75996cef92e35c30892705ca7687a6340f169b86e07781a287f8e499

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
+
+## [0.31.1] - 2026-09-02
+
+### Technical
+- Included in the coordinated all-package patch release preparation for ACE monorepo review.
 ## [0.31.0] - 2026-08-12
 
 ### Added

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/skills/as-release-rubygems-publish/SKILL.md

@@ -10,7 +10,7 @@ allowed-tools:
   - Bash(ace-bundle:*)
   - Read
 argument-hint: "[gem-name...] [--dry-run]"
-last_modified: 2026-04-10
+last_modified: 2026-08-12
 source: ace-handbook
 integration:
   targets:
@@ -46,5 +46,6 @@ None
 - Follow the workflow as the source of truth.
 - Do the work described by the workflow instead of only summarizing it.
 - When the workflow requires edits, tests, or commits, perform them in this project.
+- OTP timing: build every pending `.gem` first, then ask for one OTP (~30–45s), then push in ≤5-concurrent dependency waves aiming to finish within ~30s; verify metadata only after the burst.
 
 - After live publishing, recommend running `ace-test-e2e ace-monorepo-e2e TS-MONO-001` for installation verification.

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/handbook/workflow-instructions/release/rubygems-publish.wf.md

@@ -72,6 +72,7 @@ Publish plan (dry):
 echo "${GEM_HOST_API_KEY:+GEM_HOST_API_KEY is set}"
 ```
 
+If unset, try loading tooling env (for example `mise env`) without printing secrets, then re-check.
 Do not print secret values.
 
 ### 4. Publication gate
@@ -87,11 +88,23 @@ Only if a higher-priority project workflow authorizes pushes **and** the operato
 real publish (not merely prep/dry-run) may `gem build` + `gem push` proceed under that
 project contract's steps and verification gates.
 
-Suggested placeholders for a project overlay (not executed by this baseline):
+### 5. OTP-burst contract for project overlays (do not run from this baseline)
+
+When a project overlay authorizes live `gem push`, use this timing contract so one OTP can cover a large queue:
+
+1. Resolve credentials and the pending queue first
+2. **Build every pending `.gem` artifact** before asking for OTP
+3. Show the final queue (order, versions, artifact paths, count)
+4. Prompt once for OTP — codes are short-lived (**~30–45s**)
+5. Push immediately in dependency-respecting waves of **up to 5 concurrent** `gem push --otp` calls; aim to finish the burst in **≤30s**
+6. Verify RubyGems metadata **after** the burst (not between pushes)
+7. On expired/incorrect OTP: stop, list remaining gems, request a fresh OTP, resume without rebuilding unless an artifact is missing
+
+Suggested overlay commands (executed only under a project publication contract):
 
 ```bash
-# gem build <gemspec>
-# gem push <built-gem>   # only under project publication contract
+# gem build <gemspec>   # all pending artifacts first
+# gem push <built-gem> --otp <OTP>   # waves of ≤5 concurrent
 ```
 
 ## Override
@@ -105,8 +118,10 @@ WFI source). Keep URI `wfi://release/rubygems-publish` stable for the distribute
 - [ ] Ordered publish plan produced for requested gems
 - [ ] Credential presence reported without leaking secrets
 - [ ] No `gem push` / registry mutation from this baseline alone
+- [ ] Overlay guidance documents build-all → OTP → ≤5 concurrent wave publish → deferred verify
 
 ## Common Issues
 
 - ACE monorepo operators may use a specialized overlay; plain projects must not depend on it.
 - Missing credentials should block publish contracts, not local planning.
+- Asking for OTP before builds complete wastes the short OTP window on slow work.

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

@@ -34,6 +34,10 @@ module Ace
           manifest(provider).fetch("output_dir")
         end
 
+        def prompts_dir(provider)
+          manifest(provider)["prompts_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,11 @@ 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)
+              puts line
             end
             print_inventory_summary(results)
           rescue => e
@@ -33,6 +35,12 @@ 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 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,27 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "yaml"
 
 module Ace
   module Handbook
     module Organisms
       class ProviderSyncer
-        attr_reader :project_root, :registry, :inventory, :config
+        PROJECTION_SOURCE_PREFIX = "ace-handbook-integration-"
+
+        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 +36,14 @@ module Ace
         private
 
         def sync_provider(provider, skills:, source_breakdown:)
+          skills_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)
+        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 +77,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 +170,28 @@ module Ace
           stale.each { |path| FileUtils.rm_rf(path) }
           stale.size
         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 StandardError
+          ""
+        end
       end
     end
   end

data/lib/ace/handbook/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Handbook
-    VERSION = "0.31.0"
+    VERSION = "0.32.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.0
+  version: 0.32.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 2026-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.18'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: ace-support-core
   requirement: !ruby/object:Gem::Requirement
@@ -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