# Filing Pull Requests

> **Related**: [filing issues](./filing-issues.md), [versioning](./versioning.md), kernel skill `aiwg-pr` (run `aiwg show skill aiwg-pr`)

A high-quality PR is focused, verified, policy-compliant, and reaches `main` with green CI. This guide covers the AIWG-specific delivery rules — branching strategy, the no-attribution rule, the CI-green-before-done discipline, and the release-time obligations.

---

## Pre-flight: delivery policy

**Before you create a branch or open a PR**, read the project's `.aiwg/aiwg.config` `delivery.mode`. Three modes, three workflows:

| Mode | Branch | PR | Closing |
|---|---|---|---|
| `direct` | No — commit straight to `default_branch` | **No PR** | `Closes #N` in commit message |
| `feature-branch` | Branch per issue | No PR | `Closes #N` in commit on the branch |
| `pr-required` | Branch per issue | **Required** | `Closes #N` in PR body |

```bash
aiwg config get --project delivery.mode
# or
cat .aiwg/aiwg.config | jq -r '.delivery.mode'
```

**If `mode: direct`, do not open a PR.** Commit directly to `main` with `Closes #N` in the message. The [`delivery-policy`](https://github.com/jmagly/aiwg/blob/main/agentic/code/addons/aiwg-utils/rules/delivery-policy.md) rule (kernel rule, always loaded) is authoritative.

The AIWG repo runs in `direct` mode — the May-2026 fix sweep (commits `6500e167`, `497fcca7`, `3f2b557b`, `d052aa2f`, `a50c1d76`, `ac61a2b8`) landed straight to `main` with `Closes #N` per commit.

---

## The walkthrough

### 1. Find or file the issue first

Every PR closes (or refs) an issue. If you don't have one:

- Search for existing matches: `aiwg run skill steward-prep-delivery -- "<topic>"`
- If none match, file via [filing issues](./filing-issues.md) before drafting the PR

### 2. Branch (only for non-direct modes)

```bash
git checkout -b fix/{issue-number}-{slug}
# slug: short, lowercase, hyphenated derivation of the issue title
```

For `direct` mode, skip this step.

### 3. Make the change

Stay focused on the linked issue. Anti-patterns to avoid:

- **"While I'm at it"** — adding unrelated changes. Split into separate PRs/commits.
- **Reformatting unrelated files mid-PR** — send formatting as its own PR.
- **Adding new dependencies without justification** — note why in the PR body.

### 4. Verification (REQUIRED before commit)

| Check | Command | Pass criterion |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | Clean (no output) |
| Tests | `npm test` | All pass (or only pre-existing flaky perf tests fail; document the latter) |
| Lint | `npm exec markdownlint-cli2` (for docs) | Clean |
| Build | `npm run build:cli` | Succeeds (catches `dist/` vs `src/` path drift) |

Don't skip these. The CI-failure-then-fix cycle in `497fcca7` → `3f2b557b` was caused by skipping the local test run before push. Two pushes, one wasted CI cycle, easily prevented.

### 5. Commit message

Use **conventional commits**: `type(scope): subject`

```
fix(area): one-line subject

Body explains WHY, not just what. The diff already shows what.
Reference the linked issue; for `direct` mode include `Closes #N`
so the issue auto-closes on push.

Verification:
- npx tsc --noEmit clean
- npm test — 6306 pass, 1 pre-existing flake (cli-perf cold-start)
- Manual: <smoke-test description>

Closes #N
```

Conventional commit types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`, `ci`, `build`. Scope is the area (e.g., `steward`, `sdlc,release`, `cli,docs`).

### 6. No AI attribution

The project [no-attribution rule](https://github.com/jmagly/aiwg/blob/main/agentic/code/addons/aiwg-utils/rules/no-attribution.md) is universal across platforms. The commit/tag/PR body **must not** contain:

- `Co-Authored-By: Claude <…>` (or any AI tool)
- `Generated with [Claude Code]` / "Generated by Codex" / "Written by GitHub Copilot"
- 🤖 emoji or any tool branding

The AI is a tool. Tools don't sign their output.

### 7. Push

For this repository, follow [WORKSPACE.md, "Commit identity and attribution"](../../WORKSPACE.md#commit-identity-and-attribution):
author and committer must both be `Joseph Magly <1159087+jmagly@users.noreply.github.com>`,
with a valid GPG signature from `25BEE160811F66FD6F7B1BF0454C68C4A2174CE9`.
Merge locally with a signed `--no-ff` merge (the configured local merge helper is
`aiwg run skill aiwg-pr -- merge <number>`), then push through `tools/git/push-origin-as-roctinam.sh`
and close the PR. Never use the Gitea web button or merge API.

The CI Test job checks identity, signatures and the push helper's attribution rules
immediately after checkout on push events (#3838). It imports the public keys from
`.gitea/keys/maintainers.asc` into a temporary `GNUPGHOME`, then checks only
`before..after`, including side-branch commits. A missing or zero `before` uses
the pushed head's first parent; a root head is checked alone. An unavailable
nonzero base fails the check. Earlier history and the accepted #3837 exceptions
are excluded when they precede the range. Every offending commit is reported
with its SHA, author, committer and signature status before CI fails.
Manual dispatch has no push range and skips this step. This detects violations
after a push; disabling server-side merges remains a separate repository setting.

```bash
# For direct mode
tools/git/push-origin-as-roctinam.sh main

# For feature-branch / pr-required
tools/git/push-origin-as-roctinam.sh fix/{issue-number}-{slug}
```

### 8. Open the PR (only for pr-required mode)

Use the template at [`.gitea/pull_request_template.md`](https://git.integrolabs.net/roctinam/aiwg/src/branch/main/.gitea/pull_request_template.md) (or [`.github/pull_request_template.md`](https://github.com/jmagly/aiwg/blob/main/.github/pull_request_template.md)). Required sections:

- **Summary** — one paragraph: what changed and why
- **Linked issues** — `Closes #N` / `Refs #N`
- **Changes** — bullets of meaningful changes (not file count)
- **Verification** — filled-in checklist showing typecheck/test/CI status
- **Risk and rollback** — even if "low / git revert"
- **Policy reminders** — delivery mode + no-attribution + CI-green-before-done

The body should be **agent-readable**: clear sections, specific paths, no marketing speak.

### 9. Verify locally, then CI after merge

Pull requests do not run CI. Build and test on your workstation before opening and merging the PR (typecheck, `npm run build:cli`, and the touched vitest files plus neighbours with `--config config/vitest.config.js`), and list the commands and counts in the PR's Verification section.

CI runs on `origin` (Gitea) after the merge, on the push to `main`. Work isn't done until that run is green.

If it fails:

1. Diagnose the failure
2. **Fix the underlying issue** — no `|| true`, no `continue-on-error: true`, no test deletion. See [`anti-laziness`](https://github.com/jmagly/aiwg/blob/main/agentic/code/addons/aiwg-utils/rules/anti-laziness.md) and [`dev-pipeline-safety`](https://github.com/jmagly/aiwg/blob/main/agentic/code/frameworks/sdlc-complete/rules/dev-pipeline-safety.md) rules.
3. Open a fix PR, verify it locally, merge it, and wait for the next `main` run
4. Don't declare the work done until `main` is green

**Never leave `main` in a red state.**

### 10. After merge (pr-required) or push (direct)

- The linked issue auto-closes via `Closes #N`
- If you imported a cross-tracker report, **thank the original reporter** in a closing comment on the source tracker (see [filing issues § import flow](./filing-issues.md#import-flow-cross-tracker-reports))
- Update [`CHANGELOG.md`](https://github.com/jmagly/aiwg/blob/main/CHANGELOG.md) if the change is user-visible — for releases, the [`flow-release`](https://github.com/jmagly/aiwg/blob/main/agentic/code/frameworks/sdlc-complete/skills/flow-release/SKILL.md) skill handles this; for individual PRs that ship before the release, append to the unreleased section

---

## Release-time PRs

When the PR is part of a release sequence, the [`flow-release` skill](https://github.com/jmagly/aiwg/blob/main/agentic/code/frameworks/sdlc-complete/skills/flow-release/SKILL.md) handles the orchestration. The PR itself follows the same rules as any other PR, but the release flow adds extra gates:

- Version bump (`package.json` + `CHANGELOG.md` + `docs/releases/v{version}-announcement.md`)
- UAT for stable channel: `npm run uat` — all 9 tests must pass
- Tag creation, push to origin, optional GitHub mirror push
- npm dist-tag promotion

See [`flow-release`](https://github.com/jmagly/aiwg/blob/main/agentic/code/frameworks/sdlc-complete/skills/flow-release/SKILL.md) for the full sequence. The `.aiwg/release.config` declares which gates apply.

---

## Anti-patterns to avoid

- **AI attribution lines** — never. Universal rule.
- **`--no-verify` or `--no-gpg-sign`** — never bypass hooks. Fix the underlying issue.
- **`continue-on-error: true` on tests** — never silence the smoke detector. See [`dev-pipeline-safety`](https://github.com/jmagly/aiwg/blob/main/agentic/code/frameworks/sdlc-complete/rules/dev-pipeline-safety.md).
- **Skipping CI green wait** — if CI fails, fix it before declaring done.
- **Bundling unrelated changes** — split into focused PRs.
- **Workarounds instead of root-cause fixes** — see [`anti-laziness`](https://github.com/jmagly/aiwg/blob/main/agentic/code/addons/aiwg-utils/rules/anti-laziness.md) Rule 9: "real fix over workaround".
- **`Closes #N` in a PR body for `direct` mode** — wrong; use the commit message instead.

---

## When stuck

If the verification gates fail and you can't fix them in 3 attempts, **escalate** per the [`anti-laziness`](https://github.com/jmagly/aiwg/blob/main/agentic/code/addons/aiwg-utils/rules/anti-laziness.md) recovery protocol. Don't take destructive shortcuts (skip tests, weaken assertions, etc.).

---

## Quick reference

| Need to | Run |
|---|---|
| Check delivery mode | `aiwg config get --project delivery.mode` |
| Verify locally before push | `npx tsc --noEmit && npm test && npm run build:cli` |
| Run UAT (release prep) | `npm run uat` |
| Fetch full PR guide | `aiwg show skill aiwg-pr` |
| Drive a release | `aiwg show skill flow-release` |

## Related

- **In-context kernel skill**: `aiwg-pr` (always loaded; same content as this doc, accessible to agents)
- **Issue companion**: [filing issues](./filing-issues.md)
- **Templates**: [`.gitea/pull_request_template.md`](https://git.integrolabs.net/roctinam/aiwg/src/branch/main/.gitea/pull_request_template.md), [`.github/pull_request_template.md`](https://github.com/jmagly/aiwg/blob/main/.github/pull_request_template.md)
- **Rules**: [`delivery-policy`](https://github.com/jmagly/aiwg/blob/main/agentic/code/addons/aiwg-utils/rules/delivery-policy.md) (kernel), [`no-attribution`](https://github.com/jmagly/aiwg/blob/main/agentic/code/addons/aiwg-utils/rules/no-attribution.md) (core), [`anti-laziness`](https://github.com/jmagly/aiwg/blob/main/agentic/code/addons/aiwg-utils/rules/anti-laziness.md), [`dev-pipeline-safety`](https://github.com/jmagly/aiwg/blob/main/agentic/code/frameworks/sdlc-complete/rules/dev-pipeline-safety.md)
- **Release flow**: [`flow-release`](https://github.com/jmagly/aiwg/blob/main/agentic/code/frameworks/sdlc-complete/skills/flow-release/SKILL.md)
- **Versioning**: [versioning policy](./versioning.md)
- **Origin**: #1269 (templates infrastructure), #1264–#1268 (tester report sweep that codified this pattern)
