svcforge/AGENTS.md

# AGENTS.md — working in svcforge-reference

Rules for any AI agent (Claude Code, Cursor, Codex, Copilot, Gemini CLI) editing this repo.
Read this before your first edit.

---

## What this repo is, and the one rule that follows from it

This is a **reference implementation**: a complete, verified build of the system that
`../learn-python/` teaches Phuc to build himself. It exists to be *compared against*, not
copied from.

**THE RULE: never propose copying `domain/`, `repo/`, `services/worker/`, or the claim
query into `learn-python/`.** Those four are the course. If asked to "help with Module 4",
help him find his own bug; do not paste `repo/tasks.py`. Scaffolding — `pyproject.toml`,
Dockerfiles, CI, the chart — is fair game to copy, because struggling with hatchling
teaches nothing.

`learn-python/AGENTS.md` has its own, stricter rules. They still apply over there.

---

## Before you change anything

Read [ARCHITECTURE.md](ARCHITECTURE.md). Every design choice here was paid for by a
specific failure mode, and the comments say which. A change that removes a comment's
subject usually removes a guard.

Four things that look like over-engineering and are not. Do not "simplify" them:

1. **The claim query is one statement.** `repo/tasks.py::_CLAIM_SQL`. Splitting the
   `UPDATE ... WHERE id = (SELECT ... FOR UPDATE SKIP LOCKED)` into select-then-update
   creates a double-provision race that testing will not catch.
2. **`complete()` and `fail()` check `locked_by`.** That check is a repro-confirmed bug
   fix, with regression tests in `tests/integration/test_tasks.py`. Removing it lets a
   worker whose lease expired clobber a task another worker now owns.
3. **`domain/` has no I/O and no `async`.** CI greps for both.
4. **Migrations never run at app startup.** They are a Helm `pre-upgrade,pre-install` hook.

---

## Conventions

**Layers.** `transport → domain ← repo/adapters`. `domain/` imports nothing from the other
three. `repo/` knows SQL and not HTTP. `adapters/` owns every subprocess and network call.

**Python 3.14** at runtime, but ruff's `target-version` is pinned to `py313` so the
formatter never emits 3.14-only syntax. Full annotations everywhere including tests.
`X | None`, `StrEnum`, `Final`, PEP 695 `type` aliases. Keep `except (A, B):`
parenthesized — PEP 758's unparenthesized form reads exactly like Python 2's
`except E, name:`, which means something else.

**Errors.** `SvcforgeError` in `svcforge_core/errors.py` is the base. New exception types
inherit from it, plus a stdlib base when the behaviour matters (`HelmError(SvcforgeError,
RuntimeError)`).

**Logging.** `obs.get_logger(__name__)`, structlog kwargs. Never stdlib `logging` directly,
and never `extra={...}` — the ProcessorFormatter bridge silently discards it. Never use
`message` or `event` as a field name; both are reserved and raise.

**SQL.** Raw psycopg3, no ORM. Parameters, never f-strings. Rows come back as dicts
(`DictPool` in `repo/db.py`); annotate with that alias rather than a bare
`AsyncConnectionPool`, which mypy resolves to tuple rows.

**Subprocess.** `create_subprocess_exec` with `start_new_session=True`. Never `shell=True` —
`team` is tenant input that reaches a helm release name. Timeouts kill the process *group*.

**Protocols.** A `Protocol` needs two implementations (a real one and a fake) or it should
be a concrete class.

**Datetimes.** Always aware, always UTC. Domain functions take `now` as a parameter;
only adapters hold a `Clock`.

**Pinning.** Everything by digest: base images, tool images, GitHub Actions by SHA.
A SHA-pinned third-party action still resolves *its own* dependencies by mutable tag —
that is how `trivy-action` broke. Prefer running tools directly from a digest-pinned image.

---

## Writing style

Plain declaratives. **No back-and-forth phrasing**, which means none of:

- Rhetorical setup-knockdowns: "That is not a nicety. It is the whole design."
- not-X-but-Y pivots used for rhythm: "It is not a lock, but a lease."
- Throat-clearing: "It is worth noting that", "The key insight here", "Here's the thing".
- Rhetorical questions you then answer.
- Dramatic fragments for rhythm: "Not slow. Not fast. Meaningless."

Write the claim directly. Keep the *why* — it is the most valuable content in this repo —
and drop the scaffolding around it. Factual contrasts that carry information stay
("LEFT join, not inner"; "202, never 201").

---

## Testing

- **Never mock the database.** Integration tests run against real Postgres. Each pytest
  process clones its own database (`tests/integration/conftest.py`).
- **Fakes, not mocks**, for helm/kubectl/Redis/clock. `tests/fakes.py`.
- **A test that cannot fail is worse than no test.** Before adding one, ask what change
  would make it red. Bound assertions on both sides where it matters: `max_concurrent
  <= cap` alone passes on a fully serial worker.
- Markers: `slow` (>1s or hits real Upstash), `e2e` (needs a cluster). `make test` runs
  neither.

```bash
export SVCFORGE_TEST_DSN="postgresql://svcforge:svcforge@127.0.0.1:5432/svcforge_test"
make lint          # ruff + ruff format + mypy --strict
make test          # unit
make integration   # needs the DSN above
make ci            # every gate CI runs, same commands
```

---

## Environment facts that will bite you

- **This host has no Docker daemon, and must not get one.** Its `containerd` belongs to a
  Kubernetes kubelet; installing `docker.io` would evict the runtime and take down every
  pod. You cannot `docker build` here. Verify Dockerfiles by inspection and `hadolint`.
- **Postgres is local** (apt, v16) for tests. testcontainers is the CI path.
- **Redis is real Upstash on a free tier: 500K commands/month.** Redis-hitting tests are
  marked `slow`. Do not write loops that spend thousands of commands; use the fakes.
- **Secrets live in `~/.config/svcforge/secrets.env`**, chmod 600, outside every repo.
  Never echo, log, commit, or paste a DSN or token. `.env` is gitignored.
- **Infra changes go through Terraform/Ansible**, never `kubectl edit`. The Gitea runner's
  config lives in `oci-k8s/k8s/roles/addons/tasks/main.yml`.

---

## CI/CD

`.gitea/workflows/ci.yaml`. Gates in order: ruff → mypy → unit+coverage → migrate+integration
→ bandit/gitleaks/pip-audit → hadolint → helm lint/template → build → trivy → push by digest
→ bump chart digests → ArgoCD syncs.

- **CI holds no kubeconfig and must never hold one.** Its last act is a git commit.
- **Build once, promote by digest.** The image is scanned before it is pushed.
- **Every gate blocks.** If a gate is failing, fix the cause. Do not add an ignore, lower a
  threshold, or mark it advisory. A CVE finding from trivy is real: bump the pinned version.

`RUNBOOK.md` has the setup steps and the traps that cost real time.

---

## When you are unsure

Say so, and check. This repo's value is that its claims were executed, not asserted — the
race conditions have reproductions, the timeout kill has a negative control, the coverage
gate was caught measuring 0%. Guessing and sounding confident is the one failure mode that
makes it worthless.