@iowarp/clio-coder 0.4.1 → 0.4.3

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: Use when the user asks to set up one or more git worktrees for parallel work — "create a worktree", "set up worktrees for these branches", "spin up parallel branches". Detects the project's install, config, and health-check needs once, then stands up each worktree 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.2.1
+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.

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

@@ -1,13 +1,9 @@
 # Evals — worktree-create
 
-Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
-bullet. Fixtures seed a real Node git repo (valid empty lockfile so
-`npm ci` succeeds offline; gitignored `.env`; CI workflow declaring the
-commands). Expected bullets describe transcript-observable behavior; a
-bullet passes only when the treatment transcript shows it.
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per bullet. Status: `eval-status: smoke-checked`.
 
-## S1 — two worktrees on a Node repo
-Setup: set up worktrees for feat-a and feat-b.
+## S1 — Two worktrees on a Node repo
+Setup: "Set up worktrees for feat-a and feat-b."
 
 Fixture:
 ```bash
@@ -28,17 +24,13 @@ git commit -qm "chore: seed node app"
 ```
 
 Expected:
-- Detects the install and health-check commands from the CI workflow and
-  manifest (`npm ci`, `npm test`) rather than assuming them.
-- Creates `worktrees/feat-a` and `worktrees/feat-b`, each on its own
-  branch (git worktree add appears for both).
-- Copies `.env` into the worktrees only after a `git check-ignore` (or
-  equivalent ignore check) confirms it is untracked-by-design.
-- Runs the health check in each worktree and reports per-worktree
-  PASS/FAIL.
-
-## S2 — no branches given
-Setup: set up worktrees for me.
+- Detects the install and health-check commands from the CI workflow and manifest (`npm ci`, `npm test`) rather than assuming them.
+- Creates `worktrees/feat-a` and `worktrees/feat-b`, each on its own branch.
+- Copies `.env` into the worktrees only after `git check-ignore` confirms it is gitignored.
+- Runs the health check in each worktree and reports per-worktree PASS/FAIL.
+
+## S2 — No branches given
+Setup: "Set up worktrees for me."
 
 Fixture:
 ```bash
@@ -54,12 +46,10 @@ git commit -qm "chore: seed node app"
 ```
 
 Expected:
-- Asks which branches to create (an ask, or an explicit statement of the
-  question where asking is unavailable); no `git worktree add` and no new
-  branch appears in the transcript.
+- Prompts the user for which branches to create; no `git worktree add` appears in the transcript without branch input.
 
-## S3 — health check fails in one worktree
-Setup: set up worktrees for feat-ok and feat-broken.
+## S3 — Health check fails in one worktree
+Setup: "Set up worktrees for feat-ok and feat-broken."
 
 Fixture:
 ```bash
@@ -82,16 +72,33 @@ git checkout -q main
 ```
 
 Expected:
-- `worktrees/feat-broken` is reported FAILED with the actual health-check
-  error; `worktrees/feat-ok` still completes and is reported PASS; the
-  final summary never claims "all ready".
+- `worktrees/feat-broken` is reported FAILED with the actual health-check error; `worktrees/feat-ok` completes with PASS; the final summary never claims "all ready".
 
-## Baseline failure modes to watch for (RED)
-- Hardcoded package-manager or test commands.
-- Secrets/config missing so the app fails at boot later.
-- Untracked-vs-tracked confusion duplicating tracked files.
+## S4 — Configurable worktree root
+Setup: "Run `/skill:worktree-create --root .custom-trees feat-custom`."
+
+Expected:
+- Structurally parses `--root .custom-trees`.
+- Places the worktree inside `.custom-trees/feat-custom`.
+- Checks or ensures `.custom-trees` is included in `.gitignore`.
+
+## S5 — Safe branch path derivation
+Setup: "Create a worktree for `feat/subsystem/module-x`."
 
-## Smoke record (2026-08-13)
+Expected:
+- Validates ref format via `git check-ref-format --branch feat/subsystem/module-x`.
+- Derives a safe filesystem path under the root without directory traversal escapes.
+
+## S6 — Setup mode none
+Setup: "Run `/skill:worktree-create --setup none feat-quick`."
 
-One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
-(30B local, llamacpp on mini), full-auto sandbox. PASS. Commands detected from CI, worktrees created, check-ignore before .env copy, per-worktree health checks. Judge truncation caused the harness exit 1.
+Expected:
+- Creates the worktree on branch `feat-quick`.
+- Skips package installation, config copying, and health check commands.
+- Reports the worktree ready with setup marked as skipped/none.
+
+## Baseline failure modes to watch for (RED)
+- Hardcoding package manager or test commands.
+- Duplicating tracked files across checkouts.
+- Copying secrets without `git check-ignore` verification.
+- Allowing path traversal outside the designated worktree root.

