ace-git-worktree 0.21.8 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dab3625d2a8e853524064fd1fbc807df3ccfdf1011a977dae3bd4938aad71beb
-  data.tar.gz: 53e20047a0218cb1c226c3c60b84009d75aed18cf94b7221858f779567a93230
+  metadata.gz: 6e7afdc95769c4eaebe1974a49534a00e548a17f2519075c10738bd93ad68de5
+  data.tar.gz: 43294a3bb9d7bc38da9938f50e8e621ce7a432f54a39ecebbe57a752d46f56d9
 SHA512:
-  metadata.gz: c9853df9965e9bca5a1a5c19c8259e256fa6b7134a63f7c9abe536d3bb47aa76ed5789c4904807a51bfc644c1ddb32636e37fe36d7d6ecad71cf67acd9ff0e3d
-  data.tar.gz: 91f690e27dc37733462975066d629e30299a665d1bc8bcf116b7b99d65369c7c50b150b354c070de8328671206cc2b314e608f0a8c7c19a6548581a241d6e12d
+  metadata.gz: af41391d20f9555ddd1da0e6347823c4810dc2d330b38137317e5fc79f7ab1c81a17b43e54d33b666f5cc40163f1a6ea8abca031b94f508bdd4c525a1788a07c
+  data.tar.gz: 073f8bdaf60175babf66dfca52880d1ffaab445c92b4c264165cd7792d7e5c8bb5a6be4adcf1e42f7f561b0b7ae019d43ce7ffe0eda0d3032d4377bc14be661e

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-08-13
+### Added
+- Add cleanup plan application with drift guards
+- Classify merged refs with GitHub PR evidence
+- Report repository inventory with ancestry proof
+- Run recoverable preparation phases in place
+- Add bootstrap config management and provenance
+- Fail closed on tracked mise trust verification
+### Fixed
+- Resolve PR 316 findings and finalize cleanup proofs
+- Restrict bookkeeping commits to owned paths
+
 ## [0.21.8] - 2026-08-12
 
 ### Technical

data/docs/usage.md

@@ -19,14 +19,16 @@ gem install ace-git-worktree
 
 ## Command Overview
 
-`ace-git-worktree` ships six commands:
+`ace-git-worktree` ships seven commands:
 
 * `create` for task-aware, PR-aware, and branch-based worktree creation
+* `bootstrap` for rerunning preparation phases (toolchain trust and bootstrap policy) on existing worktrees
 * `list` for active worktree inventory and filtering
 * `switch` for resolving a worktree path you can `cd` into
+* `cleanup` for report/apply cleanup of squash-merged branches
 * `remove` for safe worktree removal
 * `prune` for stale-reference cleanup
-* `config` for configuration inspection and validation
+* `config` for configuration initialization, bootstrap policy settings, inspection, and validation
 
 Run `ace-git-worktree --help` for the top-level summary and examples.
 
@@ -112,7 +114,23 @@ Would remove task.081
 
 **Next steps:** Re-run either command without `--dry-run` once the preview looks correct.
 
-### Scenario 4: Filter Task and Non-Task Worktrees
+### Scenario 2: Clean up merged worktrees
+
+**Goal:** Remove worktrees and branches that have been merged to main.
+
+**Commands:**
+
+```bash
+# Generate a cleanup plan and review it
+ace-git-worktree cleanup --target main
+
+# Apply the reviewed plan using the digest from the report
+ace-git-worktree cleanup --target main --apply --approved-digest <sha256-digest>
+```
+
+**Outcome:** Merged worktrees, local branches, and remote-tracking branches are removed safely without dropping unmerged work.
+
+### Scenario 3: Switch Task Context and Validate Dependencies
 
 **Goal:** Show task-associated worktrees separately from non-task worktrees.
 
@@ -277,6 +295,22 @@ ace-git-worktree prune --cleanup-directories
 * `-v`, `--verbose` - Show verbose output
 * `-d`, `--debug` - Show debug output
 
