@iowarp/clio-coder 0.4.1 → 0.4.3

package/skills/git/resolve-merge-conflicts/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: resolve-merge-conflicts
-description: Use when a git merge, rebase, or cherry-pick is stopped on conflicts and they need resolving — "fix these conflicts", "finish the merge", conflict markers in files. Resolves by reconstructing both sides' intent from history, preserves both where possible, validates with the project's own checks, and completes the operation. Not for planning an integration of many branches; use worktree-merge.
+description: Resolves a merge, rebase, or cherry-pick stopped on conflicts by reconstructing both sides' intent, validating with the project's own checks, and completing the operation. Not for integrating many branches; use worktree-merge.
 triggers:
   - merge conflict
   - fix these conflicts
   - finish the merge
   - finish the rebase
   - resolve conflict markers
-version: 0.2.1
+version: 0.4.0
 license: Apache-2.0
+compatibility: git >=2.30.0, POSIX-compatible shell
 allowed-tools:
   - read
   - grep
@@ -16,8 +17,10 @@ allowed-tools:
   - git
   - bash
   - edit
+  - write
+  - verify
+  - tasks
   - ask_user
-  - artifact
 clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/git/resolve-merge-conflicts
@@ -34,69 +37,115 @@ clio-coder:
 
 # Resolve Merge Conflicts
 
-Conflicts are resolved from intent, not from picking the side that makes
-the markers go away. The job ends with the merge or rebase completed and
-the project's checks green.
+Resolve conflicts stopped during a merge, rebase, or cherry-pick from intent, not from picking whichever side makes markers disappear. The job ends with the operation completed and the project's validation checks green.
 
-## Step 1 — Map the state
+See [conflict matrix](references/conflict-matrix.md) for operation detection, the rebase ours/theirs reversal, and resolution patterns across conflict types (content, modify/delete, rename, binary, submodule, and lockfiles).
 
-```bash
-git status
-git log --oneline --left-right --merge 2>/dev/null || git log --oneline -10
-git diff --name-only --diff-filter=U
-```
+## Arguments
 
-Identify: which operation is in progress (merge, rebase, cherry-pick),
-which branches or commits are involved, and every conflicting file.
+Arguments are passed in the user invocation message. Interpret them structurally from the prompt:
 
-## Step 2 — Reconstruct both intents
-
-For each conflicting file, find why each side changed:
+```text
+/skill:resolve-merge-conflicts [--checks auto|command] [--continue|--no-continue]
+```
 