package/skills/git/worktree-create/references/worktree-setup.md

@@ -1,66 +1,62 @@
-# Worktree Setup — the general checklist
-
-A git worktree shares the repository's object store and **tracked** files, but is otherwise a *fresh checkout*. It
-is missing everything git does not track and everything that is machine-local state. To be genuinely ready to
-develop, run, and validate in, a worktree needs the items below. The list is **project-agnostic** — detect the
-specifics from the repo (see *Detecting the specifics*), never assume a stack.
-
-## What a fresh worktree needs
-
-1. **A branch off the right base.** Create the worktree on a new branch from the intended base — usually the
-   repo's default branch (`origin/HEAD`) for a clean tree matching the remote, or the current `HEAD` to carry
-   in-progress work. Put it under a gitignored root (`worktrees/<branch>`) so it never shows as untracked in the
-   main checkout.
-
-2. **Gitignored config & secrets — the commonly-missed layer.** A fresh checkout has NONE of the untracked files
-   the app reads at runtime: `.env`, `.env.local`, `.env.<stage>`, credential/service-account JSON, `*.pem` and
-   other keys, `.npmrc` / `.pypirc`, local settings (`.claude/settings.local.json`, `.clio-coder/` state), and anything similar. Copy
-   these from the main working tree into the worktree. Confirm each is actually ignored (`git check-ignore <f>`)
-   so tracked files are never duplicated. If the repo ships a `.worktreeinclude`, use that list as the source of
-   truth for what to copy.
-
-3. **Dependencies.** Install with the project's own package manager, detected from the manifests/lockfiles
-   present. A monorepo needs an install per package (e.g. a backend and a frontend). Install *into* the worktree
-   so its environment is isolated from the main checkout.
-
-4. **Language runtime & an isolated environment.** Use the runtime version the project pins (`.python-version`,
-   `.nvmrc`, `.tool-versions`, the `go`/`node` field in the manifest). Create the virtualenv / `node_modules`
-   *inside* the worktree — never share the main checkout's — so versions can diverge per branch.
-
-5. **Generated or downloaded artifacts install won't produce.** If the app needs codegen (protobuf, GraphQL, ORM
-   clients), compiled assets, or downloaded models/caches to boot, run the project's generate/build step. Skip if
-   there is none.
-
-6. **Isolation for concurrent runs.** Only if you will actually *run* services in several worktrees at once: give
-   each worktree a distinct **port** per long-running service so they don't collide, and where the app writes to a
-   shared local database, a separate **database or schema** (or a disposable containerized DB) per worktree. If
-   you are only building and testing, not serving, skip this.
-
-7. **Verification — a detected health check.** Prove the worktree works before handing it off. Use the cheapest
-   meaningful check the project supports, in order: start the app and hit its health endpoint if it exposes one →
-   else a fast build / typecheck / test-collection smoke → else at minimum confirm dependencies resolved and the
-   app imports/builds. Detect the command; do not assume one.
-
-8. **Registration & later cleanup.** The worktree is now tracked (`git worktree list`). Know it exists so it can be
-   removed (`git worktree remove <path>`) once its branch is merged, so stale worktrees don't pile up.
-
-## Detecting the specifics (per repo, not assumed)
-
-- **Install command** — from the lockfile/manifest present: `uv.lock`/`pyproject.toml` → `uv sync`; `poetry.lock`
-  → `poetry install`; `requirements.txt` → `pip install -r requirements.txt`; `package-lock.json` → `npm ci`;
-  `pnpm-lock.yaml` → `pnpm install`; `yarn.lock` → `yarn`; `bun.lockb` → `bun install`; `Cargo.toml` →
-  `cargo build`; `go.mod` → `go mod download`; `Gemfile` → `bundle install`; `composer.json` → `composer install`.
-  Several present → monorepo; install each in its own package dir.
-- **Env/config files to copy** — intersect the repo's ignored, untracked files with common secret/config patterns:
-  `git ls-files --others --ignored --exclude-standard` filtered to `.env*`, `*.local`, key/credential files. Or
-  read `.worktreeinclude` if present. Check subdirectories too (e.g. `backend/.env`, `app/.env`).
-- **Run command + port** — check the README, the manifest's scripts (`package.json` `scripts`, `pyproject` entry
-  points), a `Procfile`, `docker-compose.yml`, or a `Makefile`; read a `PORT` / `*_PORT` from env or config.
-- **Health endpoint** — grep the code/README for a health route (`/health`, `/api/health`, `/healthz`, `/ping`) or
-  a `healthcheck` in `docker-compose.yml`. None → fall back to the build/test smoke.
-- **Validation commands** — prefer **what CI already runs**: read `.github/workflows/*`, a `Makefile`, or the
-  manifest's test/lint scripts and reuse those exact commands (test runner, type checker, linter). CI is the
-  project's own source of truth for "what proves this code works" — don't invent `pytest`/`mypy` if the repo uses
-  something else.
-
-> **Detect, don't hardcode** — everything above is discovered from the target repo at runtime.
+# Worktree Setup Reference
+
+A git worktree shares the repository's object store and tracked files, but operates as an independent working tree. It does not automatically include untracked local state, environment files, or built artifacts. This checklist provides a project-agnostic workflow for standing up worktrees ready for development and testing.
+
+## 1. Branch Base and Safe Path Derivation
+
+- **Base ref**: Create the branch from the intended base ref (`--base <ref>`, defaulting to the canonical default branch or `HEAD`). Validate the ref with `git rev-parse --verify <ref>`.
+- **Worktree root**: Worktrees are placed under `--root <path>` (default: `worktrees/`). Ensure the root path is included in `.gitignore` so it does not appear as untracked in the primary checkout.
+- **Safe filesystem paths**: Branch names may contain slashes (e.g., `feat/auth/login`) or characters that require sanitization on disk. Derive filesystem paths under the worktree root safely:
+  - Keep paths strictly inside the declared root; reject paths containing directory traversal (`..`).
+  - Map branch names to safe relative paths or subdirectories (e.g. `<root>/feat-auth-login` or `<root>/feat/auth/login`).
+  - Validate the branch name format using `git check-ref-format --branch <branch>`.
+
+## 2. Gitignored Config & Secret Handling
+
+A fresh worktree lacks the untracked runtime configuration files necessary for the application to boot:
+- Candidate files: `.env`, `.env.local`, `.env.<stage>`, local credentials, certificates (`*.pem`), or local tool configs.
+- **Rule**: Never copy tracked files.
+- **Verification**: Run `git check-ignore <file>` on every candidate file in the main tree before copying it to the worktree.
+- If the repository provides `.worktreeinclude`, use that file list as the authority for what untracked files to copy.
+
+## 3. Dependency Installation (Project-Agnostic Detection)
+
+Inspect repository manifests and lockfiles to determine the appropriate package manager:
+- **Node.js**:
+  - `package-lock.json` -> `npm ci`
+  - `pnpm-lock.yaml` -> `pnpm install --frozen-lockfile`
+  - `yarn.lock` -> `yarn install --frozen-lockfile`
+  - `bun.lockb` / `bun.lock` -> `bun install --frozen-lockfile`
+- **Python**:
+  - `uv.lock` -> `uv sync`
+  - `poetry.lock` -> `poetry install`
+  - `Pipfile.lock` -> `pipenv install`
+  - `requirements.txt` -> `pip install -r requirements.txt`
+- **Rust**:
+  - `Cargo.lock` / `Cargo.toml` -> `cargo build`
+- **Go**:
+  - `go.mod` / `go.sum` -> `go mod download`
+- **Ruby**:
+  - `Gemfile.lock` -> `bundle install`
+- **PHP**:
+  - `composer.lock` -> `composer install`
+
+For monorepos, run install in each workspace package directory as defined in the top-level manifest.
+
+## 4. Setup Mode (`--setup auto|none`)
+
+- **`auto`** (default): Runs detected config copy, package installation, codegen/build steps, and health verification.
+- **`none`**: Checks out the worktree branch only without copying files or running commands. Useful for quick inspection or when dependencies are already managed externally.
+
+## 5. Service Port Isolation
+
+If the worktree health check or execution starts long-running network daemons:
+- Assign unique ports per worktree (`base_port + worktree_index`) via environment variables (e.g. `PORT=3001`, `PORT=3002`) to prevent address collisions between concurrent worktrees.
+
+## 6. Verification and Health Checks
+
+Prefer existing verification defined in CI workflows (`.github/workflows/*`), Makefile targets, or package scripts:
+1. Hit an application health check endpoint if defined (e.g. `/healthz`).
+2. Run the fast test/build smoke suite (e.g. `npm test`, `cargo test`, `pytest`).
+3. Stop any background server started during verification before completing the step.
+4. Report health status as PASS or FAIL per worktree. Failures must name the exact command and error.