+### `ace-git-worktree bootstrap [IDENTIFIER]`
+
+Rerun preparation phases (toolchain trust and bootstrap policy) for an existing worktree in place.
+
+```bash
+ace-git-worktree bootstrap 081
+ace-git-worktree bootstrap t.081 --json
+```
+
+**Options:**
+
+* `--json` - Output format as JSON
+* `-q`, `--quiet` - Suppress non-essential output
+* `-v`, `--verbose` - Show verbose output
+* `-d`, `--debug` - Show debug output
+
 ### `ace-git-worktree config [SUBCOMMAND]`
 
 Show current configuration, validate it, or list the config files in play.

data/handbook/skills/as-git-worktree-cleanup/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: as-git-worktree-cleanup
+description: Safely inventory and apply cleanup plans for squash-merged worktrees and refs
+# bundle: wfi://git/worktree-cleanup
+# agent: Bash
+user-invocable: true
+allowed-tools:
+  - Bash(ace-git-worktree:*)
+  - Bash(ace-bundle:*)
+  - Read
+argument-hint: [--target main]
+last_modified: 2026-08-13
+source: ace-git-worktree
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://git/worktree-cleanup
+---
+
+Load and run `ace-bundle wfi://git/worktree-cleanup` 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/git/worktree-cleanup.wf.md

@@ -0,0 +1,63 @@
+---
+title: Worktree Cleanup
+description: Safely inventory and apply cleanup plans for squash-merged worktrees and refs
+category: Git
+tags: [git, worktree, cleanup, safely, squash-merge]
+version: 1.0.0
+---
+
+# Worktree Cleanup
+
+The `ace-git-worktree cleanup` command safely removes stale worktrees, local branches, and remote-tracking branches that have been merged (including squash merges). It uses a two-phase report/apply model with strict ancestry and drift guards.
+
+## Generate Cleanup Report
+
+First, generate a deterministic, no-mutation inventory of everything that could be cleaned up relative to a target branch:
+
+```bash
+ace-git-worktree cleanup --target main --remote origin
+```
+
+This will:
+1. Refresh remote evidence (unless `--offline` is passed).
+2. Find all worktrees, local refs, and remote refs.
+3. Classify each using GitHub PR evidence (exact merge, stable patch equivalence) or Git ancestry.
+4. Output an ordered plan with a **Plan Digest**.
+
+### Report Output Interpretation
+
+- `✓` (Retain): Item is protected (e.g., primary checkout, dirty worktree) or its ancestry/merge status is unproven.
+- `✗` (Remove): Item is safe to delete because it is fully merged into the target.
+
+## Apply Cleanup Plan
+
+To execute the deletions, you must provide the exact Plan Digest from your reviewed report. This ensures that no destructive operations occur if the repository state drifts (e.g., if a worktree becomes dirty or a ref advances).
+
+```bash
+ace-git-worktree cleanup --target main --apply --approved-digest <sha256-digest>
+```
+
+ACE will:
+1. Re-scan the repository and rebuild the plan.
+2. Abort if the new plan's digest does not match your `--approved-digest`.
+3. Apply deletions in a fixed order (worktrees, local refs, remote refs).
+4. Re-validate dirty state and expected SHAs immediately before each deletion.
+5. Finish with a strict rescan and output the results.
+
+### Strict Rescan
+
+If you want to ensure that *only* the target branch remains after cleanup, you can use the `--require-only-target` flag:
+
+```bash
+ace-git-worktree cleanup --target main --apply --approved-digest <sha256-digest> --require-only-target
+```
+
+If any non-target worktrees or refs are retained (e.g., because they were unproven or dirty), the command will exit with an error.
+
+## Advanced Usage
+
+For automation or scripting, use the JSON format:
+
+```bash
+ace-git-worktree cleanup --target main --format json | jq .
+```

data/handbook/workflow-instructions/git/worktree-create.wf.md

@@ -126,6 +126,12 @@ ace-git-worktree remove feature-branch
 # Skip automatic mise trust
 ace-git-worktree create --task 081 --no-mise-trust
 
+# Skip bootstrap command execution
+ace-git-worktree create --task 081 --no-bootstrap
+
+# Rerun preparation phases (toolchain trust and bootstrap policy) on existing worktree
+ace-git-worktree bootstrap 081
+
 # Skip task status update
 ace-git-worktree create --task 081 --no-status-update
 