+### Examples
+- `/skill:resolve-merge-conflicts`
+- `/skill:resolve-merge-conflicts --checks "npm test"`
+- `/skill:resolve-merge-conflicts --no-continue`
+
+### Options
+- `--checks <auto|command>`: Validation checks execution mode.
+  - `auto` (default): Detects and runs test, typecheck, and lint commands from the repository (CI workflows, Makefile, package manifests).
+  - `<command>`: Custom shell command to run for verification (e.g. `npm test`, `cargo check`).
+- `--continue|--no-continue`: Whether to complete the in-flight operation after resolution and validation.
+  - `--continue` (default): Runs the operation's continue command (`git merge --continue`, `git rebase --continue`, or `git cherry-pick --continue`).
+  - `--no-continue`: Leaves resolved files staged in the index and stops without executing the continue command.
+
+### Unknown Arguments and Safe Execution
+- Unknown flags must be rejected with an error. Never interpolate untrusted user text into shell execution without proper quoting.
+
+## Step 1 — Map the State and Operation
+
+> [!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.
+
+Identify the in-flight operation per [conflict matrix](references/conflict-matrix.md):
+- **Merge**: `.git/MERGE_HEAD` exists. `HEAD` is ours (target branch), `MERGE_HEAD` is theirs (incoming branch).
+- **Rebase**: `.git/rebase-merge` or `.git/rebase-apply` exists.
+  > [!WARNING]
+  > In `git rebase`, `--ours` and `--theirs` are **reversed**!
+  > - `HEAD` ("ours") is the upstream branch being rebased onto.
+  > - `REBASE_HEAD` ("theirs") is your branch commit being replayed.
+- **Cherry-pick**: `.git/CHERRY_PICK_HEAD` exists. `HEAD` is target branch, `CHERRY_PICK_HEAD` is commit being cherry-picked.
+
+Query all unmerged paths:
 ```bash
-git log --oneline <ours>..<theirs> -- <file>
-git log --oneline <theirs>..<ours> -- <file>
+git diff --name-only --diff-filter=U
 ```
 
-Read the commit messages; follow PR or issue references when the message
-alone does not explain the change. A hunk resolved without knowing both
-sides' intent is a guess wearing a merge commit.
-
-## Step 3 — Resolve each hunk
+## Step 2 — Reconstruct Both Intents
+
+For each conflicting file, determine why each side modified the code:
+- Check commit logs:
+  ```bash
+  # In merge:
+  git log --oneline HEAD..MERGE_HEAD -- <file>
+  git log --oneline MERGE_HEAD..HEAD -- <file>
+  # In rebase:
+  git log -1 REBASE_HEAD -- <file>
+  ```
+- Read commit messages and linked issue references. A resolution without understanding both intents is an ungrounded guess.
+
+## Step 3 — Resolve Each Conflict by Type
+
+Handle each file according to its conflict class:
+- **Content conflict markers**: Preserve both changes if compatible (e.g. non-overlapping functions or independent parameters). If incompatible, select the change aligned with the operation goal, or prompt the user via `ask_user`. Verify no markers remain:
+  ```bash
+  grep -rn "<<<<<<<\|>>>>>>>" <files>
+  ```
+- **Add / Add**: Merge file contents if same concept, or rename if distinct concepts.
+- **Modify / Delete**: Trace whether deletion was deliberate refactoring or accidental; preserve or remove accordingly.
+- **Rename**: Follow renamed files and integrate changes into the canonical filename.
+- **Binary files**: Check out appropriate version (`git checkout --ours` / `--theirs`) or rebuild asset from source.
+- **Submodules**: Resolve submodule commit pointer via `git diff --submodule` and submodule history.
+- **Lockfiles**: Do not manually resolve JSON/YAML markers in package lockfiles. Re-derive them via the package manager (`npm install --package-lock-only`, `pnpm install --lockfile-only`, `cargo check`, `uv lock`).
+
+Stage resolved files: `git add <files>`.
 
-- Both intents compatible → preserve both.
-- Genuinely incompatible → pick the side matching the merge's stated goal
-  and record the trade-off for the report; when the goal itself does not
-  decide it, ask the user rather than choosing silently.
-- Never invent new behavior in a resolution: the merged code does only
-  what one or both sides already did.
-- Do not `--abort` to escape a hard conflict; abort only if the user
-  decides the operation itself was wrong.
+## Step 4 — Validate
 
-Search for leftover markers before moving on:
-`grep -rn "<<<<<<<\|>>>>>>>" <conflicting files>` must return nothing.
+Run the validation suite determined by `--checks`:
+- If `auto`: execute detected typecheck, tests, and linter.
+- If `<command>`: execute the specified validation command.
+- If any check fails, fix regressions caused by the resolution before proceeding.
 
-## Step 4 — Validate
+## Step 5 — Complete Operation or Multi-Stop Loop
 
-Discover the project's own checks (CI workflow, manifest scripts,
-Makefile) and run them: typecheck, then tests, then lint/format. Fix
-anything the merge broke — the resolution is not done at "markers gone",
-it is done at "checks green".
+If `--no-continue` was specified:
+- Report that all conflicts are resolved and files are staged; stop here.
 
-## Step 5 — Complete the operation
+If `--continue` is active (default):
+- Execute the operation-specific continue command:
+  - **Merge**: `git merge --continue` (or `git commit`)
+  - **Rebase**: `git rebase --continue`
+  - **Cherry-pick**: `git cherry-pick --continue`
+- **Multi-stop rebases**: If git stops on a subsequent commit conflict, loop back to Step 1 and repeat until the rebase completes.
+- **Operation Abort**: If the user decides the operation is invalid or if unresolvable contradictions occur, run the operation-specific abort command (`git merge --abort`, `git rebase --abort`, or `git cherry-pick --abort`) and verify the tree returns to clean pre-operation state.
 
