@iowarp/clio-coder 0.4.2 → 0.4.4

package/skills/git/fix-issue/references/diagnosis-and-rca.md

@@ -0,0 +1,46 @@
+# Diagnosis, Why-Chains, and Root Cause Analysis (RCA)
+
+This reference outlines diagnosis techniques, why-chain construction, and root-cause documentation for `fix-issue`.
+
+## Diagnosing Unknown Causes
+
+When an issue does not already pinpoint the root cause:
+1. **Reproduce first**: Write a reproduction test script or minimal test case before altering any application logic. Run it and verify it fails with the expected symptom.
+2. **Trace the fault**: Follow the call stack or data flow backwards from the failure site to the originating trigger.
+3. **Construct a why-chain**:
+   ```
+   WHY <observed failure>?  -> because <immediate condition> (evidence: path/file.ts:123)
+   WHY <immediate condition>? -> because <underlying cause>   (evidence: path/file.ts:89)
+   ROOT CAUSE: <the exact defect to fix>                    (evidence: path/file.ts:45)
+   ```
+   Every link in the chain must cite a verified line of code or observed runtime state. A link without an observed citation remains an unverified hypothesis.
+
+## Routine Fixes vs Standalone RCA
+
+- **Routine fixes**: The why-chain is included directly in the final completion summary presented to the user. No separate RCA file is required.
+- **Complex or high-impact defects**: A standalone RCA document or detailed why-chain is written when:
+  - The defect caused data corruption, downtime, or security exposure.
+  - The diagnosis uncovered multiple interacting failure modes.
+  - The fix requires significant architectural changes or breaking behavioral adjustments.
+
+## RCA Destination and Issue Tracking
+
+- An RCA or diagnosis artifact stays in the local repository or task output during development.
+- **Do not assume downstream tools post comments automatically**: `ship` handles atomic commits and pull requests; it does not automatically post closing comments or attach labels to issues.
+- If the maintainer or repository workflow calls for recording the RCA on the tracker issue (for example, under an `rca` status label), format the comment clearly and request explicit user confirmation (`ask_user`) before running:
+  ```bash
+  gh issue comment <id> --repo <owner/repo> --body-file "$rca_file"
+  ```
+- If the repository uses an `rca` label, propose applying it only after the user approves:
+  ```bash
+  gh issue edit <id> --repo <owner/repo> --add-label "rca"
+  ```
+
+## Respecting Maintainer Constraints
+
+If an issue contains comments from maintainers specifying:
+- Non-negotiable interfaces or constraints
+- Performance budgets or dependencies that must not be added
+- Out-of-bounds files or packages
+
+These constraints are binding. If technical reality makes compliance impossible, stop, document the contradiction with evidence, and ask for user guidance before proceeding.

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

@@ -7,8 +7,9 @@ triggers:
   - finish the merge
   - finish the rebase
   - resolve conflict markers
-version: 0.3.0
+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`.