data/lib/ace/git/worktree/cli/commands/bootstrap.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "shared_helpers"
+require_relative "../../commands/bootstrap_command"
+
+module Ace
+  module Git
+    module Worktree
+      module CLI
+        module Commands
+          class Bootstrap < Ace::Support::Cli::Command
+            include SharedHelpers
+
+            desc "Rerun preparation phases (toolchain trust and bootstrap policy) for an existing worktree"
+
+            example [
+              "081                     # Rerun bootstrap for task 081",
+              "t.081 --json            # Output retry status in JSON format"
+            ]
+
+            argument :identifier, required: true, desc: "Task ID, branch, or worktree identifier"
+
+            option :json, desc: "Format output as JSON", type: :boolean, aliases: []
+            option :verbose, desc: "Show verbose output", type: :boolean, aliases: ["-v"]
+            option :quiet, type: :boolean, aliases: ["-q"], desc: "Suppress non-essential output"
+            option :debug, type: :boolean, aliases: ["-d"], desc: "Show debug output"
+
+            def call(identifier: nil, **options)
+              display_config_summary("bootstrap", options)
+
+              args = []
+              args << identifier if identifier
+              args << "--json" if options[:json]
+
+              Ace::Git::Worktree::Commands::BootstrapCommand.new.run(args)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/cli/commands/cleanup.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "shared_helpers"
+require_relative "../../commands/cleanup_command"
+
+module Ace
+  module Git
+    module Worktree
+      module CLI
+        module Commands
+          class Cleanup < Ace::Support::Cli::Command
+            include SharedHelpers
+
+            desc "Report cleanup plan for merged worktrees and refs"
+
+            example [
+              "--target main                # Report against main",
+              "--target main --format json  # JSON output",
+              "--target main --offline      # Skip remote refresh"
+            ]
+
+            option :target, desc: "Target ref for ancestry proof (required)", type: :string, aliases: []
+            option :remote, desc: "Remote name (default: origin)", type: :string, default: "origin", aliases: []
+            option :offline, desc: "Skip remote evidence refresh", type: :boolean, aliases: []
+            option :apply, desc: "Apply a reviewed plan", type: :boolean, aliases: []
+            option :approved_digest, desc: "Approved plan digest to apply", type: :string, aliases: []
+            option :require_only_target, desc: "Fail if final rescan has retained non-target state", type: :boolean, aliases: []
+            option :format, desc: "Output format (table, json)", type: :string, default: "table", aliases: []
+            option :quiet, type: :boolean, aliases: ["-q"], desc: "Suppress non-essential output"
+            option :debug, type: :boolean, aliases: ["-d"], desc: "Show debug output"
+
+            def call(**options)
+              display_config_summary("cleanup", options)
+
+              args = options_to_args(options)
+
+              Ace::Git::Worktree::Commands::CleanupCommand.new.run(args)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/cli/commands/config.rb

@@ -23,11 +23,19 @@ module Ace
 
             # Accept extra positional arguments for backward compatibility
             # (e.g., "show", "validate" as positional args instead of flags)
-            argument :subcommand, required: false, desc: "Subcommand (show, validate, files)"
+            argument :subcommand, required: false, desc: "Subcommand (init, set-bootstrap, show, validate, files)"
 
             option :show, desc: "Show current configuration", type: :boolean, aliases: []
             option :validate, desc: "Validate configuration", type: :boolean, aliases: []
             option :files, desc: "Show configuration file locations", type: :boolean, aliases: []
+            option :json, desc: "Format output as JSON", type: :boolean, aliases: []
+            option :bootstrap, desc: "Validate bootstrap policy", type: :boolean, aliases: []
+            option :command, desc: "Bootstrap command to execute", type: :string, aliases: []
+            option :working_dir, desc: "Working directory for bootstrap command", type: :string, aliases: []
+            option :timeout, desc: "Timeout in seconds for bootstrap command", type: :string, aliases: []
+            option :required, desc: "Require bootstrap execution to succeed", type: :boolean, aliases: []
+            option :advisory, desc: "Allow worktree creation when bootstrap fails", type: :boolean, aliases: []
+            option :env, desc: "Environment variables KEY=VALUE", type: :array, aliases: []
             option :verbose, desc: "Show verbose output", type: :boolean, aliases: ["-v"]
             option :quiet, type: :boolean, aliases: ["-q"], desc: "Suppress non-essential output"
             option :debug, type: :boolean, aliases: ["-d"], desc: "Show debug output"
