Commit PR

Commit & PR Protocol

Graph-first evidence contract

Before publication, use repo_map diff_context and impact_cone as a final drift check, then verify the direct source, Git diff, and tests. Graph evidence is advisory only. If freshness is stale or inconclusive, confidence is low, source is missing, the language is unsupported/dynamic, the graph is absent, or an action fails, publication decisions rely on the direct evidence.

Follow every step in order. Do not skip steps.

Step -1 - Mandatory invariant audit

Before any build, test, push, or PR action, read:

1. ../../../AGENTS.md
2. ../../../docs/engineering-invariants.md

For every touched invariant, prepare concrete evidence for the PR body. The PR body must include:

## Invariant audit
- 1 (plugin init): touched / not touched - <evidence>
- 2 (runtime portability): touched / not touched - <evidence>
- 3 (subprocesses): touched / not touched - <evidence>
- 4 (.swarm containment): touched / not touched - <evidence>
- 5 (plan durability): touched / not touched - <evidence>
- 6 (test_runner safety): touched / not touched - <evidence>
- 7 (test writing): touched / not touched - <evidence>
- 8 (session state): touched / not touched - <evidence>
- 9 (guardrails/retry): touched / not touched - <evidence>
- 10 (chat/system msg): touched / not touched - <evidence>
- 11 (tool registration): touched / not touched - <evidence>
- 12 (release/cache): touched / not touched - <evidence>

If a touched invariant cannot be proven from source and test output, do not push.

Required validations for touched invariants

If invariants 1, 2, or 3 are touched, run all three:

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

If invariant 3 is touched, audit changed source files for subprocess use:

git diff --name-only origin/main..HEAD | xargs -r grep -nE "bunSpawn\(|spawn\(|spawnSync\(" || true

If invariant 11 is touched, run:

bun --smol test tests/unit/config --timeout 60000
for f in tests/unit/tools/*.test.ts; do bun --smol test "$f" --timeout 30000; done

If invariant 7 is touched, confirm the writing-tests skill was loaded and that new test seams avoid leaking mock.module.

Step 0 - Session start hygiene

Run before publication work:

git fetch origin main
rm -f .swarm/evidence/pr_body.md
rm -f .swarm/evidence/commit-pr-validation.md
rm -f .swarm/evidence/publication-evidence.json
git status --short

Delete ONLY those three exact publication-cache files. NEVER broad-delete .swarm/evidence/*.json — that directory also holds authoritative task/gate evidence ({taskId}.json), final-council.json, and phase-council records (issue #2131 finding 4a).

On Windows, prefer temporary save branches over git stash. If you must stash, use git stash push --include-untracked and verify the stash contents.

If this changeset edited any SKILL.md file's wording, also run file:.swarm/bundled-skills/skill-edit-validation/SKILL.md's content-assertion sweep before committing, to catch stale test assertions.

Step 1 - Commit and PR titles

Use conventional commit format <type>(<scope>): <description> exactly.

• description is lowercase and does not end with a period
• allowed types: feat, fix, perf, revert, docs, chore, refactor, test, ci, build

Choose the PR title type by the main change:

• new capability -> feat
• bug fix only -> fix
• docs or chore only -> non-bump types

The squash merge commit message must match the PR title exactly.

Note: The PR title MUST follow <type>(<scope>): <description> 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.

Step 2 - Release note fragment

Create a pending release fragment and do not calculate a version manually.

Required file shape:

docs/releases/pending/<unique-slug>.md

The fragment should cover:

• what changed
• why
• migration steps, if any
• breaking changes, if any
• known caveats

Ground-truth verification (mandatory)

Before finalizing a release note fragment, verify every concrete reference against the actual codebase:

• File paths: grep -r "path/to/file" — confirm each referenced file exists at the stated path.
• Script names: check package.json scripts or scripts/ directory.
• Attribute/variable names: grep for the exact identifier in src/.
• Environment variables: grep for the exact name in src/ and config.

Remove or correct any reference that does not resolve. AI-generated fragments frequently hallucinate paths and names — this step is not optional.

Bot authors (e.g. [bot], Copilot) and docs/workflow/meta-only changes (no src/, tests/, scripts/, package.json, etc.) are exempt from this requirement by CI; all other PRs that touch code must include a fragment.

Do not manually edit:

• package.json version
• CHANGELOG.md
• .release-please-manifest.json — exception: reconciliation when the manifest desyncs from actual releases (see below)

For the full release-please manifest desync diagnosis and fix protocol, read references/pr-incident-playbook.md.

Step 3 - Mandatory validation suite

Run 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.

Pre-flight

dist/ is not committed (#1047) — do not stage it. Confirm the build succeeds:

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

Tier 1 - quality

Run both linter AND formatter — e.g., bunx @biomejs/biome@<version> 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/biome); unversioned bunx biome resolves to a different version than the CI gate uses. (the repo script bun run lint:ci runs the pinned Biome version; prefer it over invoking bunx biome directly).

bun run typecheck
bun run lint:ci
bun run scripts/check-tool-registration.ts
bun run check:mock-cleanup
bun run check:invariants
bun run check:cross-contamination
bun run check:test-clock
bun run check:runtime-src-refs
bun run check:events
bun run check:retention
bun run check:registry-citations
bun run check:core-events
bun run check:shell-audit
bun run check:trajectory-store
bun run check:test-file-cap
bun run scripts/check-vacuous-assertions.ts
bun run check:pending-fragment
bun run check:gate-portability
bun run check:bare-spawn
bun run scripts/check-config-consumption.ts
bun run check:test-tmpdir
bun run check:bash-portability
bun run check:error-channel-discard
bun run check:path-identity
bun run check:token-formula
(cd scripts/swarm-model && node --test)
bun run package:smoke

The CI quality job also fails closed when either required dependency is not successful before running the expensive checks:

if [[ "$DETECT_RELEASE_RESULT" != "success" || "$RELEASE_OWNER_RESULT" != "success" ]]; then
  echo "::error::required dependency failed: detect-release=$DETECT_RELEASE_RESULT, release-owner-guard=$RELEASE_OWNER_RESULT"
  exit 1
fi

This list is the FULL blocking CI quality contract (issue #2131 finding 4c): every quality-job step in .github/workflows/ci.yml plus the package:smoke pack check. tests/unit/skills/commit-pr-validation-parity.test.ts derives the list from the workflow — if CI adds a quality step, the parity test fails until this skill teaches it.

Tier 2 - unit tests

bun run test:unit:ci               # CI-equivalent unit gate (quarantine ledgers + retry budget)
bun run test:unit:ci <file>...     # scoped mode: run only the listed repo-relative test files

bun run test:unit:ci runs scripts/ci/run-unit-tests-local.ts, the CI-equivalent unit gate with per-platform quarantine ledgers (scripts/ci/quarantined-tests.txt, quarantined-tests-macos.txt, quarantined-tests-windows.txt) and the retry budget. The full serial run is 45–90 min, so use the scoped mode (bun run test:unit:ci <file>...) when the evidence justifies narrowing (e.g. you only touched one module). This closes the gap the hand-rolled loops left (~40% of CI's colocated src/** tests were uncovered).

Tier 3 - integration

bun test tests/integration ./test --timeout 120000

Tier 4 - security and adversarial

bun test tests/security --timeout 120000
bun test tests/adversarial --timeout 120000

Tier 5 - smoke

bun test tests/smoke --timeout 120000

Pre-existing failure handling

If a failure looks unrelated, prove it on clean origin/main before carrying it into the PR body:

git worktree add /tmp/repro-check origin/main
cd /tmp/repro-check
bun install --frozen-lockfile
bun run build
bun --smol test <repo-relative-path-to-failing-test> --timeout 120000
cd ..
git worktree remove /tmp/repro-check

If the failure reproduces on main, document it under ## Pre-existing failures. Do not silently inherit it.

dist/ is generated, not committed

dist/ is build output and is git-ignored (#1047); do not stage or commit it, and there is no dist-check drift gate. The authoritative artifact check is package-check, which runs npm pack and verifies the packed tarball is complete (type declarations, grammar assets), installs it in a temp project, imports it under Node, and runs the CLI.

A package-check failure is a source / build / package.json#files problem — fix the source or manifest and rebuild; never "commit dist to make CI green." CI builds dist/ itself (the unit, package-check, and smoke jobs run bun run build), and release/publish builds from source.

Step 4 - Workflow changes

If any .github/workflows/*.yml file changed, every third-party uses: must be pinned to a full 40-character SHA.

Step 5 - History shape

Before opening a PR, verify no local-only files are staged:

git diff --name-only HEAD origin/main | grep -E '\.(local\.json|vscode|idea)' || true

Prefer a single clean commit for the branch before initial PR publication. Resolve the canonical remote first (see "Canonical remote resolution" below), then squash/push:

git fetch <canonical-remote> <base-branch>
git log --oneline <canonical-remote>/<base-branch>..HEAD
git reset --soft <canonical-remote>/<base-branch>
git commit -m "type(scope): description"
git push --force-with-lease -u <canonical-remote> <branch-name>

If a review cycle is already active and inline comments depend on current SHAs, avoid resquashing until threads are resolved.

If pushing to a PR branch owned by another agent or bot, push to the PR's actual head branch:

$prBranch = gh pr view <number> --json headRefName --jq '.headRefName'
git fetch <canonical-remote> $prBranch
git push <canonical-remote> "<your-local-branch>:$prBranch" --force-with-lease

Fork PR workflow approval

If the PR is from a fork (head repository differs from base repository), GitHub requires explicit workflow approval after every push. CI jobs will remain in "waiting" status until approved:

# List pending runs
gh run list --repo <upstream-owner>/<upstream-repo> --branch <branch-name> --limit 5

# Approve the pending run
gh api -X POST repos/<upstream-owner>/<upstream-repo>/actions/runs/<run-id>/approve

This requires actions: write permission on the base repository. See the fork-pr-operations skill for the full protocol including race conditions, permission requirements, and stale CI verification.

Pre-push: Push Protection and Canonical Remote

Before git push, run both checks:

1. Push protection scan — scan for literal secret patterns that trigger GitHub push protection:

   git log origin/main..HEAD -p | grep -E 'sk_live|ghp_|xox[abprs]-|AKIA|eyJ|AIza' || true

2. Canonical remote resolution — push to the canonical-org remote, not a personal fork:

   git remote -v   # identify the org-owned remote
   git push -u <canonical-remote> <branch>

For full details, patterns, workarounds, and anecdotes, read references/pr-incident-playbook.md.

Step 6 - PR creation

Before generating the PR body, read .swarm/issue-reference.json. If it exists and contains a number field, auto-populate Closes #<number> as the first line of the PR body. If the file does not exist, fall back to the Closes #<issue-number> placeholder.

PR body requirements:

• Closes #<issue-number> as the first line when the PR resolves an issue
• ## Summary
• ## Invariant audit
• ## Test plan

CI enforces both the section ORDER (Summary, then Invariant audit, then Test plan) and that each heading is on its own line with nothing trailing but whitespace (see .github/workflows/pr-standards.yml).

Publication-gate evidence

A repository publication gate (.github/hooks/pr-publication-gate.json -> scripts/copilot-pr-publication-gate.sh) may block gh pr create, gh pr edit, and gh pr ready until publication evidence exists. Before publishing, write:

• .swarm/evidence/pr_body.md — the exact PR body you will publish (must contain ## Summary, ## Invariant audit, and ## Test plan).

• .swarm/evidence/commit-pr-validation.md — the validation commands you ran and their results.

• .swarm/evidence/publication-evidence.json — the versioned, freshness-bound receipt (issue #2131 finding 4b). The gate verifies it against the CURRENT git state and the EXACT body being published:

  BODY_SHA256=$(sha256sum .swarm/evidence/pr_body.md | cut -d' ' -f1)
  cat > .swarm/evidence/publication-evidence.json <<EOF
  {
    "schema_version": 1,
    "state": "validated",
    "repository": "$(git remote get-url origin)",
    "head_sha": "$(git rev-parse HEAD)",
    "body_sha256": "$BODY_SHA256",
    "validation_commands": ["bun run typecheck", "bun run lint:ci"],
    "recorded_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
  }
  EOF

  pr_number may be added once the PR exists (for gh pr edit / gh pr ready). If HEAD changes, the body is edited, or you rerun validation, REGENERATE this receipt — a stale or mismatched receipt is rejected by the gate.

These files live under .swarm/ (runtime state, never committed) and double as the evidence the gate checks. Keep them current if you edit the PR body or rerun validation. The CI pr-standards check enforces the same body contract server-side.

PowerShell-safe pattern:

$refPath = ".swarm/issue-reference.json"
$closesLine = if ((Test-Path $refPath) -and ($ref = Get-Content $refPath -Raw | ConvertFrom-Json) -and $ref.number) {
    "Closes #$($ref.number)"
} else {
    "Closes #<issue-number>"
}
$body = @"
$closesLine

## Summary
- <bullet 1>
- <bullet 2>

## Invariant audit
- 1 (plugin init): not touched - <evidence>

## Test plan
- [ ] <validation item>
"@
$utf8NoBom = New-Object -TypeName System.Text.UTF8Encoding -ArgumentList $false
$prBodyPath = Join-Path ([System.IO.Path]::GetTempPath()) "pr_body.txt"
[System.IO.File]::WriteAllText($prBodyPath, $body, $utf8NoBom)
gh pr create --title "<type>(<scope>): <description>" --body-file $prBodyPath --base main

Issue-trace publication receipt

If this session is running an issue trace (/swarm issue --trace), call record_issue_publication with the issue number, PR number, URL, and HEAD sha immediately after gh pr create (or after gh pr edit / gh pr ready for an existing PR). This is what lets the issue-trace workflow reach its terminal published state — without it the trace stays at publication_handoff and is NOT considered resolved.