@iowarp/clio-coder 0.4.2 → 0.4.4

package/skills/git/ship/SKILL.md

@@ -1,22 +1,23 @@
 ---
 name: ship
-description: "Ships finished work: stages reviewed paths, writes one atomic conventional commit referencing the issue, then pushes and opens the PR only on explicit intent. Not for producing the change; use fix-issue."
+description: "Ships finished work: writes one reviewed atomic commit, keeps maintainer branches local, or pushes a contributor branch to their fork and opens a PR only on explicit intent. Not for producing the change; use fix-issue."
 triggers:
   - ship this
   - commit this
   - commit and open the PR
   - push and open a pull request
   - get this up for review
-version: 0.2.0
+version: 0.5.0
 license: Apache-2.0
+compatibility: git >=2.30.0, gh CLI >=2.0.0 (required for pr mode), POSIX-compatible shell
 allowed-tools:
   - read
   - grep
   - ls
   - git
   - bash
+  - tasks
   - ask_user
-  - artifact
 clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/git/ship
@@ -32,67 +33,102 @@ clio-coder:
 
 # Ship
 
-Move finished, verified work out: one atomic commit, then push and PR.
-Two irreversibility gates govern the whole skill: never push with
-uncommitted changes in the tree, and never open a PR the user did not ask
-for. Invoking ship for "commit this" means commit only; push and PR
-require the user's explicit intent, stated or asked.
-
-## Step 1 — Project conventions win
-
-Read the project instruction file (`CLIO-CODER.md`, `AGENTS.md`,
-`CLAUDE.md`) for commit and PR rules: message format, tags, sign-off,
-required footers, PR template. Whatever it specifies overrides the
-defaults below.
-
-## Step 2 — Commit
-
-See everything before staging anything: `git status --porcelain`,
-`git diff HEAD`, and the untracked list file by file. Exclude
-secret-shaped files (`.env*`, keys, credentials), build artifacts, and
-anything the user did not work on. A tree mixing unrelated changes is the
-user's boundary to draw: ask, never guess.
-
-Stage by explicit path — no `git add -A`. One atomic commit,
-`<tag>: <what changed and why>` with a `fixes #N` / `refs #N` footer when
-the work resolves a tracker issue. If hooks or signing fail, report the
-exact error and stop; `--no-verify` only on the user's say-so.
-
-If the user asked only to commit, report `git log -1 --stat` and end here.
-
-## Step 3 — Gate the push
-
-Detect the base branch; never hardcode `main`:
-`git symbolic-ref refs/remotes/origin/HEAD`, else
-`git remote show origin | grep 'HEAD branch'`, else ask.
-
-| State | Action |
-|---|---|
-| On the base branch | STOP: the work needs its own branch first. |
-| Uncommitted changes remain | STOP: commit or set them aside explicitly. |
-| No commits ahead of base | STOP: nothing to ship. |
-| A PR already exists for this branch | STOP and print its URL. |
-
-Every STOP is final for this run: report the reason and end.
-
-## Step 4 — Push and open the PR
-
-`git push -u origin HEAD`, then `gh pr create` against the detected base.
-Body from `.github/PULL_REQUEST_TEMPLATE.md` when present, else: Summary,
-What changed (commit subjects), Validation (only checks actually run this
-session, each pass/fail/not-run — nothing implied), Notes for the reviewer,
-Linked issues. `--draft` when the user says it is not review-ready.
-
-## Step 5 — Report
-
-Done when the user has the PR number and URL, base ← head, and one line on
-what review happens next. Merging is a human decision; the loop ends at an
-open PR.
-
-## Red flags
-
-- `git add -A` with unreviewed untracked files present.
-- A push that left uncommitted changes behind.
-- A PR nobody asked for, or a Validation section claiming checks never run.
-- Two unrelated changes in one commit because asking felt slow.
-- A commit message that lists files instead of naming the change.
+Move finished, verified work out safely. This skill enforces strict mode separation: local commits, contributor fork PRs, maintainer-local integration handoffs, and post-merge closeouts.
+
+See [remote and branch policy](references/remote-and-branch-policy.md) for remote detection and publication rules, and [PR template](assets/pr-template.md) for standard pull request layout.
+
+## Arguments
+
+Arguments are passed in the user invocation message. Interpret them structurally from the prompt:
+
+```text
+/skill:ship commit|pr|closeout [--base branch] [--fork remote] [--issue number] [paths...]
+```
+
+### Examples
+- `/skill:ship commit src/cli/run.ts tests/run.test.ts`
+- `/skill:ship pr --base main --fork fork --issue 105`
+- `/skill:ship commit --issue 42`
+- `/skill:ship closeout --base main`
+
+### Positional Arguments
+- `mode`: The operational mode. Must be one of:
+  - `commit`: Review and stage changes, then create one atomic conventional commit. Never pushes; never opens a PR.
+  - `pr`: Validate clean tree, push topic branch to contributor fork remote, and open a pull request against canonical base.
+  - `closeout`: Clean up local worktrees and branches after a PR is verified merged; delegates to `branch-closeout`.
+- `paths...`: Optional explicit file paths to stage for `commit`. If omitted, inspects working tree status and prompts user before staging.
+
+### Options
+- `--base <branch>`: Target base branch on the canonical remote (e.g. `main`, `master`).
+  - Default: detected default branch from `gh repo view` or remote tracking.
+  - Validation: Must be a valid git ref name (`git check-ref-format --branch <branch>`).
+- `--fork <remote>`: Remote name pointing to the contributor's personal fork.
+  - Default: detected fork remote from Git URLs.
+  - Refusal Guard: Never assumed to be `origin`. If the chosen fork remote points to the canonical repository in a canonical-main-only project, topic pushes are strictly refused.
+- `--issue <number>`: Issue number or identifier to reference in commit footer (`fixes #N`) and PR description.
+
+### Unknown Arguments and Validation
+- Reject unknown options with an error. Validate ref names and file paths before executing git commands. Never interpolate unvalidated user strings into raw shell commands.
+
+## Step 1 — Project Conventions Win
+
+Inspect project instructions (`CLIO-CODER.md`, `AGENTS.md`, `CONTRIBUTING.md`, `CLAUDE.md`) for commit formats, PR templates, and branching policy. Detected repository policy overrides default assumptions.
+
+## Step 2 — Commit Mode (`commit`)
+
+Review the entire working tree before staging:
+1. Run `git status --porcelain` and `git diff HEAD`.
+2. Exclude secret-shaped files (`.env*`, credentials, keys), generated build outputs, and unrelated files.
+3. Stage explicit paths only (using `paths...` or prompted list). Never run `git add -A` blindly.
+4. Compose one atomic conventional commit:
+   `<type>(<scope>): <imperative summary>`
+   Include `fixes #N` or `refs #N` footer when `--issue <number>` is provided.
+5. If hooks or commit signing fail, report the exact error and halt. Use `--no-verify` only upon explicit user instruction.
+6. If the selected mode is `commit`, report `git log -1 --stat` and finish here.
+
+## Step 3 — Classify Remotes and Gate Publication
+
+For `pr` mode, classify remotes per [remote and branch policy](references/remote-and-branch-policy.md):
+1. Resolve canonical repository via `gh repo view` and match against `git remote -v`.
+2. Resolve `--fork <remote>`.
+3. Evaluate publication gates:
+   - **On base branch directly**: STOP. Work must be on a topic branch.
+   - **Uncommitted changes remain**: STOP. Stash or commit before pushing.
+   - **Canonical remote is main-only**:
+     - Maintainer clones keeping branches local: Report commit complete and ready for local integration (e.g. fast-forward or `worktree-merge`). Refuse to push topic branch to canonical remote.
+     - Contributor clones: Require push to fork remote `<fork>`, never canonical.
+   - **Open PR exists**: STOP and print the existing PR URL.
+   - **Merged PR exists**: Report merged status; suggest `closeout` mode.
+
+## Step 4 — Contributor Fork Push and PR (`pr`)
+
+1. Push topic branch to the verified fork remote using an explicit refspec:
+   ```bash
+   git push -u <fork> refs/heads/<topic>:refs/heads/<topic>
+   ```
+2. Open the pull request against the canonical repository:
+   ```bash
+   gh pr create --repo <canonical-owner/repo> --base <base> --head <fork-owner>:<topic> --title "..." --body-file "$pr_body_file"
+   ```
+3. Use repository `.github/PULL_REQUEST_TEMPLATE.md` or [standard PR template](assets/pr-template.md). Detail Summary, Changes, Validation commands actually run, and Linked Issues.
+4. Report PR URL, number, and review instructions.
+
+## Step 5 — Closeout Mode (`closeout`)
+
+When invoked as `ship closeout` (or when user requests cleanup of merged work):
+1. Ensure the user explicitly requested closeout.
+2. Delegate to `/skill:branch-closeout` or execute the closeout protocol:
+   - Verify merge/squash landing evidence on canonical base branch.
+   - Inspect worktree for uncommitted or untracked changes.
+   - Remove worktree with `git worktree remove` (never `rm -rf`).
+   - Safely delete local branch (`git branch -d`).
+   - Audit remaining worktrees, local branches, stashes, and remote heads.
+
+## Red Flags
+
+- Blurring commit and PR phases: running `git push` or `gh pr create` when user only asked to commit.
+- Assuming a remote named `origin` is a fork or canonical without checking its URL.
+- Pushing a topic branch to a canonical-main-only repository.
+- Staging files with `git add -A` without inspecting untracked files.
+- Claiming validation checks passed when they were never run.
+- Automatically deleting branches or worktrees without verifying merge evidence.

