ace-git-worktree 0.19.4 → 0.21.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76d43bf4c4c653fa09da391cd661a709218da5170a08bc89071c9506df8e05f9
-  data.tar.gz: e9f1832e5b5e2c9b9173684b1bf5d8125a5ae2cb785a50e985d9e8783e2a679f
+  metadata.gz: b3b9d7c80c399123ee1a3415f80785d332b62523f914c73f012aa3eea4036001
+  data.tar.gz: 3e56b09334fd53f5483df496fbf6adc0c11879c67002c60eeee1994e8936b162
 SHA512:
-  metadata.gz: e7b8da916fed96f86cae44d25b6b5dcaa277ee8fd697006a3d27f54c86b2112b91d594ce7c98e278bc904994c45f72d1539b7de81cb7a0dc90c4af1b04ea8442
-  data.tar.gz: 23f06350a8761c0ad8cf5cc82cd6c11d922ce445facf85ed9b872fb2b956fa97a6a755f8febb7f3839a28d4974fb8eb5d5cbf918e92a795fef5bf4f471132b38
+  metadata.gz: 354e14b10b93e19b34986500a9773987388852244b400f0c2ffc4281b98f23ccd0c325ff4ec62b851a8b3f31cfb51b9855045fa85bcb14285e44bac972fe9dce
+  data.tar.gz: 000fe52ba5e7525eee2ad2e06469b680c8da6e1e289eb8f3afb11eee680b6d8592a7b2d3e8939c3eff349937502c7ad2a5844b777173aaeba34661deb458b04e

data/CHANGELOG.md

@@ -7,6 +7,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.21.6] - 2026-04-23
+
+### Technical
+- Narrowed retained `switch` E2E verification to the documented public contract by proving the returned task worktree path exists immediately and appears in `switch --list` instead of asserting deeper internal layout details.
+
+## [0.21.5] - 2026-04-23
+
+### Technical
+- Tightened retained basic-lifecycle and task-aware E2E coverage so remove/prune cleanup is verified from the exact removed worktree path and final post-cleanup snapshots.
+
+### Fixed
+- **ace-git-worktree v0.20.5**: Used `ace-tmux window` when already in a tmux session and `ace-tmux start` otherwise, so nested worktree creation stays correctly in-session.
+- **ace-git-worktree v0.20.4**: Fixed `create --pr <number>` to avoid an `ace-tmux` subcommand mismatch when launching project tmux sessions.
+- **ace-git-worktree v0.20.3**: Fixed `create --pr <number>` parsing so `--pr` is not treated as a positional branch argument when routed through `ace-support-cli`.
+
+## [0.21.4] - 2026-04-19
+
+### Technical
+- Updated the retained task-aware PR lifecycle E2E contract to treat missing or unauthenticated GitHub CLI access as a valid graceful-prerequisite branch when the command surfaces an actionable error and leaves no partial PR worktree behind.
+
+## [0.21.3] - 2026-04-18
+
+### Technical
+- Persisted the exact dry-run remove target in retained lifecycle E2E coverage so `TS-WORKTREE-001` verifies no-op behavior from the real created worktree instead of a brittle hardcoded path check.
+
+## [0.21.2] - 2026-04-16
+
+### Technical
+- Aligned retained task-aware JSON metadata E2E verification with the current compact `task_id` contract and the main-worktree null-task behavior.
+
+## [0.21.1] - 2026-04-16
+
+### Technical
+- Corrected `TS-WORKTREE-001` lifecycle verification so post-create worktree evidence is judged before later remove/prune steps intentionally clean up the sandbox state.
+
+## [0.21.0] - 2026-04-14
+
+### Changed
+- Rewrote retained basic-lifecycle and task-aware E2E runner/verifier contracts around explicit public command journeys and impact-first end-state checks.
+- Added new goal-style E2E coverage for config surface validation and PR worktree lifecycle flows.
+- Updated usage and getting-started docs with the minimal JSON output contract, task/non-task filter examples, and remove-by-task `--delete-branch` guidance.
+
+## [0.20.2] - 2026-04-13
+
+### Changed
+- Hardened the basic lifecycle and task-aware E2E scenario contracts so worktree setup, remove/prune evidence, and task-worktree creation checks are stable across reruns.
+
+## [0.20.1] - 2026-04-13
+
+### Changed
+- Completed the batch i05 migration follow-through for this package and aligned it with the restarted `fast` / `feat` / `e2e` verification model.
+
+### Technical
+- Included in the coordinated assignment-driven patch release for batch i05 package updates.
+
+
+## [0.20.0] - 2026-04-12
+
+### Changed
+- Migrated package tests to the `fast` / `feat` / `e2e` model, moving deterministic coverage from legacy test directories into `test/fast` and `test/feat`.
+- Updated retained E2E scenario contracts and metadata for task-aware and lifecycle workflows, including deterministic coverage references and sandbox setup normalization.
+- Updated package docs (`README`, usage, getting-started) to teach the `ace-test`, `ace-test ... feat`, and `ace-test-e2e` split contract.
+
+## [0.19.5] - 2026-04-10
+
+### Fixed
+- Hardened `WorktreeRemover` cleanup semantics to fail when the worktree directory still exists after cleanup, including explicit error results on removal exceptions.
+- Updated prune execution to run `git worktree prune --expire now` for immediate stale-metadata cleanup.
+
+### Technical
+- Added regression coverage asserting `--expire now` prune args and stuck-directory failure behavior in worktree remover tests.
+
 ## [0.19.4] - 2026-03-29
 
 ### Technical

