acstack 0.52.4 → 0.52.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "acstack",
   "description": "Agentic coding stack where planning grows only as far as needed: a map of decisions, tasks, checks, and handoffs behind a pluggable tracker.",
-  "version": "0.52.4",
+  "version": "0.52.5",
   "author": {
     "name": "ac8318740"
   },

package/README.md

@@ -284,7 +284,7 @@ What an effort leaves behind is what matters: updated specs, decision notes, and
 | `/acstack:bridge` | Set up and operate the Playwriter cross-device browser bridge |
 | `/acstack:visual-docs` | Write docs that lead with a diagram and derive structure from it (Minto pyramid) |
 | `/acstack:new-worktree` | Create a git worktree off the remote base branch and continue the task inside it |
-| `/acstack:teardown-worktree` | Retire finished worktrees and delete their merged local and remote branches |
+| `/acstack:teardown-worktree` | Retire finished worktrees, delete their merged local and remote branches, and clean build outputs in worktrees that stay |
 | `/acstack:terminal-workspace` | Set up a keyboard-only terminal for driving agents on a dev machine |
 
 ## 6. Every agent

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack-cli",
-  "version": "0.52.4",
+  "version": "0.52.5",
   "description": "CLI for the ACStack agentic coding stack",
   "type": "module",
   "license": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack",
-  "version": "0.52.4",
+  "version": "0.52.5",
   "private": false,
   "description": "Agentic coding stack with first-class Claude Code and pi support: skills, orchestrator instructions, and verification agents.",
   "license": "MIT",

package/skills/teardown-worktree/SKILL.md

@@ -1,14 +1,12 @@
 ---
 name: teardown-worktree
-description: "Retire finished git worktrees – move this session back to the main checkout, move the orchestrator's pane back to the main repo workspace, remove the checkouts, and delete the merged local and remote branches. Scans the whole repo, not just the current worktree. Use whenever the user says \"tear down the worktree\", \"clean up worktrees\", \"remove this worktree\", \"delete the worktree and branch\", \"clean up stale worktrees\", or otherwise wants finished worktrees and their branches gone."
+description: "Retire finished git worktrees – move this session back to the main checkout, move the orchestrator's pane back to the main repo workspace, remove the checkouts, delete the merged local and remote branches, and offer to clean rebuildable build outputs in worktrees that stay. Scans the whole repo, not just the current worktree. Use whenever the user says \"tear down the worktree\", \"clean up worktrees\", \"remove this worktree\", \"delete the worktree and branch\", \"clean up stale worktrees\", \"free disk space from old sessions\", or otherwise wants finished worktrees and their branches gone."
 argument-hint: "[worktree name, or nothing to scan the whole repo]"
 ---
 
 # Teardown worktree
 
-Retire finished worktrees.
-
-Move this session out first. Remove the worktrees next. Delete the branches they were on last.
+Retire finished worktrees. Move this session out first. Remove the worktrees next. Delete the branches they were on last.
 
 Removing a worktree this session is standing in, or one that still holds a running agent, destroys live work. The order below exists to prevent that, as far as either orchestrator can tell. Follow it.
 
@@ -24,9 +22,7 @@ One repo per run: the repo that owns the cwd. Resolve its main checkout from any
 dirname "$(git rev-parse --git-common-dir)"
 ```
 
-Submodules are separate repos with their own worktrees and their own remote.
-
-If the repo has submodules carrying worktrees, say so. Offer a second run against each. Never scan them silently.
+Submodules are separate repos with their own worktrees and their own remote. If the repo has submodules carrying worktrees, say so. Offer a second run against each. Never scan them silently.
 
 ## 1. Build the plan
 
@@ -38,11 +34,11 @@ List every worktree of the repo:
 git worktree list --porcelain
 ```
 
-Skip the main checkout. First settle who hosts this session and who owns each checkout, then classify each remaining worktree on the four checks that follow.
+Skip the main checkout. First settle who hosts this session and who owns each checkout, then classify each remaining worktree on the five checks that follow.
 
 ### Which orchestrator hosts this session, and which one owns each checkout
 
-Settle both before the four checks. A worktree orchestrator is a tool that opens panes and holds worktrees for you – herdr and Orca are the two this skill knows.
+Settle both before the five checks. A worktree orchestrator is a tool that opens panes and holds worktrees for you – herdr and Orca are the two this skill knows.
 
 Two different facts drive this skill:
 
@@ -95,9 +91,11 @@ git -C <path> status --porcelain --ignore-submodules=all
 
 Report pointer drift in the plan anyway, from `git -C <path> submodule status`. That way a real pending bump stays visible, and the ignore flag does not hide it.
 
-Any output from the status check means skip.
+Any output from the status check means skip. Do not remove it. Do not force it. List it at the end with what it holds.
+
+### Ignored data
 
-Do not remove it. Do not force it. List it at the end with what it holds.
+Removal deletes every file git ignores, forced or not, and the status check cannot see them. Follow `artifacts.md` step 1. Any preserve path, such as `.env` or Terraform state, means skip unless the user approves losing that named path.
 
 ### Merged
 
