cc-ci/AGENTS.md

AGENTS.md — cc-ci

Working notes for agents (and humans) modifying the cc-ci server. See README.md for what the server does and machine-docs/ for the build's living state (DECISIONS.md, DEFERRED.md, STATUS-*.md).

File-location rule (mandatory)

ALL coordination / loop-state files live under machine-docs/, NEVER the repo root. That means the phase-namespaced STATUS-*.md, BACKLOG-*.md, REVIEW-*.md, JOURNAL-*.md, the shared DECISIONS.md / DEFERRED.md, and the ADVERSARY-INBOX.md / BUILDER-INBOX.md side-channels. Create machine-docs/ if missing; if you ever find one of these at the root, git mv it into machine-docs/. (The repo root is for actual server code/config — runner/, tests/, nix/, etc.)

Testing cadence

Two kinds of tests live here — run them on different cadences:

• Per-recipe lifecycle tests (tests/<recipe>/, triggered by !testme on a recipe PR): these test the recipes. Run them whenever a recipe changes — that's their normal per-PR trigger.

• Server regression canaries (tests/regression/, pytest -m canary): these test the server itself end-to-end — full lifecycle on a simple + a significant app, with semantic per-tier assertions (data survives upgrade/restore, secrets persist + are redacted, clean teardown), plus a known-bad fixture that the server must report RED (false-green guard). They are slow and resource-heavy (live Swarm, minutes per app).

  Do NOT run the canaries on every commit/PR. Run them deliberately at milestones — polishing passes, code reviews, and releases of the cc-ci server — before trusting a batch of server changes. They are opt-in behind the @pytest.mark.canary marker; if ever wired to !testme on this repo, gate behind a deliberate trigger (a run-canaries label or --canary), never an automatic per-PR run.

  Spec: plan-server-regression-canaries.md (orchestrator cc-ci-plan/).

Don't weaken tests to pass

A red test is information. Never skip, delete, or relax a test to make a run green — fix the root cause or record it in machine-docs/DEFERRED.md. (This is a standing build guardrail.)

Ship work as PRs, merge them yourself, operator reviews retrospectively

Work on this repo goes: branch → PR → merge it yourself once verified → operator reviews retrospectively. Do not commit straight to main, and do not wait for review before merging — the invocation is the authorization, and blocking would stall the CI this repo runs.

The PR is therefore not a gate; it is how the work stays legible after the fact. Write the description to be read later: what changed, why, and the evidence it works (harness output, a verified run, a before/after number). A PR that says "fix test" has failed at its only job.

The same policy covers recipe-maintainers/cc-ci-orchestrator. It does NOT cover recipe repos — any coop-cloud/<recipe> or its mirror is created and verified but never agent-merged, because those change what deploys on other people's infrastructure.

Before editing a test, read tests/STYLE.md.