data/README.md

@@ -36,5 +36,20 @@
 
 **Orchestrate parallel task work with ace-overseer** - pair with [ace-overseer](../ace-overseer) to spin up worktrees per task, drive agents in parallel, and prune finished worktrees automatically.
 
+## Testing Contract
+
+Run package tests with the restarted deterministic + scenario split:
+
+```bash
+ace-test ace-git-worktree
+ace-test ace-git-worktree feat
+ace-test ace-git-worktree all
+ace-test-e2e ace-git-worktree
+```
+
+- `ace-test ace-git-worktree` runs deterministic package tests (default `fast` group).
+- `ace-test ace-git-worktree feat` runs deterministic feature-level tests migrated from legacy integration-style coverage.
+- `ace-test-e2e ace-git-worktree` runs retained workflow scenarios only.
+
 ---
 [Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)

data/docs/getting-started.md

@@ -3,7 +3,7 @@ doc-type: user
 title: ace-git-worktree Getting Started
 purpose: Tutorial for first-run ace-git-worktree workflows
 ace-docs:
-  last-updated: 2026-03-22
+  last-updated: 2026-04-14
   last-checked: 2026-03-22
 ---
 
@@ -106,6 +106,68 @@ Add hooks, auto-push, tmux launch, or PR automation only after the basic create/
 | Remove a task worktree | `ace-git-worktree remove --task 081` |
 | Preview stale cleanup | `ace-git-worktree prune --dry-run` |
 
+## Goal-Style Examples
+
+Use these focused flows when validating public lifecycle behavior end-to-end.
+
+### Dry-run no-op check
+
+```bash
+ace-git-worktree create bugfix/test-fix --dry-run
+ace-git-worktree remove --task 081 --dry-run
+ace-git-worktree list
+```
+
+### Remove lifecycle with branch deletion
+
+```bash
+ace-git-worktree remove --task 081 --delete-branch
+ace-git-worktree list
+```
+
+### Task filtering behavior
+
+```bash
+ace-git-worktree list --show-tasks
+ace-git-worktree list --task-associated
+ace-git-worktree list --no-task-associated
+```
+
+### Prune final-state check
+
+```bash
+ace-git-worktree prune --dry-run
+ace-git-worktree prune
+ace-git-worktree list
+```
+
+### PR worktree lifecycle
+
+```bash
+ace-git-worktree create --pr 26
+ace-git-worktree switch pr-26
+ace-git-worktree remove pr-26
+```
+
+### Config surface validation
+
+```bash
+ace-git-worktree config --show
+ace-git-worktree config --validate
+ace-git-worktree config --files
+```
+
+## Validate Package Tests
+
+After making changes, run the package test split explicitly:
+
+```bash
+ace-test ace-git-worktree
+ace-test ace-git-worktree feat
+ace-test ace-git-worktree all
+ace-test-e2e ace-git-worktree
+```
+
 ## Next Steps
 
 * Run `ace-git-worktree config --files` to see which config files are active

