@iowarp/clio-coder 0.4.2 → 0.4.3

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.

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.

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

@@ -1,21 +1,22 @@
 ---
 name: worktree-merge
-description: Integrates finished worktree branches through one throwaway integration branch, testing after each merge and running the full suite before the main line moves, with exact rollback on failure. Not for creating worktrees; use worktree-create.
+description: Integrates finished worktree branches through one throwaway integration branch, testing after each merge and running the full suite before the main line moves, with exact rollback on failure. Not for creating worktrees; use worktree-create. Not for closeout; use branch-closeout.
 triggers:
   - merge my worktrees
   - integrate these worktree branches
   - combine parallel branches
   - land finished 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
   - 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/worktree-merge
@@ -31,70 +32,116 @@ clio-coder:
 
 # Worktree Merge
 
-Integrate finished branches through a disposable integration branch. The
-original branch moves only after every merge lands and the full suite
-passes; nothing reaches it red.
-
-## Step 1 — Inputs and preconditions
-
-- Fewer than two branches named → ask which to integrate; never guess.
-- Confirm you are at the repository root, not inside `worktrees/`
-  (`pwd` containing `/worktrees/` is an abort).
-- Store the current branch as `<original>`.
-- `git rev-parse --verify <branch>` for every branch in the list; any
-  missing branch aborts before anything is created.
-- Uncommitted changes on `<original>` → stop: commit or stash first.
-
-## Step 2 — Detect the validation commands ONCE
-
-Reuse exactly what CI runs: read `.github/workflows/*`, the Makefile, or
-the manifest's scripts for the test, type-check, and lint commands. Never
-substitute a generic runner for the project's own. Identify the fast test
-command (per-merge) and the full suite (final gate).
-
-## Step 3 — Integration branch
-
-Create one throwaway branch off `<original>`, named for the set
-(`integration-<first-branch>`, suffixed if needed, filesystem-safe). All
-merging happens here.
-
-## Step 4 — Merge each branch in order
-
-Per branch: `git merge --no-ff <branch>`, then run the fast test command,
-so a break is localized to the branch that caused it.
-
-- **Conflict** → stop. Name the conflicting branch and files, give the
-  resolution steps (resolve → `git add` → `git commit` → re-run with the
-  same list), and do not attempt automatic resolution.
-- **Test failure** → stop. Report which tests failed and the rollback:
-  `git checkout <original> && git branch -D <integration>`.
-
-## Step 5 — Full gate, then land
-
-All branches merged → run the full detected suite (tests, type checks,
-lint). Any failure: report and roll back as above. All green:
-`git checkout <original> && git merge --no-ff <integration>`, then delete
-the integration branch.
-
-## Step 6 — Offer cleanup
-
-Ask (via `ask_user` when active): remove the merged worktrees and delete
-their feature branches, or keep them? On yes, per branch:
-`git worktree remove worktrees/<branch> && git branch -d <branch>`. Never
-clean up without the answer.
+Integrate finished branches through a disposable integration branch. The target branch moves only after every branch integrates cleanly and the project's full validation suite passes; nothing reaches the main line broken.
+
+See [merge strategies](references/merge-strategies.md) for strategy mechanics (`merge`, `squash`, `ff`), rollback details, and protected base guards.
+
+## Arguments
+
+Arguments are passed in the user invocation message. Interpret them structurally from the prompt:
+
+```text
+/skill:worktree-merge [--into branch] [--strategy merge|squash|ff] [--cleanup ask|keep] <branch...>
+```
+
+### Examples
+- `/skill:worktree-merge feat-a feat-b`
+- `/skill:worktree-merge --into main --strategy squash feat/payments feat/invoicing`
+- `/skill:worktree-merge --strategy ff --cleanup keep feat/docs-update`
+
+### Positional Arguments
+- `<branch...>`: Two or more branch names to integrate in order (or at least one when integrating into a distinct target branch).
+  - Required. If fewer than the necessary branches are specified, prompt the user for the branch list; never guess.
+  - Validation: Verify each ref exists via `git rev-parse --verify <branch>`.
+
+### Options
+- `--into <branch>`: Target base branch receiving the merges.
+  - Default: the current branch at invocation time (`<original>`).
+  - Validation: Must be a verified local branch.
+- `--strategy <merge|squash|ff>`: Git integration strategy.
+  - `merge` (default): Uses `git merge --no-ff <branch>` to preserve commit topology.
+  - `squash`: Uses `git merge --squash <branch>`, followed by an atomic conventional commit.
+  - `ff`: Uses `git merge --ff-only <branch>`. Fails if the branch has diverged.
+- `--cleanup <ask|keep>`: Post-integration scaffolding cleanup policy.
+  - `ask` (default): Prompt the user via `ask_user` before removing worktrees or deleting branches.
+  - `keep`: Retain all source worktrees and branches after integration.
+
+### Unknown Arguments and Ref Validation
+- Unknown flags must be rejected with an error. Validate all branch names before creating integration branches. Never interpolate unvalidated user input into shell strings without safe quoting.
+
+## Step 1 — Preconditions and Base Guards
+
+1. Verify working directory is the repository root (fail if currently inside a worktree directory).
+2. Record current branch as `<into>` (or use `--into <branch>`).
+3. Verify no uncommitted changes exist on `<into>`. If dirty, STOP: commit or stash first.
+4. **Base Guard**: Check if `<into>` is a protected or canonical default branch. In canonical-main-only repositories (such as `CONTRIBUTING.md`), maintainer integration is strictly local; never push integration or topic branches to the canonical remote.
+5. Verify every branch in `<branch...>` with `git rev-parse --verify <branch>`. Any missing branch aborts the run before anything is created.
+
+## Step 2 — Detect Validation Commands Once
+
+Detect the project's test and validation suite per repository manifests and CI workflows (`.github/workflows/*`, Makefile, npm scripts):
+- **Fast test command**: run immediately after each branch merge to localize failures.
+- **Full validation suite**: run after all branches have merged (unit tests, typecheck, lint).
+
+## Step 3 — Stand Up Disposable Integration Branch
+
+Create a disposable integration branch off `<into>`:
+```bash
+git checkout -b integration-<first-branch> <into>
+```
+All integration and intermediate test runs occur exclusively on this branch.
+
+## Step 4 — Merge Each Branch in Order
+
+For each branch in `<branch...>`:
+1. Apply the specified `--strategy`:
+   - **`merge`**: `git merge --no-ff <branch>`
+   - **`squash`**: `git merge --squash <branch> && git commit -m "feat: squash <branch>"`
+   - **`ff`**: `git merge --ff-only <branch>`
+2. **Conflict**: STOP immediately. Name conflicting branch and files, report manual resolution steps, and do not attempt automatic resolution.
+3. **Run fast test command**:
+   - If tests fail: STOP immediately. Localize the failure to this branch and execute exact rollback:
+     ```bash
+     git checkout <into> && git branch -D integration-<first-branch>
+     ```
+   - Report the breaking branch, test failures, and that `<into>` remains untouched.
+
+## Step 5 — Full Gate, Land, and Rollback Safety
+
+1. Once all branches are merged, run the full validation suite (tests, typecheck, lint).
+2. If any check fails: report failures and execute rollback as in Step 4.
+3. If all checks pass:
+   - Land integration branch into `<into>`:
+     ```bash
+     git checkout <into>
+     git merge --no-ff integration-<first-branch>
+     ```
+   - Delete the disposable integration branch: `git branch -d integration-<first-branch>`.
+
+## Step 6 — Cleanup Scaffolding
+
+If `--cleanup ask` is active, prompt the user via `ask_user` whether to clean up the merged branches and worktrees:
+- On approval, delegate to or execute `branch-closeout`:
+  - Locate registered worktree paths via `git worktree list --porcelain`.
+  - Inspect tracked and untracked worktree state.
+  - Remove worktrees with `git worktree remove` (never `rm -rf`).
+  - Delete local source branches with `git branch -d`.
+  - Audit and report surviving worktrees, local branches, and remote heads.
+- If `--cleanup keep` is active, leave worktrees and branches intact.
 
 ## Step 7 — Report
 
-Success: integration branch used, each branch with its post-merge test
-result, the full-gate result, the merge into `<original>`, cleanup status
-(with manual commands if kept). Failure: the exact step and branch, current
-state, rollback commands, and how to continue after fixing. Done when one
-of those two reports is delivered and the repo is on `<original>`.
+Deliver a comprehensive completion report:
+- Strategy used (`merge`, `squash`, or `ff`)
+- Per-branch fast test outcomes
+- Full gate results
+- Merge commit SHA on `<into>`
+- Cleanup status and inventory of remaining local refs
 
-## Red flags
+## Red Flags
 
-- Merging directly into `<original>` "to save a step".
-- Running a guessed test command instead of the repo's own.
-- Auto-resolving conflicts.
-- Deleting worktrees or branches nobody approved.
-- A red full gate absorbed into "mostly passing".
+- Merging directly into `<into>` without a disposable integration branch.
+- Auto-resolving conflicts without user intervention.
+- Skipping the fast test between merges, losing failure localization.
+- Deleting worktrees or branches when `--cleanup keep` was passed or without confirmation.
+- Pushing integration or topic branches to a canonical-main-only remote.