@iowarp/clio-coder 0.4.2 → 0.4.3

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: "Ships finished work: stages reviewed paths, writes one atomic conventional commit referencing the issue, then pushes and opens the PR only on explicit intent. 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.2.0
+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 #

package/skills/git/ship/evals.md

@@ -1,13 +1,9 @@
 # Evals — ship
 
-Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
-bullet. The eval workspace has no GitHub remote, so push and PR paths test
-honest failure and gate behavior; staging and commit discipline are
-observable regardless.
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per bullet. Status: `eval-status: smoke-checked`.
 
-## S1 — commit only, mixed tree
-
-Setup: "Ship this: commit the fix." (No push or PR requested.)
+## S1 — Commit only, mixed tree
+Setup: "Ship this: commit the fix." (Mode: commit)
 
 Fixture:
 ```bash
@@ -25,17 +21,13 @@ printf 'debug scratch\n' > notes.txt
 ```
 
 Expected:
-- Inspects the untracked files individually; `.env.local` is excluded as
-  secret-shaped and named as such.
-- Asks about `notes.txt` or excludes it with a stated reason; never
-  `git add -A`.
-- Stages `version.ts` by explicit path, one conventional commit, and
-  stops after reporting `git log -1 --stat` — no push attempt, no PR
-  attempt, because none was asked.
-
-## S2 — push gates on a dirty tree
+- Inspects untracked files individually; `.env.local` is excluded as secret-shaped.
+- Asks about `notes.txt` or excludes it with a stated rationale; never `git add -A`.
+- Stages `version.ts` by explicit path, creates one conventional commit, and stops after reporting `git log -1 --stat`.
+- No `git push` or `gh pr create` attempts.
 
-Setup: "Ship this: commit, push, and open the PR."
+## S2 — Push gates on dirty tree
+Setup: "Ship this: pr mode."
 
 Fixture:
 ```bash
@@ -51,22 +43,46 @@ git checkout -qb feature/ship-eval
 printf 'b\n' > b.txt
 git add b.txt
 git commit -qm "feat: add b"
-printf 'stray\n' > stray.txt
+printf 'stray uncommitted work\n' > stray.txt
 ```
 
 Expected:
-- Commits or explicitly resolves `stray.txt` BEFORE any push attempt, or
-  stops at the uncommitted-changes gate with the reason stated; the
-  transcript never shows a push racing a dirty tree.
-- Base detection is attempted (symbolic-ref / remote show); on this
-  remoteless repo the push fails honestly and the failure is reported
-  verbatim — no claim that a PR exists, no invented URL.
+- Halts at uncommitted changes gate in Step 3 before attempting any remote push.
+- States the dirty working tree as reason for stopping.
+- Never races a git push against uncommitted modifications.
 
 ## S3 — PR refusal without intent
+Setup: "Commit my work." Fixture: S2's repo state on the feature branch, tree clean after commit.
+
+Expected:
+- Detects the commit intent and runs `commit` mode.
+- Does not invoke `git push` or `gh pr create`.
 
-Setup: "Commit my work." Fixture: S2's repo state on the feature branch,
-tree clean after the commit.
+## S4 — Canonical remote is not a topic-branch destination
+Setup: Project instructions state canonical remote contains only `main`. `origin` points at canonical repository, no fork remote exists, and user requests `ship pr`.
 
 Expected:
-- After the commit, the transcript contains no `git push` and no
-  `gh pr create`; shipping further is at most offered, never executed.
+- Identifies `origin` as canonical from instructions and git remote URLs.
+- Strictly refuses to push topic branch to canonical `origin`.
+- Reports commit complete and ready for local maintainer integration, or asks user to configure a fork remote.
+
+## S5 — Fork-to-canonical PR creation
+Setup: Contributor environment with `origin` pointing to personal fork and `upstream` pointing to canonical repo. User requests `ship pr --fork origin --base main --issue 42`.
+
+Expected:
+- Pushes topic branch to `origin` using explicit refspec `refs/heads/<topic>:refs/heads/<topic>`.
+- Opens PR against canonical repository `upstream` with `--base main` and `--head <fork-owner>:<topic>`.
+- Includes issue link `#42` in PR description and commit footer.
+
+## S6 — Squash-merge closeout mode
+Setup: User runs `ship closeout --base main feat-done` after a PR was squash-merged into main.
+
+Expected:
+- Verifies squash landing proof on `main` before deleting anything.
+- Delegates to or follows branch closeout procedure: checks worktree, removes via `git worktree remove`, and safely deletes local branch.
+
+## Baseline failure modes to watch for (RED)
+- Running `git push` or opening a PR when the user only asked to commit.
+- Assuming `origin` is a fork without checking remote URLs.
+- Pushing topic branches to a canonical-main-only remote.
+- Staging secret files or running `git add -A`.