data/docs/usage.md

@@ -3,7 +3,7 @@ doc-type: user
 title: ace-git-worktree CLI Usage Reference
 purpose: Command reference for ace-git-worktree
 ace-docs:
-  last-updated: 2026-03-22
+  last-updated: 2026-04-14
   last-checked: 2026-03-22
 ---
 
@@ -112,6 +112,45 @@ 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
+
+**Goal:** Show task-associated worktrees separately from non-task worktrees.
+
+**Commands:**
+
+```bash
+ace-git-worktree list --show-tasks
+ace-git-worktree list --task-associated
+ace-git-worktree list --no-task-associated
+```
+
+**Expected output:**
+
+```text
+... --show-tasks includes task metadata ...
+... --task-associated excludes the main worktree ...
+... --no-task-associated shows main/non-task entries only ...
+```
+
+### Scenario 5: Remove by Task and Delete Branch
+
+**Goal:** Remove a task worktree and also delete its branch in one command.
+
+**Commands:**
+
+```bash
+ace-git-worktree remove --task 081 --delete-branch
+ace-git-worktree list
+```
+
+**Expected output:**
+
+```text
+Removed worktree for task 081
+Deleted branch ...
+... task.081 no longer appears in list output ...
+```
+
 ## Commands
 
 ### `ace-git-worktree create [BRANCH]`
@@ -164,12 +203,20 @@ ace-git-worktree list --search auth
 * `--format` - Output format: `table`, `json`, or `simple`
 * `--show-tasks` - Include task associations
 * `--task-associated` - Show only task-associated worktrees
+* `--no-task-associated` - Show only non-task worktrees
 * `--usable` - Show only usable worktrees
 * `--search` - Filter by branch-name pattern
 * `-q`, `--quiet` - Suppress non-essential output
 * `-v`, `--verbose` - Show verbose output
 * `-d`, `--debug` - Show debug output
 
+**Minimal JSON contract (`--format json`):**
+
+- Output is valid JSON (`array` or object containing worktree entries).
+- Each entry includes a stable path/identity surface usable by scripts (`path` and `branch` fields).
+- Task-associated entries expose `task_id`.
+- Non-task entries either omit `task_id` or set it to `null`.
+
 ### `ace-git-worktree switch [IDENTIFIER]`
 
 Resolve a worktree path for shell navigation.
@@ -286,6 +333,21 @@ git:
 The defaults file also documents timeout controls, hook execution, current-task symlink creation, push remotes, and PR
 title formatting.
 
+## Testing
+
+Use the package testing contract below when validating changes:
+
+```bash
+ace-test ace-git-worktree
+ace-test ace-git-worktree feat
+ace-test ace-git-worktree all
+ace-test-e2e ace-git-worktree
+```
+
+- `ace-test ace-git-worktree` targets deterministic package tests (`fast`).
+- `ace-test ace-git-worktree feat` targets deterministic feature-level coverage.
+- `ace-test-e2e ace-git-worktree` targets real workflow scenarios only.
+
 ## Troubleshooting
 
 ### Problem: `create --task` cannot find the task

data/handbook/agents/worktree.ag.md

@@ -15,7 +15,7 @@ A specialized agent for managing git worktrees with task-aware automation. Handl
 
 ### Task-Aware Operations
 - Create worktrees for specific tasks with automatic metadata integration
-- Fetch task information from ace-taskflow
+- Fetch task information from ace-task
 - Update task status and add worktree metadata
 - Commit task changes before worktree creation
 
@@ -88,7 +88,7 @@ git:
 
 ## Integration Points
 
-- **ace-taskflow**: Task metadata fetching and status updates
+- **ace-task**: Task metadata fetching and status updates
 - **ace-git-commit**: Consistent commit message generation
 - **ace-git**: Safe git command execution
 - **ace-core**: Configuration cascade management

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

@@ -16,7 +16,7 @@ Create git worktrees with task-aware automation or traditional branch-based crea
 ## Prerequisites
 
 - Git repository initialized and accessible
