ℹ️ 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\":\"**_{_{![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)}} Preserve sold quantities when adding recount stock**\\n\\nWhen a lot has prior sales, this ceiling permits a positive reconciliation to replace those sold eggs: producing 100 and selling 30 leaves 70 available, but reconciling `+30` passes and makes all 100 available again, allowing the lot to supply up to 130 sales in total. It can also make voiding the original sale fail because `Restore` would then exceed production. Positive recounts need a ceiling that preserves quantities already removed by sale allocations, rather than comparing only the new cached balance with `QuantityProduced`.\\n\\nUseful? React with 👍 / 👎.\",\"path\":\"src/Cluckwork.Domain/Eggs/EggLot.cs\",\"side\":\"RIGHT\",\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"**_{_{![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)}} Separate refresh retries from the completed write**\\n\\nIf the POST succeeds but `getStock`, `listEggLots`, or `listEggLotMovements` fails, the completed request's key is retained while the editable dialog remains open. If the user changes the quantity/reason or closes and reopens the dialog, the next write uses that completed key with a different payload and the idempotency middleware returns a mismatch conflict; because `clearKey` is reached only after a successful refresh, repeated attempts remain stuck. Once the POST has resolved, retain its result and retry only the refresh, or otherwise rotate/bind the key before permitting another logical write.\\n\\nUseful? React with 👍 / 👎.\",\"path\":\"web/src/routes/StockPage.tsx\",\"side\":\"RIGHT\",\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"**_{_{![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)}} Expose write-offs beyond the first lot page**\\n\\nThe new action is rendered only for `lots`, but `toggleGrade` calls `listEggLots({ gradeId })` without paging and the API defaults that request to the newest 50 lots. Once a grade has more than 50 lots, any older lot— including one that still has available or restricted stock—cannot be reached or written off anywhere in the SPA even though it contributes to the displayed stock total. Add paging/search or otherwise expose all relevant lots before making the per-lot action the only UI entry point.\\n\\nUseful? React with 👍 / 👎.\",\"path\":\"web/src/routes/StockPage.tsx\",\"side\":\"RIGHT\",\"line\":243}{\"type\":\"pull_request_comment\",\"body\":\"@codex review — internal review round complete in 848c4ce: positive Reconciliation is now capped at the lot's cumulative write-off total (EggLot.ReconcileExceedsWrittenOff — the produced-only ceiling let a recount re-add eggs allocated to a confirmed order, overselling the lot and making the order un-voidable), bound guards in EggLot.AdjustAvailable/Restore sum in 64-bit (near-int.MaxValue wrap), sold-floor messages now mention write-offs, and a per-endpoint idempotency-replay test was added. All suites green: 1407 backend, 1422 web, Playwright quick suite, E2E mutation check.\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"**_{_{![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)}} Add stock write-off to the in-app glossary**\\n\\nAlongside this new Help bullet, add a “Stock write-off” entry to the in-app glossary table later in `HelpPage` and provide its en/es/tl catalog keys. The PR introduces this as a named user-facing concept and updates the product glossary, but users consulting the SPA glossary cannot find it; the repository explicitly requires both Help prose and the in-app glossary to be updated for user-visible behavior.\\n\\nAGENTS.md reference: [AGENTS.md:L168-L168](https://github.com/mforce/cluckwork/blob/848c4ce60e45729d6d4284442562de19d0bf691a/AGENTS.md#L168-L168)\\n\\nUseful? React with 👍 / 👎.\",\"path\":\"web/src/routes/HelpPage.tsx\",\"side\":\"RIGHT\",\"line\":277}{\"type\":\"pull_request_comment\",\"body\":\"\\n### 💡 Codex Review\\n\\nHere are some automated review suggestions for this pull request.\\n\\n**Reviewed commit:** `848c4ce60e`\\n \\n\\n

ℹ️ About Codex in GitHub

