docs: rewrite the agent context layer to match the live system #81

Merged

admin_emi merged 1 commit from worktree-docs+context-layer-truth into dev

2026-07-25 07:08:55 +00:00

admin_emi commented

2026-07-25 04:00:14 +00:00

Owner

Phase 1 of the architecture simplification plan: make the files an agent reads before every change actually true.

Why

Four of the five domain CLAUDE.md files described the pre-monorepo split-repo world, and several statements were the exact inverse of reality. Verified against the tree:

File	Claimed	Actual
`infra/CLAUDE.md`	"the old monorepo (`emi/thermograph`) is archived — do not point anything at it"	That is the live repo. The split repos are the archived ones.
`infra/CLAUDE.md`	"this repo never checks out app source"	One repo now; hosts check out the monorepo.
`infra/README.md`	"compose in production today"; Swarm "not currently live"	Prod runs Swarm, from `deploy/stack/thermograph-stack.yml`.
`backend/CLAUDE.md`	"There is no Makefile in this repo"	`backend/Makefile` exists.
`backend/CLAUDE.md`	image `emi/thermograph-backend/app`, workflows `build-push.yml`/`deploy.yml`	`emi/thermograph/backend`, `backend-*.yml`
`frontend/CLAUDE.md`	"one of four sibling repos in `thermograph-repos/`"; no `requirements-dev.txt`; no `Makefile`	One repo; both files exist.
`observability/CLAUDE.md`	"Single `main` branch, no protection"	Lives in the monorepo under `dev`/`main`/`release`.

These files are load-bearing input to every change, so staleness here is a correctness problem, not a documentation one. The root CLAUDE.md did warn that domain files used repo-era wording — but each domain file still reads as authoritative on its own.

What changed

Root CLAUDE.md now owns cross-cutting truth once: branch model, the SERVICE + *_IMAGE_TAG deploy contract, image names, which orchestrator each environment runs, and that everything is a PR. Domain files carry only what differs and are capped at ~70 lines.
Deleted infra/docker-stack.yml. It defined db/app/worker, was referenced by nothing that deploys, and was described in prose as a design record for a "possible future" Swarm deploy — while the real 8-service prod stack already lives under deploy/stack/. A file that looks authoritative and affects nothing is the worst case for someone asked to change the prod stack.
Recorded that the two *-deploy-dev.yml workflows are inert, rather than leaving a reader to discover it.
infra/README.md: corrected the orchestrator claim and recorded infra-sync.yml, replacing "there is no separate infra deploy trigger".
The compose timescale-pin comment now points at how deploy-stack.sh actually resolves the digest from the running container (including the compose thermograph-db-1 name).

Adopts one rule going forward, stated at the top of the root file: a CLAUDE.md may only contain statements that would break CI if they became false, or that name a file that exists. Everything else belongs in thermograph-docs.

Net −305 lines. No behaviour change; the only non-markdown edits are the deleted decoy file and a comment.

Verification

Every known-false string greps clean across the five CLAUDE.md files plus both READMEs.
infra/docker-compose.yml, docker-compose.openmeteo.yml and deploy/stack/thermograph-stack.yml all still parse; docker compose config fails only on the expected unset POSTGRES_PASSWORD.
No remaining reference to the deleted file outside deploy/forgejo/, which legitimately has its own.
The one surviving "sibling" is deploy.sh's sibling service, which is correct usage.

