[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7329E4KHQN8HK5FNGTYCFHH":3,"skill-same:01M7329E4KHQN8HK5FNGTYCFHH":49},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":32,"ownerDescription":33,"updatedAt":34,"install":35,"resources":48},"01M7329E4KHQN8HK5FNGTYCFHH","commit-pr",null,"Apply when committing, pushing, opening or updating a PR, writing a pull request, creating release notes, or closing out remote CI. Enforces the opencode-swarm invariant audit, release-note fragment workflow, full validation suite, issue comment requirement, and post-PR lifecycle rules.","djimit\u002Fdjimitflo","djimit","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F19958832?v=4","01M7327CH792DZPFZPYAEFPRXT","Dutch Dim","01M7327CHWPSXT9AWE4MPWCX9Q",2,"MIT","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fcommit-pr\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: commit-pr\ndescription: >\n  Apply when committing, pushing, opening or updating a PR, writing a pull request,\n  creating release notes, or closing out remote CI. Enforces the opencode-swarm\n  invariant audit, release-note fragment workflow, full validation suite, issue\n  comment requirement, and post-PR lifecycle rules.\neffort: medium\n---\n\n# Commit & PR Protocol\n\nFollow every step in order. Do not skip steps.\n\n## Step -1 - Mandatory invariant audit\n\nBefore any build, test, push, or PR action, read:\n\n1. [`..\u002F..\u002F..\u002FAGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md)\n2. [`..\u002F..\u002F..\u002Fdocs\u002Fengineering-invariants.md`](..\u002F..\u002F..\u002Fdocs\u002Fengineering-invariants.md)\n\nFor every touched invariant, prepare concrete evidence for the PR body. The PR body must include:\n\n```md\n## Invariant audit\n- 1 (plugin init): touched \u002F not touched - \u003Cevidence>\n- 2 (runtime portability): touched \u002F not touched - \u003Cevidence>\n- 3 (subprocesses): touched \u002F not touched - \u003Cevidence>\n- 4 (.swarm containment): touched \u002F not touched - \u003Cevidence>\n- 5 (plan durability): touched \u002F not touched - \u003Cevidence>\n- 6 (test_runner safety): touched \u002F not touched - \u003Cevidence>\n- 7 (test writing): touched \u002F not touched - \u003Cevidence>\n- 8 (session state): touched \u002F not touched - \u003Cevidence>\n- 9 (guardrails\u002Fretry): touched \u002F not touched - \u003Cevidence>\n- 10 (chat\u002Fsystem msg): touched \u002F not touched - \u003Cevidence>\n- 11 (tool registration): touched \u002F not touched - \u003Cevidence>\n- 12 (release\u002Fcache): touched \u002F not touched - \u003Cevidence>\n```\n\nIf a touched invariant cannot be proven from source and test output, do not push.\n\n### Required validations for touched invariants\n\nIf invariants 1, 2, or 3 are touched, run all three:\n\n```bash\nbun run build\nnode scripts\u002Frepro-704.mjs\nnode --input-type=module -e \"await import('.\u002Fdist\u002Findex.js'); console.log('dist import OK')\"\n```\n\nIf invariant 3 is touched, audit changed source files for subprocess use:\n\n```bash\ngit diff --name-only origin\u002Fmain..HEAD | xargs -r grep -nE \"bunSpawn\\(|spawn\\(|spawnSync\\(\" || true\n```\n\nIf invariant 11 is touched, run:\n\n```bash\nbun --smol test tests\u002Funit\u002Fconfig --timeout 60000\nfor f in tests\u002Funit\u002Ftools\u002F*.test.ts; do bun --smol test \"$f\" --timeout 30000; done\n```\n\nIf invariant 7 is touched, confirm the writing-tests skill was loaded and that new test seams avoid leaking `mock.module`.\n\n## Step 0 - Session start hygiene\n\nRun before publication work:\n\n```bash\ngit fetch origin main\nrm -f .swarm\u002Fevidence\u002F*.json\ngit status --short\n```\n\nOn Windows, prefer temporary save branches over `git stash`. If you must stash, use `git stash push --include-untracked` and verify the stash contents.\n\n## Step 1 - Commit and PR titles\n\nUse `\u003Ctype>(\u003Cscope>): \u003Cdescription>` exactly.\n\n- description is lowercase and does not end with a period\n- allowed types: `feat`, `fix`, `perf`, `revert`, `docs`, `chore`, `refactor`, `test`, `ci`, `build`\n\nChoose the PR title type by the main change:\n\n- new capability -> `feat`\n- bug fix only -> `fix`\n- docs or chore only -> non-bump types\n\nThe squash merge commit message must match the PR title exactly.\n\n> **Note:** The PR title MUST follow `\u003Ctype>(\u003Cscope>): \u003Cdescription>` exactly — CI runs `action-semantic-pull-request` which will fail the `check-title` job if the format is wrong. Do not deviate from this format.\n\n## Step 2 - Release note fragment\n\nCreate a pending release fragment and do not calculate a version manually.\n\nRequired file shape:\n\n```text\ndocs\u002Freleases\u002Fpending\u002F\u003Cunique-slug>.md\n```\n\nThe fragment should cover:\n\n- what changed\n- why\n- migration steps, if any\n- breaking changes, if any\n- known caveats\n\nDo not manually edit:\n\n- `package.json` version\n- `CHANGELOG.md`\n- `.release-please-manifest.json` — exception: reconciliation when the manifest desyncs from actual releases (see below)\n\n### Release-please manifest desync\n\n`.release-please-manifest.json` is the version source of truth for release-please. If it desyncs from the actual published release (e.g., `7.26.0` in manifest but `v7.27.1` on GitHub), release-please will propose a version that goes backwards.\n\n**Common cause:** An older release PR (e.g., `chore(main): release 7.26.0`) merges after a newer one (`chore(main): release 7.27.1`). Both PRs modify the manifest, so the later one to merge wins — regardless of which version is higher.\n\n**Detection:** If a release-please PR proposes a version that seems too low, check:\n1. `gh release list --limit 5` — what's the latest published release?\n2. `git show origin\u002Fmain:.release-please-manifest.json` — what does the manifest say?\n3. If different, the manifest is desynced.\n\n**Fix:** Open a PR that updates `.release-please-manifest.json` to match the actual latest release (e.g., `\"7.27.1\"`). Close the incorrect release PR with explanation. After the manifest fix merges, release-please will auto-create a correct release PR.\n\n## Step 3 - Mandatory validation suite\n\nRun the full validation stack before pushing. The exact commands may be narrowed only when the repo contract or current task explicitly justifies it in evidence, not by intuition.\n\n### Pre-flight\n\n`dist\u002F` is generated output and is **not** committed (#1047). Confirm the build still\nsucceeds and the bundle loads — do not stage `dist\u002F`:\n\n```bash\nbun run build\nnode --input-type=module -e \"await import('.\u002Fdist\u002Findex.js'); console.log('dist import OK')\"\n```\n\n### Tier 1 - quality\n\nRun both linter AND formatter — e.g., `bunx @biomejs\u002Fbiome@\u003Cversion> check --write .` or equivalent — because CI quality gates reject code that passes tests but fails style validation. **Pin the tool version** to match the version in `package.json` (`@biomejs\u002Fbiome`); unversioned `bunx biome` resolves to a different version than the CI gate uses.\n\n```bash\nbun run typecheck\nbunx @biomejs\u002Fbiome@\u003Cversion> ci .\n```\n\n### Tier 2 - unit tests\n\n```bash\nfor f in tests\u002Funit\u002Ftools\u002F*.test.ts; do bun --smol test \"$f\" --timeout 30000; done\nfor f in tests\u002Funit\u002Fservices\u002F*.test.ts; do bun --smol test \"$f\" --timeout 30000; done\nfor f in tests\u002Funit\u002Fagents\u002F*.test.ts; do bun --smol test \"$f\" --timeout 30000; done\nfor f in tests\u002Funit\u002Fhooks\u002F*.test.ts; do bun --smol test \"$f\" --timeout 30000; done\nbun --smol test tests\u002Funit\u002Fcli tests\u002Funit\u002Fcommands tests\u002Funit\u002Fconfig --timeout 120000\n```\n\nIf agent prompt text changed, grep for the changed text in tests and rerun every matching file individually.\n\n### Tier 3 - integration\n\n```bash\nbun test tests\u002Fintegration .\u002Ftest --timeout 120000\n```\n\n### Tier 4 - security and adversarial\n\n```bash\nbun test tests\u002Fsecurity --timeout 120000\nbun test tests\u002Fadversarial --timeout 120000\n```\n\n### Tier 5 - smoke\n\n```bash\nbun test tests\u002Fsmoke --timeout 120000\n```\n\n### Pre-existing failure handling\n\nIf a failure looks unrelated, prove it on clean `origin\u002Fmain` before carrying it into the PR body:\n\n```bash\ngit worktree add \u002Ftmp\u002Frepro-check origin\u002Fmain\nbun --smol test \u002Ftmp\u002Frepro-check\u002F\u003Cpath-to-failing-test> --timeout 30000\ngit worktree remove \u002Ftmp\u002Frepro-check\n```\n\nIf the failure reproduces on `main`, document it under `## Pre-existing failures`. Do not silently inherit it.\n\n### dist\u002F is generated, not committed\n\n`dist\u002F` is build output and is git-ignored (#1047); do **not** stage or commit it, and\nthere is no `dist-check` drift gate. The authoritative artifact check is `package-check`,\nwhich runs `npm pack` and verifies the packed tarball is complete (type declarations,\ngrammar assets), installs it in a temp project, imports it under Node, and runs the CLI.\n\nA `package-check` failure is a source \u002F build \u002F `package.json#files` problem — fix the\nsource or manifest and rebuild; never \"commit dist to make CI green.\" CI builds `dist\u002F`\nitself (the `unit`, `package-check`, and `smoke` jobs run `bun run build`), and\nrelease\u002Fpublish builds from source.\n\n## Step 4 - Workflow changes\n\nIf any `.github\u002Fworkflows\u002F*.yml` file changed, every third-party `uses:` must be pinned to a full 40-character SHA.\n\n## Step 5 - History shape\n\nBefore opening a PR, verify no local-only files are staged:\n\n```bash\ngit diff --name-only HEAD origin\u002Fmain | grep -E '\\.(local\\.json|vscode|idea)' || true\n```\n\nPrefer a single clean commit for the branch before initial PR publication:\n\n```bash\ngit fetch origin main\ngit log --oneline origin\u002Fmain..HEAD\ngit reset --soft origin\u002Fmain\ngit commit -m \"type(scope): description\"\ngit push --force-with-lease -u origin \u003Cbranch-name>\n```\n\nIf a review cycle is already active and inline comments depend on current SHAs, avoid resquashing until threads are resolved.\n\nIf pushing to a PR branch owned by another agent or bot, push to the PR's actual head branch:\n\n```powershell\n$prBranch = gh pr view \u003Cnumber> --json headRefName --jq '.headRefName'\ngit fetch origin $prBranch\ngit push origin \"\u003Cyour-local-branch>:$prBranch\" --force-with-lease\n```\n\n### Pre-push: Push Protection and Canonical Remote\n\nBefore `git push`, run both checks:\n\n#### Push protection scan\n\nGitHub push protection blocks commits containing literal secret patterns. This bit the\nfirst commit of PR #1472 — a test file with a literal `sk_live_*` Stripe fixture\npattern was pushed before the string-concatenation workaround was applied.\n\n**The primary check (pre-push, after commit exists):**\n\n```bash\ngit log origin\u002Fmain..HEAD -p | grep -E \"$(printf '%s' \"${PREFIX:-sk_live}|ghp_|xox[abprs]-|AKIA|eyJ|AIza\")\" || true\n```\n\n**The optional pre-commit add-on (staged changes only):**\n\n```bash\ngit diff --cached | grep -E \"$(printf '%s' \"${PREFIX:-sk_live}|ghp_|xox[abprs]-|AKIA|eyJ|AIza\")\" || true\n```\n\nForbidden patterns: Stripe (`sk_live_*`), GitHub (`ghp_*`), Slack (`xox[abprs]-*`),\nAWS (`AKIA*`), JWT (`eyJ*`), Google API (`AIza*`).\n\n**The fix:** Construct test fixtures via string concatenation rather than literal\npatterns. For example:\n\n```typescript\n\u002F\u002F Wrong — triggers push protection:\nconst stripeKey = 'sk_live_' + '1234567890abcdefghijklmn'\n\n\u002F\u002F Right — split the literal so it never appears verbatim in source:\nconst stripeKey = 'sk_' + 'live_' + '1234567890abcdefghijklmn'\n```\n\n> **Note:** This scan is a best-effort heuristic. It will not catch deliberately obfuscated patterns (e.g., base64 or hex encoding, runtime string assembly). For genuinely sensitive keys, use environment variables or a secret store — never commit credentials to source.\n\n#### Canonical remote resolution\n\nWhen a repo has multiple remotes (e.g. `zaxbysauce\u002Fopencode-swarm` and\n`ZaxbyHub\u002Fopencode-swarm`), pushing to the wrong remote causes `gh pr create` to\nfail with \"No commits between \u003Ccanonical>:main and \u003Cmirror>:\u003Cbranch>\". This happened\non PR #1472.\n\n**The check:** `git remote -v` before push. Identify the canonical-org remote.\n\n**The rule:** Push to the canonical-org remote explicitly:\n\n```bash\ngit push -u \u003Ccanonical-remote> \u003Cbranch>\n```\n\nCreate the PR against the canonical repo:\n\n```bash\ngh pr create --repo \u003Ccanonical-org>\u002F\u003Crepo>\n```\n\n**Heuristic for identifying the canonical remote:** the canonical remote is the one whose URL points to the owning organization (e.g. `github.com\u002F\u003Corg>\u002F\u003Crepo>.git`), not a personal fork or mirror. When the owning org differs from the local fork's owner, the org-owned remote is canonical. Example: `github.com\u002FZaxbyHub\u002Fopencode-swarm.git` is canonical; `github.com\u002Fzaxbysauce\u002Fopencode-swarm.git` is a personal fork.\n\n## Step 6 - PR creation\n\nPR body requirements:\n\n- `Closes #\u003Cissue-number>` as the first line when the PR resolves an issue\n- `## Summary`\n- `## Invariant audit`\n- `## Test plan`\n\n### Publication-gate evidence\n\nA repository publication gate (`.github\u002Fhooks\u002Fpr-publication-gate.json` ->\n`scripts\u002Fcopilot-pr-publication-gate.sh`) may block `gh pr create`, `gh pr edit`,\nand `gh pr ready` until publication evidence exists. Before publishing, write:\n\n- `.swarm\u002Fevidence\u002Fpr_body.md` — the exact PR body you will publish (must contain\n  `## Summary`, `## Invariant audit`, and `## Test plan`).\n- `.swarm\u002Fevidence\u002Fcommit-pr-validation.md` — the validation commands you ran and\n  their results.\n\nThese files live under `.swarm\u002F` (runtime state, never committed) and double as the\nevidence the gate checks. Keep them current if you edit the PR body or rerun\nvalidation. The CI `pr-standards` check enforces the same body contract server-side.\n\nPowerShell-safe pattern:\n\n```powershell\n$body = @\"\nCloses #\u003Cissue-number>\n\n## Summary\n- \u003Cbullet 1>\n- \u003Cbullet 2>\n\n## Invariant audit\n- 1 (plugin init): not touched - \u003Cevidence>\n\n## Test plan\n- [ ] \u003Cvalidation item>\n\"@\n$utf8NoBom = New-Object -TypeName System.Text.UTF8Encoding -ArgumentList $false\n$prBodyPath = Join-Path ([System.IO.Path]::GetTempPath()) \"pr_body.txt\"\n[System.IO.File]::WriteAllText($prBodyPath, $body, $utf8NoBom)\ngh pr create --title \"\u003Ctype>(\u003Cscope>): \u003Cdescription>\" --body-file $prBodyPath --base main\n```\n\n## Step 6a - PR monitoring subscription\n\nAfter PR creation, if the project uses PR monitoring (`pr_monitor.enabled: true`\nin resolved opencode-swarm config), the new PR must be subscribed for background\nmonitoring:\n\n- **Automatic (default):** when `pr_monitor.auto_subscribe_on_pr_create` is\n  enabled (default `true`), the subscription is created automatically after\n  `gh pr create` succeeds — no command needed. Verify with `\u002Fswarm pr status`\n  if in doubt.\n- **Manual fallback:** when auto-subscribe is disabled or did not fire, run\n  `\u002Fswarm pr subscribe \u003Cpr-url>`, which records the subscription and\n  lazy-starts the polling worker.\n\nThe post-subscription monitoring protocol — event intake, triage\n(fix \u002F ask \u002F skip), bounded-retry escalation, and terminal-state behavior —\nlives in the swarm-pr-subscribe skill (`..\u002Fswarm-pr-subscribe\u002FSKILL.md`).\n\n## Step 6.5 - Issue comment\n\nIf the PR closes an issue, post a comment on the issue. This is mandatory.\n\nThe issue comment must include:\n\n1. the PR link\n2. what changed\n3. how to use it\n4. migration steps or \"No migration required\"\n\nPowerShell-safe pattern:\n\n````powershell\n$comment = @\"\nFixed in PR #\u003Cpr-number>.\n\n## What changed\n- \u003Cbullet 1>\n- \u003Cbullet 2>\n\n## How to use\n```json\n{ \"config\": \"example\" }\n```\n\n## Migration\nNo migration required.\n\"@\n$utf8NoBom = New-Object -TypeName System.Text.UTF8Encoding -ArgumentList $false\n$issueCommentPath = Join-Path ([System.IO.Path]::GetTempPath()) \"issue-comment.txt\"\n[System.IO.File]::WriteAllText($issueCommentPath, $comment, $utf8NoBom)\ngh issue comment \u003Cissue-number> --body-file $issueCommentPath\n````\n\n## Commit messages\n\n`git commit -m \"...\"` with parens, brackets, backticks, or dollar-signs in the message fails on PowerShell because the shell parses them as expressions. Write the commit message to a UTF-8 (no BOM) file first and use `git commit -F \u003Cfile>`.\n\nPowerShell-safe pattern:\n\n```powershell\n$msg = @\"\n\u003Ctype>(\u003Cscope>): \u003Cdescription>\n\n\u003Coptional body — note this is for the git commit message, NOT the PR body>\n\"@\n$utf8NoBom = New-Object -TypeName System.Text.UTF8Encoding -ArgumentList $false\n$commitMsgPath = Join-Path ([System.IO.Path]::GetTempPath()) \"commit-msg.txt\"\n[System.IO.File]::WriteAllText($commitMsgPath, $msg, $utf8NoBom)\ngit commit -F $commitMsgPath\n```\n\nApply this pattern for any commit message containing special characters, multi-paragraph bodies, or code blocks. The plain `git commit -m \"...\"` form remains fine for short single-line messages with no special characters.\n\nIf the PR merged before this was done, post the missing issue comment immediately.\n\n## Step 7 - Existing PR follow-up and closeout\n\nIf a PR already exists for the branch:\n\n1. do not open a second PR\n2. inspect unresolved PR feedback surfaces before updating or readying the PR: review threads\u002Fcomments, requested-changes reviews, CI\u002Fcheck failures, mergeability\u002Fconflicts, and whether check data belongs to the current head SHA\n3. use `..\u002Fswarm-pr-feedback\u002FSKILL.md` when feedback needs fixes before closeout\n4. update the existing PR body when summary, invariant evidence, test counts, caveats, or pre-existing failure notes changed\n5. keep the PR draft while follow-up edits are still expected or required checks are still pending\n6. mark the PR ready only after the body is current and required remote checks are green, unless the user explicitly wants it ready earlier\n7. after any follow-up push or force-push, verify the PR head matches the expected commit and that reported checks belong to the current `headRefOid`:\n\n```powershell\ngh pr view \u003Cnumber> --json headRefOid,body,isDraft,state,mergeable,mergeStateStatus,statusCheckRollup,url\n```\n\nUseful commands:\n\n```powershell\ngh pr edit \u003Cnumber> --body-file \"$env:TEMP\\pr_body.txt\"\ngh pr ready \u003Cnumber>\ngh pr checks \u003Cnumber> --watch --fail-fast\n```\n\n### Conflict closeout\n\nAfter resolving merge conflicts or syncing a stale branch:\n\n1. verify there are no local unmerged paths or conflict markers,\n2. push the conflict-resolution commit,\n3. verify GitHub reports both `mergeable: MERGEABLE` and\n   `mergeStateStatus: CLEAN`, not merely that local markers are gone, and\n4. keep a conflict\u002Fbranch-drift item in the PR closure ledger when it affected\n   the PR.\n\nIf GitHub still reports `DIRTY`, `BLOCKED`, or stale checks after local conflict\nresolution, fetch current `origin\u002Fmain` again and re-evaluate before claiming the\nconflict is resolved.\n\n### GitHub auto-merge race condition\n\nWith a merge queue enabled, prefer queuing over manual freshness rebases, which\navoids this race entirely. It can still occur if you rebase manually: when `main`\nadvances while your PR is open, GitHub's PR sync machinery may **automatically push a\nmerge commit to your branch** in the window between when you fetch and when you push.\nThis is distinct from a conflict — it is GitHub creating a merge commit on your behalf\nwithout rebuilding generated outputs (lockfiles, etc.).\n\nSymptoms:\n- `git push` is rejected with \"fetch first\" even though you just fetched\n- `git log HEAD..origin\u002F\u003Cbranch>` shows a commit authored by GitHub\u002Fthe repo owner with message `Merge branch 'main' into \u003Cbranch>`\n- generated outputs (e.g. lockfiles) on that auto-merge commit are stale because it was not rebuilt\n\nRecovery:\n```bash\ngit fetch origin \u003Cbranch>\ngit log HEAD..origin\u002F\u003Cbranch>   # confirm it's only the GitHub auto-merge\n# Your local commit is correct. Force-push it:\ngit push origin \u003Cbranch> --force-with-lease\n```\n\nAfter force-pushing, verify the PR head SHA updated and cancel any CI run\ntargeting the superseded auto-merge SHA to unblock concurrency:\n\n```powershell\ngh run list --branch \u003Cbranch> --limit 5 --json databaseId,headSha,status,workflowName\ngh run cancel \u003Cstale-run-id>\n```\n\n### Check closeout\n\n`gh pr checks --watch --fail-fast` is useful but can lag or flatten matrix and\ndownstream jobs. When the PR checks view looks stale, missing, or inconsistent,\nuse the workflow run as the authoritative detail:\n\n> **MCP environments:** When using GitHub MCP tools instead of `gh`, prefer\n> `get_check_runs` over `get_status`. The `get_status` method uses GitHub's\n> legacy commit status API: it returns `state: \"pending\"` even when all GitHub\n> Actions jobs are green, because Actions creates check-runs (not legacy\n> statuses). `get_check_runs` returns the actual job results.\n\n```powershell\ngh run view \u003Crun-id> --json headSha,status,conclusion,jobs,url\n```\n\nKeep watching after unit jobs pass; this repository may enqueue integration and\nsmoke jobs later in the same CI run. Do not call the PR green until the current\n`headRefOid` has all required jobs completed successfully.\n\nIf a previous run from an older PR head is still in progress or already failed\nand is blocking the current head's workflow through concurrency, inspect it with\n`gh run view \u003Crun-id> --json headSha,status,conclusion,jobs,url`. Cancel only\nobsolete older-head runs that are no longer relevant to the PR head you are\nvalidating, then wait for the current-head checks to complete.\n\nIf you edit the PR body after checks are green, expect PR Standards \u002F title\nchecks to rerun. Re-check before claiming final green or merge-readiness.\n\n### Merge queue (current-base validation)\n\nWhen `main` has a GitHub **merge queue** enabled, do not rebase or force-push a PR\n*solely because `main` advanced*. Once required checks and review are green, add the\nPR to the merge queue; GitHub re-runs the required workflows against the queued\nchange on top of the latest `main` (and any earlier queued PRs) before merging, so\nmanual \"freshness\" rebases are unnecessary.\n\nStill rebase\u002Fforce-push when there is a **real** reason: a genuine merge conflict,\na stale review thread that depends on current SHAs, or a correctness issue that only\nappears against current `main`. The queue handles up-to-date validation; it does not\nresolve conflicts for you.\n\nRequired workflows trigger on both `pull_request` and `merge_group`. PR-only checks\n(title\u002Fbody validation) no-op to success on `merge_group` because the PR already\nsatisfied them before being queued.\n\n## Step 8 - Cancelled jobs and skipped dependents\n\nIf a required GitHub Actions job is `cancelled` and downstream jobs are `skipped`:\n\n1. inspect the run:\n\n```powershell\ngh run view \u003Crun-id> --json status,conclusion,jobs,url\n```\n\n2. if the cancellation looks like orchestration or infrastructure rather than a code failure, rerun the failed or cancelled jobs:\n\n```powershell\ngh run rerun \u003Crun-id> --failed\n```\n\n3. re-check the PR until required jobs are green:\n\n```powershell\ngh pr checks \u003Cnumber> --watch --fail-fast\n```\n\nDo not call the PR green or merge-ready while a required job is `cancelled`, `skipped`, `in_progress`, or otherwise non-green unless the user explicitly accepts that state.\n\n## Step 9 - Pre-merge checklist\n\n- [ ] invariant audit is complete and current\n- [ ] required build and validation commands ran for touched invariants\n- [ ] `test_runner` was not used with broad repo-validation scopes\n- [ ] release fragment exists and version files are untouched\n- [ ] `dist\u002F` was NOT staged (it is generated output, not committed — #1047)\n- [ ] PR body has `Closes`, `## Summary`, `## Invariant audit`, and `## Test plan`\n- [ ] if this was review follow-up, the PR body was refreshed to match current evidence\n- [ ] if the PR resolves an issue, the issue comment was posted with PR link, what changed, how to use it, and migration notes\n- [ ] if any required job was cancelled and dependent jobs skipped, the run was rerun or the non-green state was explicitly accepted by the user\n- [ ] for high-risk work (security, isolation, IPC, auth, payments, migrations), an independent adversarial review subagent ran before the final substantive push and all confirmed findings were addressed — if this was not done before pushing, run the review now and force-push a corrected commit before marking the PR ready\n- [ ] all required CI checks are green before calling the PR merge-ready\n","# Commit & PR Protocol\n\nFollow every step in order. Do not skip steps.\n\n## Step -1 - Mandatory invariant audit\n\nBefore any build, test, push, or PR action, read:\n\n1. [`..\u002F..\u002F..\u002FAGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md)\n2. [`..\u002F..\u002F..\u002Fdocs\u002Fengineering-invariants.md`](..\u002F..\u002F..\u002Fdocs\u002Fengineering-invariants.md)\n\nFor every touched invariant, prepare concrete evidence for the PR body. The PR body must include:\n\n```md\n## Invariant audit\n- 1 (plugin init): touched \u002F not touched - \u003Cevidence>\n- 2 (runtime portability): touched \u002F not touched - \u003Cevidence>\n- 3 (subprocesses): touched \u002F not touched - \u003Cevidence>\n- 4 (.swarm containment): touched \u002F not touched - \u003Cevidence>\n- 5 (plan durability): touched \u002F not touched - \u003Cevidence>\n- 6 (test_runner safety): touched \u002F not touched - \u003Cevidence>\n- 7 (test writing): touched \u002F not touched - \u003Cevidence>\n- 8 (session state): touched \u002F not touched - \u003Cevidence>\n- 9 (guardrails\u002Fretry): touched \u002F not touched - \u003Cevidence>\n- 10 (chat\u002Fsystem msg): touched \u002F not touched - \u003Cevidence>\n- 11 (tool registration): touched \u002F not touched - \u003Cevidence>\n- 12 (release\u002Fcache): touched \u002F not touched - \u003Cevidence>\n```\n\nIf a touched invariant cannot be proven from source and test output, do not push.\n\n### Required validations for touched invariants\n\nIf invariants 1, 2, or 3 are touched, run all three:\n\n```bash\nbun run build\nnode scripts\u002Frepro-704.mjs\nnode --input-type=module -e \"await import('.\u002Fdist\u002Findex.js'); console.log('dist import OK')\"\n```\n\nIf invariant 3 is touched, audit changed source files for subprocess use:\n\n```bash\ngit diff --name-only origin\u002Fmain..HEAD | xargs -r grep -nE \"bunSpawn\\(|spawn\\(|spawnSync\\(\" || true\n```\n\nIf invariant 11 is touched, run:\n\n```bash\nbun --smol test tests\u002Funit\u002Fconfig --timeout 60000\nfor f in tests\u002Funit\u002Ftools\u002F*.test.ts; do bun --smol test \"$f\" --timeout 30000; done\n```\n\nIf invariant 7 is touched, confirm the writing-tests skill was loaded and that new test seams avoid leaking `mock.module`.\n\n## Step 0 - Session start hygiene\n\nRun before publication work:\n\n```bash\ngit fetch origin main\nrm -f .swarm\u002Fevidence\u002F*.json\ngit status --short\n```\n\nOn Windows, prefer temporary save branches over `git stash`. If you must stash, use `git stash push --include-untracked` and verify the stash contents.\n\n## Step 1 - Commit and PR titles\n\nUse `\u003Ctype>(\u003Cscope>): \u003Cdescription>` exactly.\n\n- description is lowercase and does not end with a period\n- allowed types: `feat`, `fix`, `perf`, `revert`, `docs`, `chore`, `refactor`, `test`, `ci`, `build`\n\nChoose the PR title type by the main change:\n\n- new capability -> `feat`\n- bug fix only -> `fix`\n- docs or chore only -> non-bump types\n\nThe squash merge commit message must match the PR title exactly.\n\n> **Note:** The PR title MUST follow `\u003Ctype>(\u003Cscope>): \u003Cdescription>` exactly — CI runs `action-semantic-pull-request` which will fail the `check-title` job if the format is wrong. Do not deviate from this format.\n\n## Step 2 - Release note fragment\n\nCreate a pending release fragment and do not calculate a version manually.\n\nRequired file shape:\n\n```text\ndocs\u002Freleases\u002Fpending\u002F\u003Cunique-slug>.md\n```\n\nThe fragment should cover:\n\n- what changed\n- why\n- migration steps, if any\n- breaking changes, if any\n- known caveats\n\nDo not manually edit:\n\n- `package.json` version\n- `CHANGELOG.md`\n- `.release-please-manifest.json` — exception: reconciliation when the manifest desyncs from actual releases (see below)\n\n### Release-please manifest desync\n\n`.release-please-manifest.json` is the version source of truth for release-please. If it desyncs from the actual published release (e.g., `7.26.0` in manifest but `v7.27.1` on GitHub), release-please will propose a version that goes backwards.\n\n**Common cause:** An older release PR (e.g., `chore(main): release 7.26.0`) merges after a newer one (`chore(main): release 7.27.1`). Both PRs modify the manifest, so the later one to merge wins — regardless of which version is higher.\n\n**Detection:** If a release-please PR proposes a version that seems too low, check:\n1. `gh release list --limit 5` — what's the latest published release?\n2. `git show origin\u002Fmain:.release-please-manifest.json` — what does the manifest say?\n3. If different, the manifest is desynced.\n\n**Fix:** Open a PR that updates `.release-please-manifest.json` to match the actual latest release (e.g., `\"7.27.1\"`). Close the incorrect release PR with explanation. After the manifest fix merges, release-please will auto-create a correct release PR.\n\n## Step 3 - Mandatory validation suite\n\nRun the full validation stack before pushing. The exact commands may be narrowed only when the repo contract or current task explicitly justifies it in evidence, not by intuition.\n\n### Pre-flight\n\n`dist\u002F` is generated output and is **not** committed (#1047). Confirm the build still\nsucceeds and the bundle loads — do not stage `dist\u002F`:\n\n```bash\nbun run build\nnode --input-type=module -e \"await import('.\u002Fdist\u002Findex.js'); console.log('dist import OK')\"\n```\n\n### Tier 1 - quality\n\nRun both linter AND formatter — e.g., `bunx @biomejs\u002Fbiome@\u003Cversion> check --write .` or equivalent — because CI quality gates reject code that passes tests but fails style validation. **Pin the tool version** to match the version in `package.json` (`@biomejs\u002Fbiome`); unversioned `bunx biome` resolves to a different version than the CI gate uses.\n\n```bash\nbun run typecheck\nbunx @biomejs\u002Fbiome@\u003Cversion> ci .\n```\n\n### Tier 2 - unit tests\n\n```bash\nfor f in tests\u002Funit\u002Ftools\u002F*.test.ts; do bun --smol test \"$f\" --timeout 30000; done\nfor f in tests\u002Funit\u002Fservices\u002F*.test.ts; do bun --smol test \"$f\" --timeout 30000; done\nfor f in tests\u002Funit\u002Fagents\u002F*.test.ts; do bun --smol test \"$f\" --timeout 30000; done\nfor f in tests\u002Funit\u002Fhooks\u002F*.test.ts; do bun --smol test \"$f\" --timeout 30000; done\nbun --smol test tests\u002Funit\u002Fcli tests\u002Funit\u002Fcommands tests\u002Funit\u002Fconfig --timeout 120000\n```\n\nIf agent prompt text changed, grep for the changed text in tests and rerun every matching file individually.\n\n### Tier 3 - integration\n\n```bash\nbun test tests\u002Fintegration .\u002Ftest --timeout 120000\n```\n\n### Tier 4 - security and adversarial\n\n```bash\nbun test tests\u002Fsecurity --timeout 120000\nbun test tests\u002Fadversarial --timeout 120000\n```\n\n### Tier 5 - smoke\n\n```bash\nbun test tests\u002Fsmoke --timeout 120000\n```\n\n### Pre-existing failure handling\n\nIf a failure looks unrelated, prove it on clean `origin\u002Fmain` before carrying it into the PR body:\n\n```bash\ngit worktree add \u002Ftmp\u002Frepro-check origin\u002Fmain\nbun --smol test \u002Ftmp\u002Frepro-check\u002F\u003Cpath-to-failing-test> --timeout 30000\ngit worktree remove \u002Ftmp\u002Frepro-check\n```\n\nIf the failure reproduces on `main`, document it under `## Pre-existing failures`. Do not silently inherit it.\n\n### dist\u002F is generated, not committed\n\n`dist\u002F` is build output and is git-ignored (#1047); do **not** stage or commit it, and\nthere is no `dist-check` drift gate. The authoritative artifact check is `package-check`,\nwhich runs `npm pack` and verifies the packed tarball is complete (type declarations,\ngrammar assets), installs it in a temp project, imports it under Node, and runs the CLI.\n\nA `package-check` failure is a source \u002F build \u002F `package.json#files` problem — fix the\nsource or manifest and rebuild; never \"commit dist to make CI green.\" CI builds `dist\u002F`\nitself (the `unit`, `package-check`, and `smoke` jobs run `bun run build`), and\nrelease\u002Fpublish builds from source.\n\n## Step 4 - Workflow changes\n\nIf any `.github\u002Fworkflows\u002F*.yml` file changed, every third-party `uses:` must be pinned to a full 40-character SHA.\n\n## Step 5 - History shape\n\nBefore opening a PR, verify no local-only files are staged:\n\n```bash\ngit diff --name-only HEAD origin\u002Fmain | grep -E '\\.(local\\.json|vscode|idea)' || true\n```\n\nPrefer a single clean commit for the branch before initial PR publication:\n\n```bash\ngit fetch origin main\ngit log --oneline origin\u002Fmain..HEAD\ngit reset --soft origin\u002Fmain\ngit commit -m \"type(scope): description\"\ngit push --force-with-lease -u origin \u003Cbranch-name>\n```\n\nIf a review cycle is already active and inline comments depend on current SHAs, avoid resquashing until threads are resolved.\n\nIf pushing to a PR branch owned by another agent or bot, push to the PR's actual head branch:\n\n```powershell\n$prBranch = gh pr view \u003Cnumber> --json headRefName --jq '.headRefName'\ngit fetch origin $prBranch\ngit push origin \"\u003Cyour-local-branch>:$prBranch\" --force-with-lease\n```\n\n### Pre-push: Push Protection and Canonical Remote\n\nBefore `git push`, run both checks:\n\n#### Push protection scan\n\nGitHub push protection blocks commits containing literal secret patterns. This bit the\nfirst commit of PR #1472 — a test file with a literal `sk_live_*` Stripe fixture\npattern was pushed before the string-concatenation workaround was applied.\n\n**The primary check (pre-push, after commit exists):**\n\n```bash\ngit log origin\u002Fmain..HEAD -p | grep -E \"$(printf '%s' \"${PREFIX:-sk_live}|ghp_|xox[abprs]-|AKIA|eyJ|AIza\")\" || true\n```\n\n**The optional pre-commit add-on (staged changes only):**\n\n```bash\ngit diff --cached | grep -E \"$(printf '%s' \"${PREFIX:-sk_live}|ghp_|xox[abprs]-|AKIA|eyJ|AIza\")\" || true\n```\n\nForbidden patterns: Stripe (`sk_live_*`), GitHub (`ghp_*`), Slack (`xox[abprs]-*`),\nAWS (`AKIA*`), JWT (`eyJ*`), Google API (`AIza*`).\n\n**The fix:** Construct test fixtures via string concatenation rather than literal\npatterns. For example:\n\n```typescript\n\u002F\u002F Wrong — triggers push protection:\nconst stripeKey = 'sk_live_' + '1234567890abcdefghijklmn'\n\n\u002F\u002F Right — split the literal so it never appears verbatim in source:\nconst stripeKey = 'sk_' + 'live_' + '1234567890abcdefghijklmn'\n```\n\n> **Note:** This scan is a best-effort heuristic. It will not catch deliberately obfuscated patterns (e.g., base64 or hex encoding, runtime string assembly). For genuinely sensitive keys, use environment variables or a secret store — never commit credentials to source.\n\n#### Canonical remote resolution\n\nWhen a repo has multiple remotes (e.g. `zaxbysauce\u002Fopencode-swarm` and\n`ZaxbyHub\u002Fopencode-swarm`), pushing to the wrong remote causes `gh pr create` to\nfail with \"No commits between \u003Ccanonical>:main and \u003Cmirror>:\u003Cbranch>\". This happened\non PR #1472.\n\n**The check:** `git remote -v` before push. Identify the canonical-org remote.\n\n**The rule:** Push to the canonical-org remote explicitly:\n\n```bash\ngit push -u \u003Ccanonical-remote> \u003Cbranch>\n```\n\nCreate the PR against the canonical repo:\n\n```bash\ngh pr create --repo \u003Ccanonical-org>\u002F\u003Crepo>\n```\n\n**Heuristic for identifying the canonical remote:** the canonical remote is the one whose URL points to the owning organization (e.g. `github.com\u002F\u003Corg>\u002F\u003Crepo>.git`), not a personal fork or mirror. When the owning org differs from the local fork's owner, the org-owned remote is canonical. Example: `github.com\u002FZaxbyHub\u002Fopencode-swarm.git` is canonical; `github.com\u002Fzaxbysauce\u002Fopencode-swarm.git` is a personal fork.\n\n## Step 6 - PR creation\n\nPR body requirements:\n\n- `Closes #\u003Cissue-number>` as the first line when the PR resolves an issue\n- `## Summary`\n- `## Invariant audit`\n- `## Test plan`\n\n### Publication-gate evidence\n\nA repository publication gate (`.github\u002Fhooks\u002Fpr-publication-gate.json` ->\n`scripts\u002Fcopilot-pr-publication-gate.sh`) may block `gh pr create`, `gh pr edit`,\nand `gh pr ready` until publication evidence exists. Before publishing, write:\n\n- `.swarm\u002Fevidence\u002Fpr_body.md` — the exact PR body you will publish (must contain\n  `## Summary`, `## Invariant audit`, and `## Test plan`).\n- `.swarm\u002Fevidence\u002Fcommit-pr-validation.md` — the validation commands you ran and\n  their results.\n\nThese files live under `.swarm\u002F` (runtime state, never committed) and double as the\nevidence the gate checks. Keep them current if you edit the PR body or rerun\nvalidation. The CI `pr-standards` check enforces the same body contract server-side.\n\nPowerShell-safe pattern:\n\n```powershell\n$body = @\"\nCloses #\u003Cissue-number>\n\n## Summary\n- \u003Cbullet 1>\n- \u003Cbullet 2>\n\n## Invariant audit\n- 1 (plugin init): not touched - \u003Cevidence>\n\n## Test plan\n- [ ] \u003Cvalidation item>\n\"@\n$utf8NoBom = New-Object -TypeName System.Text.UTF8Encoding -ArgumentList $false\n$prBodyPath = Join-Path ([System.IO.Path]::GetTempPath()) \"pr_body.txt\"\n[System.IO.File]::WriteAllText($prBodyPath, $body, $utf8NoBom)\ngh pr create --title \"\u003Ctype>(\u003Cscope>): \u003Cdescription>\" --body-file $prBodyPath --base main\n```\n\n## Step 6a - PR monitoring subscription\n\nAfter PR creation, if the project uses PR monitoring (`pr_monitor.enabled: true`\nin resolved opencode-swarm config), the new PR must be subscribed for background\nmonitoring:\n\n- **Automatic (default):** when `pr_monitor.auto_subscribe_on_pr_create` is\n  enabled (default `true`), the subscription is created automatically after\n  `gh pr create` succeeds — no command needed. Verify with `\u002Fswarm pr status`\n  if in doubt.\n- **Manual fallback:** when auto-subscribe is disabled or did not fire, run\n  `\u002Fswarm pr subscribe \u003Cpr-url>`, which records the subscription and\n  lazy-starts the polling worker.\n\nThe post-subscription monitoring protocol — event intake, triage\n(fix \u002F ask \u002F skip), bounded-retry escalation, and terminal-state behavior —\nlives in the swarm-pr-subscribe skill (`..\u002Fswarm-pr-subscribe\u002FSKILL.md`).\n\n## Step 6.5 - Issue comment\n\nIf the PR closes an issue, post a comment on the issue. This is mandatory.\n\nThe issue comment must include:\n\n1. the PR link\n2. what changed\n3. how to use it\n4. migration steps or \"No migration required\"\n\nPowerShell-safe pattern:\n\n````powershell\n$comment = @\"\nFixed in PR #\u003Cpr-number>.\n\n## What changed\n- \u003Cbullet 1>\n- \u003Cbullet 2>\n\n## How to use\n```json\n{ \"config\": \"example\" }\n```\n\n## Migration\nNo migration required.\n\"@\n$utf8NoBom = New-Object -TypeName System.Text.UTF8Encoding -ArgumentList $false\n$issueCommentPath = Join-Path ([System.IO.Path]::GetTempPath()) \"issue-comment.txt\"\n[System.IO.File]::WriteAllText($issueCommentPath, $comment, $utf8NoBom)\ngh issue comment \u003Cissue-number> --body-file $issueCommentPath\n````\n\n## Commit messages\n\n`git commit -m \"...\"` with parens, brackets, backticks, or dollar-signs in the message fails on PowerShell because the shell parses them as expressions. Write the commit message to a UTF-8 (no BOM) file first and use `git commit -F \u003Cfile>`.\n\nPowerShell-safe pattern:\n\n```powershell\n$msg = @\"\n\u003Ctype>(\u003Cscope>): \u003Cdescription>\n\n\u003Coptional body — note this is for the git commit message, NOT the PR body>\n\"@\n$utf8NoBom = New-Object -TypeName System.Text.UTF8Encoding -ArgumentList $false\n$commitMsgPath = Join-Path ([System.IO.Path]::GetTempPath()) \"commit-msg.txt\"\n[System.IO.File]::WriteAllText($commitMsgPath, $msg, $utf8NoBom)\ngit commit -F $commitMsgPath\n```\n\nApply this pattern for any commit message containing special characters, multi-paragraph bodies, or code blocks. The plain `git commit -m \"...\"` form remains fine for short single-line messages with no special characters.\n\nIf the PR merged before this was done, post the missing issue comment immediately.\n\n## Step 7 - Existing PR follow-up and closeout\n\nIf a PR already exists for the branch:\n\n1. do not open a second PR\n2. inspect unresolved PR feedback surfaces before updating or readying the PR: review threads\u002Fcomments, requested-changes reviews, CI\u002Fcheck failures, mergeability\u002Fconflicts, and whether check data belongs to the current head SHA\n3. use `..\u002Fswarm-pr-feedback\u002FSKILL.md` when feedback needs fixes before closeout\n4. update the existing PR body when summary, invariant evidence, test counts, caveats, or pre-existing failure notes changed\n5. keep the PR draft while follow-up edits are still expected or required checks are still pending\n6. mark the PR ready only after the body is current and required remote checks are green, unless the user explicitly wants it ready earlier\n7. after any follow-up push or force-push, verify the PR head matches the expected commit and that reported checks belong to the current `headRefOid`:\n\n```powershell\ngh pr view \u003Cnumber> --json headRefOid,body,isDraft,state,mergeable,mergeStateStatus,statusCheckRollup,url\n```\n\nUseful commands:\n\n```powershell\ngh pr edit \u003Cnumber> --body-file \"$env:TEMP\\pr_body.txt\"\ngh pr ready \u003Cnumber>\ngh pr checks \u003Cnumber> --watch --fail-fast\n```\n\n### Conflict closeout\n\nAfter resolving merge conflicts or syncing a stale branch:\n\n1. verify there are no local unmerged paths or conflict markers,\n2. push the conflict-resolution commit,\n3. verify GitHub reports both `mergeable: MERGEABLE` and\n   `mergeStateStatus: CLEAN`, not merely that local markers are gone, and\n4. keep a conflict\u002Fbranch-drift item in the PR closure ledger when it affected\n   the PR.\n\nIf GitHub still reports `DIRTY`, `BLOCKED`, or stale checks after local conflict\nresolution, fetch current `origin\u002Fmain` again and re-evaluate before claiming the\nconflict is resolved.\n\n### GitHub auto-merge race condition\n\nWith a merge queue enabled, prefer queuing over manual freshness rebases, which\navoids this race entirely. It can still occur if you rebase manually: when `main`\nadvances while your PR is open, GitHub's PR sync machinery may **automatically push a\nmerge commit to your branch** in the window between when you fetch and when you push.\nThis is distinct from a conflict — it is GitHub creating a merge commit on your behalf\nwithout rebuilding generated outputs (lockfiles, etc.).\n\nSymptoms:\n- `git push` is rejected with \"fetch first\" even though you just fetched\n- `git log HEAD..origin\u002F\u003Cbranch>` shows a commit authored by GitHub\u002Fthe repo owner with message `Merge branch 'main' into \u003Cbranch>`\n- generated outputs (e.g. lockfiles) on that auto-merge commit are stale because it was not rebuilt\n\nRecovery:\n```bash\ngit fetch origin \u003Cbranch>\ngit log HEAD..origin\u002F\u003Cbranch>   # confirm it's only the GitHub auto-merge\n# Your local commit is correct. Force-push it:\ngit push origin \u003Cbranch> --force-with-lease\n```\n\nAfter force-pushing, verify the PR head SHA updated and cancel any CI run\ntargeting the superseded auto-merge SHA to unblock concurrency:\n\n```powershell\ngh run list --branch \u003Cbranch> --limit 5 --json databaseId,headSha,status,workflowName\ngh run cancel \u003Cstale-run-id>\n```\n\n### Check closeout\n\n`gh pr checks --watch --fail-fast` is useful but can lag or flatten matrix and\ndownstream jobs. When the PR checks view looks stale, missing, or inconsistent,\nuse the workflow run as the authoritative detail:\n\n> **MCP environments:** When using GitHub MCP tools instead of `gh`, prefer\n> `get_check_runs` over `get_status`. The `get_status` method uses GitHub's\n> legacy commit status API: it returns `state: \"pending\"` even when all GitHub\n> Actions jobs are green, because Actions creates check-runs (not legacy\n> statuses). `get_check_runs` returns the actual job results.\n\n```powershell\ngh run view \u003Crun-id> --json headSha,status,conclusion,jobs,url\n```\n\nKeep watching after unit jobs pass; this repository may enqueue integration and\nsmoke jobs later in the same CI run. Do not call the PR green until the current\n`headRefOid` has all required jobs completed successfully.\n\nIf a previous run from an older PR head is still in progress or already failed\nand is blocking the current head's workflow through concurrency, inspect it with\n`gh run view \u003Crun-id> --json headSha,status,conclusion,jobs,url`. Cancel only\nobsolete older-head runs that are no longer relevant to the PR head you are\nvalidating, then wait for the current-head checks to complete.\n\nIf you edit the PR body after checks are green, expect PR Standards \u002F title\nchecks to rerun. Re-check before claiming final green or merge-readiness.\n\n### Merge queue (current-base validation)\n\nWhen `main` has a GitHub **merge queue** enabled, do not rebase or force-push a PR\n*solely because `main` advanced*. Once required checks and review are green, add the\nPR to the merge queue; GitHub re-runs the required workflows against the queued\nchange on top of the latest `main` (and any earlier queued PRs) before merging, so\nmanual \"freshness\" rebases are unnecessary.\n\nStill rebase\u002Fforce-push when there is a **real** reason: a genuine merge conflict,\na stale review thread that depends on current SHAs, or a correctness issue that only\nappears against current `main`. The queue handles up-to-date validation; it does not\nresolve conflicts for you.\n\nRequired workflows trigger on both `pull_request` and `merge_group`. PR-only checks\n(title\u002Fbody validation) no-op to success on `merge_group` because the PR already\nsatisfied them before being queued.\n\n## Step 8 - Cancelled jobs and skipped dependents\n\nIf a required GitHub Actions job is `cancelled` and downstream jobs are `skipped`:\n\n1. inspect the run:\n\n```powershell\ngh run view \u003Crun-id> --json status,conclusion,jobs,url\n```\n\n2. if the cancellation looks like orchestration or infrastructure rather than a code failure, rerun the failed or cancelled jobs:\n\n```powershell\ngh run rerun \u003Crun-id> --failed\n```\n\n3. re-check the PR until required jobs are green:\n\n```powershell\ngh pr checks \u003Cnumber> --watch --fail-fast\n```\n\nDo not call the PR green or merge-ready while a required job is `cancelled`, `skipped`, `in_progress`, or otherwise non-green unless the user explicitly accepts that state.\n\n## Step 9 - Pre-merge checklist\n\n- [ ] invariant audit is complete and current\n- [ ] required build and validation commands ran for touched invariants\n- [ ] `test_runner` was not used with broad repo-validation scopes\n- [ ] release fragment exists and version files are untouched\n- [ ] `dist\u002F` was NOT staged (it is generated output, not committed — #1047)\n- [ ] PR body has `Closes`, `## Summary`, `## Invariant audit`, and `## Test plan`\n- [ ] if this was review follow-up, the PR body was refreshed to match current evidence\n- [ ] if the PR resolves an issue, the issue comment was posted with PR link, what changed, how to use it, and migration notes\n- [ ] if any required job was cancelled and dependent jobs skipped, the run was rerun or the non-green state was explicitly accepted by the user\n- [ ] for high-risk work (security, isolation, IPC, auth, payments, migrations), an independent adversarial review subagent ran before the final substantive push and all confirmed findings were addressed — if this was not done before pushing, run the review now and force-push a corrected commit before marking the PR ready\n- [ ] all required CI checks are green before calling the PR merge-ready\n",{"name":5,"effort":24,"description":25},"medium","Apply when committing, pushing, opening or updating a PR, writing a pull request, creating release notes, or closing out remote CI. Enforces the opencode-swarm invariant audit, release-note fragment workflow, full validation suite, issue comment requirement, and post-PR lifecycle rules.\n","main","1667541871a3a917f9e544e5584ef06a544a119d",".opencode\u002Fskills\u002Fcommit-pr",0,"https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo","https:\u002F\u002Fgithub.com\u002Fdjimit","https:\u002F\u002Fdjimit.nl\u002F","About me\r\n\r\nI’m Dennis a strategic IT advisor specializing in cloud, cybersecurity, privacy, AI, and enterprise architecture. ","2026-11-15 04:42:36",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add djimit\u002Fdjimitflo --skill commit-pr",{"tool":41,"command":42},"bunx","bunx skills add djimit\u002Fdjimitflo --skill commit-pr",{"tool":44,"command":45},"pnpm","pnpm dlx skills add djimit\u002Fdjimitflo --skill commit-pr","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fcommit-pr\u002FSKILL.md",true,[],[50,57,64,71,78,85],{"skillNo":51,"name":52,"nameZh":6,"description":53,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":19},"01M732DRW7MHQP9VTJ5JSBMWC3","provider-step-usage-v1-0-0","Sum measured OpenCode step_finish token totals with replay deduplication and fail-closed validation.","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002Fskills\u002Fprovider-step-usage-v1-0-0\u002FSKILL.md",[],[],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M732DKXHWZ1P99ZDNA4PX7BV","writing-tests","Guidelines for writing, organizing, and maintaining tests in the opencode-swarm repository. Covers framework rules (bun:test), mock isolation, CI pipeline structure, file placement, and anti-patterns that break cross-platform CI. Load this skill before writing or modifying any test file.","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fwriting-tests\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M732DCEG1R9S45A68T5WR2T7","worktree-retry-cleanup","Protocol for cleaning parallel-coder worktree lanes before retry. Triggered before re-dispatching any task that already has a lane (completed, denied, cancelled, or failed).","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fworktree-retry-cleanup\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M732D8KYWE5RHJ1AA76F70K7","swarm","Cross-agent swarm-mode behavior model — a higher-rigor workflow using parallel investigation, independent reviewer validation, and critic challenge, plus the mandatory implementation closeout gate. Runtime adapters (.claude, .agents) add execution-specific notes and command wiring.","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fswarm\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M732D232XCMYP3XYKEAQC3YT","swarm-pr-subscribe","Monitor a pull request after creation and act autonomously on pushed PR activity. Use when subscribing to a PR after opening it, when asked to watch, babysit, or autofix a PR until merge, or when a \u003Cpr-activity> wake message or [pr-monitor:...] advisory arrives for a subscribed PR. Owns event triage (fix \u002F ask \u002F skip), bounded-retry escalation, and terminal-state cleanup.","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fswarm-pr-subscribe\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M732CVKJ4QEN83DQ30EYG75A","swarm-pr-review","Run a graph-guided, tool-augmented Swarm PR review using context packing, parallel exploration, triggered plugin micro-lanes, independent reviewer validation, critic challenge, and metrics writeback. Use for deep pull request review with low false-positive tolerance and high recall.","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fswarm-pr-review\u002FSKILL.md",[],[]]