diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d70ce09e26..f68d7ff882 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,7 +4,9 @@ ## How it was checked - + ## Checklist @@ -14,5 +16,4 @@ - [ ] The manual knows about it — `internal/manual/chat/` updated in this change if a slash command, key, tool, default, limit or refusal moved. CLAUDE.md states the law; three gates fail the build if it is skipped. -- [ ] No new line in `.github/known-red.txt`, or one with the reason above. - [ ] Only my own paths are staged — no `git add -A`. diff --git a/CLAUDE.md b/CLAUDE.md index 2f0ef430b5..ac0e8415cc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -115,6 +115,41 @@ The repository is public now, so the free plan's former private-repository restriction no longer prevents branch rules. `.github/rulesets/` holds the intended rules; inspect live enforcement before assuming they were applied. +## What you are running on — CI is real, Spark is not yours, no key is normal + +Agents keep reporting three absences that are not problems. None of them belongs +in a summary or a pull request. + +- **CI exists and runs on every pull request.** It is GitHub Actions: `PR gate` + (`ci.yml`, whose `check` is the one required status) on every pull request and + every push to `dev`, `Full check` (`ci-full.yml`) nightly, `Release` on every + push. A failing `gh` is your credentials, not the repository: in a claude.ai + cloud container `gh` is installed but its `GH_TOKEN` does not authenticate, so + read runs, jobs and logs with the GitHub MCP tools (`actions_list`, + `get_job_logs`, `pull_request_read`). Never write "there is no CI" or "could not + check CI" without having tried them. +- **Spark is the owner's own build machine**, reachable only from the owner's + laptop. Design notes say "measured on Spark" because that is where they were + measured — a record, never a step you owe. For everyone else its work is done by + CI: `touched packages` on every pull request and `Full check` nightly. +- **No provider key is the normal state** away from the owner's laptop. The tagged + e2e suites, `TestRealRouter` and `internal/lane`'s `TestReal` SKIP green without + one, by design. Say "e2e not run: no key" once under "How it was checked" and + move on — do not ask for a key and do not go looking for one. + +**Spend the box on the change, not the ritual.** CI's `touched packages` runs the +same selector as `make pr-ready`, on the same four-core runner size, in parallel +legs, and it blocks the merge — so running it twice buys nothing. + +| When | Run | +| --- | --- | +| while editing | `make test-focus PKGS=… RUN=…` on the tests you wrote or touched | +| before every push | `make test-quick` — build, vet, fmt, corpora, change entry, manual gates, laws; about a minute and a half warm, seven in a fresh cloud container (the first module download and build) | +| before the pull request, on the owner's laptop | `make pr-ready` (below) | +| before the pull request, in a cloud container | `make test-quick` plus your focused tests; then push and let `touched packages` be the full proof | +| after the push | read `check` through the GitHub MCP tools; a red `touched packages` is yours to read before anything else | +| never as routine | `make check`, `make test-e2e`, bare `go test ./...`, a full `tui3` or `session` suite | + ## Build and ship — the owner's standing orders - **Always build with `make build`**, which writes `bin/codeaf`. Never a bare @@ -139,8 +174,8 @@ run `make check`, bare `go test ./...`, or a full `go test ./internal/tui3` / `./internal/session` as the merge ritual — those thrash the box and are not what the pull-request gate demands. Edit with `make test-focus`; prove the change with `make test-touched` or `make pr-ready`. `make check` remains the full-tree -build, test and size ritual for Spark, staging, or an intentional full laptop -run. Concurrent full runs of `tui3` or `session` share one per-box lock so two +build, test and size ritual for staging, the owner's Spark box, or an +intentional full laptop run. Concurrent full runs of `tui3` or `session` share one per-box lock so two agents cannot stack those binaries. The performance laws those targets enforce — and the rule that changing any cap changes the doc in the same commit — are in [PERF.md](PERF.md). diff --git a/docs/changes/unreleased/1884-agents-ci-spark-keys.md b/docs/changes/unreleased/1884-agents-ci-spark-keys.md new file mode 100644 index 0000000000..1c2e243504 --- /dev/null +++ b/docs/changes/unreleased/1884-agents-ci-spark-keys.md @@ -0,0 +1,20 @@ +--- +kind: internal +title: the agent guide says CI is real, Spark is private, and no provider key is normal +pr: 1884 +surface: [docs] +invalidates: + - >- + Agents in cloud sessions concluded the repository had no CI because `gh` + failed there. CI is GitHub Actions (`PR gate` on every pull request, + `Full check` nightly); `gh` fails only because the container's GH_TOKEN + does not authenticate, and the GitHub MCP tools read runs and logs. + - >- + "Run it on Spark" read as a step every contributor owed. Spark is the + owner's private machine; CI's `touched packages` and `Full check` do its + work for everyone else, and a cloud session need not repeat `make pr-ready` + before CI runs the same selector. + - >- + The pull-request template asked about `.github/known-red.txt`, deleted in + #1012; the line is gone. +--- diff --git a/docs/rules/ci.md b/docs/rules/ci.md index 39fc7a35f5..c4c88fcc2e 100644 --- a/docs/rules/ci.md +++ b/docs/rules/ci.md @@ -178,7 +178,8 @@ saves remain useful even after a test failure. Hosted scheduling, cache hits and archive sizes still need an actual workflow run to confirm. This is pull-request parity, not the full-tree ritual. `make check` remains for -Spark, staging, or an intentional full laptop run; it runs the whole test tree, +staging, the owner's Spark box (a private machine; nobody else is expected to +reach it), or an intentional full laptop run; it runs the whole test tree, builds the shipped binary and enforces its size budget. ## What the full gate checks