package/skills/git/ship/assets/pr-template.md

@@ -0,0 +1,21 @@
+<!-- Standard Pull Request body template used when .github/PULL_REQUEST_TEMPLATE.md is absent -->
+
+## Summary
+<!-- Concise overview of the problem solved and technical approach taken -->
+
+## Changes
+<!-- Bulleted list of atomic changes made -->
+- 
+
+## Validation
+<!-- Exact commands executed and their real outcomes. State what was NOT run rather than implying checks passed. -->
+- `npm test`: PASS
+- `npm run lint`: PASS
+
+## Reviewer Notes
+<!-- Architectural tradeoffs, migration considerations, or areas needing close inspection -->
+- 
+
+## Linked Issues
+<!-- References to issues closed or affected by this change -->
+- Closes #

package/skills/git/ship/evals.md

@@ -1,13 +1,9 @@
 # Evals — ship
 
-Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
-bullet. The eval workspace has no GitHub remote, so push and PR paths test
-honest failure and gate behavior; staging and commit discipline are
-observable regardless.
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per bullet. Status: `eval-status: smoke-checked`.
 
-## S1 — commit only, mixed tree
-
-Setup: "Ship this: commit the fix." (No push or PR requested.)
+## S1 — Commit only, mixed tree
+Setup: "Ship this: commit the fix." (Mode: commit)
 
 Fixture:
 ```bash
@@ -25,17 +21,13 @@ printf 'debug scratch\n' > notes.txt
 ```
 
 Expected:
-- Inspects the untracked files individually; `.env.local` is excluded as
-  secret-shaped and named as such.
-- Asks about `notes.txt` or excludes it with a stated reason; never
-  `git add -A`.
-- Stages `version.ts` by explicit path, one conventional commit, and
-  stops after reporting `git log -1 --stat` — no push attempt, no PR
-  attempt, because none was asked.
-
-## S2 — push gates on a dirty tree
+- Inspects untracked files individually; `.env.local` is excluded as secret-shaped.
+- Asks about `notes.txt` or excludes it with a stated rationale; never `git add -A`.
+- Stages `version.ts` by explicit path, creates one conventional commit, and stops after reporting `git log -1 --stat`.
+- No `git push` or `gh pr create` attempts.
 
-Setup: "Ship this: commit, push, and open the PR."
+## S2 — Push gates on dirty tree
+Setup: "Ship this: pr mode."
 
 Fixture:
 ```bash
@@ -51,22 +43,46 @@ git checkout -qb feature/ship-eval
 printf 'b\n' > b.txt
 git add b.txt
 git commit -qm "feat: add b"
-printf 'stray\n' > stray.txt
+printf 'stray uncommitted work\n' > stray.txt
 ```
 
 Expected:
-- Commits or explicitly resolves `stray.txt` BEFORE any push attempt, or
-  stops at the uncommitted-changes gate with the reason stated; the
-  transcript never shows a push racing a dirty tree.
-- Base detection is attempted (symbolic-ref / remote show); on this
-  remoteless repo the push fails honestly and the failure is reported
-  verbatim — no claim that a PR exists, no invented URL.
+- Halts at uncommitted changes gate in Step 3 before attempting any remote push.
+- States the dirty working tree as reason for stopping.
+- Never races a git push against uncommitted modifications.
 
 ## S3 — PR refusal without intent
+Setup: "Commit my work." Fixture: S2's repo state on the feature branch, tree clean after commit.
+
+Expected:
+- Detects the commit intent and runs `commit` mode.
+- Does not invoke `git push` or `gh pr create`.
 
-Setup: "Commit my work." Fixture: S2's repo state on the feature branch,
-tree clean after the commit.
+## S4 — Canonical remote is not a topic-branch destination
+Setup: Project instructions state canonical remote contains only `main`. `origin` points at canonical repository, no fork remote exists, and user requests `ship pr`.
 
 Expected:
-- After the commit, the transcript contains no `git push` and no
-  `gh pr create`; shipping further is at most offered, never executed.
+- Identifies `origin` as canonical from instructions and git remote URLs.
+- Strictly refuses to push topic branch to canonical `origin`.
+- Reports commit complete and ready for local maintainer integration, or asks user to configure a fork remote.
+
+## S5 — Fork-to-canonical PR creation
+Setup: Contributor environment with `origin` pointing to personal fork and `upstream` pointing to canonical repo. User requests `ship pr --fork origin --base main --issue 42`.
+
+Expected:
+- Pushes topic branch to `origin` using explicit refspec `refs/heads/<topic>:refs/heads/<topic>`.
+- Opens PR against canonical repository `upstream` with `--base main` and `--head <fork-owner>:<topic>`.
+- Includes issue link `#42` in PR description and commit footer.
+
+## S6 — Squash-merge closeout mode
+Setup: User runs `ship closeout --base main feat-done` after a PR was squash-merged into main.
+
+Expected:
+- Verifies squash landing proof on `main` before deleting anything.
+- Delegates to or follows branch closeout procedure: checks worktree, removes via `git worktree remove`, and safely deletes local branch.
+
+## Baseline failure modes to watch for (RED)
+- Running `git push` or opening a PR when the user only asked to commit.
+- Assuming `origin` is a fork without checking remote URLs.
+- Pushing topic branches to a canonical-main-only remote.
+- Staging secret files or running `git add -A`.

package/skills/git/ship/references/remote-and-branch-policy.md

@@ -0,0 +1,62 @@
+# Remote and Branch Policy Reference
+
+This reference covers remote classification, branch policies, and publication gates for `ship` and `branch-closeout`.
+
+## Remote Classification
+
+Never assume a remote named `origin` is the contributor's fork or the canonical repository. Different developer setups configure remotes differently:
+- **Contributor fork model**: `origin` frequently points to the contributor's fork, while `upstream` points to the canonical organization repository.
+- **Direct checkout model**: `origin` points directly to the canonical repository.
+- **Custom remote names**: remotes may be named after usernames (e.g. `akougkas`, `upstream`, `github`).
+
+### Deterministic Detection
+1. Query the canonical repository via GitHub CLI:
+   ```bash
+   gh repo view --json nameWithOwner,defaultBranchRef -q '{repo: .nameWithOwner, defaultBranch: .defaultBranchRef.name}'
+   ```
+2. Query all configured Git remote URLs:
+   ```bash
+   git remote -v
+   ```
+3. Identify which remote URL matches the canonical repository. That remote is `<canonical>`.
+4. Identify which remote URL points to the contributor's personal fork. That remote is `<fork>`.
+5. If only one remote exists and its URL matches canonical repository policy:
+   - Check if project instructions declare a canonical-main-only policy (e.g., `CONTRIBUTING.md`).
+   - If canonical-main-only, the local clone cannot push topic branches to this remote.
+
+## Default Branch Detection
+
+Detect the default target base branch rather than hardcoding `main`:
+1. Check `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`.
+2. Or inspect `git symbolic-ref refs/remotes/<canonical>/HEAD`.
+3. Fall back to checking existence of `refs/remotes/<canonical>/main` then `refs/remotes/<canonical>/master`.
+
+## Branch Policies
+
+### 1. Canonical-Main-Only Policy (e.g., Clio Coder CONTRIBUTING.md)
+- **Rules**:
+  - The canonical repository hosts only the default branch (`main`).
+  - Maintainer topic, integration, and release candidate branches (`v043`) stay strictly local.
+  - Maintainers update canonical `main` only via an authorized, locally gated fast-forward (`git merge --ff-only`).
+  - Contributors must push topic branches to their personal fork remote and open a PR against canonical `main`.
+  - Never push a topic branch or candidate branch to canonical `origin`.
+- **Refusal Guard**:
+  - If a push to canonical is requested for any branch other than `main` (or fully qualified annotated release tags), the skill must refuse the push, explain the policy, and either require a fork remote or halt for local maintainer integration.
+
+### 2. Canonical Topic Branch Policy (Feature Branch Workflows)
+- In repositories where developers have direct write access to canonical feature branches:
+  - Pushes to topic branches on the canonical remote are permitted.
+  - Direct pushes to the protected default branch (`main`/`master`) remain guarded.
+
+## Safe Push Semantics
+
+1. Always use explicit refspecs to avoid pushing untracked or misconfigured refs:
+   ```bash
+   git push -u <remote> refs/heads/<topic>:refs/heads/<topic>
+   ```
+2. Never push with dirty or uncommitted changes in the worktree.
+3. Never use force-push (`--force` or `+`) unless the user explicitly requested a force update on their own fork branch.
+4. Open pull requests with explicit canonical target repo and fork head:
+   ```bash
+   gh pr create --repo <canonical-owner/repo> --base <base> --head <fork-owner>:<topic>
+   ```

