ci-fix-monitor

# CI Fix & Monitor Protocol

Activates when the user asks to monitor CI, fix CI failures, or resolve red
checks on a PR.

## Environment note — tool availability

This skill was originally written for desktop Claude Code (Windows) with `gh`
CLI. In the **remote execution / GitHub MCP** environment, use the equivalent
MCP tools instead:

| Desktop / `gh` CLI | Remote MCP equivalent |
|---|---|
| `gh pr checks <number>` | `mcp__github__pull_request_read` method `get_check_runs` |
| `gh run view <run-id> --job <job-id> --log` | `mcp__github__get_job_logs` with `job_id` and `return_content: true` |
| `gh pr edit --title` | `mcp__github__update_pull_request` with `title` |
| `gh pr view --json mergeable` | `mcp__github__pull_request_read` method `get` |

> MCP tool names are injected by the runtime harness and not guaranteed to be
> stable across environments. Use `ToolSearch` to verify availability before
> calling any `mcp__github__*` tool for the first time in a session.

## Step 1 — Fetch current status

Fetch all check runs for the PR head commit. If all green: report success
and stop.

## Step 2 — Classify each failure

| Failure type | Root cause pattern | Fix action |
|---|---|---|
| **check-title** | PR title lacks `<type>(<scope>):` prefix | Update title via PR edit |
| **package-check** | npm tarball validation failed (source/build/package-manifest problem) | Fix source/build/manifest — see section below. Not generated-file drift. |
| **branch behind main** | Branch is behind main; main had a release commit; CI uses merge-commit checkout | Rebase onto main, force-push — see section below |
| **lint/quality: format** | Code style violations (long lines, spacing) | `bunx biome format --write <files>` then commit |
| **lint/quality: lint** | Lint rule violations (noExplicitAny, etc.) | `bunx biome check --write <files>` or fix manually |
| **unit test** | Test failures | Read log, fix code, commit |
| **integration** | Integration failures | Read log, check if pre-existing on main |
| **macOS unit test** | Cross-platform file I/O race (atomic write-then-read returns null on macOS) | See "macOS file I/O fixes" below |
| **security** | SAST/secret findings | Read log, fix or suppress with justification |
| **smoke** | Smoke test failures | Read log, check if environment-specific |

## macOS file I/O fixes (cross-platform atomic write)

macOS/APFS has different filesystem timing than Linux ext4. `fs.renameSync` can
complete before the data is visible to subsequent reads. The most common
manifestation is `unit (macos-latest)` failing on tests that write-then-read
atomic files (e.g., `curator atomic write > writeCuratorSummary > after write,
readCuratorSummary reads file back successfully`), while the same tests pass
on `ubuntu-latest` and `windows-latest`.

**Canonical patterns:** See
[`.claude/skills/writing-tests/SKILL.md`](../../../claude/skills/writing-tests/SKILL.md)
§ Cross-Platform Requirements → "macOS rename-visibility race" for the
full three-layer fix pattern (bunWrite + ENOENT retry + Node FileHandle.sync()
not fsync()). This skill is a triage pointer; the canonical technical
reference lives in `writing-tests` so it survives any regeneration of this
`generated/` file.

**Related security test pattern:** if the CI failure involves a long task ID
or path, the security test `ADVERSARIAL: Command Services Attack Vectors >
Attack Vector 1: Malformed Arguments > EVIDENCE: extremely long task ID
(buffer overflow) - ACCEPTED by regex but no crash` requires a path length
guard BEFORE `validateSwarmPath` in `src/evidence/manager.ts:loadEvidence`.
See [`.claude/skills/engineering-conventions/SKILL.md`](../../../claude/skills/engineering-conventions/SKILL.md)
for the evidence file flow that this gate check triggers on macOS CI.

## Step 3 — Diagnose with logs

For every failed check, fetch the full log content. Fetch only the tail
(last 80–100 lines) unless the error is near the start.

Read the log carefully before concluding root cause. Distinguish between:
- a failure introduced by this PR,
- a pre-existing failure on `main` (verify by checking main's last CI run for
  the same check), and
- a failure caused by the CI environment or branch drift.

## Step 4 — Fix

### check-title
No commit needed. Update the PR title.

### package-check failure

`package-check` validates the npm tarball (`npm pack` + tarball contents). A
failure is a source/build/package-manifest problem, **not** generated-file
drift. `dist/` is generated and NOT committed — do not stage it. Run
`bun run build` locally only when you need the bundle to verify the failure:

```bash
bun run build
node --input-type=module -e "await import('./dist/index.js'); console.log('dist import OK')"
```

Fix the underlying source/build/`package.json` `files` manifest issue, then
commit the source fix (not `dist/`) and push.

### branch behind main (version drift)

**Identifying this case:** A version string differs (`version: "X.Y.Z"` changed
to a higher version) because main had a release commit after the branch was cut,
and GitHub Actions checks out the merge-commit for CI. Rebase onto main to pick
up the release commit.

**Fix:**

```bash
git fetch origin main
git rebase origin/main       # fast-forward the branch onto the release commit
# If the rebase halts with conflicts, run `git rebase --abort` and escalate
# to the user — do not attempt to resolve a conflicted rebase automatically.
git push --force-with-lease origin <branch>   # force-push is required after rebase
```

> `--force-with-lease` is safe here: it refuses to overwrite commits that
> appeared on the remote after your last fetch. After the rebase, the local
> branch has diverged from remote history — a regular push will be rejected.

### lint/quality: format violations

Biome format violations (line too long, spacing, bracket style) — these can
appear when a code change introduces a line that exceeds Biome's print-width.
Auto-fix only the changed files to minimize