\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"Fixed in 848c4ce (this was also flagged by our internal security review). The handler now caps a positive Reconciliation at the lot's cumulative write-off total, summed from the ledger under the same FOR UPDATE lock (`EggLot.ReconcileExceedsWrittenOff`) — allocation headroom can no longer be re-added. Covered by three integration tests watched red first, including the exact produce-100/sell-30/reconcile-+30 exploit shape (`Reconciliation_CannotReAddAllocatedEggs`) and `Reconciliation_CappedAtCumulativeWriteOffs`. Full suites green.\",\"path\":\"src/Cluckwork.Domain/Eggs/EggLot.cs\",\"side\":\"RIGHT\",\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"Fixed in 5a6e5ba. The key now rotates the moment the POST answers success — verified against IdempotencyMiddleware that only 2xx publishes a replay record, so an error response leaves the key safely reusable while a stored success no longer collides with an edited resubmit. A failed refresh closes the dialog with the success message and shows a page-level stale-view error. Pinned by a Vitest case that fails the refresh and asserts the next write-off uses a fresh key.\",\"path\":\"web/src/routes/StockPage.tsx\",\"side\":\"RIGHT\",\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"Pre-existing screen behavior — the lots drill-down has always shown only the newest 50 (the history action is equally unreachable for older lots). Agreed #406 raises the stakes, so it's now tracked as #465 (added to the Phase 1.1 epic checklist) rather than widened into this PR.\",\"path\":\"web/src/routes/StockPage.tsx\",\"side\":\"RIGHT\",\"line\":243}{\"type\":\"pull_request_comment\",\"body\":\"Fixed in 5a6e5ba — \\\"Stock write-off\\\" row added to the in-app glossary table next to the egg movement ledger entry, with en/es/tl catalog keys matching the product GLOSSARY entry.\",\"path\":\"web/src/routes/HelpPage.tsx\",\"side\":\"RIGHT\",\"line\":277}{\"type\":\"pull_request_comment\",\"body\":\"@codex all round-2 findings are addressed: the allocated-eggs reconciliation ceiling in 848c4ce (write-off-total cap + exploit-shaped tests), the idempotency-key rotation and the in-app glossary entry in 5a6e5ba, and the lot-list 50-row cap tracked as #465. Suites green: 1407 backend, 1423 web, coverage floor holds, typecheck clean.\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"No additional findings. I verified that:\\n\\n- Positive reconciliation is capped by cumulative write-offs under the lot lock, preventing allocated eggs from being reintroduced. [src/Cluckwork.Application/Features/EggLots/RecordEggLotMovement/RecordEggLotMovementHandler.csL47-L68](https://github.com/mforce/cluckwork/blob/5a6e5ba7c671f8e7a21a22ab604aa1afc25fdd95/src/Cluckwork.Application/Features/EggLots/RecordEggLotMovement/RecordEggLotMovementHandler.cs#L47-L68)\\n- The idempotency key rotates immediately after a successful write, while refresh failures are handled as stale-view errors. [web/src/routes/StockPage.tsxL141-L171](https://github.com/mforce/cluckwork/blob/5a6e5ba7c671f8e7a21a22ab604aa1afc25fdd95/web/src/routes/StockPage.tsx#L141-L171)\\n- “Stock write-off” is included in the in-app glossary. [web/src/routes/HelpPage.tsxL538-L543](https://github.com/mforce/cluckwork/blob/5a6e5ba7c671f8e7a21a22ab604aa1afc25fdd95/web/src/routes/HelpPage.tsx#L538-L543)\\n- The 50-row lot-list limitation is appropriately separated into #465.\\n\\n**Checks**\\n\\n- ✅ `git diff --check 81a6eac..HEAD`\\n- ✅ `git status --short` (clean)\\n- ⚠️ `dotnet test tests/Cluckwork.Domain.Tests/Cluckwork.Domain.Tests.csproj --no-restore --filter FullyQualifiedName~EggLotTests` (`dotnet` is unavailable in this environment)\\n- ⚠️ `npm test -- --run src/routes/StockPage.test.tsx` (the environment’s Node 20 rejects the configured `--no-experimental-webstorage` option)\\n\\nNo code changes were needed, so no commit or follow-up PR was created.\\n\\n [View task →](https://chatgpt.com/s/cd_6a76eef9404081918b40d15f7f3d2a73)\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"@codex one more commit since your last round: 366de81 fixes a CI-only e2e race — the manager specs filled daily-entry counts before the #446 prefill settled, and a slow runner's prefill wiped the fills, submitting an all-zeros day (caught frame-by-frame in the failure video). Both specs now wait for the save buttons to enable (disabled while prefill is pending) before filling, and the write-off spec pins the created-lot count in the submit message. Playwright smoke is green on CI for this commit; all other checks green.\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"### Review finding\\n\\n**P1 — Wait for the prefill response, not merely an enabled button.**\\n\\nBoth new `toBeEnabled()` assertions can pass before the prefill begins. Selecting the flock updates React state, but `prefillPending` is set later inside `useEffect`; during the intervening render, the zero-count form is already reconciled and the submit button can remain enabled. The test can therefore start filling before the request settles, preserving the same race this commit intends to fix. [tools/simulation/ui/specs/manager.spec.tsL59-L68](https://github.com/mforce/cluckwork/blob/366de8182089df056777e86f9b59af81af66dc71/tools/simulation/ui/specs/manager.spec.ts#L59-L68) [tools/simulation/ui/specs/manager.spec.tsL176-L183](https://github.com/mforce/cluckwork/blob/366de8182089df056777e86f9b59af81af66dc71/tools/simulation/ui/specs/manager.spec.ts#L176-L183) [web/src/routes/DailyEntryPage.tsxL163-L177](https://github.com/mforce/cluckwork/blob/366de8182089df056777e86f9b59af81af66dc71/web/src/routes/DailyEntryPage.tsx#L163-L177) [web/src/routes/DailyEntryPage.tsxL740-L742](https://github.com/mforce/cluckwork/blob/366de8182089df056777e86f9b59af81af66dc71/web/src/routes/DailyEntryPage.tsx#L740-L742)\\n\\n`selectOptionContaining` returns immediately after `selectOption` and does not wait for the resulting prefill request or UI transition. [tools/simulation/ui/src/dom.tsL24-L33](https://github.com/mforce/cluckwork/blob/366de8182089df056777e86f9b59af81af66dc71/tools/simulation/ui/src/dom.ts#L24-L33)\\n\\nRegister a `page.waitForResponse(...)` promise for the matching daily-entry prefill request **before** selecting the flock, then await that response before filling. That directly synchronizes the specs with the operation that can overwrite the fields. Waiting for disabled-then-enabled would still be vulnerable when a sufficiently fast response completes before the disabled assertion observes it.\\n\\n**Checks**\\n\\n* ✅ `git diff --check 5a6e5ba7c671f8e7a21a22ab604aa1afc25fdd95..366de8182089df056777e86f9b59af81af66dc71`\\n* ✅ `git diff 5a6e5ba7c671f8e7a21a22ab604aa1afc25fdd95..366de8182089df056777e86f9b59af81af66dc71 -- tools/simulation/ui`\\n* ✅ `git status --short` (clean)\\n\\nNo code changes were made, so no commit or follow-up PR was created.\\n\\n [View task →](https://chatgpt.com/s/cd_6a76f3e453cc8191bf692bfff84ca1e3)\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"@codex the prefill-synchronization finding is addressed in e5771a0 — both manager specs now register `page.waitForResponse` for the daily-entries prefill (keyed to the selected flock's id) before selecting, await it, and only then assert the save button enabled; as you noted, the response existing proves the effect ran, so enabled-after-response can only be the post-reset state. Typecheck clean; manager + readonly specs green locally.\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"No additional findings. The synchronization now correctly:\\n\\n- Registers `page.waitForResponse` before changing the flock selection.\\n- Keys the response to the selected flock ID.\\n- Awaits the prefill response before checking the submit button and filling counts.\\n- Reuses the helper in both affected manager scenarios. [tools/simulation/ui/specs/manager.spec.tsL34-L53](https://github.com/mforce/cluckwork/blob/e5771a01d1a2bd71d7d01bc9ed685532eac1b9a3/tools/simulation/ui/specs/manager.spec.ts#L34-L53) [tools/simulation/ui/specs/manager.spec.tsL80-L87](https://github.com/mforce/cluckwork/blob/e5771a01d1a2bd71d7d01bc9ed685532eac1b9a3/tools/simulation/ui/specs/manager.spec.ts#L80-L87) [tools/simulation/ui/specs/manager.spec.tsL195-L200](https://github.com/mforce/cluckwork/blob/e5771a01d1a2bd71d7d01bc9ed685532eac1b9a3/tools/simulation/ui/specs/manager.spec.ts#L195-L200)\\n\\nThe response predicate matches the query generated by `listDailyEntries`, which includes `flockId` in the `/daily-entries` request. [web/src/api/cluckwork.tsL193-L202](https://github.com/mforce/cluckwork/blob/e5771a01d1a2bd71d7d01bc9ed685532eac1b9a3/web/src/api/cluckwork.ts#L193-L202)\\n\\n**Checks**\\n\\n- ✅ `git diff --check 366de8182089df056777e86f9b59af81af66dc71..e5771a01d1a2bd71d7d01bc9ed685532eac1b9a3`\\n- ✅ `git status --short`\\n- ⚠️ `npm run typecheck` (local dependencies are incomplete: TypeScript could not find the Node type definitions)\\n\\nNo code changes were needed, so no commit or follow-up PR was created.\\n\\n [View task →](https://chatgpt.com/s/cd_6a76fb38746c819195c20f9acb60dadd)\",\"path\":null,\"side\":null,\"line\":null}","text_elements",[],{"_398":629,"_377":378,"_400":384},{"_401":630,"_403":-5,"_45":-5,"_405":631,"_407":-5,"_99":328,"_95":409},[632],{"_410":384},{"_49":625,"_95":433},{"_398":634,"_377":378,"_400":384},{"_401":635,"_403":-5,"_45":-5,"_405":636,"_407":-5,"_99":328,"_95":409},[637,638],{"_410":384},{"_49":640,"_95":433},{"_49":639,"_95":433},"\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",{"_398":642,"_377":378,"_400":384},{"_401":643,"_403":-5,"_45":-5,"_405":644,"_407":-5,"_99":645,"_95":409},[646],{"_410":384},"developer",{"_49":647,"_95":433},"Do not spawn sub-agents unless the user or applicable AGENTS.md/skill instructions explicitly ask for sub-agents, delegation, or parallel agent work.",{"_398":649,"_377":378,"_400":384},{"_401":650,"_403":-5,"_45":-5,"_405":651,"_407":-5,"_99":645,"_95":409},[652],{"_410":384},{"_49":653,"_95":433},"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.",{"_398":655,"_377":378,"_400":384},{"_401":656,"_403":-5,"_45":-5,"_405":657,"_407":-5,"_99":645,"_95":409},[658,659],{"_410":384},{"_49":661,"_95":433},{"_49":660,"_95":433},"\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",{"_377":378,"_90":664},{"_106":-5,"_45":384,"_385":665,"_387":388,"_389":390,"_391":666},[],"inProgress",{"_391":668,"_377":378},{"_669":670,"_95":671},"activeFlags",[],"active","thread/started",{"_674":675},"thread",{"_676":-5,"_677":-5,"_678":679,"_680":390,"_443":444,"_681":18,"_682":-5,"_683":-5,"_684":-5,"_685":686,"_45":378,"_687":688,"_184":-5,"_689":-5,"_164":690,"_691":202,"_692":390,"_693":378,"_449":694,"_391":695,"_696":-5,"_80":697,"_698":390},"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-08T10-21-00-019fe0e3-eaa6-7f32-bc40-fd4e9bc4b340.jsonl","preview","recencyAt","sessionId","vscode",{"_95":395},"threadSource",[],"updatedAt",[],"messages",[702],{"_45":703,"_704":705,"_706":707,"_708":707,"_401":709,"_391":710,"_403":-5,"_711":35,"_712":713,"_714":715,"_716":-5},"2e528483-c2cb-451c-8616-4a68f2ea5fc5","author",{"_99":328,"_184":-5,"_712":725},"create_time",1786184460.13185,"update_time",{"_721":49,"_722":723},"finished_successfully","weight","metadata",{"_717":718},"recipient","all","channel","l1239dk1",{"_719":720},"inline_comments",[],"content_type","parts",[724],"@codex the prefill synchronization needed one more turn — e5771a0's select-scoped wait hangs when the new flock is already the page's auto-default (selecting the same value fires no change, so no request; that was the next CI red). e2e60?? — see latest commit: the wait is now registered before goto and keyed to the flock id captured from the POST /flocks response, catching every path that fires the prefill. Local: manager+readonly and the full quick suite green; CI run pending.\nfeat(stock): let an admin write off lost egg stock without restating production\n\nCloses #406.\n\n## What\n\n`POST /api/v1/stock/lots/{id}/movements` — the stock group's first write, `AuthPolicies.AdminOnly` (Owner + Manager), `Idempotency-Key` required, reason required. Accepts `Discard` / `InternalUse` (negative only) and `Reconciliation` (signed — a recount may also find eggs). The signed `quantityDelta` moves only the lot's available quantity; the daily entry's production figures and hen-day % are never restated.\n\n- **Domain**: `EggLot.AdjustAvailable(delta)` — floor at 0 available (a write-off can never consume sold/allocated eggs, `EggLot.InsufficientStock`), ceiling at produced (`EggLot.ReconcileExceedsProduced`, pointing at daily-entry adjust), `Version++`. Withdrawal restriction deliberately not checked — restricted eggs spoil too, and removing stock is the safe direction.\n- **Handler**: lot locked `FOR UPDATE`; movement row + audit row (`EggLot.Movement`, new `AuditActions` constant mirrored in `enums.ts` per #247) in the same transaction. Response carries the movement plus the lot's new balance and version.\n- **SPA**: per-lot **write off** action on the Stock screen (admin-gated, muted hint otherwise) — type select, `NumberField` stepper, direction toggle for Reconciliation only, required reason, live resulting-balance preview, stable idempotency key rotated only after write + refresh succeed.\n- **Docs**: GLOSSARY \"Stock write-off\" entry, Help page bullet, all copy in en/es/tl (machine-drafted, pending native review).\n\n## Verification\n\n- Backend: 1402 tests green (8 new domain, 13 validator+guards, 14 integration incl. both bounds, restricted lot, cross-tenant 404, audit row, ledger-sum invariant).\n- **Parallel-race test**: two concurrent write-offs on one lot — one 200, one 422, ledger still sums to the cached balance, exactly one Discard row.\n- **Role matrix**: Owner 200, Manager 200, Sales 403, ReadOnly 403, Worker 403 — each asserted separately. The `AdminOnly` gate was mutation-checked (removed → test red → restored → green).\n- SPA: 1422 Vitest green (10 new dialog tests incl. idempotency-key retry stability and i18n catalog wiring); coverage floor holds; typecheck clean.\n- Playwright quick suite run locally against the seeded sim fixture: 29 passed, including the new manager write-off flow (self-owned lot, rerunnable against a dirty fixture) and the readonly negative. `npm run mutation`: baseline GREEN, 9 real kills, 0 survivors, restore GREEN.\n\n## Contract notes (#394)\n\nNew endpoint — no existing non-CI caller posts to it; seeders and k6 untouched. The account export picks the new rows up automatically (`egg-inventory-movements` dataset has no movement-type filter).\n@codex review\n\n### 💡 Codex Review\n\nHere are some automated review suggestions for this pull request.\n\n**Reviewed commit:** `c22042cd6a`\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