-Stage the resolved files and commit the merge; for a rebase or
-cherry-pick, `git rebase --continue` / `git cherry-pick --continue` and
-repeat from Step 1 for each further stop until the operation reports
-complete.
+## Step 6 — Report
 
-Done when the operation has fully finished, checks are green, and the
-report lists each conflict with which intent(s) survived and any recorded
-trade-offs.
+Summarize:
+- Completed operation type (merge, rebase, cherry-pick)
+- Each conflicting file, conflict type, and how intent was resolved
+- Validation checks run and real outputs
+- Current branch status and clean working tree verification
 
-## Red flags
+## Red Flags
 
-- Taking `--ours`/`--theirs` wholesale without reading either side.
-- A resolution that introduces logic neither side had.
-- Committing with conflict markers still in a file.
-- Declaring done without running the project's checks.
+- Taking `--ours` or `--theirs` wholesale without reading both sides.
+- Inverting intent during a rebase by misunderstanding reversed ours/theirs semantics.
+- Hand-editing conflict markers in binary files or complex lockfiles.
+- Leaving `<<<<<<<` or `>>>>>>>` markers in any committed file.
+- Declaring done without running validation checks.
+- Executing an abort without user instruction.

package/skills/git/resolve-merge-conflicts/evals.md

@@ -1,12 +1,9 @@
 # Evals — resolve-merge-conflicts
 
-Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
-bullet. Status: written at port time, not yet executed (`eval-status:
-untested`).
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per bullet. Status: `eval-status: smoke-checked`.
 
-## S1 — compatible two-sided conflict
-Setup: the merge of feat-rename stopped on a conflict in util.js. Resolve
-it and finish the merge.
+## S1 — Compatible two-sided conflict
+Setup: the merge of feat-rename stopped on a conflict in util.js. Resolve it and finish the merge.
 
 Fixture:
 ```bash
@@ -28,31 +25,61 @@ git merge feat-rename > merge-output.txt 2>&1 || true
 ```
 
 Expected:
-- Reads both sides' history (log/show on main and feat-rename) before
-  touching the file.
-- Resolution preserves both intents: the function is named findUser and
-  getUserName calls findUser.
-- The merge is committed and no conflict markers remain in util.js.
+- Reads both sides' history (log/show on main and feat-rename) before editing.
+- Resolution preserves both intents: the function is named `findUser` and `getUserName` calls `findUser`.
+- The merge is committed and no conflict markers remain in `util.js`.
 
-## S2 — incompatible conflict
+## S2 — Incompatible conflict
 Setup: both sides changed the same default to different values.
+
+Expected:
+- Identifies the incompatibility. Picks per the merge's stated goal or prompts the user; trade-off recorded in the report.
+
+## S3 — Mid-rebase, multiple stops
+Setup: a rebase is stopped on its first conflict with more commits still to replay; resolve and finish the whole rebase.
+
 Expected:
-- Picks per the merge's stated goal, or asks when the goal doesn't decide;
-  trade-off recorded in the report.
+- Correctly treats `HEAD` as upstream target and `REBASE_HEAD` as incoming replayed commit (recognizes reversed ours/theirs).
+- Continues the rebase with `git rebase --continue` across multiple stops until complete.
+- Runs validation checks at completion.
+
+## S4 — Binary file conflict
+Setup: merge conflict on a binary asset (e.g. `logo.png`).
+
+Expected:
+- Detects binary conflict (no text conflict markers present).
+- Determines intended version and resolves using `git checkout --ours` or `git checkout --theirs`.
+- Stages binary asset with `git add logo.png`.
+
+## S5 — Modify/delete conflict
+Setup: one branch modified `helper.js`, the other deleted it.
 
-## S3 — mid-rebase, multiple stops
-Setup: a rebase is stopped on its first conflict with more commits still to
-replay; resolve and finish the whole rebase.
 Expected:
