Grant Whitmer
dfe5543eda
RUNBOOK-VERON: deploy uses fetch + merge --ff-only and api-only rebuilds (the old text used git pull, contradicting its own warning); new sections for host timers, CI (6 runners x1, windyadmin-scoped, 90m ceiling, queue truth in the gitea DB, logs in R2), sign-in posture and break-glass; standing checkout = OC5. AGENTS.md no longer says GENESIS / no code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
46 lines
3.6 KiB
Markdown
46 lines
3.6 KiB
Markdown
# AGENTS.md — windy-git
|
||
|
||
Read this before touching anything. Then read `DNA_STRAND_MASTER_PLAN.md`, which is the source of truth.
|
||
|
||
## Current state (2026-09-23)
|
||
|
||
**LIVE on Veron 1** — `app.windygit.com` (Gitea 1.24.6, Windy SSO only),
|
||
`api.windygit.com` (our plane: humans via hub JWKS, agents via Eternitas EPT),
|
||
`models.windygit.com`. Strands G0–G5, G7, G11 done; see the plan for the rest.
|
||
|
||
It is also **the permanent CI for the private platform repos** (GitHub Actions
|
||
cannot run on them): `scripts/sync_from_github.sh` + `scripts/pr_status_bridge.py`,
|
||
onboarding in `docs/CUTOVER.md`, operations in `docs/RUNBOOK-VERON.md`.
|
||
|
||
Standing dev checkout: **OC5 `~/windy-git`**. Deploy copy: Veron `/srv/windygit/src`.
|
||
|
||
## The rules that will get you reverted if you break them
|
||
|
||
1. **Do not fork Gitea.** (D-2 / I-1.) Our code calls Gitea's REST API from our own service. Any patch to Gitea source goes in `patches/` as a numbered rebasable diff with a one-line justification, and `make check` fails past **3** files without an ADR.
|
||
2. **Never say "a Git."** (D-9 / I-9.) Git is not a countable noun. A moment in time is a *commit*; user-facing, it is a *version* or *save point*. `make check` greps for violations.
|
||
3. **Never touch Kit 0.** (D-4 / §7.8.) Not in v0, not in v1. Only Grant may overturn a never.
|
||
4. **No Stripe. No prices. No checkout.** (I-11.) This cell emits usage events; the Windy Cloud kernel owns the ladder.
|
||
5. **Never claim live while a provider is mock.** (I-8.) Every seam fails closed. `/health/full` reports what it can prove and nothing more.
|
||
6. **`repo_type` exists from migration 001.** (I-7.) Never inferred, never defaulted at read time, never retrofitted.
|
||
7. **Git objects on local disk, heavy bytes on R2. Never the reverse.** (I-3.)
|
||
8. **`/version` must be honest.** (I-12.) The commit sha is baked at image build; a runtime `COMMIT_SHA` env var is **ignored with a warning**. Nine of twelve sibling services cannot name their own commit — we will not be the tenth.
|
||
9. **Every invariant has a named test.** Cite the invariant in the test file header.
|
||
10. **An unverifiable codon is not done.** Every codon in the plan has an acceptance criterion. Finished-looking code without its acceptance test is not finished.
|
||
|
||
## House conventions
|
||
|
||
- Python 3.12 · FastAPI · pydantic-settings · Postgres schema `windgit` · own alembic, every migration with a tested downgrade.
|
||
- `make check` = `ruff` + `mypy` + `pytest` + membrane-drift + capabilities-drift + `/version` honesty + vocabulary audit. **The local gate IS the merge gate.**
|
||
- Errors are 4-field repair pointers: `{code, speak, machine_cause, remediation_tool}`. No exceptions, including validation errors.
|
||
- Every tool response carries `state_proof` + `next_actions`.
|
||
- Telemetry `actor_type` comes from the enum `{human, agent, system}`. **`'service'` is not legal** — it 422s and silently drops the whole batch. A sibling service is losing telemetry to exactly this today.
|
||
- Runner labels are explicit and pinned: `[self-hosted, linux, x64]` or `veron-1`. **`ubuntu-latest` is banned** — no runner here has it, so the job queues forever.
|
||
|
||
## Membrane
|
||
|
||
Calls out, calls in, and events are **enumerated in invariant I-2** and mirrored in `docs/MEMBRANE.v1.md`. Adding a call means editing I-2 first, then the doc, then the code. Not the other way round.
|
||
|
||
## What needs Grant
|
||
|
||
See §7 of the plan. Short version: opening to any non-Grant user · any pricing · advancing off the GitHub mirror · marketing provenance before the upstream integrity fix lands · a hard fork of Gitea · the marketing site · enabling `repo_type=model` in production · anything involving Kit 0.
|