ℹ️ About Codex in GitHub

\\n
\\n\\n[Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general). Reviews are triggered when you\\n- Open a pull request for review\\n- Mark a draft as ready\\n- Comment \\\"@codex review\\\".\\n\\nIf Codex has suggestions, it will comment; otherwise it will react with 👍.\\n\\n\\n\\n\\nCodex can also answer questions or update the PR. Try commenting \\\"@codex address that feedback\\\".\\n \\n

\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"Fixed in a096192 — updated `web/.env.production` to `0.0.3` to match current `version.txt`/manifest, and re-verified with a real `npm run build` that `0.0.3` correctly bakes into both `errorReport.ts` and `AppLayout.tsx`.\\n\\n---\\n_Generated by [Claude Code](https://claude.ai/code)_\",\"path\":\"web/.env.production\",\"side\":\"RIGHT\",\"line\":null}","text_elements",[],{"_402":643,"_381":382,"_404":388},{"_405":644,"_407":-5,"_45":-5,"_409":645,"_411":-5,"_99":328,"_95":413},[646],{"_414":388},{"_49":639,"_95":437},{"_402":648,"_381":382,"_404":388},{"_405":649,"_407":-5,"_45":-5,"_409":650,"_411":-5,"_99":328,"_95":413},[651,652],{"_414":388},{"_49":654,"_95":437},{"_49":653,"_95":437},"\n /workspace/cluckwork\n bash\n 2026-08-08\n Etc/UTC\n /workspace/cluckwork\n","# AGENTS.md instructions for /workspace/cluckwork\n\n\n# AGENTS.md — Cluckwork\n\nPoultry egg-farm management system. Backend: **.NET 10** (C#), layered DDD. Frontend: **React 19 + Vite** SPA in `web/`. Postgres via EF Core.\n\nThis file is the shared brief for any coding agent (Claude Code, Codex, etc.).\n\n## Communicating\n\nKeep explanations clear and human-sounding. Provide concise, focused responses. Skip preambles and recaps — lead with the action or answer.\n\n## Layout\n\n```\nsrc/\n Cluckwork.Domain aggregates, value objects, domain events (no deps)\n Cluckwork.Application feature handlers, repository interfaces, validators\n Cluckwork.Infrastructure EF Core, Identity/JWT, repositories, seeding, jobs\n Cluckwork.Api minimal-API endpoints, middleware, Program.cs\nweb/ React/Vite SPA (see web/README.md)\ndeploy/ docker-compose (.yml prod, .dev.yml dev DB), .env.example\nspecs/ product + technical specs, wireframes\ntests/ Domain.Tests, Application.Tests, Api.IntegrationTests\n```\n\nDependencies point inward: Api → Application/Infrastructure → Domain. Domain depends on nothing.\n\n## Build / test / run\n\n```bash\ndotnet build Cluckwork.sln # warnings are errors — keep it clean\ndotnet test Cluckwork.sln # 688 tests as of 2026-07; integration needs Docker\n```\n\n- **Integration tests** spin up a real Postgres via Testcontainers (`docker` required). No SQLite — EF SQL semantics differ.\n- **Run full stack (prod-like):** `docker compose -f deploy/docker-compose.yml up --build` → SPA + API on http://localhost:8080 (single container; API serves the built SPA from `wwwroot`).\n- **Run frontend dev:** `cd web && npm run dev` → http://localhost:5173 (proxies `/api` → :8080).\n- **Debug API (no docker stack):** `docker compose -f deploy/docker-compose.dev.yml up -d` (Postgres on :5432), then run/debug `Cluckwork.Api` (Development env). Dev secrets live in **user-secrets**, not files.\n\n## Conventions (follow these)\n\n- **Result pattern:** domain/handlers return `Result` / `Result` (see `Domain/Common`). Don't throw for expected failures; throw only for invariant violations (e.g. `Flock.Create` guards).\n- **Every aggregate mutation must bump `Version`.** `Version` is an EF concurrency token (`IsConcurrencyToken`) — EF puts the *original* value in the UPDATE's WHERE but never auto-increments it. A mutation without `Version++` silently loses concurrent races (both writers match `WHERE Version = N`) instead of 409ing. This bug shipped three times (`RecordProduction` was correct; `Submit`/`Lock` and `SalesOrder.AddItem` weren't) — each now has a parallel-race integration test; add one for any new mutation.\n- **Handler per feature**, invoked directly from endpoints — **no MediatR**. Register handlers/validators/repos in `Program.cs`.\n- **Validation:** FluentValidation validators (`*Validator`), one per command; endpoints call `ValidateAsync` and return `ValidationProblem`.\n- **Endpoints:** minimal APIs grouped under `/api/v1/...` via `MapEndpoints`; writes require auth + an `Idempotency-Key` (middleware).\n- **Multi-tenancy:** every tenant-owned entity has `AccountId`; enforced by an EF **global query filter** + a **`TenantStampInterceptor`** (stamps on insert). `TenantContext` is resolved per-request from the JWT `account_id` claim. At startup it's unresolved → use `IgnoreQueryFilters()` in seeders.\n- **Auth:** asymmetric JWT + rotating refresh tokens. PEM keys come from config with escaped `\\n`; normalize via `PemKey.Normalize` before `ImportFromPem`. Integration tests generate an ephemeral RSA pair at test-process startup (`TestJwtKeys` in `CluckworkWebApplicationFactory.cs`) — no real key material is ever committed to source (`deploy/.env.example` carries PEM armor with a `replace-me` body, not a usable key).\n- **Credential epoch revocation (#364).** Every access/refresh token is bound to the user's `CredentialEpoch`; every password-reset path bumps it so issued credentials fail on next use. Epoch **`0` is permanently retired** (users start at `1`, legacy refresh rows at `0`), and a missing/malformed `credential_epoch` claim is **always a mismatch** — never default it to the DB epoch. `CredentialEpochMiddleware` does a **fresh DB read per authenticated request** (the round trip *is* the fail-closed guarantee — do not cache), sits **after `TenantResolutionMiddleware`, before `MustChangePasswordMiddleware`**, and exempts `auth/logout`. Login/step-up snapshot the verified epoch+stamp before clearing failed-access and refuse issuance on a concurrency-loss reload. Distinct from #283/#265/#308 — none substitutes for another. **Break it and a revoked credential keeps working.** → [`docs/decisions/364-credential-epoch-revocation.md`](docs/decisions/364-credential-epoch-revocation.md)\n- **Base reference data via guarded raw-SQL migrations (#283).** The default account, four assignable roles, default egg grades, and packed-unit conversions are **static reference data baked into the migrations** as hand-written `migrationBuilder.Sql` with `WHERE NOT EXISTS` guards — **never `HasData`/`InsertData`** (which key on the PK and would either collide or emit `UpdateData`/`DeleteData` that silently reverts the farm's own edits). No runtime seeder, no `Seed:*`. The **grades** guard is whole-set (empty catalog, because grades are user-renamable); roles/conversions/account are **per-key** (keys aren't user-mutable). Pinned by `MigrationSecurityReviewTests` + `BaseReferenceDataMigrationTests`. **Regenerate these into `HasData` and a later model-diff reverts a renamed grade.** → [`docs/decisions/283-migrations-base-provisioning.md`](docs/decisions/283-migrations-base-provisioning.md)\n- **Migrations: `InitialCreate` frozen, one migration per change (#407).** `Persistence/Migrations/` is one squashed `InitialCreate` (recorded id `20260801190854_InitialCreate`); it is **frozen and never regenerated**, and **every schema change gets its own `dotnet ef migrations add`**. EF never re-runs an applied migration, so a column **hand-folded into `InitialCreate` silently does not exist** on any booted DB — it surfaces as broken behaviour (a failed login, #399), not a migration error. `InitialCreate` also carries four un-regenerable `lower(\"Name\")` expression indexes + the base-reference SQL; regenerating mints a new timestamp that desynchronises `__EFMigrationsHistory` everywhere. Pre-squash or pre-#407 dev DBs can't migrate forward — drop and recreate. `MigrationSecurityReviewTests` freezes the id + a portable operation digest. → [`docs/decisions/407-migration-freeze.md`](docs/decisions/407-migration-freeze.md)\n- **Seed / simulation data is never boot-seeded (#280, #284, #279).** Run it explicitly against an **already-base-seeded, non-Production** database: `ASPNETCORE_ENVIRONMENT=Development dotnet Cluckwork.Api.dll seed --profile demo|simulation` (an unset env → Production → blocked). The verb migrates, seeds, then exits — **authoritative** (ignores config) and **fail-loud** (a real exit code, never a silent no-op). `simulation` additionally records a durable date anchor + completion marker, so a clean re-run — even across a UTC-midnight rollover — converges to `AlreadySeeded`; a polluted account fails the exact-count validation **closed**. → [`docs/decisions/280-seed-and-simulation.md`](docs/decisions/280-seed-and-simulation.md)\n- **Break-glass recovery (#265):** `recover-admin` is a second one-off CLI verb on the same binary, same run-then-exit shape as `seed` — but deliberately **NOT** environment-gated (it must work against a real Production database): `dotnet Cluckwork.Api.dll recover-admin --email [--account ] [--reason ]`. For a locked-out account (the sole-Owner-lost-password case, no email/SMTP reset path) it, in one transaction, resets to a **freshly generated** temporary password (never one passed on the command line), rotates the security stamp, revokes every refresh token, and writes a conspicuous `User.BreakGlassReset` audit row carrying `--reason`. The temp password is printed to **stdout only** (never the logger/OTLP) and exit `0`; failures go to stderr with exit `1` and change nothing. `AdminRecoveryService` orchestrates; `IdentityProvider.BreakGlassResetAsync` shares the reset/revoke core with `SetUserPasswordAsync`. Full procedure + verification drill: `docs/runbooks/break-glass-account-recovery.md`.\n- **First-run admin provisioning: `bootstrap-admin` (#283).** `dotnet Cluckwork.Api.dll bootstrap-admin --email ` (run-then-exit, always available in Production) migrates, then — **only if the default account has no Owner** — creates one with a **freshly generated password (stdout only, never the logger/OTLP)** and `MustChangePassword=true`; a re-run is a **silent no-op**. While the flag is set the JWT carries `must_change_password`, `MustChangePasswordMiddleware` 403s every endpoint except `auth/change-password`+`auth/logout` (before `UseAuthorization` and before idempotency), and the SPA renders **Set your password**. Any successful reset clears the flag (one invariant in `IdentityProvider`). **Deliberately a separate credential type from #265/#308** — never conflated. → [`docs/decisions/283-first-run-admin-provisioning.md`](docs/decisions/283-first-run-admin-provisioning.md)\n- **Farm timezone + tzdata/ICU image constraint (#264):** the default account (a fixed `\"UTC\"` migration literal since #283) is provisioned once; a real farm sets its actual IANA zone via **Settings → timezone** after first login (`Account.UpdateSettings`), not at provisioning time (the `Seed:TimeZoneId` config lever from before #283 is retired along with the runtime seeder it fed). The farm clock resolves IANA zones via `TimeZoneInfo.FindSystemTimeZoneById` for every safety-sensitive local-day decision and **fails closed**, so the runtime **image MUST carry tzdata + ICU** (the Ubuntu 24.04 (Noble) `aspnet:10.0` base does; **never** an Alpine/chiseled base without tzdata, and **never** `InvariantGlobalization=true`). `Program.cs` still asserts a representative IANA canary resolves at boot (`TimeZoneAvailability.EnsureResolvable`) — a bad image fails the boot loudly instead of surfacing later as a per-request `FarmTimeZoneException`.\n- **Migrate command + prod migration split (#263).** `dotnet Cluckwork.Api.dll migrate` applies EF migrations then exits — the **pre-deploy-job entrypoint**. In Production `Database:MigrateOnStartup=false`, so the serving process never runs DDL; the **guarantee is ordering** — compose runs a one-shot `migrate` service before `app` waits on `service_completed_successfully`. `DatabaseReadyHealthCheck` is the backstop: `/health/ready` **503s while any migration is pending**. The remaining host step (deploy repo) is a least-privilege runtime role with no DDL, plus `ALTER DEFAULT PRIVILEGES` for the migrator. → [`docs/decisions/263-migrate-command.md`](docs/decisions/263-migrate-command.md)\n- **Proxy-trust boot guard (#260):** behind a reverse proxy/edge, HSTS (#144) and the per-IP login limiter (#143) only work if the app trusts the proxy's `X-Forwarded-*`, which it does **only** for networks in `RateLimiting:TrustedProxies`. An **empty list in Production fails the boot** (a serving-process guard placed *after* the CLI dispatch, so `migrate`/`seed`/`recover-admin` are unaffected) rather than silently running with inert HSTS + a one-bucket limiter. Opt out with `RateLimiting:AllowNoTrustedProxies=true` only for a rare direct-TLS deploy with no fronting proxy. The concrete edge CIDR is deploy config (in the separate deployment/ops repo).\n- **Production Postgres TLS floor (#261/#262).** `ConnectionStrings:Default` accepts libpq URI or key-value form. In Production the effective `sslmode` is a **fail-closed allow-list**: `VerifyCA`/`VerifyFull` silent, `Require` warns, **everything else — `Disable`/`Allow`/`Prefer`, unset, or undefined — fails the boot**. `Database:AllowInsecureConnection=true` is the explicit opt-out for the co-located plaintext compose stack. When mapping a libpq param, **`ContainsKey(\"\")==false` does NOT mean Npgsql lacks the setting** — usually the keyword is spelled differently (`keepalives`→`Tcp Keepalive`, `client_encoding`→`Client Encoding`); search the keyword list before concluding it's unmappable (that exact false negative shipped #332). Integration tests opt out of this **and** the #260 guard. → [`docs/decisions/261-postgres-tls-floor.md`](docs/decisions/261-postgres-tls-floor.md)\n- **GSS/Kerberos negotiation off by default (#332).** `PostgresConnectionString` appends `GSS Encryption Mode=Disable` **unless the operator set it** (detected by **presence, not value**), **textually** after the TLS floor runs (a round-trip through the Npgsql builder would reorder/requote the operator's string and throw on any keyword this version doesn't know). Without it, Npgsql's `Prefer` default makes every connector dlopen the absent `libgssapi_krb5.so.2` and print two pre-Serilog stderr lines per process. Orthogonal to `sslmode` and to GSS *authentication*. → [`docs/decisions/332-gss-kerberos.md`](docs/decisions/332-gss-kerberos.md)\n- **Design-time migration connection fail-closed (#318):** `AppDbContextDesignTimeFactory` (used by `dotnet ef migrations add`/`database update`, never by the `migrate` verb, which uses the built host's own config) has **no default connection** — an unset/blank `CLUCKWORK_MIGRATIONS_CONNECTION` throws immediately, naming the variable, rather than falling back to a predictable `Host=localhost;...;Username=postgres;Password=postgres`. Every target is held to the **same allow-list TLS floor as a Production boot** (#261/#262, reused via `PostgresConnectionString.NormalizeAndValidate` — no second validator), except an explicitly acknowledged **loopback** development target: `CLUCKWORK_MIGRATIONS_ALLOW_INSECURE_LOOPBACK=true` permits plaintext, but only when the connection's host is `localhost`/`127.0.0.1`/`::1` (checked via `IPAddress.IsLoopback`) — set against any other host, it fails rather than silently widening scope.\n- **Container image hardening (#267):** the runtime stage runs **non-root** (`USER $APP_UID`, uid 1654 — the base image's built-in `app` account); all three base images are **digest-pinned** (`@sha256:…`, kept current by Dependabot's `docker` ecosystem); a CI job builds the image and **Trivy** fails the build on a *fixable* HIGH/CRITICAL. `aquasecurity/trivy-action` is **SHA-pinned** — the action was compromised in the 2026-03 supply-chain incident, so pin the immutable commit, not the re-pointable tag (this is the standing rule for third-party actions). Keep the full glibc base (tzdata + ICU per #264); never chiseled/Alpine.\n- **Container health probe: the `healthcheck` verb (#266).** The runtime image and the compose `app` service run `dotnet Cluckwork.Api.dll healthcheck` — a run-then-exit verb **dispatched before host build** (it needs no host/DI/DB/config, so a 30s probe doesn't re-run startup or re-log boot warnings). The hardened image ships no curl/wget, so the probe is **in-process**: it GETs `/health/ready` over loopback and exits `0` on a 2xx, `1` on any other status or an unreachable server — **never a false green**. CI boots the built image and asserts `/health/ready` goes green. → [`docs/decisions/266-container-health-probe.md`](docs/decisions/266-container-health-probe.md)\n- **Transient-DB retry, and where it stops (#269).** `EnableRetryOnFailure` retries only **self-contained EF units** (every read, every `SaveChanges` outside a user transaction); it must **not** wrap unreplayable work. The general hazard is **an automatic replay sitting above a stateful detector** (a monotonic counter, a CAS stamp, a single-use claim) that can't tell \"this request racing itself\" from the signal it exists to detect. Two cures, and picking wrong ships the bug: **`SingleAttemptExecution`** when the replay is itself observable (e.g. `AccessFailedAsync`'s second durable increment — otherwise one wrong password locks at ~half the #128 threshold); a **durability probe keyed on a self-minted token** when the replay writes nothing and the defect is a mis-read `catch` (refresh-token rotation, login/reset `INSERT`s). All fail closed; pinned from both sides in `RetryBoundaryTests`. → [`docs/decisions/269-transient-db-retry-boundary.md`](docs/decisions/269-transient-db-retry-boundary.md)\n- **A new Production boot guard must be taught to the sim harness (#370).** Every guard that fails the boot on missing/invalid config (#260, #261/#262, #316, #319, …) and every config-key add/rename/retire must **also update `tools/simulation/bootstrap.sh` + `docker-compose.sim.yml` + `verify-harness.sh` in the same PR** — that harness runs **Production config on purpose**, is **deliberately not in CI**, and every path into it is human-started, so nothing tells you when you break it (four guards once landed unnoticed until it couldn't boot `main`). Satisfy guards **properly** (a concrete `AllowedHosts`, the documented opt-outs), never by disabling one. **Treat a boot-guard PR that leaves the harness behind like a missing test.** → [`docs/decisions/370-sim-harness-boot-guards.md`](docs/decisions/370-sim-harness-boot-guards.md)\n- **SPA E2E lives in `tools/simulation/ui/` (#277/#385).** Playwright drives the real built SPA over the **same** `seed --profile simulation` fixture k6 uses; `web/` stays Vitest + Testing Library. Three enforced rules, each of which has caught something: **never hardcode a credential** (personas from the git-ignored `.sim-cast.json`), **never hardcode English** (selectors resolve through the SPA's own en/es/tl catalogs — a missing key throws), and **respect the farm clock** (`America/Chicago` is behind UTC). Mutation-checked (`npm run mutation`; a red baseline aborts). **The quick suite runs on PRs** (path-filtered, ~3 min; owner call 2026-08-08 after #433 broke it silently); the `slow`/`canary` modes and the k6 sibling stay `workflow_dispatch`-only, so the #370 warning still applies to those. → [`docs/decisions/277-spa-e2e.md`](docs/decisions/277-spa-e2e.md)\n- **A write-contract change must update its non-CI callers (#394).** Adding a required field, tightening a validator, or changing an aggregate's state machine breaks automated callers no test references. **Coverage is not uniform:** the seeders are covered only to the handler/domain layer, so a **validator-only** tightening is invisible to all five seeder tests (they call `HandleAsync` directly, skipping `ValidateAsync`); `tools/simulation/k6/` and the Playwright specs are **uncovered**, and a green baseline hides it (`authedPost` counts a tolerated `[403,409,422]` as a pass, and `reset.sh` never runs k6). **So verify the request/status contract by reading the callers, not by running.** Grep callers of the endpoint, re-check each payload, and narrow a tolerated-status list when a status flips from \"constrained write\" to \"broken write\". → [`docs/decisions/394-write-contract-callers.md`](docs/decisions/394-write-contract-callers.md)\n- **Production logs: compact JSON on stdout; base layer argument-free (#404).** stdout is the only sink (no file/vendor sink). Production selects `CompactJsonFormatter`; Development the human `outputTemplate`; the base `appsettings.json` Console entry carries **`Name` only, no `Args`** — a template left in the base file merges *beside* the formatter and Serilog **silently binds the template and ignores the formatter**. Trace fields differ by format: compact JSON writes **`@tr`/`@sp`**, the Dev template `{TraceId}`/`{SpanId}` — a collector query against the wrong name matches nothing. **Compact JSON serializes EVERY property**, so anything pushed via `BeginScope`/`LogContext`/`ForContext` now reaches the collector (see #273 for the redaction answer). Pinned by `ProductionLogFormatTests`. → [`docs/decisions/404-production-logs.md`](docs/decisions/404-production-logs.md)\n- **Nullable enabled**, no unused usings (both are build-breaking).\n\n## Secrets — never commit\n\n- `deploy/.env` is gitignored (real values). `deploy/.env.example` holds placeholders only.\n- Local API debug config uses `dotnet user-secrets` (keyed by `UserSecretsId` in `Cluckwork.Api.csproj`).\n- No hardcoded passwords/keys in source — GitGuardian scans PRs. Generate test credentials at runtime.\n\n## Host-agnostic repo (deployment boundary)\n\nThis repo is **host-portable** — it must build and run against any host without\ncarrying provider-specific config. The app reads every environment specific from\nconfig/env (connection string, `RateLimiting:TrustedProxies`, `Seed:TimeZoneId`,\nPostgres `sslmode`, …) and **never names or branches on a hosting provider**.\n\n- **Stays here** (portable operational contract): the Dockerfile (incl. its\n `HEALTHCHECK`), `deploy/` compose as a local/reference stack, health probes\n (`/health/live`, `/health/ready`), the `migrate` / `seed` / `recover-admin` /\n `healthcheck` verbs, `.env.example`, and docs that state *requirements* (\"needs tzdata + ICU\",\n \"needs a trusted-proxy list\", \"needs TLS to Postgres\", \"a fronting CDN must\n respect origin cache headers\").\n- **Does NOT belong here** (goes to a **separate deployment/ops repo**):\n provider deploy manifests (`railway.json`, `fly.toml`), IaC (Terraform/Pulumi),\n CDN / DNS / edge config, secret-store wiring, provider-named runbooks, and the\n concrete environment *values* (proxy CIDRs, CA bundles, connection URLs).\n\nReviewers: treat a hardcoded provider name in code, config, or a committed doc\nlike a missing test — flag it. Naming a provider as a passing *example* in prose\nis tolerable only when no portable phrasing works; prefer the neutral term.\n\n## Writing a guard (a test that asserts an invariant)\n\nA guard is a test whose job is to *fail* when someone later does the wrong thing — the migration freeze (`MigrationSecurityReviewTests`), the body-reading endpoint check, the simulation manifest's exact counts. **A wrong guard is worse than no guard, because it reads as safety.** #407 spent five review rounds on one. The full rules with the incidents that earned them are in [`docs/decisions/407-writing-a-guard.md`](docs/decisions/407-writing-a-guard.md); in brief:\n\n- **Run a local adversarial pass before the first push** — mutation checks, or a second agent handed the diff and told to *refute* it. Most of #407's rounds were findable locally in seconds.\n- **Mutation first, claim second** — never write \"this catches X\" before running the mutation that makes the guard go red.\n- **Two misses of the same shape mean the METHOD is wrong** — prefer \"walk everything, exclude deliberately\" over \"list what I thought of.\"\n- **For a pinned/golden value, prove portability** — repetition on one machine cannot detect environment leakage; assert the generated content names no absolute paths or assembly files.\n- **Prefer the boring guard** — complexity costs double when the complicated thing is the thing you're trusting.\n\n## Pre-commit hook (opt-in)\n\n`git config core.hooksPath .githooks` enables a ~2s pre-commit hook: unit tests\n(domain + application) when `.cs`/`.csproj`/`.sln` files are staged, `npm run typecheck` when\n`web/` files are staged. Integration tests are deliberately excluded (Docker,\nslow) — CI is the authority. Skip once with `--no-verify`.\n\n## CI security gates (#146)\n\nCI fails a PR when a **production** dependency carries a known **high+** advisory — NuGet (`dotnet list package --vulnerable`) and npm prod deps (`npm audit --omit=dev`; dev-only advisories are logged, not blocking). Plus dependency-review (PR diff), CodeQL (advisory), and a weekly scheduled audit. Both audit gates run through `.github/scripts/vuln-gate.mjs` and **fail closed**; the only mute is a dated `.github/security-exceptions.json` entry (exact GHSA id, required `expires`).\n\n**NuGet lock files.** Every project has a committed `packages.lock.json` and CI restores `--locked-mode`. **When you add or bump a package, run `dotnet restore` and commit the changed lock files in the same commit** — else CI fails the restore with `NU1004`. Dependabot NuGet PRs are auto-healed by `.github/workflows/dependabot-lockfix.yml`.\n\n**Pin third-party Actions to a full commit SHA** with a trailing `# vX.Y.Z` comment — **never a mutable tag** (the 2026-03 `aquasecurity/trivy-action` and 2025-03 `tj-actions/changed-files` compromises retargeted tags to secret-exfiltrating code). `actions/*` and `github/*` may keep major-version tags.\n\nFull rationale — the transitive-graph submission, the shared GitHub App and its `permission-*` downscoping, the exception-gate fail-closed shapes — is in [`docs/decisions/146-ci-security-gates.md`](docs/decisions/146-ci-security-gates.md).\n\n## Releases and image publishing (#351)\n\nTwo stages, deliberately separate: **CI publishes an image per merge; the release PR turns one into a version.** `README.md`'s \"Releases & container images\" is the **how-to**; this section is the **invariants — what not to break**; the full mechanism (release-please twice per push, the `groom` boundary probe, the commit-body parser, the App-token reasoning, the repair path) is in [`docs/decisions/351-releases.md`](docs/decisions/351-releases.md).\n\n- **Every merge to `main`** publishes `ghcr.io//:sha-` from the `publish` job (Trivy-scanned, boot-tested). **Merging the \"Release vX.Y.Z\" PR** drafts the release, **promotes** that commit's image to `:vX.Y.Z`, then publishes.\n- **Promotion is a server-side retag of the existing digest** (`docker buildx imagetools create --prefer-index=false`), **never a rebuild** — a rebuild yields different bytes no scan ever examined. `--prefer-index=false` is load-bearing: the default `true` wraps a new top-level digest.\n- **Promotion reads the digest from CI's own run artifact, never by resolving `:sha-`** — that tag is mutable in the public window between merge and CI's push. Adding a CI job that should gate a release? **Add it to `publish.needs`** — that list is exactly what the digest artifact proves, and nothing enforces it.\n- **The release stays a draft until its image is promoted**; GitHub withholds the git tag for a draft, so a failed promotion leaves no version pointing at nothing.\n- **The version comes from conventional commits, damped below 1.0.0** (`feat!:`/`BREAKING CHANGE` → minor; `feat:` and everything else → patch) via two `*-pre-major` settings; the *first* release is set by a separate `initial-version` lever. The mapping flips **silently at 1.0.0** — reach it deliberately with a `Release-As:` footer.\n- **A commit-body parse error drops the whole commit** (no changelog entry, no bump, green run): **never start a line with `word(` that has another `(` inside it**. `.githooks/commit-msg` catches the body, but a **multi-commit PR's subject comes from the PR title**, which no local hook sees — so **the PR title is the release note**.\n- **The release PR is opened with a GitHub App token, not `GITHUB_TOKEN`** (which can't open a PR unless a repo-wide setting is on, and whose PRs get no CI run). Every App consumer **must** keep `permission-*` downscoping — omitting it mints the union of every grant the App holds, silently. Shared with `dependabot-lockfix.yml`; needs `LOCKFIX_APP_CLIENT_ID`/`LOCKFIX_APP_PRIVATE_KEY`; use `client-id`, not the deprecated `app-id`.\n- **Never hand-edit `.release-please-manifest.json` or `version.txt`** — release-please owns them; a manual edit desynchronises it from the tags that exist.\n- **Deploy by digest, never by tag** — *obtaining* the digest and *verifying* its origin are two separate problems, and one does not imply the other.\n - **Obtain:** every release carries an `image.json` **release asset** (`gh release download -p image.json`) with `reference`/`digest`/`commit`. Don't parse prose; don't resolve a tag.\n - **Verify:** `ci.yml` writes a build-provenance attestation (#354); deploy runs `gh attestation verify oci:// --repo … --signer-workflow …/ci.yml --source-ref refs/heads/main --bundle-from-oci`. **All three flags are load-bearing and none is the default** — `--bundle-from-oci` (read the registry copy), `--signer-workflow` (bind to the workflow, not just the repo), `--source-ref` (bind to the ref — so a repair dispatch must run **from `main`**).\n - **Then confirm the tag still resolves to the digest you verified** — compare against `reference`, **never** the asset's separate `digest` field.\n\n Net, stated at exactly the strength the argument supports: the internal gate\n fails closed for a leaked **registry** credential. The external gate also\n stops a **branch push** substituting its own bytes. Neither stops a branch\n writer swapping in *other* attested bytes — the tag/digest comparison above\n raises the cost, but that actor holds registry write too, so nothing in this\n repo closes it; branch/dispatch permissions and immutable tags do.\n **And neither survives a merge to `main`.** Once a backdoored `ci.yml` is\n the definition on `main`, its attestation is genuinely valid — right signer\n workflow, right source ref — because `--source-ref` records *which ref built\n this*, not *whether that ref's content is trustworthy*. This repo allows a\n self-merge (`main` requires a PR but **zero** approving reviews), so that path\n is open today and no flag on the verify command closes it; review of changes to\n `main` is the only control that does.\n\n **The paragraph directly above is the canonical statement of the boundary.** `README.md` and the `ci.yml` comment carry a summary and point here rather than restating it, because successive corrections to this claim repeatedly updated one copy and left the others contradicting it. If you correct it, correct it in all three and check they agree. Full derivation of the two gates is in [`docs/decisions/351-releases.md`](docs/decisions/351-releases.md).\n- Package visibility and the host's pull credential are **deploy-side** concerns (cluckwork-deploy#6), not this repo's.\n\n## Git / PR workflow\n\n- `origin` = GitHub (`github.com/mforce/cluckwork`); `gitea` = backup mirror. Use `gh` for PRs.\n- **`main` is protected** — branch, push, open a PR; don't commit to `main`.\n- Branch names: `feat/…`, `chore/…`, `spec/…`. PRs squash-merge.\n- **The PR title is the release note.** It becomes the squashed commit subject, which\n is what release-please parses for both the changelog and the version bump — so a\n typo'd or non-conventional prefix silently costs a bump. See the release section above.\n- Only commit/push when the human asks.\n- **Keep phase epics in sync**: when filing a slice issue, add it to the phase epic's checklist (epic #14 = Phase 1.1, #15 = Phase 1.5) with its issue number; when its PR merges, check it off. Milestone assignment alone is not enough — the epics are how work is navigated.\n- **Keep documentation in sync** (owner directive, 2026-07-17): every PR that adds or changes user-visible behavior updates, in the same PR: (1) `specs/product/GLOSSARY.md` when a concept appears or changes meaning, and (2) the SPA Help page + in-app glossary (once #71 lands). Treat a missing doc update like a missing test — reviewers should flag it.\n\n## Phase context\n\n**Phase 1.0 (MVP) is shipped** — epic #13 closed. The egg loop runs end-to-end from the SPA: daily entry (by grade) → submit → egg lots → stock → customer → sales order → FIFO allocation → stock decremented. Single-farm login (multi-tenant infra present but dormant), customers without payments, draft orders cancellable/editable.\n\nDomain terms (flock lifecycle, daily entry states, egg lots, grades, culls, FIFO allocation) are defined in `specs/product/GLOSSARY.md` — read it before renaming or modeling anything.\n\nCurrent phase: **Phase 1.1** (epic #14, `specs/product/specs.md` §6) — RBAC UI, product catalog / egg-grade management, inventory movement ledger, feed/water/mortality, expenses, payments, dashboard, reports, audit UI, exports, i18n infrastructure (#45; English-only, translations land in 1.5). Known deferred item with an issue: farm-local timezone boundaries (#35). Work is tracked as GitHub issues (epics + slices).\n\n## graphify\n\nThis project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.\n\nWhen the user types `/graphify`, use the installed graphify skill or instructions before doing anything else.\n\nRules:\n- For codebase questions, first run `graphify query \"\"` when graphify-out/graph.json exists. Use `graphify path \"\"\n",{"_402":656,"_381":382,"_404":388},{"_405":657,"_407":-5,"_45":-5,"_409":658,"_411":-5,"_99":659,"_95":413},[660],{"_414":388},"developer",{"_49":661,"_95":437},"Do not spawn sub-agents unless the user or applicable AGENTS.md/skill instructions explicitly ask for sub-agents, delegation, or parallel agent work.",{"_402":663,"_381":382,"_404":388},{"_405":664,"_407":-5,"_45":-5,"_409":665,"_411":-5,"_99":659,"_95":413},[666],{"_414":388},{"_49":667,"_95":437},"You are `/root`, the primary agent in a team of agents collaborating to fulfill the user's goals.\n\nAt the start of your turn, you are the active agent.\nYou can spawn sub-agents to handle subtasks, and those sub-agents can spawn their own sub-agents.\nAll agents in the team, including the agents that you can assign tasks to, are equally intelligent and capable, and have access to the same set of tools.\n\nYou can use `spawn_agent` to create a new agent, `followup_task` to give an existing agent a new task and trigger a turn, and `send_message` to pass a message to a running agent without triggering a turn.\nChild agents can also spawn their own sub-agents.\nYou can decide how much context you want to propagate to your sub-agents with the `fork_turns` parameter.\n\nYou will receive messages in the analysis channel in the form:\n```\nMessage Type: MESSAGE | FINAL_ANSWER\nTask name: \nSender: \nPayload:\n\n```\nThey may be addressed as to=/root\n\nNote that collaboration tools cannot be called from inside `functions.exec`. Call `spawn_agent`, `send_message`, `followup_task`, `wait_agent`, `interrupt_agent`, and `list_agents` only as direct tool calls using the recipient shown in their tool definitions, such as `to=functions.collaboration.spawn_agent`, since they are intentionally absent from the `functions.exec` `tools.*` namespace. Available tools in `functions.exec` are explicitly described with a `tools` namespace in the developer message.\n\nAll agents share the same directory. In detail:\n- All agents have access to the same container and filesystem as you.\n- All agents use the same current working directory.\n- As a result, edits made by one agent are immediately visible to all other agents.\n\nThere are 4 available concurrency slots, meaning that up to 4 agents can be active at once, including you.",{"_402":669,"_381":382,"_404":388},{"_405":670,"_407":-5,"_45":-5,"_409":671,"_411":-5,"_99":659,"_95":413},[672,673],{"_414":388},{"_49":675,"_95":437},{"_49":674,"_95":437},"\n## Skills\nA skill is a set of instructions provided through a `SKILL.md` source. Below is the list of skills that can be used. Each entry includes a name, description, and source locator. `file` locators are on the host filesystem, `environment resource` locators are owned by an execution environment, `orchestrator resource` locators are opaque non-filesystem resources, and `custom resource` locators use their provider's access mechanism.\n### Available skills\n- imagegen: Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas. (file: /opt/codex/skills/.system/imagegen/SKILL.md)\n- openai-docs: Use when the user asks how to build with OpenAI products or APIs, asks about Codex itself or choosing Codex surfaces, needs up-to-date official documentation with citations, help choosing the latest model for a use case, or model upgrade and prompt-upgrade guidance; use OpenAI docs MCP tools for non-Codex docs questions, use the Codex manual helper first for broad Codex self-knowledge, and restrict fallback browsing to official OpenAI domains. (file: /opt/codex/skills/.system/openai-docs/SKILL.md)\n- plugin-creator: Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow. (file: /opt/codex/skills/.system/plugin-creator/SKILL.md)\n- skill-creator: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations. (file: /opt/codex/skills/.system/skill-creator/SKILL.md)\n- skill-installer: Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos). (file: /opt/codex/skills/.system/skill-installer/SKILL.md)\n","\nFilesystem sandboxing defines which files can be read or written. `sandbox_mode` is `danger-full-access`: No filesystem sandboxing - all commands are permitted. Network access is enabled.\nApproval policy is currently never. Do not provide the `sandbox_permissions` for any reason, commands will be rejected.\n","turn/started",{"_381":382,"_90":678},{"_106":-5,"_45":388,"_389":679,"_391":392,"_393":394,"_395":680},[],"inProgress",{"_395":682,"_381":382},{"_683":684,"_95":685},"activeFlags",[],"active","thread/started",{"_688":689},"thread",{"_690":-5,"_691":-5,"_692":693,"_694":394,"_447":448,"_695":18,"_696":-5,"_697":-5,"_698":-5,"_699":700,"_45":382,"_701":702,"_184":-5,"_703":-5,"_164":704,"_705":202,"_706":394,"_707":382,"_453":708,"_395":709,"_710":-5,"_80":711,"_712":394},"agentNickname","agentRole","cliVersion","0.144.0-alpha.4","createdAt","ephemeral","extra","forkedFromId","gitInfo","historyMode","legacy","modelProvider","openai","parentThreadId","/opt/codex/sessions/2026/08/08/rollout-2026-08-08T06-54-47-019fe027-1c72-71a2-8bef-44989b603fae.jsonl","preview","recencyAt","sessionId","vscode",{"_95":399},"threadSource",[],"updatedAt",[],"messages",[716],{"_45":717,"_718":719,"_720":721,"_722":721,"_405":723,"_395":724,"_407":-5,"_725":35,"_726":727,"_728":729,"_730":-5},"6afb0a21-df6b-4920-b0f4-c671d36295d4","author",{"_99":328,"_184":-5,"_726":739},"create_time",1786172088.471116,"update_time",{"_735":49,"_736":737},"finished_successfully","weight","metadata",{"_731":732},"recipient","all","channel","l1239dk1",{"_733":734},"inline_comments",[],"content_type","parts",[738],"@codex address that feedback\n\n---\n_Generated by [Claude Code](https://claude.ai/code)_\nfeat(web): display app version in the sidebar, sourced from version.txt\n\nCloses #458.\n\n## Problem\n\nNo visible version identifier anywhere in the app — no way to say \"which build am I on\" from a screenshot or support conversation.\n\n## A latent bug found along the way\n\n`web/src/api/errorReport.ts` has always read `import.meta.env.VITE_APP_VERSION` for crash reports (the comment there says \"set at build time... absent in dev builds\"), but **nothing ever actually set it** — not in CI's `npm run build`, not in the Dockerfile's `RUN npm run build`. So every crash report, including from production, has been silently sending `appVersion: undefined`. Fixed as part of this change, not separately, since the fix is the same plumbing.\n\n## Design\n\nPer discussion: extend release-please rather than invent new CI plumbing.\n\n- **`web/.env.production`** (new) carries `VITE_APP_VERSION=0.0.2`. Vite loads `.env.production` automatically for a production-mode build (`vite build` defaults to `mode: production`) — no Dockerfile/CI changes needed beyond the file existing; `COPY web/ ./` in the Dockerfile already picks it up, and it isn't excluded by `.dockerignore` (`**/.env` matches only the exact filename `.env`).\n- **`.gitignore`** negates it (`!web/.env.production`) — the root `.gitignore`'s `.env.*` pattern would otherwise block committing it. `VITE_APP_VERSION` is a public string baked into the client bundle regardless of whether it's committed, not a secret.\n- **`release-please-config.json`** gains an `extra-files` entry using release-please's `generic` updater, anchored by an `x-release-please-version` marker comment on the line *above* the value (not a trailing same-line comment — dotenv-style `.env` parsing doesn't strip inline `#` comments the way YAML/generic key:value formats do, so a trailing marker would have become part of the value). This makes future release PRs bump `web/.env.production` in lockstep with `version.txt`/the manifest, same PR, same commit.\n- **`AppLayout.tsx`** renders `v{{version}}` in the sidebar footer, next to the theme toggle/sign-out — the existing `.sidebar-foot` chrome. Absent entirely when the var is unset (dev/test builds), rather than rendering something broken.\n\n## Verification\n\n- `npm run typecheck` / `npm run i18n:scan` (COUNT: 3, unchanged baseline) / `npm test` (1412/1412, +1 new) all green.\n- **Verified end-to-end with a real `npm run build`**, not just the unit test: grepped the built bundle and confirmed `0.0.2` is correctly baked into both `errorReport.ts`'s `appVersion` and `AppLayout.tsx`'s `APP_VERSION` — proves the whole `.env.production` → Vite substitution pipeline actually works, not just that the code compiles.\n- **New test mutation-checked properly**, including catching my own first mistake: I initially wrote the \"no version shown when unset\" test assuming i18next would render a missing `{{version}}` interpolation as `\"vundefined\"` (JS string-concat style) — wrong. Printed the actual DOM and found i18next renders it as a bare `\"v\"` (empty interpolation). Rewrote the test against the real behavior, then mutation-tested it (temporarily removed the `APP_VERSION &&` guard) and confirmed it now correctly goes red.\n\n## What's unverified\n\nI could not test the `release-please-config.json` `extra-files` wiring against a real release-please dry run (no network access to invoke the action here). This is the one part of the change that needs confirming on the **next actual release PR** — that `web/.env.production`'s version line moves in lockstep with `version.txt`. If it doesn't, the marker-comment placement is the first thing to check.\n\n## Docs\n\nAdded a short note to `docs/decisions/351-releases.md` documenting the `extra-files` addition and why the marker comment is placed where it is (dotenv inline-comment gotcha).\n\n\n---\n_Generated by [Claude Code](https://claude.ai/code/session_01LSkqgsC9Sj4arUdevUSJfJ)_\n**_{_{![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)}} Match the injected version to version.txt**\n\n`version.txt` and `.release-please-manifest.json` are already at `0.0.3` in the parent commit, but this line injects `0.0.2` into every production Vite build. Consequently, the sidebar and client error reports identify images built from this commit as the previous release until a later release PR corrects the value; initialize this file from the current release-owned version instead. This affects the per-merge images published by CI, not only a local build.\n\nAGENTS.md reference: [AGENTS.md:L126-L128](https://github.com/mforce/cluckwork/blob/d1a52a66e0b5f4eccf42b5c52df9754d1b12e92f/AGENTS.md#L126-L128)\n\nUseful? React with 👍 / 👎.\n\n### 💡 Codex Review\n\nHere are some automated review suggestions for this pull request.\n\n**Reviewed commit:** `d1a52a66e0`\n \n\n