@@ -135,7 +133,9 @@ Nothing holds agent state, so nothing can confirm liveness. Classification then
 
 ### Show it
 
-Print one table with six columns: worktree, branch, whether the local branch goes, whether the remote branch goes, blocking panes, and the reason. Then ask once.
+Print one table with seven columns: worktree, branch, whether the local branch goes, whether the remote branch goes, blocking panes, ignored data (each preserve path with its size, then the rebuildable total), and the reason.
+
+Below the table, list the build outputs step 5 could clean in worktrees that stay. Then ask once: the user approves the removals and picks which cleans to run.
 
 The blocking panes column names each pane that blocks the removal, pane id first and process name after – `w26:p2 claude` for example. Leave the cell empty when nothing blocks. The user then knows which pane to close.
 
@@ -147,9 +147,7 @@ Do this before removing anything, and only after approval.
 
 So no tool call walks the session cwd back. `ExitWorktree` only unwinds a worktree this session entered with `EnterWorktree`. It is a no-op for a session that launched inside one.
 
-The removal itself is what moves the session. Run it from the main checkout against an absolute path.
-
-The harness then resets the session cwd to the main checkout on its own. Confirm with `pwd` afterwards.
+The removal itself is what moves the session. Run it from the main checkout against an absolute path. The harness then resets the session cwd to the main checkout on its own. Confirm with `pwd` afterwards.
 
 - Entered with `EnterWorktree`: call `ExitWorktree` with `action: "keep"` first. Keep, not remove: step 3 owns the removal, and `remove` refuses on a worktree entered by path.
 - Launched inside the worktree: no call needed.
@@ -158,9 +156,7 @@ The harness then resets the session cwd to the main checkout on its own. Confirm
 
 That much is the same everywhere. What follows depends on the branch `active` names. This step is the one place `active` still decides anything: how this session moves itself.
 
-When `active` is `herdr`, follow `herdr.md` step 2 before you remove anything.
-
-When `active` is `orca`, follow `orca.md` step 2. It leaves this session's own checkout in place.
+When `active` is `herdr`, follow `herdr.md` step 2 before you remove anything. When `active` is `orca`, follow `orca.md` step 2. It leaves this session's own checkout in place.
 
 ### Host: none
 
@@ -172,11 +168,9 @@ Every removal through herdr or plain git passes `--force`. Orca is the exception
 
 Plain `git worktree remove` refuses on any worktree containing submodules with "working trees containing submodules cannot be moved or removed". That refusal hits every worktree in a repo that has them.
 
-Forcing is safe only because step 1 already proved the tree clean. It is never a way past uncommitted changes.
-
-The hard rule: never run `worktree remove --force` on a workspace that still holds a pane other than this session's own. Forcing waives herdr's own check, so the pane enumeration is the only guard left.
+Forcing is safe only because step 1 already proved the tree clean and its ignored data rebuildable or approved for loss. It is never a way past uncommitted changes.
 
-Enumerate the panes again immediately before the call. Refuse the removal while any other pane remains.
+The hard rule: never run `worktree remove --force` on a workspace that still holds a pane other than this session's own. Forcing waives herdr's own check, so the pane enumeration is the only guard left. Enumerate the panes again immediately before the call. Refuse the removal while any other pane remains.
 
 Take the branch each checkout's `owner` names, not the branch `active` names. Decide per worktree: one checkout in the plan can belong to herdr while the next is plain git.
 
@@ -210,12 +204,17 @@ Use `branch -d`, never `-D`. If `-d` refuses, the merge test was wrong. Stop and
 
 Skip the remote delete when nobody ever pushed the branch, or when merging the pull request already deleted it. The `git fetch origin --prune` from step 1 keeps a branch GitHub already removed from looking like work to do.
 
-## 5. Report
+## 5. Clean build outputs in kept worktrees
+
+Only for worktrees that stay, whether step 1 skipped them or step 3 kept them, and only for the paths the user picked. Follow `artifacts.md` step 5. This step never retires a worktree, stops an agent, or closes a workspace.
+
+## 6. Report
 
 State what went and what stayed:
 
 - Worktrees removed, with their branches
-- Worktrees skipped, each with its reason: uncommitted work, an unmerged branch, a live agent or terminal, or the checkout this Orca terminal stands in
+- Build outputs cleaned, with the space each freed, and the ones left because something was running
+- Worktrees skipped, each with its reason: uncommitted work, preserve data it holds, an unmerged branch, a live agent or terminal, or the checkout this Orca terminal stands in
 - Which live-agent checks ran against each worktree, and which did not, so nobody reads a missing check as a passed check
 - Anything left for the user to decide
 
@@ -228,6 +227,9 @@ State what went and what stayed:
 - Remove a workspace that still holds a pane other than your own.
 - Reach for `EnterWorktree` to get back to the main checkout. It rejects the main working tree.
 - Force past uncommitted changes. Skip and report instead.
