diff --git a/.agents/skills/github-prs/SKILL.md b/.agents/skills/github-prs/SKILL.md index 33c11e6..4a9d8ea 100644 --- a/.agents/skills/github-prs/SKILL.md +++ b/.agents/skills/github-prs/SKILL.md @@ -1,106 +1,37 @@ --- name: github-prs -description: How every agent verifies and attests locally (`make ci-local RAN="…"`), opens, stacks and merges pull requests in this repo, fast. Use before any `git commit`, `gh pr create`, `gh pr merge`, retargeting or rebasing a stacked PR, or re-running a check, and whenever you are about to wait on CI, write a merge script, or merge PRs "one at a time". +description: How every agent opens, stacks and merges pull requests in this repo, after verifying with the local-ci skill. Use before any `gh pr create`, `gh pr merge`, retargeting or rebasing a stacked PR, and whenever you are about to wait on CI, write a merge script, or merge PRs "one at a time". --- -# Pull requests: run what you need, attest, stack, merge at once +# Pull requests -Run the checks your change needs (lint, tests, build), then attest with `make ci-local RAN="…"` and merge right away. `make ci-local` runs nothing: it tells the PR you checked, and what. GitHub runs no verification on `main`, and on a PR only two small jobs that check the attestation. Stack PRs and merge each the moment it is attested; after the merge, check its staging deploy. +Verify and attest first: the [local-ci](../local-ci/SKILL.md) skill. -The rules on what may merge are in `AGENTS.md` ("Verifying", "Pull requests", "Environments: staging is always current"). This skill is how you do it. +## Open -## 1. Before every commit +- `gh pr create --base ` from `.github/pull_request_template.md`, ready (never draft), no labels. +- Title: a conventional commit in plain language (`fix(api): PATCH /users no longer drops the image`). Body: the problem in a sentence or two, then the fix; UI changes need before/after images. The body ends with the attribution line. +- One concern per PR; push follow-ups to the same branch. Never close and reopen a PR. -- **Never skip the hooks.** `make hooks` installs the pre-push hook (`make check-fast`); when it fails, fix what it found and push again; never skip it. -- **Default: `make check-pr`.** It runs what the branch's changes need (the table is in `scripts/check-pr.sh`), fails when the affected-package selection does not match the diff, and prints the `make ci-local RAN="…"` line to attest with. By hand: `make lint LINT_DIRS=` and `make test TEST_PKGS=` for the Go packages it can affect (`scripts/affected.sh` prints them; `make check-fast` is the seconds-long pass), `make check-generated` for sqlc, templ or mock inputs, `make check-migrations` for a migration, `make deploy-check` for `deploy/`, `make actionlint` for workflows, `make release-smoke` for a Dockerfile or what it builds, `make ci` for a change to the tooling. In a Davit box, `make box-ci COMMIT=` runs check-generated, lint, build and test on exactly that commit and prints one PASS/FAIL line; never hand-write an inline `davit box run -- bash -lc "... rm ..."`. Tests only at the test boundaries (`AGENTS.md`, "Test boundaries"); never a test in `deploy/` or the UI. -- A change adds no lint or format findings, warnings included. -- Add the paths you changed; never `git add -A` in an old worktree. +## Stack -## 2. Attest: `make ci-local RAN="…"` +- Needs nothing unmerged: base `main`. Needs an open PR: base that PR's branch. +- `make pr-merge` retargets children to `main` before their parent merges. Then `git rebase --onto origin/main `, `git push --force-with-lease`, attest. -After **every** push or rebase, once you have run what the change needs: +## Merge ```bash -git push # pushed head, clean worktree -make check-pr # runs what the change needs, prints the RAN line -make ci-local RAN="make lint LINT_DIRS='./apps/web/internal/services ...'; make test TEST_PKGS='...'; make secret-scan" -``` - -- It runs nothing and takes seconds. It refuses a dirty worktree, a detached HEAD (except `COMMIT=` of a `main` commit), a head that is not the pushed branch head, or a head that already has a failed `local-ci`. -- It posts `local-ci` on that exact SHA and fills the PR body's **Local verification** section (head, who, and your statement). **Never edit the section by hand:** the status carries its digest. -- **One attestation, one commit.** Any push, amend or rebase needs a new one. No PR yet? Open it (section 3) and run it again. -- **Something failed?** Fix it before attesting. If you attest a failure (`make ci-local FAILED=""`), that head is final: fix forward with a new commit. Code this PR touched: fix it here. Anything else: its own PR off `main` with a test that fails before the fix, then rebase. Add the prevention. -- Say exactly what ran; a reviewer reads the scope from it. - -## 3. Open and stack - -- `gh pr create --base ` with `.github/pull_request_template.md`, open and ready, no labels: problem, fix, and the Local verification section. Conventional commit title; the body ends with the attribution line. -- **Base per layer.** Needs nothing unmerged: base `main`. Needs an open PR: base that PR's branch. Independent work gets its own PR on `main`. -- One concern per PR; push follow-ups to the same branch. **Never close and reopen a PR.** - -## 4. What PR CI and the merge script refuse - -PR CI runs only `Secret scan` and `Local verification`, the two checks the main ruleset requires, on the `CI_RUNNER` runner. It runs only on a PR body edit, and until `make ci-local` claims the head (posts `local-ci` or fills the section for it) the check runs as `Awaiting make ci-local`, so the required one shows **Expected**, not red; red is a real problem. `Local verification` and `make pr-merge` share one rule (`scripts/cilocal/verify`, `LocalVerificationProblems`): - -| Refused because | Fix | -|---|---| -| no `local-ci` status on the head (never attested, or a new push) | run what it needs, `make ci-local RAN="…"` | -| `local-ci` is `failure`, or failed on this head before | fix forward with a new commit, push, attest | -| no Local verification section, it names another head or no "Ran:" | `make ci-local RAN="…"` | -| the section is not the attested one (edited by hand) | `make ci-local RAN="…"` again restores it | -| `Secret scan` found a credential | remove it (rotate it if real), push, attest | -| it conflicts with `main` | rebase onto `main`, push, attest | - -`make ci-local` posts the status before it edits the body, and that edit starts the PR run, so you never re-run `Local verification` by hand; when the body was already current, `make ci-local` re-runs the run itself. - -## 5. Merge - -```bash -make pr-merge PR=" [ ...]" # merges every green PR now, reports the rest +make pr-merge PR=" [ ...]" # merges every attested, green PR now, reports the rest make pr-merge PR= ARGS=--dry-run # says what it would do +make land PR= # rebase, make ci-pg, attest and merge inside one hold of the CI lock ``` -- **Green** means `local-ci` and the section attest the exact head, GitHub can merge it without conflicts, and the checks passed. It squash-merges with `--match-head-commit `, so only the attested head lands. A head behind `main` is refused ("rebase onto origin/main and re-attest"): the merged tree must be the one you verified. Where Actions cannot run (no CI job ran, or GitHub never started them), it merges on `local-ci` alone and says so. -- Anything else (draft, unattested, pending, failing, conflicting, stacked) is reported with its next step; the script never waits. A head behind `main` or a conflict needs rebase, push, run what it needs, attest; after each merge in a burst, rebase the next PR. -- **After each merge, check its deploy** (a follow-up, never a gate; merge the next PR now): it prints `make pr-merge ARGS="--check-deploy "`. Run it once "Deploy staging" has run for that commit. Failed or refused: top priority, fix forward. Cancelled by a newer main deploy: `make pr-merge ARGS=--check-staging` checks main's head. A dry run (`RAILWAY_DEPLOY` not `true`) deployed nothing. With Actions off, it reads what Railway runs instead: deploy with `make railway-up PLATFORM_ENV=staging` from a clean checkout of the commit, which records it. After a burst, `ARGS=--then-check-staging` follows main's deploy (bounded). -- **Stacked children** are retargeted to `main` before their parent merges. Then `git rebase --onto origin/main `, `git push --force-with-lease`, attest. -- Integration branches (`feat/`): `make pr-merge PR= ARGS=--any-base`. -- Never `gh pr merge --delete-branch`: it closes every PR stacked on the branch and deletes any worktree holding it. Never write your own merge or queue script; change `scripts/cilocal` (rules and tests in `scripts/cilocal/verify`). -- **Admin bypass** only when the developer authorized it and a GitHub check is red for a reason outside the code, and only after `make ci-local RAN="…"` attested the head: `gh pr merge --squash --admin --match-head-commit `, then a PR comment "Authorized by , merged by " with the attestation. - -## 6. Checks that fail outside the code - -- **Lost runner** ("lost communication with the server", "received a shutdown signal", "The operation was canceled.", a timeout with no log): `gh run rerun --failed`, once, by hand. Nothing re-runs it automatically. -- **Actions blocked** (billing or a spending limit: "The job was not started because…"): those jobs count as not run; `make pr-merge` merges on `local-ci` alone. -- A real failure belongs to the PR's owner; the rest of the burst doesn't wait for it. -- One read per question (`gh pr checks `, `gh run view --json jobs`), never a polling loop. - -## 7. Staging deploys itself - -`main` runs no CI. "Deploy staging" deploys a push to Railway staging only when `make ci-local` attested it (`cilocal attest`): the squash of an attested PR head, or a commit with its own `local-ci`. `make pr-merge` refuses a head behind `main`, so every squash is a tree someone verified. The hourly "Staging catch-up" deploys `main` whenever staging is behind and `main` is attested. Never wait for a deploy or for another PR to settle: merge each PR when its own head is attested and conflict-free, and stack the next at once; check its deploy afterwards (section 5); "Post-merge report" comments on the PR when a push workflow on its commit fails. A failed deploy is fixed forward in parallel and blocks no unrelated merge. - -An unattested `main` is the top priority: both workflows fail and say why. Fix it forward: `git worktree add --detach `, run what the commits since the last attested one need (`make ci` when there is none, as in a new project's first attestation), then `make ci-local COMMIT= RAN="…"` there. It refuses a dirty tree, a commit off `origin/main` or one that already failed, and posts `local-ci` on the commit; then dispatch "Deploy staging". - -## 8. Waiting without losing the work - -- **Never end a turn while your own wait, watcher or helper still runs.** Register it (`t3_background_wait`) or wait for it. -- **Never `pgrep -f`, `pkill -f` or kill a process found by name**; wait on a PID captured at spawn or the background task's ID. -- A background command from a T3 tool call dies with that tool's scope and has a two-hour limit. A merge never needs one. - -## Rules and what enforces them - -| Rule | Enforced by | -|---|---| -| Every PR is attested on its exact head | `Local verification` (`ci.yml`) and `verify.Decide`, through `verify.LocalVerificationProblems`; a skipped `Secret scan` is never green | -| The section is the script's, never hand-edited | the section digest in the `local-ci` status | -| Merge only the verified head, never a conflict | `--match-head-commit` and the conflict refusal in `make pr-merge` | -| Staging deploys only an attested PR head or commit | `cilocal attest` in Deploy staging's plan, `verify.Attestation` and its test | -| Merge every green PR at once; stacks survive | `make pr-merge` (no wait path, retargets children), `scripts/cilocal/verify/merge_test.go` | -| A push workflow that fails on main is reported | `Post-merge report`; a verify test fails when a push-to-main workflow is missing from its list | -| Never skip the pre-push hook, no reopen, no `pgrep -f` | this skill only; add a check if an agent repeats one | +- Merge only with `make pr-merge` (or `make land`). Never `gh pr merge` (`--delete-branch` closes every PR stacked on the branch) and never your own merge or queue script. +- It never waits: anything not mergeable is reported with its next step. Merge each PR the moment it is attested; never wait for another PR or a deploy. +- Integration branches (`feat/`): `ARGS=--any-base`. +- Admin bypass only when the developer authorized it, after `make ci-local` attested the head: `gh pr merge --squash --admin --match-head-commit `, then comment "Authorized by , merged by ". -## Done means +## After the merge -- Every PR you were asked to land is merged, or reported with its blocker and next step. -- Every PR you pushed to is attested on its current head, and each merge's staging deploy was checked. -- No PR was closed and reopened, and no hooks were skipped. +- Once "Deploy staging" has run, check it once with the command `make pr-merge` prints: `make pr-merge ARGS="--check-deploy "`. One read, never a polling loop. +- **A failed staging deploy, or an unattested `main` staging refuses, is the top priority.** Fix it forward before merging anything else: attest `main` (local-ci, "An unattested `main` commit"), then `gh workflow run deploy-staging.yml --ref main`. diff --git a/.agents/skills/local-ci/SKILL.md b/.agents/skills/local-ci/SKILL.md new file mode 100644 index 0000000..2c4c0f5 --- /dev/null +++ b/.agents/skills/local-ci/SKILL.md @@ -0,0 +1,21 @@ +--- +name: local-ci +description: Every CI check in this repo runs locally; GitHub Actions is never what you wait on. Use before any commit, push or PR, and whenever asked to "run CI" or check that a change passes. +--- + +# Local CI + +Every check runs on your machine (or a Davit box). GitHub only checks that you attested them. + +1. **Before every push: `make check-fast`.** The pre-push hook runs it (`make hooks`). Fix what it finds; never skip the hook. A change adds no lint or format findings, warnings included. +2. **Run what the change needs: `make check-pr`.** It picks the checks from the diff, stops at the first failure, and prints the `make ci-local RAN="…"` line. `ARGS=--dry-run` only lists them. A user-visible UI change also gets one pass in a real browser against a running `make dev`. +3. **Attest the pushed head: `make ci-local RAN="…"`.** Commit, push, then run it in the clean worktree. It runs nothing: it posts `local-ci` on the exact SHA and fills the PR's "Local verification" section. Every push or rebase needs a new attestation; no PR yet, open it and attest again. Never edit that section by hand. +4. **A failed head is final.** Never attest a red head. `make ci-local FAILED=""` marks it failed for good. Fix forward with a new commit: in this PR if this branch caused it, otherwise in its own PR off `main`. +5. **Never rerun remotely what you ran locally.** No GitHub Actions run, no `gh workflow run` and no "re-run checks" as verification. The only remote checks are the attestation and the secret scan, and they take seconds. +6. **Busy machine: `make box-ci COMMIT=`.** The one exception: when a heavy check reports every slot busy, or for a long suite, it runs check-generated, lint, build and test on that commit in a Davit box, instead of locally, never in addition. Attest the `PASS` line it prints. With no Docker, `make ci-pg` runs `make ci` on a throwaway Postgres. + +**An unattested `main` commit:** `git worktree add --detach `, run what the commits since the last attested one need (`make ci` when there is none), then `make ci-local COMMIT= RAN="…"` there. + +Tests only at the test boundaries (`AGENTS.md`, "Test boundaries"). + +Opening, stacking and merging PRs: the [github-prs](../github-prs/SKILL.md) skill. diff --git a/.claude/skills/github-prs/SKILL.md b/.claude/skills/github-prs/SKILL.md index 0466da2..4a9d8ea 100644 --- a/.claude/skills/github-prs/SKILL.md +++ b/.claude/skills/github-prs/SKILL.md @@ -1,108 +1,37 @@ --- name: github-prs -description: How every agent verifies and attests locally (`make ci-local RAN="…"`), opens, stacks and merges pull requests in this repo, fast. Use before any `git commit`, `gh pr create`, `gh pr merge`, retargeting or rebasing a stacked PR, or re-running a check, and whenever you are about to wait on CI, write a merge script, or merge PRs "one at a time". +description: How every agent opens, stacks and merges pull requests in this repo, after verifying with the local-ci skill. Use before any `gh pr create`, `gh pr merge`, retargeting or rebasing a stacked PR, and whenever you are about to wait on CI, write a merge script, or merge PRs "one at a time". --- -# Pull requests: run what you need, attest, stack, merge at once +# Pull requests -Run the checks your change needs (lint, tests, build), then attest with `make ci-local RAN="…"` and merge right away. `make ci-local` runs nothing: it tells the PR you checked, and what. GitHub runs no verification on `main`, and on a PR only two small jobs that check the attestation. Stack PRs and merge each the moment it is attested; after the merge, check its staging deploy. +Verify and attest first: the [local-ci](../local-ci/SKILL.md) skill. -The rules on what may merge are in `AGENTS.md` ("Verifying", "Pull requests", "Environments: staging is always current"). This skill is how you do it. +## Open -## 1. Before every commit +- `gh pr create --base ` from `.github/pull_request_template.md`, ready (never draft), no labels. +- Title: a conventional commit in plain language (`fix(api): PATCH /users no longer drops the image`). Body: the problem in a sentence or two, then the fix; UI changes need before/after images. The body ends with the attribution line. +- One concern per PR; push follow-ups to the same branch. Never close and reopen a PR. -- **Never skip the hooks.** `make hooks` installs the pre-push hook (`make check-fast`); when it fails, fix what it found and push again; never skip it. -- **Default: `make check-pr`.** It runs what the branch's changes need (the table is in `scripts/check-pr.sh`), fails when the affected-package selection does not match the diff, and prints the `make ci-local RAN="…"` line to attest with. By hand: `make lint LINT_DIRS=` and `make test TEST_PKGS=` for the Go packages it can affect (`scripts/affected.sh` prints them; `make check-fast` is the seconds-long pass), `make check-generated` for sqlc, templ or mock inputs, `make check-migrations` for a migration, `make deploy-check` for `deploy/`, `make actionlint` for workflows, `make release-smoke` for a Dockerfile or what it builds, `make ci` for a change to the tooling. In a Davit box, `make box-ci COMMIT=` runs check-generated, lint, build and test on exactly that commit and prints one PASS/FAIL line; never hand-write an inline `davit box run -- bash -lc "... rm ..."`. Tests only at the test boundaries (`AGENTS.md`, "Test boundaries"); never a test in `deploy/` or the UI. -- A change adds no lint or format findings, warnings included. -- Add the paths you changed; never `git add -A` in an old worktree. +## Stack -## 2. Attest: `make ci-local RAN="…"` +- Needs nothing unmerged: base `main`. Needs an open PR: base that PR's branch. +- `make pr-merge` retargets children to `main` before their parent merges. Then `git rebase --onto origin/main `, `git push --force-with-lease`, attest. -After **every** push or rebase, once you have run what the change needs: +## Merge ```bash -git push # pushed head, clean worktree -make check-pr # runs what the change needs, prints the RAN line -make ci-local RAN="make lint LINT_DIRS='./apps/web/internal/services ...'; make test TEST_PKGS='...'; make secret-scan" -``` - -- It runs nothing and takes seconds. It refuses a dirty worktree, a detached HEAD (except `COMMIT=` of a `main` commit), a head that is not the pushed branch head, or a head that already has a failed `local-ci`. -- It posts `local-ci` on that exact SHA and fills the PR body's **Local verification** section (head, who, and your statement). **Never edit the section by hand:** the status carries its digest. -- **One attestation, one commit.** Any push, amend or rebase needs a new one. No PR yet? Open it (section 3) and run it again. -- **Something failed?** Fix it before attesting. If you attest a failure (`make ci-local FAILED=""`), that head is final: fix forward with a new commit. Code this PR touched: fix it here. Anything else: its own PR off `main` with a test that fails before the fix, then rebase. Add the prevention. -- Say exactly what ran; a reviewer reads the scope from it. - -## 3. Open and stack - -- `gh pr create --base ` with `.github/pull_request_template.md`, open and ready, no labels: problem, fix, and the Local verification section. Conventional commit title; the body ends with the attribution line. -- **Base per layer.** Needs nothing unmerged: base `main`. Needs an open PR: base that PR's branch. Independent work gets its own PR on `main`. -- One concern per PR; push follow-ups to the same branch. **Never close and reopen a PR.** - -## 4. What PR CI and the merge script refuse - -PR CI runs only `Secret scan` and `Local verification`, the two checks the main ruleset requires, on the `CI_RUNNER` runner. It runs only on a PR body edit, and until `make ci-local` claims the head (posts `local-ci` or fills the section for it) the check runs as `Awaiting make ci-local`, so the required one shows **Expected**, not red; red is a real problem. `Local verification` and `make pr-merge` share one rule (`scripts/cilocal/verify`, `LocalVerificationProblems`): - -| Refused because | Fix | -|---|---| -| no `local-ci` status on the head (never attested, or a new push) | run what it needs, `make ci-local RAN="…"` | -| `local-ci` is `failure`, or failed on this head before | fix forward with a new commit, push, attest | -| no Local verification section, it names another head or no "Ran:" | `make ci-local RAN="…"` | -| the section is not the attested one (edited by hand) | `make ci-local RAN="…"` again restores it | -| `Secret scan` found a credential | remove it (rotate it if real), push, attest | -| it conflicts with `main` | rebase onto `main`, push, attest | - -`make ci-local` posts the status before it edits the body, and that edit starts the PR run, so you never re-run `Local verification` by hand; when the body was already current, `make ci-local` re-runs the run itself. - -## 5. Merge - -```bash -make land PR= # the whole landing inside one hold of /tmp/gfs-ci.lock (below) -make pr-merge PR=" [ ...]" # merges every green PR now, reports the rest +make pr-merge PR=" [ ...]" # merges every attested, green PR now, reports the rest make pr-merge PR= ARGS=--dry-run # says what it would do +make land PR= # rebase, make ci-pg, attest and merge inside one hold of the CI lock ``` -- **Land inside the CI lock** on this machine: `make land PR=` in a clean worktree on its branch takes `/tmp/gfs-ci.lock`, rebases and pushes, runs `make ci-pg` inside that hold, attests, waits for the checks, merges with `make pr-merge` and releases the lock, so nothing lands between the rebase and the merge. -- **Green** means `local-ci` and the section attest the exact head, GitHub can merge it without conflicts, and the checks passed. It squash-merges with `--match-head-commit `, so only the attested head lands. A head behind `main` is refused ("rebase onto origin/main and re-attest"): the merged tree must be the one you verified. Where Actions cannot run (no CI job ran, or GitHub never started them), it merges on `local-ci` alone and says so. -- Anything else (draft, unattested, pending, failing, conflicting, stacked) is reported with its next step; the script never waits. A head behind `main` or a conflict needs rebase, push, run what it needs, attest; after each merge in a burst, rebase the next PR. -- **After each merge, check its deploy** (a follow-up, never a gate; merge the next PR now): it prints `make pr-merge ARGS="--check-deploy "`. Run it once "Deploy staging" has run for that commit. Failed or refused: top priority, fix forward. Cancelled by a newer main deploy: `make pr-merge ARGS=--check-staging` checks main's head. A dry run (`RAILWAY_DEPLOY` not `true`) deployed nothing. With Actions off, it reads what Railway runs instead: deploy with `make railway-up PLATFORM_ENV=staging` from a clean checkout of the commit, which records it. After a burst, `ARGS=--then-check-staging` follows main's deploy (bounded). -- **Stacked children** are retargeted to `main` before their parent merges. Then `make land PR=` rebases it `--onto origin/main ` itself (by hand: that command, `git push --force-with-lease`, attest). -- Integration branches (`feat/`): `make pr-merge PR= ARGS=--any-base`. -- Never `gh pr merge --delete-branch`: it closes every PR stacked on the branch and deletes any worktree holding it. Never write your own merge or queue script; change `scripts/cilocal` (rules and tests in `scripts/cilocal/verify`). -- **Admin bypass** only when the developer authorized it and a GitHub check is red for a reason outside the code, and only after `make ci-local RAN="…"` attested the head: `gh pr merge --squash --admin --match-head-commit `, then a PR comment "Authorized by , merged by " with the attestation. - -## 6. Checks that fail outside the code - -- **Lost runner** ("lost communication with the server", "received a shutdown signal", "The operation was canceled.", a timeout with no log): `gh run rerun --failed`, once, by hand. Nothing re-runs it automatically. -- **Actions blocked** (billing or a spending limit: "The job was not started because…"): those jobs count as not run; `make pr-merge` merges on `local-ci` alone. -- A real failure belongs to the PR's owner; the rest of the burst doesn't wait for it. -- One read per question (`gh pr checks `, `gh run view --json jobs`), never a polling loop. - -## 7. Staging deploys itself - -`main` runs no CI. "Deploy staging" deploys a push to Railway staging only when `make ci-local` attested it (`cilocal attest`): the squash of an attested PR head, or a commit with its own `local-ci`. `make pr-merge` refuses a head behind `main`, so every squash is a tree someone verified. The hourly "Staging catch-up" deploys `main` whenever staging is behind and `main` is attested. Never wait for a deploy or for another PR to settle: merge each PR when its own head is attested and conflict-free, and stack the next at once; check its deploy afterwards (section 5); "Post-merge report" comments on the PR when a push workflow on its commit fails. A failed deploy is fixed forward in parallel and blocks no unrelated merge. - -An unattested `main` is the top priority: both workflows fail and say why. Fix it forward: `git worktree add --detach `, run what the commits since the last attested one need (`make ci` when there is none, as in a new project's first attestation), then `make ci-local COMMIT= RAN="…"` there. It refuses a dirty tree, a commit off `origin/main` or one that already failed, and posts `local-ci` on the commit; then dispatch "Deploy staging". - -## 8. Waiting without losing the work - -- **Never end a turn while your own wait, watcher or helper still runs.** Register it (`t3_background_wait`) or wait for it. -- **Never `pgrep -f`, `pkill -f` or kill a process found by name**; wait on a PID captured at spawn or the background task's ID. -- A background command from a T3 tool call dies with that tool's scope and has a two-hour limit. A merge never needs one. - -## Rules and what enforces them - -| Rule | Enforced by | -|---|---| -| Every PR is attested on its exact head | `Local verification` (`ci.yml`) and `verify.Decide`, through `verify.LocalVerificationProblems`; a skipped `Secret scan` is never green | -| The section is the script's, never hand-edited | the section digest in the `local-ci` status | -| Merge only the verified head, never a conflict | `--match-head-commit` and the conflict refusal in `make pr-merge` | -| Staging deploys only an attested PR head or commit | `cilocal attest` in Deploy staging's plan, `verify.Attestation` and its test | -| Merge every green PR at once; stacks survive | `make pr-merge` (no wait path, retargets children), `scripts/cilocal/verify/merge_test.go` | -| A push workflow that fails on main is reported | `Post-merge report`; a verify test fails when a push-to-main workflow is missing from its list | -| Never skip the pre-push hook, no reopen, no `pgrep -f` | this skill only; add a check if an agent repeats one | +- Merge only with `make pr-merge` (or `make land`). Never `gh pr merge` (`--delete-branch` closes every PR stacked on the branch) and never your own merge or queue script. +- It never waits: anything not mergeable is reported with its next step. Merge each PR the moment it is attested; never wait for another PR or a deploy. +- Integration branches (`feat/`): `ARGS=--any-base`. +- Admin bypass only when the developer authorized it, after `make ci-local` attested the head: `gh pr merge --squash --admin --match-head-commit `, then comment "Authorized by , merged by ". -## Done means +## After the merge -- Every PR you were asked to land is merged, or reported with its blocker and next step. -- Every PR you pushed to is attested on its current head, and each merge's staging deploy was checked. -- No PR was closed and reopened, and no hooks were skipped. +- Once "Deploy staging" has run, check it once with the command `make pr-merge` prints: `make pr-merge ARGS="--check-deploy "`. One read, never a polling loop. +- **A failed staging deploy, or an unattested `main` staging refuses, is the top priority.** Fix it forward before merging anything else: attest `main` (local-ci, "An unattested `main` commit"), then `gh workflow run deploy-staging.yml --ref main`. diff --git a/.claude/skills/local-ci/SKILL.md b/.claude/skills/local-ci/SKILL.md new file mode 100644 index 0000000..2c4c0f5 --- /dev/null +++ b/.claude/skills/local-ci/SKILL.md @@ -0,0 +1,21 @@ +--- +name: local-ci +description: Every CI check in this repo runs locally; GitHub Actions is never what you wait on. Use before any commit, push or PR, and whenever asked to "run CI" or check that a change passes. +--- + +# Local CI + +Every check runs on your machine (or a Davit box). GitHub only checks that you attested them. + +1. **Before every push: `make check-fast`.** The pre-push hook runs it (`make hooks`). Fix what it finds; never skip the hook. A change adds no lint or format findings, warnings included. +2. **Run what the change needs: `make check-pr`.** It picks the checks from the diff, stops at the first failure, and prints the `make ci-local RAN="…"` line. `ARGS=--dry-run` only lists them. A user-visible UI change also gets one pass in a real browser against a running `make dev`. +3. **Attest the pushed head: `make ci-local RAN="…"`.** Commit, push, then run it in the clean worktree. It runs nothing: it posts `local-ci` on the exact SHA and fills the PR's "Local verification" section. Every push or rebase needs a new attestation; no PR yet, open it and attest again. Never edit that section by hand. +4. **A failed head is final.** Never attest a red head. `make ci-local FAILED=""` marks it failed for good. Fix forward with a new commit: in this PR if this branch caused it, otherwise in its own PR off `main`. +5. **Never rerun remotely what you ran locally.** No GitHub Actions run, no `gh workflow run` and no "re-run checks" as verification. The only remote checks are the attestation and the secret scan, and they take seconds. +6. **Busy machine: `make box-ci COMMIT=`.** The one exception: when a heavy check reports every slot busy, or for a long suite, it runs check-generated, lint, build and test on that commit in a Davit box, instead of locally, never in addition. Attest the `PASS` line it prints. With no Docker, `make ci-pg` runs `make ci` on a throwaway Postgres. + +**An unattested `main` commit:** `git worktree add --detach `, run what the commits since the last attested one need (`make ci` when there is none), then `make ci-local COMMIT= RAN="…"` there. + +Tests only at the test boundaries (`AGENTS.md`, "Test boundaries"). + +Opening, stacking and merging PRs: the [github-prs](../github-prs/SKILL.md) skill. diff --git a/AGENTS.md b/AGENTS.md index 7924928..8613555 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,7 +32,7 @@ The most common defect is a change that works on the path you tested and is miss ## Verifying -- Verify code changes both ways and walk the tree for failures and regressions. How to verify and attest a PR: the [github-prs](.claude/skills/github-prs/SKILL.md) skill. +- Verify code changes both ways and walk the tree for failures and regressions. CI runs locally: the [local-ci](.claude/skills/local-ci/SKILL.md) skill. - Merged migrations are append-only; a new one takes the next number above the highest on origin/main (`make check-migrations`). ## Test boundaries (mandatory) @@ -74,12 +74,12 @@ The platform runs on Railway: environments are declared in [deploy/platform.yaml - **Staging always runs the latest `main`.** Every merge of a head `make ci-local` attested deploys to staging automatically (`Deploy staging`, `.github/workflows/deploy-staging.yml`), and the hourly "Staging catch-up" deploys `main` whenever staging is behind ([docs/RELEASES.md](docs/RELEASES.md)). - **Production may lag staging, never lead it.** Production only ever runs a commit that staging has already run and passed its readiness check on. No hotfixes straight to production, no production deploys of branches, and never a production commit that staging has not run. -- **A failed staging deploy, or an unattested `main` that staging refuses, is the top priority.** After a merge, check its deploy once with `make pr-merge ARGS="--check-deploy "` (one read, not a polling loop); "Post-merge report" also comments on the merged PR when Deploy staging fails on `main`. If it failed, fix it, or attest and dispatch `main` ([github-prs](.claude/skills/github-prs/SKILL.md)), before merging anything else. Never leave staging behind `main`. +- **A failed staging deploy, or an unattested `main` that staging refuses, is the top priority.** After a merge, check its deploy once with `make pr-merge ARGS="--check-deploy "` (one read, not a polling loop); "Post-merge report" also comments on the merged PR when Deploy staging fails on `main`. If it failed, fix it, or attest and dispatch `main` ([github-prs](.claude/skills/github-prs/SKILL.md), "After the merge"), before merging anything else. Never leave staging behind `main`. - **Production ships only as a GitHub release** ([docs/RELEASES.md](docs/RELEASES.md)): publishing a `vX.Y.Z` release starts "Deploy production", whose gate proves staging ran that commit, still runs it or a later `main` commit and is healthy, and that the publisher is in `PRODUCTION_RELEASERS`. An agent publishes or dispatches one only when the developer explicitly says so. ## Branches and releases -`main` is the only long-lived branch, named once in `scripts/branches.sh`. Agents push feature branches and open PRs that target `main`; CI runs locally and every PR is attested before it merges. +`main` is the only long-lived branch, named once in `scripts/branches.sh`. Agents push feature branches and open PRs that target `main`; CI runs locally: every PR runs the [local-ci](.claude/skills/local-ci/SKILL.md) skill before it merges. ## Pull requests diff --git a/CONTEXT.md b/CONTEXT.md index e3042eb..b00ce8a 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -43,7 +43,7 @@ file holds the names. | service error | a named `*services.Error` matched with `errors.Is`, plus kind sentinels | `apps/web/internal/services/` | | mock / mock session | generated mockgen output; `apitest.AsUser` / `apitest.Anonymous` for handler tests | `services/mocks`, `api/mocks`, `api/apitest` | | test boundary | one of the only places tests may live, each with allowed imports and a coverage floor | AGENTS.md "Test boundaries" | -| local verification | run what the change needs on the pushed head, then `make ci-local RAN="…"` attests it | `scripts/cilocal/`, the github-prs skill | +| local verification | run what the change needs on the pushed head, then `make ci-local RAN="…"` attests it | `scripts/cilocal/`, the local-ci skill | | attested / claimed / failed head | a head whose attestation holds / that `make ci-local` has touched / that failed and stays failed | `scripts/cilocal/verify` | | release | a published `vX.Y.Z` on a `main` commit staging already ran; the only path to production | `Deploy production`, `docs/RELEASES.md` | | routes config | `AppRoutes` (pages) and `APIRoutes` (endpoints) | `apps/web/internal/config/routes.go` | diff --git a/Makefile b/Makefile index 17ae446..e70cb19 100644 --- a/Makefile +++ b/Makefile @@ -178,7 +178,7 @@ vulncheck: ## Known vulnerabilities: govulncheck (pinned) on every Go module + p $(GO) run ./scripts/vulncheck $(ARGS) .PHONY: check-pr -check-pr: ## Before make ci-local: run what this branch's changes need, then print the RAN line (ARGS=--dry-run: only say what) +check-pr: ## Before make ci-local: run what this branch's changes need (the local-ci skill), then print the RAN line (ARGS=--dry-run: only say what) ./scripts/check-pr.sh $(ARGS) .PHONY: check-fast diff --git a/README.md b/README.md index 28bcc8a..6fa7735 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ A new project made from this template attests its first `main` commit once: | `make generate check-generated lint test build` | Regenerate sqlc/mocks/templ, prove the output is committed, lint, race tests with time budgets and coverage floors, build the server | | `make ci` | Everything, on this checkout as it is: the above plus the layering probes and `make vulncheck` | | `make release-smoke` | Build every Dockerfile's binary, migrate, boot web and admin in production mode | -| `make check-pr`, `make ci-local` | What a branch's change needs, and the attestation that records it ([github-prs skill](.claude/skills/github-prs/SKILL.md)) | +| `make check-pr`, `make ci-local` | What a branch's change needs, and the attestation that records it ([local-ci skill](.claude/skills/local-ci/SKILL.md)) | Tests live only at the boundaries described in [AGENTS.md](AGENTS.md#test-boundaries-mandatory). Lint enforces the layers, and `make lint-layering` proves the rules still @@ -87,7 +87,7 @@ rules are in [docs/RELEASES.md](docs/RELEASES.md). ## Learn more -- [Releases](docs/RELEASES.md) · [Pull requests](.claude/skills/github-prs/SKILL.md) +- [Releases](docs/RELEASES.md) · [Local CI](.claude/skills/local-ci/SKILL.md) · [Pull requests](.claude/skills/github-prs/SKILL.md) - [Mobile app](apps/mobile-app/README.md) · [Auth](packages/auth/README.md) · [UI kit](packages/uikit/README.md) - [AGENTS.md](AGENTS.md) (rules for agents and contributors) · [CONTEXT.md](CONTEXT.md) (shared vocabulary) diff --git a/docs/RELEASES.md b/docs/RELEASES.md index a8028a9..c1be81d 100644 --- a/docs/RELEASES.md +++ b/docs/RELEASES.md @@ -13,7 +13,7 @@ GitHub auto-deploy stays off (`repo: ""`): only these workflows ship code. ## The flow 1. **Merge to `main`.** `make ci-local` attested the PR's head - ([github-prs](../.claude/skills/github-prs/SKILL.md)), then `Deploy staging` checks that attestation and ships + (the [local-ci](../.claude/skills/local-ci/SKILL.md) skill), then `Deploy staging` checks that attestation and ships the commit to Railway staging (see [Railway rollout](#railway-rollout)). 2. **Draft a release.** Actions → **Draft release** → Run workflow (`bump` patch, minor or major, or an exact `version`). It drafts a release at the @@ -129,7 +129,7 @@ leaked admin token can push a `v*` tag as easily as it can publish a release. `Deploy staging` run's commit is not `main`'s head (a refused, failed or cancelled deploy), it dispatches `Deploy staging` on `main`. A `main` that is not attested is refused again, every hour, until someone attests it -([github-prs](../.claude/skills/github-prs/SKILL.md)). +([github-prs](../.claude/skills/github-prs/SKILL.md), "After the merge"). ## Rollback or redeploy diff --git a/scripts/check-pr.sh b/scripts/check-pr.sh index bb38ac9..8be304e 100755 --- a/scripts/check-pr.sh +++ b/scripts/check-pr.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # What a pull request needs before make ci-local (`make check-pr`): runs the -# checks this checkout's changes need against +# checks this checkout's changes need (the local-ci skill) against # the merge base with origin/main, in order, stopping at the first failure, # then prints the `make ci-local RAN="…"` line that says exactly what ran. #