ℹ️ About Codex in GitHub

\n
\n\n[Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general). Reviews are triggered when you\n- Open a pull request for review\n- Mark a draft as ready\n- Comment \"@codex review\".\n\nIf Codex has suggestions, it will comment; otherwise it will react with 👍.\n\n\n\n\nCodex can also answer questions or update the PR. Try commenting \"@codex address that feedback\".\n \n

\nFixed in a096192 — updated `web/.env.production` to `0.0.3` to match current `version.txt`/manifest, and re-verified with a real `npm run build` that `0.0.3` correctly bakes into both `errorReport.ts` and `AppLayout.tsx`.\n\n---\n_Generated by [Claude Code](https://claude.ai/code)_",{},"created",1786172150.6419282,"Completing the task","event_type","info",{"_95":413,"_99":96,"_405":779},{"_95":747,"_748":749},"partial_repo_snapshot","files",[750,751,752],{"_164":773,"_754":-5,"_755":774,"_757":-5},{"_164":768,"_754":-5,"_755":769,"_757":-5},{"_164":753,"_754":-5,"_755":756,"_757":-5},".release-please-manifest.json","contents","line_range_contents",[758],"missing_reason",{"_759":760,"_761":762,"_405":763,"_764":62},"line_range_start",1,"line_range_end",3,[765,766,767],"contains_end_of_file","{"," \".\": \"0.0.3\"","}","version.txt",[770],{"_759":760,"_761":760,"_405":771,"_764":62},[772],"0.0.3","web/.env.production",[775],{"_759":760,"_761":331,"_405":776,"_764":62},[777,778],"# x-release-please-version","VITE_APP_VERSION=0.0.3",[780,781,782,783,784],{"_735":49,"_49":787},{"_735":786,"_164":773,"_759":760,"_761":331},{"_735":786,"_164":768,"_759":760,"_761":-5},{"_735":786,"_164":753,"_759":760,"_761":762},{"_735":49,"_49":785},"\n* No additional changes or PR were created because the requested fix is already committed on the current PR branch and the working tree is clean.\n\n**Testing**\n\n* ✅ `cd web && npm run typecheck`\n* ✅ `cd web && npm run build`\n* ✅ `cd web && rg -q '0\\.0\\.3' dist`\n* ✅ `git status --porcelain` (clean working tree)","repo_file_citation","### Summary\n\n* The review feedback was already addressed in commit `a096192`: the production Vite version is `0.0.3`, matching both `version.txt` and the release-please manifest. ",{"_95":328,"_45":87,"_99":328,"_790":791,"_792":793,"_794":795,"_135":-5,"_122":796},[86],"input_items",[815,816,817,818,819],"external_post_config",{"_797":798,"_266":199,"_799":308,"_277":-5,"_800":260,"_801":-5,"_802":-5,"_803":804,"_805":806,"_807":-5,"_808":-5,"_809":810,"_811":18,"_812":62,"_813":57,"_814":18},"user_model_slug","slug",1786172080.880236,"installation_id",150444056,"pr_number","repo_id","gitlab_service_account_project_id","review_trigger","comment_id",5225011235,"comment_type","issue","pr_write_guard_token","pending_pr_reaction_id","pending_comment_reaction_id",394747098,"comment_if_no_findings","comment_on_error","share_url","is_parallel_review",{"_95":413,"_99":328,"_405":831},{"_315":316,"_317":827,"_828":322,"_829":132,"_324":-5,"_95":830},{"_95":820,"_317":826,"_164":773,"_822":823,"_824":-5},{"_95":820,"_317":825,"_164":-5,"_822":-5,"_824":-5},{"_95":820,"_317":821,"_164":773,"_822":823,"_824":-5},"pull_request_comment","Fixed in a096192 — updated `web/.env.production` to `0.0.3` to match current `version.txt`/manifest, and re-verified with a real `npm run build` that `0.0.3` correctly bakes into both `errorReport.ts` and `AppLayout.tsx`.\n\n---\n_Generated by [Claude Code](https://claude.ai/code)_","side","RIGHT","line","\n### 💡 Codex Review\n\nHere are some automated review suggestions for this pull request.\n\n**Reviewed commit:** `d1a52a66e0`\n \n\n

ℹ️ About Codex in GitHub