-- Continues the rebase after each resolution until complete; validates at
-  the end.
+- Checks git status for `CONFLICT (modify/delete)`.
+- Inspects the commit that deleted the file to determine if deletion was intentional.
+- Resolves by either staging the file (`git add helper.js`) or completing the deletion (`git rm helper.js`).
+
+## S6 — Operation-specific abort behavior
+Setup: user requests aborting an in-flight rebase or merge.
+
+Expected:
+- For merge: invokes `git merge --abort`.
+- For rebase: invokes `git rebase --abort`.
+- Verifies working tree returns to clean pre-operation state.
+
+## S7 — No-continue flag
+Setup: user runs `/skill:resolve-merge-conflicts --no-continue`.
+
+Expected:
+- Resolves all conflict markers and stages resolved files with `git add`.
+- Does not run `git merge --continue` or `git rebase --continue`.
+- Reports files staged and ready for user inspection.
 
 ## Baseline failure modes to watch for (RED)
-- `checkout --theirs` on everything to make it compile.
-- Invented "compromise" behavior neither side had.
-- `--abort` at the first hard hunk.
+- Running `git checkout --theirs` on everything to make markers go away.
+- Inverting intent during a rebase due to ours/theirs reversal.
+- Leaving conflict markers in files.
+- Running generic abort when resolution is achievable.
 
 ## Smoke record (2026-08-13)
-
-One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
-(30B local, llamacpp on mini), full-auto sandbox. PASS. Both sides' history read; both intents preserved; merge committed, no markers.
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning (30B local, llamacpp on mini), full-auto sandbox. PASS. Both sides' history read; both intents preserved; merge committed, no markers.

package/skills/git/resolve-merge-conflicts/references/conflict-matrix.md

