steward

Steward: driving a QRCraftly PR to merged

AGENTS.md holds the invariants and RELEASING.md holds the release flow. This skill is the loop for one PR. Where they disagree, they win.

Before the first push

1. Branch from current main with a prefix: feat/, fix/, docs/, refactor/, chore/, agent/, or claude/ for the branch a Claude session is given.
2. While you work, use the targeted commands in the "Fast loop" section of AGENTS.md. Before pushing, run the checks a contributor runs locally, in this order, and fix everything:
   • pnpm run lint
   • pnpm test -- --run
   • pnpm build when the change touches the build, routing, the generator or public/
   • pnpm test:e2e when the change touches navigation, rendering or input flows
3. Run pnpm run docs:sync after changing anything in src/components/ui/, src/components/inputs/, src/components/style-controls/, docs/public/ or docs/SECURITY.md, and commit what it writes.
4. If you touch a file in MAPPING in scripts/git_lineage_auditor.js, update the paired doc in the same PR.

Opening the PR

• The title is a Conventional Commit (fix(scanner): handle empty frames). It becomes the squash commit and drives the version bump, so pick feat versus fix deliberately.
• The base is always main. There is no dev branch.
• Open it as a draft and keep it there until it is done. CI minutes are metered (ADR 0050): drafts skip unit tests, E2E and Lighthouse, and ready PRs run Chromium E2E only.
• Add the full-e2e label when the change may behave differently in Firefox or WebKit (and on a release PR whose branch does not start with release/). Add it before the push or ready toggle that should use it: main.yml does not run on labeled, so a label added later changes nothing until the next push or draft-to-ready toggle.
• Write one closing keyword per issue (Closes #12. Closes #13.). In Closes #12, #13 GitHub closes only #12.
• Prefer one complete, tested PR over a chain of small ones. Every merge deploys to production.

Getting it green

The required checks are CI, PR Title and Workers Builds: qrcraftly.

• Out of date with main: merge main into the branch (never rebase or force-push a branch someone else owns), re-run the local checks, push.

• CI red: open the failing job's log, reproduce the failure locally, fix the root cause, show the same check passing, push. A failing test is never an infra flake until you have shown it fails the same way on main.

• Workers Builds: qrcraftly red: the Cloudflare build runs pnpm run build; reproduce it with pnpm build.

• Bundle size: CI runs pnpm run check-bundle-size after the build. Shrink the change rather than raising the budget.

• Never skip, disable or quarantine a test, push an empty commit, or close and reopen a PR to re-trigger CI.

• Visual baselines: screenshots taken locally or in a cloud session never match CI's fonts. For a PR that moves layout on purpose, add full-e2e, then the update-snapshots label; .github/workflows/update-snapshots.yml commits refreshed baselines to the branch. CI runs on that bot commit wait as action_required until a maintainer approves them.

Reviews

• Fix small, local review asks (nits, renames, an added test) and push.
• Larger asks on someone else's PR: reply with a proposal and let the author decide.
• Resolve the threads you addressed.

Merging

• Merge only when every required check is green on the current head. Local checks alone never justify a merge.
• The maintainer merges. Never merge a PR or enable auto-merge on one unless the maintainer has said so in words for that PR (ADR 0020, amendment).
• Once the PR is complete and every required check is green on the current head, mark it ready for review and tell the maintainer it is ready. Remember that marking a PR ready starts the full CI tier, so let that run finish green before saying so.
• Never enable auto-merge on, or merge, a chore(release): vX.Y.Z PR, even when asked to merge others. A maintainer merges those by hand.
• No admin bypass of the main ruleset.

Merge conflicts

• Merge main into the branch; never rebase or force-push a branch you did not create.
• Regenerate lockfiles, docs/public/UI_CATALOG.md (pnpm run docs:sync) and other generated files with their tools, never by hand.
• When both sides changed the same logic, keep both behaviours if they are compatible. If keeping one loses the other, stop and ask the PR's owner.
• Re-run the local checks before pushing the merge.

Merge queue

GitHub's merge queue needs an organization-owned repository, so it is not on yet (ADR 0051). The workflows already run on merge_group. Once .github/rulesets/main-merge-queue.json is imported, auto-merge adds a PR to the queue, branches no longer need updating, and a PR that fails in the queue is removed from it: fix it and tell the maintainer, who re-queues it.

After the merge

Check that Verify Production Deployment (deploy-verify.yml; CI does not re-run on main) and the Workers Builds: qrcraftly check pass on the merge commit before merging the next PR. curl -s https://qrcraftly.com/version.json shows which commit production serves. If production broke, roll back in Cloudflare first, then fix forward with a PR (see RELEASING.md).

Things a PR must never add

Ads, analytics, telemetry, diagnostics pings or third-party scripts (docs/PLEDGE.md); server-side redirects, D1 or Turnstile (dynamic QR codes were dropped for good); user input sent over the network or put in URL query strings; new persistent storage keys outside the allowlist in AGENTS.md.