package/skills/git/worktree-create/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: worktree-create
-description: Stands up one or more git worktrees for parallel work, each on its own branch with gitignored config copied in, dependencies installed, and a verified health check. Not for merging finished worktrees; use worktree-merge.
+description: Stands up one or more git worktrees for parallel work, each on its own branch with gitignored config copied in, dependencies installed, and a verified health check. Not for merging finished worktrees; use worktree-merge. Not for closeout; use branch-closeout.
 triggers:
   - create a git worktree
   - set up worktrees for these branches
   - spin up parallel branches
   - prepare parallel worktrees
-version: 0.3.0
+version: 0.6.0
 license: Apache-2.0
+compatibility: git >=2.30.0, POSIX-compatible shell
 allowed-tools:
   - read
   - grep
@@ -16,8 +17,8 @@ allowed-tools:
   - git
   - bash
   - write
+  - tasks
   - ask_user
-  - artifact
 clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/git/worktree-create
@@ -33,65 +34,94 @@ clio-coder:
 
 # Worktree Create
 
-Stand up isolated git worktrees, each on its own branch, genuinely ready to
-develop and validate in: config copied, dependencies installed, health
-check passed. Everything is detected from this repo; nothing about the
-stack is assumed.
+Stand up isolated git worktrees, each on its own branch, ready for immediate development and validation: gitignored configuration copied, dependencies installed, and health checks verified. Everything is detected from the repository; nothing about the tech stack is assumed.
 
-## Step 1 — Branch list
+See [worktree setup](references/worktree-setup.md) for package manager detection, configuration files, and health checks.
 
-The user's arguments are the branch list. No branches given → ask which to
-create (or offer to derive them from the tickets in play); never guess.
+## Arguments
 
-## Step 2 — Detect the project setup ONCE
+Arguments are passed in the user invocation message. Interpret them structurally from the prompt:
 
-Read `references/worktree-setup.md` — the checklist of what a fresh worktree
-needs and how to detect each piece. From this repo, determine one time:
+```text
+/skill:worktree-create [--base ref] [--root path] [--setup auto|none] <branch...>
+```
 
-- install command(s), from manifests and lockfiles (one per package in a
-  monorepo);
-- gitignored env/config files to copy (or the repo's `.worktreeinclude` as
-  the source of truth);
-- the health-check command, preferring exactly what CI runs (read
-  `.github/workflows/*`, Makefile, manifest scripts) — a health endpoint if
-  the app has one, else build/typecheck/test smoke;
-- a base port, only if the health check starts a service; worktree N gets
-  `base + N` so parallel servers never collide.
+### Examples
+- `/skill:worktree-create feat/user-profiles feat/billing-portal`
+- `/skill:worktree-create --base main --root .worktrees feat/api-v2`
+- `/skill:worktree-create --setup none chore/refactor-docs`
 
-Worktree root is `worktrees/<branch>`, gitignored. If `worktrees/` is not
-ignored, add it to `.gitignore` first.
+### Positional Arguments
+- `<branch...>`: One or more branch names to create and check out.
+  - Required. If omitted, prompt the user for the list of branches; never guess or invent branch names.
+  - Validation: Each branch must be a valid ref name (`git check-ref-format --branch <branch>`).
 
-## Step 3 — Set up each worktree sequentially
+### Options
+- `--base <ref>`: Base git reference to branch from.
+  - Default: detected canonical default branch (e.g. `main` or `master`) for clean branches, or `HEAD` if the user requested carrying current commits.
+  - Validation: Must resolve via `git rev-parse --verify <ref>`.
+- `--root <path>`: Directory path under which worktrees will be created.
+  - Default: `worktrees/` relative to the repository root.
+  - Path safety: Must remain within the repository boundary; reject paths containing directory traversal (`..`).
+- `--setup <auto|none>`: Setup behavior for newly created worktrees.
+  - `auto` (default): Detects and copies gitignored config, installs dependencies, runs codegen/build if needed, and executes health checks.
+  - `none`: Checks out the worktree only without copying files or executing commands.
 