@@ -0,0 +1,126 @@
+# Conflict Matrix and Resolution Reference
+
+This reference documents operation detection, ours/theirs orientations, conflict types, and operation-specific resolution workflows for `resolve-merge-conflicts`.
+
+## 1. Operation State Detection
+
+Determine which git operation is currently paused on conflicts:
+
+| Indicator | Operation | Current (`HEAD` / "ours") | Incoming ("theirs") | Abort Command | Continue Command |
+|---|---|---|---|---|---|
+| `.git/MERGE_HEAD` exists | **Merge** | Target branch receiving merge | Source branch being merged in | `git merge --abort` | `git merge --continue` (or `git commit`) |
+| `.git/rebase-merge` or `.git/rebase-apply` exists | **Rebase** | **Upstream branch** being rebased onto | **Your topic commit** being replayed | `git rebase --abort` | `git rebase --continue` |
+| `.git/CHERRY_PICK_HEAD` exists | **Cherry-pick** | Target branch receiving commit | Commit being cherry-picked | `git cherry-pick --abort` | `git cherry-pick --continue` |
+| `.git/REVERT_HEAD` exists | **Revert** | Current branch | Commit being reverted | `git revert --abort` | `git revert --continue` |
+
+### The Rebase "Ours / Theirs" Reversal Trap
+
+> [!WARNING]
+> In `git rebase`, `--ours` and `--theirs` are **reversed** compared to `git merge`!
+> - `--ours` refers to the upstream target branch you are rebasing onto.
+> - `--theirs` refers to the original topic branch commit that is being replayed.
+> Failing to account for this inversion causes accidental reversion of your own changes.
+
+To inspect intent without relying on relative terms:
+```bash
+# During merge:
+git log --oneline HEAD...MERGE_HEAD
+
+# During rebase:
+# Check the commit currently being applied:
+git log -1 REBASE_HEAD 2>/dev/null || cat .git/rebase-merge/stopped-sha
+```
+
+## 2. Conflict Types and Handling
+
+### A. Content Conflicts (Conflict Markers)
+Files contain `<<<<<<<`, `=======`, `>>>>>>>` markers.
+1. Read commit history for both sides to understand why each line changed.
+2. If both changes are compatible (e.g. adjacent methods, distinct properties), preserve both.
+3. If incompatible, choose the change aligned with the operation goal or prompt user for decision.
+4. Verify markers are gone: `grep -rn "<<<<<<<\|>>>>>>>" <files>` must return zero matches.
+
+### B. Add / Add Conflicts
+Both branches added a file at the same path with different contents.
+1. Inspect both versions:
+   ```bash
+   git show :2:path/to/file  # ours
+   git show :3:path/to/file  # theirs
+   ```
+2. Determine if the files represent the same concept or a naming collision.
+3. If distinct concepts, rename one file and adjust imports. If same concept, merge contents and stage with `git add path/to/file`.
+
+### C. Modify / Delete Conflicts
+One branch modified a file while the other deleted it.
+- Git status reports: `CONFLICT (modify/delete): file deleted in <side> and modified in <other>`.
+- To keep the modified file:
+  ```bash
+  git add path/to/file
+  ```
+- To delete the file:
+  ```bash
+  git rm path/to/file
+  ```
+- Always inspect the commit that deleted the file (`git log -n 5 -- <file>`) to confirm whether the deletion was intentional refactoring or an accidental deletion.
+
+### D. Rename Conflicts
+Git detects: `CONFLICT (rename/rename)`, `CONFLICT (rename/delete)`, or `CONFLICT (rename/modify)`.
+1. Inspect rename targets using `git status` and `git log`.
+2. Consolidate modifications into the intended canonical filename.
+3. Remove stale files with `git rm` and stage the consolidated file with `git add`.
+
+### E. Binary File Conflicts
+Binary files (images, compiled archives, model checkpoints) cannot contain text conflict markers.
+1. Determine which binary is required:
+   ```bash
+   # Select current branch version
+   git checkout --ours -- path/to/binary
+   # Or select incoming version
+   git checkout --theirs -- path/to/binary
+   ```
+2. Or regenerate the binary from source assets if applicable.
+3. Stage with `git add path/to/binary`.
+
+### F. Submodule Conflicts
+Submodule conflict occurs when both sides updated the submodule pointer to different commit SHAs.
+1. Inspect the two submodule pointers:
+   ```bash
+   git diff --submodule
+   ```
+2. Enter submodule directory and check which commit is the ancestor or latest intended state:
+   ```bash
+   cd path/to/submodule && git merge-base --is-ancestor <sha1> <sha2>
+   ```
+3. Check out the resolved commit in the submodule, return to parent repository, and stage with `git add path/to/submodule`.
+
+### G. Generated Files and Lockfiles
+Never attempt manual string edits on complex lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `Cargo.lock`, `uv.lock`, `poetry.lock`).
+1. Check out the base version or let package manager re-derive resolutions:
+   - Node (npm): `npm install --package-lock-only`
+   - Node (pnpm): `pnpm install --lockfile-only`
+   - Rust: `cargo check` (updates Cargo.lock)
+   - Python (uv): `uv lock`
+2. Stage the regenerated lockfile with `git add`.
+
+## 3. Multi-Stop Rebase Workflow
+
+When rebasing a series of commits, conflicts may occur at multiple commits:
+1. **Loop**:
+   - Inspect stopped commit and conflicting files.
+   - Reconstruct intent and resolve each conflict.
+   - Run validation checks (or fast tests).
+   - Stage all resolved files: `git add <files>`.
+   - Run `git rebase --continue`.
+2. **Next State**:
+   - If another conflict arises, repeat the loop.
+   - If the commit becomes empty (because changes were already incorporated upstream), use `git rebase --skip` only after verifying changes exist upstream.
+3. **Completion**:
+   - Once all commits are replayed, run the full validation suite.
+
+## 4. Operation Abort Handling
+
+If conflicts cannot be resolved, or if the user requests aborting:
+- **Merge**: `git merge --abort`
+- **Rebase**: `git rebase --abort`
+- **Cherry-pick**: `git cherry-pick --abort`
+- Verify working tree is clean with `git status`.

package/skills/git/ship/SKILL.md

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

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

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