acstack 0.52.4 → 0.52.6

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.6",
   "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.6",
   "description": "CLI for the ACStack agentic coding stack",
   "type": "module",
   "license": "MIT",

package/hooks/session-start.sh

@@ -206,10 +206,13 @@ if ! command -v python3 >/dev/null 2>&1; then
 fi
 
 python3 - "$claude_md" <<'PY'
-import json, sys
+import json, re, sys
 path = sys.argv[1]
 with open(path, 'r', encoding='utf-8') as f:
     content = f.read()
+# SessionStart reaches the lead session, so it keeps the lead block and drops the delegated one.
+content = re.sub(r'<!-- acstack:delegated:start -->[\s\S]*?<!-- acstack:delegated:end -->\n?', '', content)
+content = re.sub(r'<!-- acstack:lead:(start|end) -->\n?', '', content)
 print(json.dumps({
     "hookSpecificOutput": {
         "hookEventName": "SessionStart",

package/orchestrator/AGENTS.md

@@ -2,13 +2,31 @@
 
 ACStack keeps meaningful tests and chooses verification effort to fit the change.
 
+<!-- acstack:lead:start -->
 ## Your role
 
 - Understand the request, investigate the code, implement, and verify the result
 - Work directly on straightforward tasks, including research, tests, code, and checks
-- Delegate when another agent materially improves confidence or handles an independent scope
+- Delegate when another agent materially improves confidence, handles an independent scope, or keeps broad discovery out of your context
 - Honor explicit user requests for stronger process, including separate agents and tests-first work
 - Follow the shared Implementation discipline below across implement, quick-fix, and map work
+- Keep the user's session continuous
+    - Use `/acstack:handoff` to transfer work to a visible agent
+    - Use `/acstack:compact-and-continue` to preserve session state before compaction
+<!-- acstack:lead:end -->
+<!-- acstack:delegated:start -->
+## Your role
+
+- You are a delegated session: the brief your parent gave at launch sets your role, scope, and access
+    - You may be an investigator, an implementer, or a coordinator of your own scope
+    - The shared guidance below applies wherever the brief does not narrow it
+- Stay inside the assigned scope and access
+    - Report work outside them to your parent instead of doing it
+    - Treat a no-edit instruction as binding even when the launcher does not enforce it
+- Delegate further only when the brief allows it, and never grant a child more access than you have
+- Report results, evidence, and blockers to your parent
+    - Your parent owns synthesis and completion unless the brief assigns them to you
+<!-- acstack:delegated:end -->
 
 ## Non-negotiable rules
 
@@ -40,12 +58,15 @@ ACStack runs on Claude Code, Codex, and pi. The skills name each capability once
 
 - **Launch a subagent** – start a child agent with its own context, by its ACStack name (`test-writer`, `task-executor`, `task-checker`, `frontend-verifier`)
     - Claude Code: the Agent tool, with `subagent_type` set to that name
-    - pi: `Agent` from `@tintinweb/pi-subagents` (`subagent_type`), or `subagent` from `pi-subagents` (`agent`)
+    - pi: `Agent` from `@tintinweb/pi-subagents` (`subagent_type`), `subagent` from `pi-subagents` (`agent`), or `team_agent` from ac-teams
+        - `team_agent` does not load ACStack agents by name, so put the role's instructions in the brief
+        - ac-teams describes its member access controls in its own `docs/access.md`
     - **Read-only codebase-search subagent** – `Explore` on Claude Code and pi's `Agent`, or `scout` on pi's `subagent`
     - `debugger` names a debugging agent
     - On a host without a matching built-in agent, launch a general subagent with that brief
 - **Agent team** – parallel full sessions, each owning one scope and launching its own subagents
     - Claude Code has agent teams, with messaging between teammates and plan approval by the lead
+    - pi has ac-teams, through `team_agent`
     - On a host without agent teams, work directly or delegate scopes sequentially
     - When the task assigns separate test ownership, keep it separate from implementation
 - **Ask the user a structured question** – the host's question tool (AskUserQuestion on Claude Code)
@@ -215,6 +236,40 @@ flowchart TD
     - Check the design gate and load design context once per task when it is on
     - Follow the same procedure for direct work and delegated implementation
 
+### Delegate investigation
+
+- Prefer delegated investigation when discovery means broad searches, substantial reading, independent hypotheses, or separable research questions
+    - Delegation keeps raw discovery out of your context, even when the investigator runs your own model
+    - Work directly when the paths are few and known, or when briefing costs more than searching
+    - Launch one investigator per separable question, with no fixed count
+- Launch the host's read-only search agent for navigation questions (see Host tools)
+    - For other questions, launch a general agent with the investigator brief below
+    - With no launcher available, investigate directly and say that delegation was unavailable
+- Choose the model separately from the role
+    - Prefer a configured cheaper, capable model for navigation and fact gathering
+    - Use a stronger model for hard causal or ambiguous analysis
+    - Never hardcode a provider or model; use what the host or user configured
+- Request enforced read-only access when the launcher reports that it can enforce it
+    - Expect prompt-only protection on most hosts today
+    - A read-only search agent such as `Explore` lacks edit tools; that limits its tools but is not operating-system enforcement
+    - Without enforcement, instruct the investigator not to edit project files, and call that protection prompt-only
+    - If an enforced launch fails, report the failure and ask before launching without enforcement
+- Own the synthesis: verify the decisive evidence a conclusion rests on, without repeating the whole investigation
+
+The investigator brief states:
+
+- The question, and why the answer matters
+- The scope: paths, repositories, or sources to search, and what is out of scope
+- The access: enforced read-only, or a prompt-only instruction not to edit project files
+- The report the parent needs back
+
+The investigator reports:
+
+- Findings, with file paths and line references
+- Which findings rest on evidence and which are hypotheses
+- What it searched, so the parent knows what it did not cover
+- Uncertainties, and the next checks worth running
+
 ### Use independent review where needed
 
 - Require independent review for security boundaries, money, irreversible data changes, or unresolved correctness or impact uncertainty
@@ -414,8 +469,8 @@ Launch each agent by the name below (see Host tools for how your host takes it).
 | Implement task        | `task-executor`     | Source and tests unless tests have a separate owner |
 | Verify implementation | `task-checker`      | Independent review, coverage adequacy, regressions |
 | Verify frontend UI    | `frontend-verifier` | Real browser, screenshots, non-negotiable          |
-| Find/locate something | `Explore` / `scout` | Read-only codebase search; `scout` on pi           |
-| Debug/investigate     | `debugger`          | Built-in debugging agent                           |
+| Investigate a question | `Explore` / `scout`, or a general agent | Read-only; brief per Delegate investigation |
+| Debug                 | `debugger`          | Built-in debugging agent                           |
 
 ---
 
@@ -436,5 +491,3 @@ Launch each agent by the name below (see Host tools for how your host takes it).
 - Keep living specs current through commit-time sync
 - Create a map when unresolved questions need durable tracking
 - Invoke `bridge` before cross-device browser or tunnel work
-- Use `/acstack:handoff` to transfer work to a visible agent
-- Use `/acstack:compact-and-continue` to preserve session state before compaction

package/package.json

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

package/pi/extension.ts

@@ -80,6 +80,8 @@ function ensureProjectData(ctx: ExtensionContext, root: string): boolean {
 const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
 /** pi-subagents sets this instead in a child it places in its own herdr pane. */
 const HERDR_BRIDGE_CHILD_ENV = "PI_SUBAGENTS_HERDR_BRIDGE";
+/** ac-teams sets this in every member it launches. */
+const AC_TEAMS_MEMBER_ENV = "AC_TEAMS_MEMBER";
 
 function agentDir(): string {
 	return process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
@@ -622,6 +624,18 @@ export function skillsSection(skills: Map<string, SkillInfo>): string | undefine
 	return lines.join("\n");
 }
 
+/**
+ * The orchestrator text for one kind of session. orchestrator/AGENTS.md marks
+ * the lead-only and delegated-only blocks; each session keeps its own block
+ * and drops the other.
+ */
+export function orchestratorFor(text: string, role: "lead" | "delegated"): string {
+	const other = role === "lead" ? "delegated" : "lead";
+	return text
+		.replace(new RegExp(`<!-- acstack:${other}:start -->[\\s\\S]*?<!-- acstack:${other}:end -->\\n?`, "g"), "")
+		.replace(new RegExp(`<!-- acstack:${role}:(start|end) -->\\n?`, "g"), "");
+}
+
 /**
  * The user message for one ACStack skill, in the same shape pi's own
  * /skill:<name> expansion produces. Built from this package's file, so a
@@ -640,9 +654,9 @@ export function skillInvocation(name: string, file: string, args: string): strin
 // --------------------------------------------------------------------------
 
 export default function acstack(pi: ExtensionAPI): void {
-	// A background subagent loads every ambient extension. The orchestrator
-	// prompt and the nudges belong to the lead session, never to a subagent.
-	if (process.env[SUBAGENT_CHILD_ENV] === "1" || process.env[HERDR_BRIDGE_CHILD_ENV] === "1") return;
+	// A delegated session keeps the shared guidance but not the lead's role,
+	// CLI symlinks, launcher warning, context nudges, or handoff reload.
+	const delegated = process.env[SUBAGENT_CHILD_ENV] === "1" || process.env[HERDR_BRIDGE_CHILD_ENV] === "1" || Boolean(process.env[AC_TEAMS_MEMBER_ENV]);
 
 	const orchestratorFile = path.join(packageRoot, "orchestrator", "AGENTS.md");
 	const styleFile = path.join(packageRoot, "output-styles", "ac-writing-style.md");
@@ -651,7 +665,7 @@ export default function acstack(pi: ExtensionAPI): void {
 	let warnedSubagents = false;
 
 	pi.on("session_start", async (event, ctx) => {
-		linkClis(ctx);
+		if (!delegated) linkClis(ctx);
 		const root = projectRoot(ctx.cwd);
 		if (ensureProjectData(ctx, root)) unsafeProjects.delete(root);
 		else {
@@ -659,6 +673,7 @@ export default function acstack(pi: ExtensionAPI): void {
 			return;
 		}
 
+		if (delegated) return;
 		if (!warnedSubagents && !pi.getAllTools().some((tool) => tool.name === "subagent" || tool.name === "Agent" || tool.name === "team_agent")) {
 			warnedSubagents = true;
 			report(
@@ -686,14 +701,19 @@ export default function acstack(pi: ExtensionAPI): void {
 
 		if (isProject(ctx.cwd)) {
 			const orchestrator = readText(orchestratorFile);
-			if (orchestrator) sections["acstack-orchestrator"] = orchestrator;
+			if (orchestrator) sections["acstack-orchestrator"] = orchestratorFor(orchestrator, delegated ? "delegated" : "lead");
 			else report(ctx, `acstack: could not read ${orchestratorFile}`, "warning");
 		}
 
 		const styleCfg = writingStyleSettings();
 		if (styleCfg.mode === "off") return;
 		const resolvedStyleFile = styleCfg.mode === "custom" && styleCfg.path ? expandUserPath(styleCfg.path) : styleFile;
-		const style = readText(resolvedStyleFile);
+		let style = readText(resolvedStyleFile);
+		// A sandboxed delegated session may not see a custom file outside its read roots.
+		if (!style && delegated && resolvedStyleFile !== styleFile) {
+			report(ctx, `acstack: could not read writing style at ${resolvedStyleFile}; using the bundled style`, "warning");
+			style = readText(styleFile);
+		}
 		if (!style) {
 			report(ctx, `acstack: could not read writing style at ${resolvedStyleFile}`, "warning");
 			return;
@@ -705,7 +725,7 @@ export default function acstack(pi: ExtensionAPI): void {
 		return { message: { customType: "acstack-writing-style-reminder", content: reminder, display: false } };
 	});
 
-	pi.on("agent_before_settle", async (event, ctx) => {
+	if (!delegated) pi.on("agent_before_settle", async (event, ctx) => {
 		if (event.outcome !== "completed") return;
 		const usage = ctx.getContextUsage();
 		if (!usage || usage.tokens === null) return;
@@ -736,7 +756,7 @@ export default function acstack(pi: ExtensionAPI): void {
 		};
 	});
 
-	pi.on("session_compact", async (_event, ctx) => {
+	if (!delegated) pi.on("session_compact", async (_event, ctx) => {
 		// The compaction threw the old context away, so the ladder starts over.
 		const key = sessionKey(ctx);
 		if (key) {

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.