Phase 1 of the architecture simplification plan: make the files an agent reads before every change actually true. ## Why Four of the five domain `CLAUDE.md` files described the pre-monorepo split-repo world, and several statements were the **exact inverse** of reality. Verified against the tree: | File | Claimed | Actual | |---|---|---| | `infra/CLAUDE.md` | "the old monorepo (`emi/thermograph`) is archived — do not point anything at it" | That is the live repo. The *split* repos are the archived ones. | | `infra/CLAUDE.md` | "this repo never checks out app source" | One repo now; hosts check out the monorepo. | | `infra/README.md` | "compose in production today"; Swarm "not currently live" | **Prod runs Swarm**, from `deploy/stack/thermograph-stack.yml`. | | `backend/CLAUDE.md` | "There is **no Makefile in this repo**" | `backend/Makefile` exists. | | `backend/CLAUDE.md` | image `emi/thermograph-backend/app`, workflows `build-push.yml`/`deploy.yml` | `emi/thermograph/backend`, `backend-*.yml` | | `frontend/CLAUDE.md` | "one of four sibling repos in `thermograph-repos/`"; no `requirements-dev.txt`; no `Makefile` | One repo; both files exist. | | `observability/CLAUDE.md` | "Single `main` branch, no protection" | Lives in the monorepo under `dev`/`main`/`release`. | These files are load-bearing input to every change, so staleness here is a correctness problem, not a documentation one. The root `CLAUDE.md` did warn that domain files used repo-era wording — but each domain file still reads as authoritative on its own. ## What changed - **Root `CLAUDE.md` now owns cross-cutting truth once**: branch model, the `SERVICE` + `*_IMAGE_TAG` deploy contract, image names, which orchestrator each environment runs, and that everything is a PR. Domain files carry only what differs and are capped at ~70 lines. - **Deleted `infra/docker-stack.yml`.** It defined `db`/`app`/`worker`, was referenced by nothing that deploys, and was described in prose as a design record for a "possible future" Swarm deploy — while the real 8-service prod stack already lives under `deploy/stack/`. A file that looks authoritative and affects nothing is the worst case for someone asked to change the prod stack. - Recorded that the two `*-deploy-dev.yml` workflows are **inert**, rather than leaving a reader to discover it. - `infra/README.md`: corrected the orchestrator claim and recorded `infra-sync.yml`, replacing "there is no separate infra deploy trigger". - The compose timescale-pin comment now points at how `deploy-stack.sh` actually resolves the digest from the running container (including the compose `thermograph-db-1` name). Adopts one rule going forward, stated at the top of the root file: *a `CLAUDE.md` may only contain statements that would break CI if they became false, or that name a file that exists.* Everything else belongs in `thermograph-docs`. Net **−305 lines**. No behaviour change; the only non-markdown edits are the deleted decoy file and a comment. ## Verification - Every known-false string greps clean across the five `CLAUDE.md` files plus both READMEs. - `infra/docker-compose.yml`, `docker-compose.openmeteo.yml` and `deploy/stack/thermograph-stack.yml` all still parse; `docker compose config` fails only on the expected unset `POSTGRES_PASSWORD`. - No remaining reference to the deleted file outside `deploy/forgejo/`, which legitimately has its own. - The one surviving "sibling" is `deploy.sh`'s sibling *service*, which is correct usage.

admin_emi added 1 commit 2026-07-25 04:00:15 +00:00

docs: rewrite the agent context layer to match the live system

secrets-guard / encrypted (pull_request) Successful in 10s

Details

PR build (required check) / changes (pull_request) Successful in 17s

Details

shell-lint / shellcheck (pull_request) Successful in 14s

Details

PR build (required check) / validate-observability (pull_request) Successful in 44s

Details

PR build (required check) / build-frontend (pull_request) Successful in 2m13s

Details

PR build (required check) / build-backend (pull_request) Successful in 2m31s

Details

PR build (required check) / gate (pull_request) Successful in 3s

Details

c98512cfcc

The four domain CLAUDE.md files still described the pre-monorepo split-repo
topology, and several statements were the exact inverse of current reality:
infra/CLAUDE.md told a reader that emi/thermograph is archived and must not be
pointed at, when that is the live repo; backend/ and frontend/ both claimed
there is no Makefile and no requirements-dev.txt when all four files exist;
frontend/ described itself as one of four sibling repos; observability/ claimed
a single unprotected main branch.

These files are read before every change, so a stale one is a correctness
problem rather than a documentation one. Rewritten against the tree:

- Root CLAUDE.md now owns the cross-cutting truth once — branch model, the
  SERVICE + *_IMAGE_TAG deploy contract, image names, which orchestrator each
  environment runs, and that everything is a PR. Domain files carry only what
  differs and are capped at ~70 lines.
- Records that prod runs Swarm from deploy/stack/thermograph-stack.yml while
  beta and LAN dev run compose, routed by /etc/thermograph/deploy-mode.
- Documents the *-deploy-dev.yml workflows as inert rather than leaving a
  reader to discover it.

Deletes infra/docker-stack.yml. It defined db/app/worker, matched nothing that
deploys, and was referenced only by prose describing it as a future design
record — while the real 8-service prod stack lives under deploy/stack/. A file
that looks authoritative and affects nothing is the worst case for a reader
asked to change the prod stack.

infra/README.md claimed "compose in production today" and that Swarm was "not
currently live"; corrected, and infra-sync.yml's existence is now recorded
instead of "there is no separate infra deploy trigger". The compose file's
timescale-pin comment now points at how deploy-stack.sh actually resolves the
digest from the running container.