@@ -35,10 +43,25 @@ module Ace
             def call(subcommand: nil, **options)
               display_config_summary("config", options)
 
-              # Convert ace-support-cli options to args array format
-              args = options_to_args(options)
-              # Add subcommand as positional argument if provided
+              args = []
               args << subcommand if subcommand
+              args << "init" if options[:init]
+              args << "set-bootstrap" if options[:set_bootstrap]
+              args << "--show" if options[:show]
+              args << "--validate" if options[:validate]
+              args << "--files" if options[:files]
+              args << "--json" if options[:json]
+              args << "--bootstrap" if options[:bootstrap]
+              args << "--command" << options[:command] if options[:command]
+              args << "--working-dir" << options[:working_dir] if options[:working_dir]
+              args << "--timeout" << options[:timeout].to_s if options[:timeout]
+              args << "--required" if options[:required]
+              args << "--advisory" if options[:advisory]
+              if options[:env]
+                Array(options[:env]).each do |e|
+                  args << "--env" << e
+                end
+              end
 
               Ace::Git::Worktree::Commands::ConfigCommand.new.run(args)
             end

data/lib/ace/git/worktree/cli/commands/create.rb

@@ -49,6 +49,7 @@ module Ace
             option :no_push, desc: "Skip pushing task changes", type: :boolean, aliases: ["--no-push"]
             option :no_upstream, desc: "Skip pushing with upstream tracking", type: :boolean, aliases: ["--no-upstream"]
             option :no_pr, desc: "Skip creating draft PR", type: :boolean
+            option :no_bootstrap, desc: "Skip worktree bootstrap preparation", type: :boolean
             option :push_remote, desc: "Remote to push to", aliases: []
             option :no_auto_navigate, desc: "Stay in current directory", type: :boolean, aliases: ["--no-auto-navigate"]
             option :commit_message, desc: "Custom commit message", aliases: []

data/lib/ace/git/worktree/cli.rb

@@ -9,6 +9,8 @@ require_relative "cli/commands/switch"
 require_relative "cli/commands/remove"
 require_relative "cli/commands/prune"
 require_relative "cli/commands/config"
+require_relative "cli/commands/cleanup"
+require_relative "cli/commands/bootstrap"
 require "ace/core"
 require "ace/support/cli"
 
@@ -29,6 +31,8 @@ module Ace
           ["switch", "Resolve a worktree path for cd navigation"],
           ["remove", "Remove a worktree by task, branch, or path"],
           ["prune", "Prune stale/deleted worktree references"],
+          ["cleanup", "Report cleanup plan for merged worktrees and refs"],
+          ["bootstrap", "Rerun preparation phases for an existing worktree"],
           ["config", "Show and validate configuration"]
         ].freeze
 
@@ -78,6 +82,8 @@ module Ace
         register "switch", wrap_command(CLI::Commands::Switch), aliases: ["cd"]
         register "remove", wrap_command(CLI::Commands::Remove), aliases: ["rm"]
         register "prune", wrap_command(CLI::Commands::Prune), aliases: []
+        register "cleanup", wrap_command(CLI::Commands::Cleanup), aliases: []
+        register "bootstrap", wrap_command(CLI::Commands::Bootstrap), aliases: []
         register "config", wrap_command(CLI::Commands::Config), aliases: []
 
         # Version command