\n**_{_{![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)}} Preserve sold quantities when adding recount stock**\n\nWhen a lot has prior sales, this ceiling permits a positive reconciliation to replace those sold eggs: producing 100 and selling 30 leaves 70 available, but reconciling `+30` passes and makes all 100 available again, allowing the lot to supply up to 130 sales in total. It can also make voiding the original sale fail because `Restore` would then exceed production. Positive recounts need a ceiling that preserves quantities already removed by sale allocations, rather than comparing only the new cached balance with `QuantityProduced`.\n\nUseful? React with 👍 / 👎.\n**_{_{![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)}} Separate refresh retries from the completed write**\n\nIf the POST succeeds but `getStock`, `listEggLots`, or `listEggLotMovements` fails, the completed request's key is retained while the editable dialog remains open. If the user changes the quantity/reason or closes and reopens the dialog, the next write uses that completed key with a different payload and the idempotency middleware returns a mismatch conflict; because `clearKey` is reached only after a successful refresh, repeated attempts remain stuck. Once the POST has resolved, retain its result and retry only the refresh, or otherwise rotate/bind the key before permitting another logical write.\n\nUseful? React with 👍 / 👎.\n**_{_{![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)}} Expose write-offs beyond the first lot page**\n\nThe new action is rendered only for `lots`, but `toggleGrade` calls `listEggLots({ gradeId })` without paging and the API defaults that request to the newest 50 lots. Once a grade has more than 50 lots, any older lot— including one that still has available or restricted stock—cannot be reached or written off anywhere in the SPA even though it contributes to the displayed stock total. Add paging/search or otherwise expose all relevant lots before making the per-lot action the only UI entry point.\n\nUseful? React with 👍 / 👎.\n@codex review — internal review round complete in 848c4ce: positive Reconciliation is now capped at the lot's cumulative write-off total (EggLot.ReconcileExceedsWrittenOff — the produced-only ceiling let a recount re-add eggs allocated to a confirmed order, overselling the lot and making the order un-voidable), bound guards in EggLot.AdjustAvailable/Restore sum in 64-bit (near-int.MaxValue wrap), sold-floor messages now mention write-offs, and a per-endpoint idempotency-replay test was added. All suites green: 1407 backend, 1422 web, Playwright quick suite, E2E mutation check.\n**_{_{![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)}} Add stock write-off to the in-app glossary**\n\nAlongside this new Help bullet, add a “Stock write-off” entry to the in-app glossary table later in `HelpPage` and provide its en/es/tl catalog keys. The PR introduces this as a named user-facing concept and updates the product glossary, but users consulting the SPA glossary cannot find it; the repository explicitly requires both Help prose and the in-app glossary to be updated for user-visible behavior.\n\nAGENTS.md reference: [AGENTS.md:L168-L168](https://github.com/mforce/cluckwork/blob/848c4ce60e45729d6d4284442562de19d0bf691a/AGENTS.md#L168-L168)\n\nUseful? React with 👍 / 👎.\n\n### 💡 Codex Review\n\nHere are some automated review suggestions for this pull request.\n\n**Reviewed commit:** `848c4ce60e`\n \n\n

ℹ️ About Codex in GitHub

ℹ️ About Codex in GitHub

","**_{_{![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)}} Add stock write-off to the in-app glossary**\n\nAlongside this new Help bullet, add a “Stock write-off” entry to the in-app glossary table later in `HelpPage` and provide its en/es/tl catalog keys. The PR introduces this as a named user-facing concept and updates the product glossary, but users consulting the SPA glossary cannot find it; the repository explicitly requires both Help prose and the in-app glossary to be updated for user-visible behavior.\n\nAGENTS.md reference: [AGENTS.md:L168-L168](https://github.com/mforce/cluckwork/blob/848c4ce60e45729d6d4284442562de19d0bf691a/AGENTS.md#L168-L168)\n\nUseful? React with 👍 / 👎.","@codex review — internal review round complete in 848c4ce: positive Reconciliation is now capped at the lot's cumulative write-off total (EggLot.ReconcileExceedsWrittenOff — the produced-only ceiling let a recount re-add eggs allocated to a confirmed order, overselling the lot and making the order un-voidable), bound guards in EggLot.AdjustAvailable/Restore sum in 64-bit (near-int.MaxValue wrap), sold-floor messages now mention write-offs, and a per-endpoint idempotency-replay test was added. All suites green: 1407 backend, 1422 web, Playwright quick suite, E2E mutation check.","**_{_{![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)}} Expose write-offs beyond the first lot page**\n\nThe new action is rendered only for `lots`, but `toggleGrade` calls `listEggLots({ gradeId })` without paging and the API defaults that request to the newest 50 lots. Once a grade has more than 50 lots, any older lot— including one that still has available or restricted stock—cannot be reached or written off anywhere in the SPA even though it contributes to the displayed stock total. Add paging/search or otherwise expose all relevant lots before making the per-lot action the only UI entry point.\n\nUseful? React with 👍 / 👎.","**_{_{![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)}} Separate refresh retries from the completed write**\n\nIf the POST succeeds but `getStock`, `listEggLots`, or `listEggLotMovements` fails, the completed request's key is retained while the editable dialog remains open. If the user changes the quantity/reason or closes and reopens the dialog, the next write uses that completed key with a different payload and the idempotency middleware returns a mismatch conflict; because `clearKey` is reached only after a successful refresh, repeated attempts remain stuck. Once the POST has resolved, retain its result and retry only the refresh, or otherwise rotate/bind the key before permitting another logical write.\n\nUseful? React with 👍 / 👎.","**_{_{![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)}} Preserve sold quantities when adding recount stock**\n\nWhen a lot has prior sales, this ceiling permits a positive reconciliation to replace those sold eggs: producing 100 and selling 30 leaves 70 available, but reconciling `+30` passes and makes all 100 available again, allowing the lot to supply up to 130 sales in total. It can also make voiding the original sale fail because `Restore` would then exceed production. Positive recounts need a ceiling that preserves quantities already removed by sale allocations, rather than comparing only the new cached balance with `QuantityProduced`.\n\nUseful? React with 👍 / 👎.","\n### 💡 Codex Review\n\nHere are some automated review suggestions for this pull request.\n\n**Reviewed commit:** `c22042cd6a`\n \n\n

ℹ️ About Codex in GitHub