From e7fd5f44bc5aff523f5504a91fc633ebf3b9bb4e Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 19:57:53 +0000 Subject: [PATCH 1/2] docs(agents): say CI is real, Spark is private and no key is normal Agents in cloud sessions kept reporting that the repository has no CI and no Spark. CI is GitHub Actions and runs on every pull request; gh fails there only because its token does not authenticate, so the guide now points at the GitHub MCP tools. Spark is the owner's private machine and was never a step anyone else owed. Add a when-to-run table so cloud sessions lean on touched packages instead of repeating it locally, and drop the PR template's line about the deleted known-red ledger. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MtiPtzDsHa753NHJBpKYpn --- .github/PULL_REQUEST_TEMPLATE.md | 5 ++-- CLAUDE.md | 39 ++++++++++++++++++++++++++++++-- docs/rules/ci.md | 3 ++- 3 files changed, 42 insertions(+), 5 deletions(-) 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/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 From 84023cc256a66b8acf0e9170ec01da68d0bb21c7 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 20:03:18 +0000 Subject: [PATCH 2/2] docs(changelog): add entry for PR 1884 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MtiPtzDsHa753NHJBpKYpn --- .../unreleased/1884-agents-ci-spark-keys.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docs/changes/unreleased/1884-agents-ci-spark-keys.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. +---