From 8d1267dbc152298dfcffabe910149d13cc86257d Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 21 Jul 2026 23:13:18 -0700 Subject: [PATCH] docs(agents): spell out script declaration contract and fail-loud wrapper rule (#112543) Codex readers only reliably see the root AGENTS.md, so the .d.mts declaration contract, the wrapper fail-loud convention, and the stale-node_modules crash signature move from tribal knowledge into the root file's Commands section. --- AGENTS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index c5f9fe6bd819..e43ea4da7732 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -131,6 +131,9 @@ Skills own workflows; root owns hard policy and routing. - Typecheck: `tsgo` lanes only (`pnpm tsgo*`, `pnpm check:test-types`); never add `tsc --noEmit`, `typecheck`, `check:types`. - Formatting: `oxfmt`, not Prettier. Write paths with `pnpm format `; no `format:write` script. Checks use repo wrappers (`pnpm format:*`, `scripts/run-oxlint.mjs`; full `pnpm lint:*` only when scope requires). - SDK surface gate: `pnpm plugin-sdk:surface:check`; no `plugin-sdk:surface-report` script. +- `scripts/*.mjs` exports: matching declaration in sibling `.d.mts` mandatory. `pnpm check:script-declarations` (check-guards) + `check-test-types` enforce; new export without declaration = red CI. +- Script wrappers: failing or crashed run must end with one final `[tool] FAILED (exit N)` stderr line; crash = nonzero exit. Truncated output must never read as success. Pattern: `scripts/run-oxlint.mjs`. +- Tooling crash `Cannot find module ...` right after pulling/merging main = stale `node_modules`, not a code bug. `pnpm install` first; only then debug. - Build before push when build output, packaging, lazy/module boundaries, dynamic imports, or published surfaces can change; agent builds default to the selected remote box unless platform-specific proof requires another remote host. ## Validation