@iowarp/clio-coder 0.4.2 → 0.4.4

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.

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

@@ -1,12 +1,9 @@
 # Evals — worktree-merge
 
-Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
-bullet. Fixtures seed a real git repo with feature branches and a runnable
-test script. 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 — clean two-branch integration
-Setup: merge my worktree branches feat-a and feat-b.
+## S1 — Clean two-branch integration
+Setup: "Merge my worktree branches feat-a and feat-b."
 
 Fixture:
 ```bash
@@ -32,17 +29,13 @@ git checkout -q main
 ```
 
 Expected:
-- Detects the test command from the manifest (`npm test` / `node test.js`)
-  rather than assuming one.
-- Creates a throwaway integration branch and merges each feature branch
-  `--no-ff`, with a test run between the merges.
-- Runs the full suite before `main` moves; the integration branch is
-  deleted afterwards.
-- Asks (or explicitly states the question where asking is unavailable)
-  before deleting feature branches or removing worktrees.
-
-## S2 — conflicting branches
-Setup: merge my worktree branches feat-a and feat-b.
+- Detects the test command from manifest (`npm test` / `node test.js`).
+- Creates a throwaway integration branch and merges each feature branch `--no-ff`, with tests between.
+- Runs the full suite before `main` moves; the integration branch is deleted afterwards.
+- Prompts user before deleting feature branches or removing worktrees.
+
+## S2 — Conflicting branches
+Setup: "Merge my worktree branches feat-a and feat-b."
 
 Fixture:
 ```bash
@@ -67,13 +60,12 @@ git checkout -q main
 ```
 
 Expected:
-- Stops at the conflict on the integration branch; names the conflicting
-  branch and `shared.txt`; gives manual resolution steps.
-- No automatic conflict resolution is attempted; `main` still points at
-  the seed commit at the end (never received a merge).
+- Stops at the conflict on the integration branch; names conflicting branch and `shared.txt`.
+- No automatic conflict resolution is attempted.
+- `main` remains at seed commit (never received a merge).
 
-## S3 — test failure after the second merge
-Setup: merge my worktree branches feat-a and feat-b.
+## S3 — Test failure after second merge
+Setup: "Merge my worktree branches feat-a and feat-b."
 
 Fixture:
 ```bash
@@ -98,17 +90,33 @@ git checkout -q main
 ```
 
 Expected:
-- The test failure is localized to feat-b (feat-a's merge tested green
-  first); the report names feat-b as the breaking branch.
-- Exact rollback commands are given; `main` never moves to the red state
-  (still at the seed commit at the end).
+- Test failure is localized to `feat-b` (`feat-a` tested green first).
+- Exact rollback is executed; `main` never receives the broken commit.
 
-## Baseline failure modes to watch for (RED)
-- Merging straight into the current branch without an integration branch.
-- Skipping the per-merge test run, losing failure localization.
-- Cleanup without asking.
+## S4 — Squash integration strategy
+Setup: "Run `/skill:worktree-merge --strategy squash feat-a feat-b`."
+
+Expected:
+- Uses `git merge --squash` on the integration branch for each feature.
+- Commits each squashed change with a conventional message.
+- Lands on `<into>` with clean squashed history.
+
+## S5 — Fast-forward integration strategy
+Setup: "Run `/skill:worktree-merge --strategy ff feat-linear`."
 
-## Smoke record (2026-08-13)
+Expected:
+- Uses `git merge --ff-only` on the integration branch.
+- Fails with explicit error if the branch is not a fast-forward of `<into>`.
+
+## S6 — Cleanup keep mode
+Setup: "Run `/skill:worktree-merge --cleanup keep feat-a feat-b`."
 
-One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
-(30B local, llamacpp on mini), full-auto sandbox. PASS. Integration branch, --no-ff merges with tests between. Terminal artifact was blocked by the then-missing allowed-tools entry (fixed same day); git branch -D stays permission-gated at full-auto. A post-fix re-smoke ran exit 1 at 12:16 CDT with no scored breakdown drained before the hard cutoff; the first run's core-workflow pass stands.
+Expected:
+- After successful integration into `<into>`, does not remove worktrees or delete feature branches.
+- Reports surviving branches and worktrees intact.
+
+## Baseline failure modes to watch for (RED)
+- Merging directly into target base without a disposable integration branch.
+- Skipping the per-merge test run.
+- Auto-resolving conflicts.
+- Deleting branches when `--cleanup keep` was specified.

package/skills/git/worktree-merge/references/merge-strategies.md

@@ -0,0 +1,52 @@
+# Merge Strategies and Integration Architecture
+
+This reference outlines integration strategies, throwaway branch lifecycles, and protected base guards for `worktree-merge`.
+
+## 1. Supported Integration Strategies
+
+| Strategy | Flag / Command | When to Use | Ancestry Behavior |
+|---|---|---|---|
+| `merge` (default) | `git merge --no-ff <branch>` | Multi-commit features where history and branch topology should be explicitly preserved. | Direct ancestor; `git merge-base --is-ancestor` passes. |
+| `squash` | `git merge --squash <branch>` | Features with exploratory commits, fixups, or noisy history that should land as one atomic commit. | Not a direct ancestor; commit SHA and patch change. Closeout requires PR/commit evidence. |
+| `ff` | `git merge --ff-only <branch>` | Clean, linear history where the feature branch was rebased onto `<into>` and no merge commit is desired. | Direct ancestor; `<into>` moves pointer to branch tip. Fails if diverged. |
+
+## 2. Disposable Integration Branch Lifecycle
+
+Never merge directly into the target base branch (`<into>`, e.g. `main` or `release-candidate`) while testing individual branches. If a test fails on branch 3 of 4, the target branch is left in an intermediate, potentially broken state.
+
+### Execution Pattern
+1. Create disposable branch off `<into>`:
+   ```bash
+   git checkout -b integration-<first-branch> <into>
+   ```
+2. Integrate each branch sequentially using 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>`
+3. Run fast tests immediately after each branch is merged. If tests fail:
+   - Abort integration and roll back:
+     ```bash
+     git checkout <into>
+     git branch -D integration-<first-branch>
+     ```
+   - Report the exact branch that broke the build.
+4. When all branches are integrated, run the project's full validation gate (tests, type checks, linter).
+5. Only after all checks pass, land the integration branch into `<into>`:
+   - If `merge` strategy was used: `git checkout <into> && git merge --no-ff integration-<first-branch>`
+   - If `squash` strategy was used: `git checkout <into> && git merge --ff-only integration-<first-branch>`
+   - If `ff` strategy was used: `git checkout <into> && git merge --ff-only integration-<first-branch>`
+6. Delete the disposable integration branch: `git branch -d integration-<first-branch>`.
+
+## 3. Protected Base Guards
+
+- If `<into>` is the canonical default branch (`main`/`master`) or a release branch:
+  - Check repository instructions (`CONTRIBUTING.md`). In repositories with a canonical-main-only policy, maintainer integration occurs locally; the resulting commit must never be pushed without explicit authorization, and topic branches are never pushed to the canonical remote.
+  - Verify that `<into>` matches the intended target before landing.
+  - If `<into>` has moved upstream during the merge, fetch and re-verify before finalizing.
+
+## 4. Integration Proof Before Closeout
+
+Before offering to delete source branches or remove worktrees:
+- For `merge` and `ff`: Verify `git merge-base --is-ancestor <branch> <into>`.
+- For `squash`: Verify the squashed commit containing the changes is present on `<into>` (`git log --grep="<branch>" <into>` or diff comparison).
+- Once proved, delegate cleanup to `branch-closeout` or prompt the user.