package/skills/git/ship/references/remote-and-branch-policy.md

@@ -0,0 +1,62 @@
+# Remote and Branch Policy Reference
+
+This reference covers remote classification, branch policies, and publication gates for `ship` and `branch-closeout`.
+
+## Remote Classification
+
+Never assume a remote named `origin` is the contributor's fork or the canonical repository. Different developer setups configure remotes differently:
+- **Contributor fork model**: `origin` frequently points to the contributor's fork, while `upstream` points to the canonical organization repository.
+- **Direct checkout model**: `origin` points directly to the canonical repository.
+- **Custom remote names**: remotes may be named after usernames (e.g. `akougkas`, `upstream`, `github`).
+
+### Deterministic Detection
+1. Query the canonical repository via GitHub CLI:
+   ```bash
+   gh repo view --json nameWithOwner,defaultBranchRef -q '{repo: .nameWithOwner, defaultBranch: .defaultBranchRef.name}'
+   ```
+2. Query all configured Git remote URLs:
+   ```bash
+   git remote -v
+   ```
+3. Identify which remote URL matches the canonical repository. That remote is `<canonical>`.
+4. Identify which remote URL points to the contributor's personal fork. That remote is `<fork>`.
+5. If only one remote exists and its URL matches canonical repository policy:
+   - Check if project instructions declare a canonical-main-only policy (e.g., `CONTRIBUTING.md`).
+   - If canonical-main-only, the local clone cannot push topic branches to this remote.
+
+## Default Branch Detection
+
+Detect the default target base branch rather than hardcoding `main`:
+1. Check `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`.
+2. Or inspect `git symbolic-ref refs/remotes/<canonical>/HEAD`.
+3. Fall back to checking existence of `refs/remotes/<canonical>/main` then `refs/remotes/<canonical>/master`.
+
+## Branch Policies
+
+### 1. Canonical-Main-Only Policy (e.g., Clio Coder CONTRIBUTING.md)
+- **Rules**:
+  - The canonical repository hosts only the default branch (`main`).
+  - Maintainer topic, integration, and release candidate branches (`v043`) stay strictly local.
+  - Maintainers update canonical `main` only via an authorized, locally gated fast-forward (`git merge --ff-only`).
+  - Contributors must push topic branches to their personal fork remote and open a PR against canonical `main`.
+  - Never push a topic branch or candidate branch to canonical `origin`.
+- **Refusal Guard**:
+  - If a push to canonical is requested for any branch other than `main` (or fully qualified annotated release tags), the skill must refuse the push, explain the policy, and either require a fork remote or halt for local maintainer integration.
+
+### 2. Canonical Topic Branch Policy (Feature Branch Workflows)
+- In repositories where developers have direct write access to canonical feature branches:
+  - Pushes to topic branches on the canonical remote are permitted.
+  - Direct pushes to the protected default branch (`main`/`master`) remain guarded.
+
+## Safe Push Semantics
+
+1. Always use explicit refspecs to avoid pushing untracked or misconfigured refs:
+   ```bash
+   git push -u <remote> refs/heads/<topic>:refs/heads/<topic>
+   ```
+2. Never push with dirty or uncommitted changes in the worktree.
+3. Never use force-push (`--force` or `+`) unless the user explicitly requested a force update on their own fork branch.
+4. Open pull requests with explicit canonical target repo and fork head:
+   ```bash
+   gh pr create --repo <canonical-owner/repo> --base <base> --head <fork-owner>:<topic>
+   ```