+- Read a clean status as proof the checkout holds nothing. It hides ignored files, and removal deletes them.
+- Clean build outputs in a worktree with a live agent or process. Report the size instead.
+- Remove a worktree, stop an agent, or delete a Docker volume only to reclaim disk space.
 - Reach for `git branch -D` when `-d` refuses.
 - Call a branch unmerged on the ancestor check alone. Check the pull request before deciding.
 - Delete a remote branch with no merged pull request and no ancestor in an integration branch.

package/skills/teardown-worktree/artifacts.md

@@ -0,0 +1,82 @@
+# Teardown worktree: ignored data and build outputs
+
+What to do with the files git ignores. `SKILL.md` step 1 lists them, and step 5 cleans build outputs in worktrees that stay. Each section names the step it belongs to.
+
+## Why ignored data needs its own check
+
+`git worktree remove` deletes every ignored file in the checkout, with or without `--force`, and says nothing. The uncommitted-work check cannot see them, because `git status` hides ignored paths.
+
+Ignored does not mean disposable. `.env`, local databases, Terraform state, backups, notebooks, and review or design output are often ignored precisely because they are local and unique. Clean, merged, idle, and done are not proof either.
+
+## Step 1 – list and classify
+
+List the ignored paths, collapsed to directories, with their sizes:
+
+```bash
+git -C <path> ls-files --others --ignored --exclude-standard --directory -z \
+  | xargs -0 -r -I{} du -sh -- "<path>/{}"
+```
+
+Class each path as one of two things:
+
+- **Rebuildable**: a tool-native command regenerates it from tracked files. The table below gives the common cases. Each one needs the tracked manifest or lockfile it names to exist in the checkout.
+- **Preserve**: everything else. A generated-looking name or extension alone is not evidence. When unsure, preserve.
+
+| Path | Rebuilt by | Needs tracked | Native clean |
+|---|---|---|---|
+| Cargo `target/` | `cargo build` | `Cargo.toml` | `cargo clean --manifest-path <path>/Cargo.toml` |
+| `node_modules/` | `npm ci`, `pnpm install`, `yarn install` | the lockfile | `rm -rf <path>/node_modules` |
+| `.next/`, `dist/`, `build/` | the project's build script | `package.json` naming that output | the project's `clean` script, or `rm -rf` the directory |
+| `.terraform/providers/` | `terraform init` | `.terraform.lock.hcl` | `rm -rf <path>/.terraform/providers` |
+| `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/` | the next run | nothing | `rm -rf` the directory |
+
+The listing collapses a wholly ignored directory to one line. Class that line by everything inside it, and list inside any directory that can mix the two classes:
+
+```bash
+du -sh -- <path>/.terraform/*
+```
+
+Only the `providers/` directory under `.terraform/` is rebuildable. The rest of `.terraform/`, `*.tfstate`, and `*.tfstate.backup` are state. Preserve them.
+
+A Python virtual environment is preserve by default, even with a tracked requirements file. Packages installed by hand do not show up in it. Call it rebuildable only when the user confirms.
+
+Prefer the project's own clean script when `package.json`, a `Makefile`, or `justfile` defines one. Read what it deletes first.
+
+### What the sizes do and do not say
+
+`du` reports allocated size. Hardlinked stores, such as pnpm's, free less than that when removed. A symlink costs nothing, and removal deletes the link, never its target.
+
+Shared caches outside the checkout, such as `~/.cargo`, `~/.npm`, and the pip cache, serve every project. They are out of scope. Never clean them from a teardown.
+
+### Data outside the checkout
+
+Removal leaves behind what the session created elsewhere. Report the parts you can find. Never delete them from a teardown:
+
+- Docker Compose containers and their volumes, when Docker is installed:
+
+    ```bash
+    docker ps -a --filter "label=com.docker.compose.project.working_dir=<path>" --format '{{.Names}} {{.Status}}'
+    ```
+
+- A Cargo target directory moved out by `CARGO_TARGET_DIR` or `.cargo/config.toml`
+
+## Step 1 – what it means for the plan
+
+Removing a worktree deletes everything ignored in it, so:
+
+- Every ignored path rebuildable: the worktree can go. List the paths and total size in the plan.
+- Any preserve path: skip the worktree. Name each preserve path and its size, so the user can move or delete it deliberately.
+
+The user can approve losing a named preserve path in the plan. Only an explicit approval naming that path counts. A general yes to the plan does not.
+
+## Step 5 – clean build outputs in kept worktrees
+
+A worktree can be skipped from retirement and still hold gigabytes of build output. Cleaning that output is a separate decision from removing the worktree. It never retires the worktree, stops an agent, or closes a workspace.
+
+Offer it for each kept worktree whose rebuildable paths total more than about 100 MB. List the paths, sizes, and the native clean command for each. The user picks which to run.
+
+Clean a path only when step 1's live-agent checks found nothing running in that worktree. A live agent, editor, dev server, or build may be using the output, so report the size instead and leave it.
+
+Rerun the live-agent checks immediately before each clean. Even then, finding no process is a snapshot, not a lock. Something can start using the path a moment later. Say so in the report rather than calling the clean safe.
+
+Run the native command from the table, against absolute paths. Never run `git clean -X` or `git clean -x`. Either one deletes every preserve path along with the build output.