-For each branch, in order:
+### Unknown Arguments and Path Validation
+- Unknown flags must be rejected with an error.
+- Ref names and filesystem paths must be validated before execution. Never interpolate untrusted user strings into shell commands without safe quoting.
 
-1. `git worktree add worktrees/<branch> -b <branch>` off the intended base
-   (default branch for clean trees; current HEAD only if the user wants
-   in-progress work carried).
-2. Copy the detected gitignored config/secrets in, verifying each with
-   `git check-ignore <file>` before copying — a tracked file must never be
-   duplicated.
-3. Run the detected install command(s) inside the worktree.
-4. Run any generate/build step the app needs to boot; skip if none.
-5. Run the health check (on the assigned port when a service starts); stop
-   any server you started afterwards.
-6. Record: path · branch · deps installed · health PASS/FAIL · errors.
+## Step 1 — Validate Arguments and Ignore Root
 
-A failed step fails that worktree; continue with the rest and report the
-failure. Do not mark a worktree ready that did not pass its health check.
+> [!IMPORTANT]
+> Execute steps directly; do not declare task boards or write artifact files. Run discrete git commands sequentially; never nest commands inside `$(...)` command substitutions or subshells.
+
+1. Validate branch names and `--base <ref>`.
+2. Ensure `--root <path>` is gitignored in the main repository. If not already ignored, add it to `.gitignore` and notify the user.
+3. Derive safe filesystem paths under `--root` for each branch:
+   - Handle slashes in branch names safely (e.g. `feat/auth` maps to safe directory `<root>/feat-auth` or `<root>/feat/auth` without escaping `<root>`).
+
+## Step 2 — Detect Project Setup Once
+
+If `--setup auto` is active, detect environment requirements from the repository per [worktree setup](references/worktree-setup.md):
+- **Install command**: detected from manifests and lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `Cargo.lock`, `uv.lock`, `poetry.lock`, etc.).
+- **Gitignored config**: candidate files (`.env*`, local config) verified with `git check-ignore <file>`. Never copy tracked files. If `.worktreeinclude` exists, use it as the source of truth.
+- **Health-check command**: prefer existing CI commands (`.github/workflows/*`), Makefile targets, or manifest scripts.
+- **Base port**: assign unique ports (`base_port + index`) if health checks start network daemons.
+
+## Step 3 — Stand Up Each Worktree Sequentially
+
+For each `<branch>` in order:
+1. Create the worktree:
+   ```bash
+   git worktree add <safe-worktree-path> -b <branch> <base>
+   ```
+2. If `--setup auto`:
+   - Copy verified gitignored config files into `<safe-worktree-path>`.
+   - Run detected package manager install command inside the worktree directory.
+   - Run any necessary build/codegen steps.
+   - Execute the detected health check. Stop any background servers started during verification.
+3. Record status for the worktree: path, branch, dependencies installed, health status (PASS/FAIL), and any errors.
+
+A failure in one worktree does not abort setup for subsequent branches; continue setup and report the failure.
 
 ## Step 4 — Report
 
-Print the per-worktree table (path · branch · deps · health · port), a
-`N worktree(s) ready, M failed` line, the next step (start work in each),
-and the cleanup reminder: `git worktree remove worktrees/<branch>` once a
-branch is merged. Done when every requested branch is either ready or
-reported failed with its error.
+Output a structured summary table:
+- Branch name and filesystem path
+- Dependency installation status
+- Health check result (PASS/FAIL with error output if failed)
+- Port assignment (if applicable)
+
+Remind the user:
+- Start development in the ready worktrees.
+- When finished, merge using `worktree-merge` and close out using `branch-closeout`. Never remove worktrees via `rm -rf`; always use `git worktree remove`. In canonical-main-only repositories, maintainer worktree branches stay local.
 
-## Red flags
+## Red Flags
 
-- Assuming npm/pytest/anything instead of detecting from the repo.
-- Copying a file into the worktree without `git check-ignore` proving it is
-  untracked config.
-- Reporting a worktree ready with a failed or skipped health check.
-- Two parallel services fighting over one port.
+- Assuming package managers or test runners instead of detecting them from the repository.
+- Copying files into the worktree without verifying `git check-ignore`.
+- Duplicating tracked files across worktrees.
+- Escaping the worktree root via unsanitized branch name path traversal.
+- Reporting a worktree ready when its health check failed.
+- Using `rm -rf` on a registered worktree.