@iowarp/clio-coder 0.4.1 → 0.4.3

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

@@ -1,21 +1,22 @@
 ---
 name: worktree-merge
-description: Use when parallel worktree branches are finished and the user asks to integrate them — "merge my worktrees", "integrate these branches". Merges any number of branches through one throwaway integration branch, testing after each merge, running the full detected suite before the main line moves, with exact rollback on any 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.2.1
+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.

package/skills/meta/clio-coder-dev/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: clio-coder-dev
-description: Use when modifying Clio Coder's own source in this repository, evolving its harness (TUI, skills, agents, tools, prompts, domains), or deciding whether a change stays local versus becomes a contribution. Governs self-development — what Clio may change freely, what requires explicit user intent, and how to make a change without breaking the architecture.
+description: "Governs changes to Clio Coder's own source and harness (TUI, skills, agents, tools, prompts, domains): what may change freely, what needs explicit user intent, and how to change it without breaking the architecture. Not for verifying a change against the harness; use clio-coder-test."
 triggers:
   - modify Clio Coder
   - change the Clio harness
   - edit Clio skills or agents
   - evolve Clio tools or prompts
   - Clio contribution boundary
-version: 0.2.2
+version: 0.4.0
 license: Apache-2.0
 clio-coder:
   registry-id: iowarp/clio-coder
@@ -72,9 +72,13 @@ Follow in order for every change:
 3. **Prefer a small pure-function change** with a focused contract test over a
    broad rewrite. Side effects live in `extension.ts`; testable policy lives
    in sibling pure modules.
-4. **Respect the hard invariants** (rule1/2/3): no value-import of `pi-*`
-   outside `src/engine/**`; no importing another domain's `extension.ts`; the
-   worker never imports domains. Add or reuse a contract instead.
+4. **Respect all six boundary invariants.** Pi SDK imports stay in
+   `src/engine/**`; worker value imports from domains stay within the declared
+   provider rehydration seams; domains never import another domain's
+   `extension.ts`; tools never import the interactive layer;
+   `src/interactive/turn-*.ts` and `chat-loop.ts` never import entry modules;
+   Stage 0 is entered only through declared seams. Add or reuse a contract
+   instead.
 5. **Validate narrowly, then report.** Run the narrowest meaningful layer per
    `clio-coder-test`, then state exactly what ran and what remains unverified. Done
    when the report names both.

package/skills/meta/clio-coder-dev/evals.md

@@ -26,13 +26,14 @@ Prompt: "Domain A needs something from domain B — just import B's extension.ts
 it's faster."
 Expected:
 - Refuses the rule3 violation; routes through B's `index.ts` contract.
-- Defers to `clio-coder-test` (`check:boundaries`) to verify.
+- Defers to `clio-coder-test` and runs `npm run lint` to verify the boundary.
 
 ## D4 — classify before editing
 Prompt: "Change how the worker gets its spec." (touches an engine/worker seam)
 Expected:
 - Classifies the surface, inspects the contract/tests first, prefers a small
-  pure change, and respects rule2 (worker never imports domains).
+  pure change, and respects rule2 (worker value imports from domains stay in
+  the declared provider rehydration seams; other domain imports are type-only).
 
 ## Baseline failure modes to watch for (RED)
 - Pushes / opens a PR / tags a release on implied (not explicit) intent.