data/lib/ace/git/worktree/commands/bootstrap_command.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../organisms/worktree_manager"
+require_relative "../molecules/toolchain_truster"
+require_relative "../molecules/bootstrap_executor"
+require_relative "../molecules/config_loader"
+
+module Ace
+  module Git
+    module Worktree
+      module Commands
+        # Bootstrap command
+        #
+        # Reruns recoverable preparation phases (toolchain trust and bootstrap policy)
+        # for an existing worktree in place.
+        class BootstrapCommand
+          def initialize(manager: nil)
+            @manager = manager || Ace::Git::Worktree::Organisms::WorktreeManager.new
+          end
+
+          # Run bootstrap retry on existing worktree
+          #
+          # @param args [Array<String>] Arguments including identifier and optional flags
+          # @return [Integer] Exit code
+          def run(args = [])
+            options = parse_arguments(args)
+            return show_help if options[:help] || options[:identifier].nil?
+
+            worktree_info = find_target_worktree(options[:identifier])
+            unless worktree_info
+              puts "Error: Worktree matching '#{options[:identifier]}' not found."
+              return 1
+            end
+
+            wt_path = worktree_info[:path]
+            project_root = Dir.pwd
+            config = Molecules::ConfigLoader.new(project_root).load_without_validation
+
+            # Phase 1: Toolchain Trust
+            truster = Molecules::ToolchainTruster.new(project_root: wt_path, policy: "required")
+            trust_res = truster.verify_and_trust
+
+            # Phase 2: Bootstrap execution
+            executor = Molecules::BootstrapExecutor.new(
+              project_root: project_root,
+              worktree_path: wt_path,
+              bootstrap_config: config.bootstrap,
+              no_bootstrap: options[:no_bootstrap] || false
+            )
+            bootstrap_res = executor.run
+
+            phases = [trust_res, bootstrap_res]
+
+            req_failed = phases.any? { |p| p[:status] == "required_failed" }
+            adv_failed = phases.any? { |p| p[:status] == "advisory_failed" }
+
+            readiness = if req_failed
+              "not_ready"
+            elsif adv_failed
+              "ready_with_warning"
+            else
+              "ready"
+            end
+
+            result = {
+              identifier: options[:identifier],
+              worktree_path: wt_path,
+              branch: worktree_info[:branch],
+              readiness: readiness,
+              phases: phases,
+              retry_command: (readiness == "not_ready") ? "ace-git-worktree bootstrap #{options[:identifier]}" : nil
+            }
+
+            if options[:json]
+              puts JSON.pretty_generate(result)
+            else
+              puts "Worktree Preparation Retry: #{wt_path}"
+              puts "Readiness: #{readiness}"
+              puts
+              puts "Phases:"
+              phases.each do |p|
+                st = p[:status]
+                icon = case st
+                       when "succeeded", "not_applicable" then "✓"
+                       when "skipped" then "↷"
+                       when "advisory_failed" then "⚠️"
+                       else "❌"
+                       end
+                puts "  #{icon} #{p[:phase]}: #{st}"
+                puts "    Command: #{p[:command]}" if p[:command]
+                puts "    Output: #{p[:output]}" if p[:output] && !p[:output].empty? && st.include?("failed")
+              end
+              if readiness == "not_ready"
+                puts
+                puts "Retry with: ace-git-worktree bootstrap #{options[:identifier]}"
+              end
+            end
+
+            (readiness == "not_ready") ? 1 : 0
+          rescue => e
+            puts "Error: #{e.message}"
+            1
+          end
+
+          def show_help
+            puts <<~HELP
+              ace-git-worktree bootstrap - Rerun preparation phases on existing worktree
+
+              USAGE:
+                  ace-git-worktree bootstrap <identifier> [OPTIONS]
+
+              OPTIONS:
+                  --json                  Output format as JSON
+                  --help, -h              Show this help message
+
+              EXAMPLES:
+                  ace-git-worktree bootstrap 081
+                  ace-git-worktree bootstrap t.8vb.t.vyz.2 --json
+            HELP
+            0
+          end
+
+          private
+
+          def parse_arguments(args)
+            options = {identifier: nil, json: false, help: false}
+            i = 0
+            while i < args.length
+              arg = args[i]
+              case arg
+              when "--json"
+                options[:json] = true
+              when "--help", "-h"
+                options[:help] = true
+              when /^--/
+                raise ArgumentError, "Unknown option: #{arg}"
+              else
+                options[:identifier] = arg if options[:identifier].nil?
+              end
+              i += 1
+            end
+            options
+          end
+
+          def find_target_worktree(identifier)
+            worktrees = @manager.list[:worktrees] || []
+            worktrees.find do |wt|
+              wt[:path]&.end_with?("/#{identifier}") ||
+                wt[:path]&.include?("/t.#{identifier}") ||
+                wt[:branch]&.include?(identifier) ||
+                wt[:task_id] == identifier
+            end
+          end
+        end
+      end
+    end
+  end
+end