-- ace-taskflow available (for task-aware creation)
+- ace-task available (for task-aware creation)
 - Configuration available in `.ace/git/worktree.yml`
 - Write permissions for worktree root directory
 

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

@@ -48,7 +48,7 @@ module Ace
             option :no_commit, desc: "Skip committing task changes", type: :boolean, aliases: ["--no-commit"]
             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, aliases: ["--no-pr"]
+            option :no_pr, desc: "Skip creating draft PR", 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/commands/list.rb

@@ -22,9 +22,9 @@ module Ace
             ]
 
             option :format, desc: "Output format: table, json, simple", aliases: [], default: "table"
-            option :show_tasks, desc: "Include task associations", type: :boolean, aliases: ["--show-tasks"]
-            option :task_associated, desc: "Show only task-associated worktrees", type: :boolean, aliases: ["--task-associated"]
-            option :usable, desc: "Show only usable worktrees", type: :boolean, aliases: ["--usable"]
+            option :show_tasks, desc: "Include task associations", type: :boolean
+            option :task_associated, desc: "Show only task-associated worktrees", type: :boolean
+            option :usable, desc: "Show only usable worktrees", type: :boolean
             option :search, desc: "Filter by branch name pattern", aliases: []
             option :quiet, type: :boolean, aliases: ["-q"], desc: "Suppress non-essential output"
             option :verbose, type: :boolean, aliases: ["-v"], desc: "Show verbose output"

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

@@ -816,6 +816,7 @@ module Ace
           #
           # When tmux config is enabled and ace-tmux is available, launches a tmux
           # session rooted at the worktree path (replaces current process).
+          # Uses `start` outside tmux and `window` inside tmux.
           # Otherwise falls back to displaying the cd command.
           #
           # @param worktree_path [String] Path to the worktree
@@ -824,7 +825,8 @@ module Ace
 
             if tmux_enabled?
               if ace_tmux_available?
-                Kernel.exec("ace-tmux", "--root", worktree_path)
+                command = ENV["TMUX"].to_s.strip.empty? ? "start" : "window"
+                Kernel.exec("ace-tmux", command, "--root", worktree_path)
               else
                 puts "Warning: tmux is enabled in config but ace-tmux is not installed."
                 puts "Install ace-tmux or disable tmux in .ace/git/worktree.yml"

data/lib/ace/git/worktree/molecules/worktree_remover.rb

@@ -84,7 +84,8 @@ module Ace
 
               # Optionally remove the directory
               if remove_directory && File.exist?(expanded_path)
-                remove_worktree_directory(expanded_path)
+                directory_result = remove_worktree_directory(expanded_path)
+                return directory_result unless directory_result[:success]
               end
 
               # Optionally delete the branch
@@ -305,11 +306,14 @@ module Ace
           #
           # @param worktree_path [String] Worktree path
           def remove_worktree_directory(worktree_path)
-            if File.exist?(worktree_path)
-              FileUtils.rm_rf(worktree_path)
-            end
+            return {success: true, message: "Worktree directory already absent"} unless File.exist?(worktree_path)
+
+            FileUtils.rm_rf(worktree_path)
+            return {success: true, message: "Worktree directory removed"} unless File.exist?(worktree_path)
+
+            error_result("Worktree directory still exists after removal: #{worktree_path}")
           rescue => e
-            warn "Warning: Failed to remove worktree directory: #{e.message}"
+            error_result("Failed to remove worktree directory: #{e.message}")
           end
 
           # Check if worktree has uncommitted changes
@@ -339,7 +343,7 @@ module Ace
           # @return [Hash] Command result
           def execute_git_worktree_prune
             require_relative "../atoms/git_command"
-            Atoms::GitCommand.worktree("prune", timeout: @timeout)
+            Atoms::GitCommand.worktree("prune", "--expire", "now", timeout: @timeout)
           end
 
           # Parse prune output to count pruned worktrees

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

@@ -3,7 +3,7 @@
 module Ace
   module Git
     module Worktree
-      VERSION = '0.19.4'
+      VERSION = '0.21.6'
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git-worktree
 version: !ruby/object:Gem::Version
-  version: 0.19.4
+  version: 0.21.6
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-03-29 00:00:00.000000000 Z
+date: 2026-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli