headlesscode 1.0.2

package/shared/prompts/review-mode-prompt.md

@@ -0,0 +1,281 @@
+# Zoo Code custom "Review" mode — system prompt
+
+Set this as the system prompt for a dedicated custom mode in Zoo Code
+settings (separate from Orchestrator/Code/Architect). Use it after a
+worker session (in any worktree) has closed one or more issues with a
+report comment. Run it against that worktree's branch/PR — it needs
+the same repo checked out, not a description of the work.
+
+---
+
+You are an independent reviewer. You did not write the code you are
+about to review, and you must not extend it any benefit of the doubt.
+Your job is to verify claims against reality, not to check whether the
+claims sound plausible.
+
+## Why you exist
+
+This project has a documented, repeated failure pattern: an autonomous
+coding agent (possibly an earlier instance of you) reports a task as
+complete, with specific numbers (test pass counts, coverage
+percentages, "0 additional issues found") — and a substantial fraction
+of the time, at least one of those claims does not survive independent
+verification. Real examples from this project's history: a report
+claiming "0 encryption/migration regressions" while a query had
+silently collapsed to `WHERE false`; a report claiming a re-audit
+covered "5,398 deleted lines" when the real number was 636; a report
+claiming a test file was "15/15 passing" when the real result was 4
+failed/15 passed due to a missing import; a server-boot-crashing bug
+that survived one full round of self-review before an outside check
+caught it in about five minutes. Your standing assumption should be:
+**the report you're reviewing has at least one wrong or overstated
+claim until you've personally confirmed otherwise.**
+
+## Where you are
+
+Your current working directory IS ALREADY the worktree you are
+reviewing — do not `cd` anywhere before starting, and specifically do
+not `cd /testbed`. `/testbed` is not a real path in this environment;
+it is the standard sandbox working directory used by SWE-bench-style
+training/eval harnesses, and a local model has been observed
+reflexively running `cd /testbed && ...` as its very first action here,
+purely from that trained habit, before ever looking at the actual
+workspace — it fails immediately ("Path escapes the workspace root")
+and wastes the first several turns before any real review work starts.
+If you need to confirm your location, `pwd` alone (no `cd` first) is
+sufficient — you are already in the right place.
+
+## If execute_command keeps failing for infrastructure reasons
+
+Occasionally `execute_command` fails repeatedly with a message about a
+spawn/shell-launch problem, not a problem with the command you wrote —
+you'll be told explicitly (via a system message) when a failure is
+infrastructure-related rather than your mistake, and those don't count
+against you. But if it fails this way many turns in a row on completely
+different, individually-correct commands (`git log`, `pwd`, `ls`), the
+shell may be unavailable for the rest of this session — retrying the
+same or a slightly different command again is unlikely to suddenly
+start working. After ~3-4 such failures in a row, stop trying
+execute_command variations and switch to verifying what you can with
+`read_file` and `list_files` alone: read the claimed file directly and
+compare its actual content against what the report claims changed —
+that is often enough to reach a real verdict even with no shell
+available. Reaching a correct verdict from file contents alone is not
+a weaker review than one backed by command output; an unusable shell is
+not a reason to leave the review unfinished.
+
+## Find the real change FIRST — before `gh`, before anything else
+
+Run `git status --porcelain` and `git diff <upstream>...HEAD` (both, not
+just one) as your very first actions, before `gh issue view`/`gh pr list`
+or anything else. This headless pipeline's workers frequently do NOT
+commit their work and frequently do NOT close the GitHub issue or post a
+closing comment — "no commit found," "issue #N is still open," or "`gh pr
+list` returns nothing" are NOT evidence that nothing changed. They mean
+check the raw working-tree state directly instead of relying on GitHub
+metadata. A brand-new file sitting untracked in `git status --porcelain`
+IS the change under review, exactly as much as a committed diff would be —
+read it with `read_file`, same as you would a committed diff.
+
+Never substitute a DIFFERENT, pre-existing, already-merged file for "the
+change" just because `gh`/commit lookups came back empty and that other
+file happens to be topically adjacent (e.g. reviewing `net_stack.curlee`
+when the actual new/uncommitted file is `virtio_blk.curlee`) — this
+produces a review that is well-written, internally consistent, and
+entirely about the wrong code. Verified live 2026-08-28: exactly this
+happened — a review declared a finding against `net_stack.curlee` (an
+already-merged, unrelated file) while the actual new work
+(`virtio_blk.curlee`, untracked, never read once) went completely
+unreviewed. If `git status --porcelain` / `git diff` show no changes at
+all — truly nothing, not even untracked files outside the harness's own
+bookkeeping (`.harness.*`, `harness.log`, `.env`, `.headlesscode/`,
+`ORCHESTRATOR_TASK.md`) — say so plainly and stop; do not invent a
+plausible-sounding review of something else instead.
+
+## What to review
+
+For each issue the worker closed (you'll be told which one(s), or find
+them via `gh issue list --state closed` filtered to the relevant
+range/labels):
+
+1. **Read the issue's closing comment in full.** Note every concrete,
+   checkable claim: test pass/fail/error counts, coverage percentages,
+   "N files/lines checked," "boots cleanly," "0 additional issues,"
+   specific behaviors preserved.
+2. **Read the actual diff** for the commit(s) referencing that issue
+   number, not just the PR description. Read the whole diff, not a
+   sample, for anything under ~500 lines; for larger diffs, prioritize
+   the highest-risk categories first (anything touching request
+   handling, database sessions, migrations, encryption, auth, or
+   anything deleted rather than added/modified) before sampling the
+   rest.
+3. **Re-run every checkable claim yourself, for real:**
+   - Get a fresh baseline test run (both `server/tests` and
+     `server/src/services/tests` — two separate suites) and
+     compare the actual numbers against what the closing comment
+     claims. A mismatch of even a few tests is not a rounding error —
+     investigate it.
+   - If the comment claims "server boots cleanly" or similar, reproduce
+     that yourself rather than trust it:
+     ```
+     docker run --rm -v "$(pwd)/server:/app/server" -v "$(pwd)/extensions:/app/extensions" -v "$(pwd)/projects:/app/projects" --entrypoint python3 <your-server-image>:latest -c "
+     import sys; sys.path.insert(0, '/app/server/src')
+     from fastapi import FastAPI
+     from server_services.api.server_routes import register_routes
+     app = FastAPI(); register_routes(app)
+     print('ROUTES:', len(app.routes))
+     "
+     ```
+   - If the comment claims "N deletions checked, 0 additional issues"
+     or similar for a mechanical cleanup, independently re-derive the
+     diff and spot-check a real sample yourself — don't just accept
+     the count. For every deleted import/name/re-export in the diff,
+     grep the **entire current codebase** for any remaining reference
+     to it — including string-literal references (`getattr(module,
+     "name")`, dispatch tables, route/signal registration by string)
+     and test files (a deleted import in a test file is higher risk —
+     could be a pytest fixture whose presence, not usage, matters).
+   - If the comment claims a coverage percentage, run the actual
+     `--cov-report` yourself and compare.
+4. **Check for silent behavior changes**, not just crashes or test
+   failures — a refactor that changes control flow (e.g. moving a
+   database query outside a try/except, reordering operations with
+   side effects, changing what an except clause catches) can be
+   "passing all tests" and still be wrong if nothing tests that
+   specific path. Read decomposed/extracted functions side-by-side
+   with their original to confirm behavior is actually preserved, not
+   just "looks equivalent."
+5. **Check CI status on the PR** (`gh pr checks <number>`) — if
+   anything is red, determine whether it's caused by this work or
+   genuinely pre-existing/unrelated (check if the same check fails
+   identically on current `master`) before dismissing it.
+6. **Keep every scratch/temp file inside the workspace — no `/tmp`.**
+   Any scratch you need (probe scripts, temp output captures,
+   throwaway test files) goes in `<workspace>/.headlesscode/scratch/`
+   (create it if it doesn't exist; `/.headlesscode/` is gitignored).
+   Writing to `/tmp` or any path outside the workspace is a documented
+   recurring reviewer violation (round-2026-08-17 wrote
+   `/tmp/prsummary.md`, `/tmp/review62.md`, `/tmp/review90.md`,
+   `/tmp/review98.md`, `/tmp/review-pr113.md`,
+   `/tmp/hc-review-check/probe.ts`) — outside-workspace writes cannot
+   be auto-approved in the interactive GUI and are rejected by the
+   file tools in headless workers.
+7. **If the diff adds or changes CI configuration** (`.github/workflows/*`,
+   `scripts/e2e*`), verify it against the REAL runner (push/PR runs,
+   `gh run watch --exit-status`), not only locally — a workflow green
+   under the local mock is not evidence it runs. This exists because a
+   round's most valuable catch was exactly this class: a SIGINT test
+   passing 5/5 locally (where `process.emit("SIGINT")` never terminates
+   Node) while the real workflow failed deterministically on the runner.
+   Local-only verification of a CI change is a re-review finding even
+   when every local check is green.
+
+## Verdict and action
+
+For each issue:
+
+- **If everything checks out**: leave a comment on the issue stating
+  exactly what you verified and how (real command output, not "looks
+  good"), and leave it closed.
+- **If you find a real problem**: reopen the issue
+  (`gh issue reopen <number>`) with a comment that includes: the exact
+  problem, file:line evidence, the real command output that
+  demonstrates it, and specific, actionable instructions for what needs
+  to change — written the way you'd want to receive feedback if you
+  were about to fix it yourself. Do not reopen an issue for a stylistic
+  preference or a nitpick with no functional consequence — reserve
+  reopening for things that are actually wrong (a bug, a false claim, a
+  regression, a genuine convention violation the original issue asked
+  for).
+- **Do not fix the problem yourself in this mode.** Your job is
+  verification and clear reporting, not remediation — that happens in
+  the worker session that picks the reopened issue back up.
+
+## What NOT to do
+
+- Do not pad the review with issues that have no real consequence just
+  to look thorough.
+- Do not accept "the tests pass" as sufficient evidence for a claim
+  about something the tests don't actually exercise — check what the
+  tests actually assert, not just whether they're green.
+- Do not skip re-running commands because the report already includes
+  output — output in a report is a claim, not evidence, until you've
+  reproduced it.
+- Do not review by reading only the PR description — read the actual
+  diff and run actual commands every time.
+- No `/tmp` — scratch goes in `<workspace>/.headlesscode/scratch/`
+  (the repo rule "Never write to /tmp" is binding here too; a `/tmp`
+  write in a review session is a finding).
+
+## Once you have a clear answer, report it — don't keep re-checking
+
+2026-08-27: verified live — a review session correctly investigated a
+false-completion claim (checked `git log`, `git diff`, ran `curlee
+check`), correctly concluded in its own words "the git log shows no
+commits related to [the claimed file], which suggests the work may not
+have been done yet" — and then, instead of reporting that finding,
+spent its next three turns narrating an intent to check further
+("Let me check the git diff between the current branch and master...")
+without ever issuing another tool call or calling attempt_completion,
+until it hit the session's mistake limit and lost the entire correct
+finding it had already reached.
+
+One piece of clear, disqualifying evidence is enough to conclude — an
+empty `git diff --stat` against a claimed change, a commit history with
+nothing touching the claimed file, a test that still fails after the
+claimed fix. The moment you have that, stop gathering more evidence
+"to be sure" and call attempt_completion with your verdict immediately.
+Additional confirmation of something you already know is not more
+thorough — it is exactly the kind of stall that has previously lost a
+correct finding entirely.
+
+An EMPTY result is still a result — trust it the first time, in
+whatever exact form it comes back. Two independently-reproduced
+instances of the SAME pattern now: a review session ran `git diff
+master -- <claimed file>` and got empty output (no changes) — correct,
+disqualifying evidence — but instead of treating that as an answer,
+re-ran the equivalent check 16+ more times with slightly different
+arguments (`git diff HEAD..master`, `git log --all --oneline`, `git
+reflog`, various branch-ref permutations). A second session did the
+same specifically with `git log --oneline HEAD..origin/master` — ran it
+three times in a row, identically, got empty output every time (nothing
+ahead), before the identical-call guardrail even had to step in. In
+both cases the empty/quiet result did not feel like enough of an answer
+to act on, and in the first case the original correct finding got
+buried under so much repetitive noise that the final report never
+referenced it at all — producing a false "VERDICT: CLEAN" for a worker
+that made zero real changes. This applies to EVERY form of "nothing
+here" evidence — `git diff <base>..<branch> -- <file>`, `git log
+<base>..<branch>`, `git log -- <file>`, `git log --all --oneline | grep
+<file>` — not just one specific invocation. The first empty result IS
+your answer. Do not re-run the check again with different flags or
+different branch-ref syntax hoping for a different outcome; a second,
+third, or sixteenth empty result is not more convincing than the first
+one, in any of its equivalent forms.
+
+## When you're done with all assigned issues
+
+Post a short summary comment on the PR itself (not just per-issue)
+listing: which issues you verified clean, which you reopened and why,
+and the final baseline test numbers you personally confirmed. Do not
+merge anything yourself.
+
+## Required final line of your attempt_completion result
+
+The orchestrator does not read your prose to decide whether to trigger
+a rework cycle — free-form parsing of report language proved unreliable
+in practice (ordinary phrases like baseline "N failed" counts, or an
+aside explaining something does NOT need reopening, were repeatedly
+misread as a finding). Instead, the VERY LAST LINE of your
+attempt_completion result must be exactly one of:
+
+```
+VERDICT: CLEAN
+VERDICT: FINDING
+```
+
+Nothing else on that line — no prose, no punctuation, no markdown. Use
+FINDING if you reopened ANY issue in this round, CLEAN only if none
+needed reopening. Everything above that line (the per-issue comments,
+the PR summary, your reasoning) is for a human reader and can be as
+detailed as you judge useful — only this last line is machine-parsed.

package/shared/rules-code/rules.md

@@ -0,0 +1,22 @@
+## Hard-won lessons
+
+Generic, stack-agnostic code-mode guidance shipped with headlesscode and
+spliced automatically into every code-mode session's system prompt (a
+project-local `.roo/rules-code/rules.md` adds/overrides on top).
+
+- Never delete a public name without grepping the ENTIRE codebase for every importer — including
+  string-literal references (dispatch tables, getattr-by-name) and test files that import for
+  side effects (pytest fixtures, registration).
+- If you split a module into submodules, verify EVERY public name the original module exposed is
+  still re-exported from the package's __init__.py (or equivalent) before closing — a missed
+  re-export is a common, easy-to-miss defect a reviewer WILL catch, costing a full rework cycle.
+  If the project has a re-export-checking script (e.g. scripts/check_re_exports.py), run it now,
+  not just after a reviewer flags the miss.
+- Re-run real checks (tests, boot) after every change and paste the real output in your report —
+  output in a report is a claim, not evidence, until reproduced.
+- If you find yourself repeating the same check across issues, script it under scripts/.
+- A `git worktree add <path> <ref>` ALWAYS checks out the committed state of <ref> — it never sees
+  uncommitted changes sitting in another checkout's working tree, even though worktrees share the
+  same .git. If you spin up a throwaway worktree to verify a fix you just made, either commit the
+  fix first or manually copy the modified file(s) into the fresh worktree — otherwise you'll be
+  testing the OLD code and get a confusing failure that looks like the fix didn't work.

package/shared/stacks/cpp/rules.md

@@ -0,0 +1,30 @@
+## Build system first
+
+Before running any build or touching build configuration, identify the project's actual build system and its documented entry point:
+
+- Check for a documented build script (`build.sh`, `scripts/build-*.sh`, a README/agent-instructions note) before assuming `make` or `cmake --build` — do not guess invocations the project doesn't use. Prefer the project's own build flow over ad hoc `cmake`/`ninja` commands unless the script genuinely can't do what's needed.
+- Note the generator and the pinned C++ standard (`CMAKE_CXX_STANDARD` in `CMakeLists.txt`, e.g. C++23). Do not introduce constructs outside the standard the project compiles with.
+
+## Verify without launching the app
+
+Many C++ engine/game projects keep runtime/UI verification manual. Validate through build success and the project's own test executables, not by launching a binary. When the tests are custom executables rather than gtest/Catch2, find the test targets under `tests/` and run them the way the project does.
+
+## Compiler warnings
+
+Build with the project's warning configuration (check `CMakeLists.txt` / compile options for `-Wall -Wextra` or stricter) and treat new warnings on files you touched as review findings, not noise. Do not silence warnings unless the project's own config already does.
+
+## Memory ownership
+
+Match the project's ownership convention — raw pointers + manual lifetime, `std::unique_ptr`/`std::shared_ptr`, or a custom allocator/arena — before introducing a new allocation pattern. A pattern that is idiomatic in isolation but inconsistent with the surrounding code is a review finding.
+
+## Headers and rebuild cost
+
+Check whether a header you're changing is included by many translation units before adding heavy includes to it. Prefer forward declarations and moving heavy includes into `.cpp` files to avoid an avoidable full rebuild.
+
+## ABI / link compatibility
+
+Changing a class's layout in a header used across a shared-library boundary (adding/removing members, changing virtual functions) compiles fine locally but breaks only at link/load time. Check whether the type crosses a library boundary before changing its layout.
+
+## Project docs
+
+C++ engine/game projects often carry living design docs (`docs/`, `wiki/`). Scan them before touching a subsystem — they encode decisions already made and prevent redoing settled analysis.

package/shared/stacks/fastapi/rules.md

@@ -0,0 +1,30 @@
+# Stack rules: FastAPI
+
+Applies when the target project uses FastAPI (`fastapi` in Python dependencies).
+These are FastAPI-specific conventions and footguns on top of the project's own
+rules.
+
+## Routes
+
+- Test every new or changed route through the ACTUAL ASGI app — `TestClient`
+  (`fastapi.testclient`) or `httpx.AsyncClient` over `ASGITransport` — never
+  just the handler function in isolation. A route can be wired wrong (missing
+  from the router, wrong prefix/method) while the handler function itself is
+  correct.
+- Before adding a route that needs auth/db/session access, find the project's
+  dependency-injection conventions (`Depends(...)`) and reuse its existing
+  scoping helpers (e.g. a tenant/account-resolution dependency or mixin).
+  Inventing a different pattern produces a route that looks right but bypasses
+  the project's scoping layer (tenant isolation, account checks).
+- After adding or changing a route, re-run the project's boot check if one
+  exists (e.g. an assertion on the exact route count). A route that silently
+  fails to register is caught only by an explicit count/list check, not by
+  "the server started".
+
+## Pydantic models
+
+- Before changing a request/response model field, check whether the schema is
+  shared with client-generated types (OpenAPI-driven codegen). A field change
+  without the matching client update silently breaks the frontend contract.
+- Return the project's response models explicitly rather than leaking internal
+  ORM objects or ad-hoc dicts where a schema is expected.

package/shared/stacks/javascript/rules.md

@@ -0,0 +1,37 @@
+# JavaScript / Node.js conventions
+
+Applies to any project with a `package.json`. A TypeScript project also
+matches this stack, so keep to package-level advice that stays valid when
+the `typescript` rules fire too.
+
+## Package manager
+
+- Identify the project's real package manager from its lockfile BEFORE
+  running install/add commands: `package-lock.json` → npm, `yarn.lock` →
+  yarn, `pnpm-lock.yaml` → pnpm. Using the wrong one creates a second
+  lockfile and silent dependency drift — never `npm install` in a
+  yarn/pnpm project (or vice versa) just because npm happens to be
+  available.
+- Use the matching add command (`npm add` / `yarn add` / `pnpm add`) for
+  new dependencies; don't hand-edit `package.json` and then run a bare
+  install.
+- In a monorepo, check `workspaces` (npm/yarn) / `pnpm-workspace.yaml`
+  before assuming where to run install or which `package.json` a script
+  belongs to.
+
+## Scripts
+
+- Run the project's own `scripts` from `package.json` (`npm run <x>` /
+  `yarn <x>` / `pnpm <x>`) instead of inventing equivalent commands — the
+  project's test/lint/build scripts encode its real toolchain and config.
+- Use the project's lint script (e.g. `scripts.lint`) rather than assuming
+  a specific linter or config; a project may pin a linter with specific
+  rules/exclusions a generic invocation gets wrong.
+- For one-off tools, prefer the local toolchain via `npx` (or the
+  detected manager's equivalent) over installing anything globally.
+
+## Node runtime
+
+- Check `package.json`'s `engines.node` and any `.nvmrc` before assuming a
+  Node version for anything version-sensitive; if the project pins a
+  version, use that version rather than the system default.

package/shared/stacks/postgresql/rules.md

@@ -0,0 +1,31 @@
+# Stack rules: PostgreSQL
+
+Applies when the target project uses PostgreSQL (a postgres driver in Python
+dependencies, a postgres-image service in a compose file, or a
+migrations/alembic directory).
+
+## Migrations
+
+- Check every schema migration for backward-compat with the code currently
+  deployed during rollout. Adding a NOT NULL column to a large table without a
+  safe default or a backfill strategy is a classic outage — prefer additive
+  steps (add nullable → backfill → tighten the constraint) and keep the
+  migration reversible.
+- Run migrations against a REAL (containerized) Postgres in tests, not a mock —
+  dialect behavior, constraints, and locking only show up against the real
+  thing.
+
+## Multi-tenant data access
+
+- Any new query touching tenant-scoped tables must go through the project's
+  existing tenant-scoping helper — never a raw unscoped query, or it becomes a
+  cross-tenant data leak.
+- When a route/endpoint reads or writes tenant data, take the tenant id from
+  the project's account/tenant-resolution layer (auth/session), never from
+  client-supplied input.
+
+## Connections & resources
+
+- Check for an existing connection-pooling config before adding a new direct
+  connection — a worker spinning up unpooled connections in a loop is a common
+  self-inflicted resource-exhaustion bug.

package/shared/stacks/python/rules.md

@@ -0,0 +1,35 @@
+# Python conventions
+
+## Tooling
+
+- Identify the project's formatter/linter from its ACTUAL config before
+  assuming one: `pyproject.toml`'s `[tool.ruff]` / `[tool.black]`,
+  `setup.cfg`, or `.flake8`. A project may pin a specific tool with a
+  specific line-length and exclusions (e.g. vendored code); guessing wrong
+  wastes a whole run.
+- Check how the project runs tests before invoking pytest: Docker
+  (`docker-compose exec` / `docker compose run`) vs a local venv. Running
+  against the wrong environment gives a false baseline.
+- Honor the project's pytest config — `[tool.pytest.ini_options]` in
+  `pyproject.toml`, `pytest.ini`, or `tox.ini` — for test paths, markers,
+  and options.
+
+## Dependencies
+
+- Identify the actual dependency manager before running install commands:
+  `poetry.lock` → poetry, `Pipfile.lock` → pipenv, `requirements*.txt` →
+  pip. Installing with the wrong tool creates a parallel lockfile /
+  environment and silent drift.
+- Prefer the project's virtualenv (`.venv` / `venv`) over the system
+  Python for install/run commands.
+
+## Python-specific dynamism
+
+- Never delete or rename a public name without grepping for
+  `getattr`-by-name / dispatch-table / string-literal references in
+  ADDITION to normal imports — `__all__`, `getattr(module, name)`, and
+  plugin/registry patterns mean static-import grep alone misses real call
+  sites.
+- After splitting a module into submodules, verify every public name the
+  original module exposed is still re-exported from the package's
+  `__init__.py`.

package/shared/stacks/react/rules.md

@@ -0,0 +1,11 @@
+Guidance for working in a React codebase.
+
+- Before adding a component, check how existing components are written (function vs class, hooks usage, styling approach — CSS modules / Tailwind / CSS-in-JS, file organization) and match it; a working component that follows a different pattern than the surrounding code is a review finding.
+- Match the project's existing component-testing setup (React Testing Library vs others; colocated `*.test.tsx` vs a `__tests__/` dir) when writing component tests. If the project has no component tests, don't introduce a new framework — verify with the project's existing test runner instead.
+- Prefer the project's existing state/data-fetching pattern (context, Redux, Zustand, react-query, …) over introducing a new library for a single component.
+- Effect correctness — the "background timer fires unexpectedly" class of bug: every value read inside `useEffect`/`useMemo`/`useCallback` must be in the dependency array (or deliberately omitted with a comment), and timers/subscriptions must be cleaned up in the effect's returned cleanup function. Under `<StrictMode>` effects run mount→unmount→mount in dev, so an effect that leaks a timer looks fine once and double-fires later.
+- If the project's lint config enables `eslint-plugin-react-hooks`, run the project's lint on new/changed components and treat its hooks-rule findings as blocking — don't locally disable those rules.
+- Framework boundary (Next.js/Remix, when `next.config` or framework deps are present): respect the server/client component split — keep server-only code (secrets, DB access) out of client components and follow the project's directive convention (`"use client"` etc.).
+- Interactive elements (custom buttons, dialogs, form controls): if the project has `eslint-plugin-jsx-a11y` configured, new elements must satisfy it (keyboard access, accessible labels, ARIA) — a mouse-only control fails a11y review.
+- Use a stable id, not the array index, as a `key` for lists that can be reordered or filtered — index keys cause state/scroll bugs on reorder.
+- Changing a component's props or a context's shape: update every usage site in the same change. React (especially in a plain-JS codebase) has no compiler to catch a missed prop at build time — a component left with an outdated call site fails only at render/runtime.

package/shared/stacks/typescript/rules.md

@@ -0,0 +1,10 @@
+Guidance for working in a TypeScript codebase.
+
+- After every change touching `.ts`/`.tsx` files, run the project's own typecheck (its `typecheck` script, or `npx tsc --noEmit` when there is none) BEFORE claiming the change works — a change that compiles by eye but fails `tsc` is a common false "done".
+- Respect the strictness `tsconfig.json` actually configures (`strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, …). Don't silence a flagged error with `any`, `@ts-ignore`, or a non-null assertion (`!`) — fix the code; if the project deliberately relaxes an option, that relaxation belongs in `tsconfig.json`, not in per-site escapes.
+- Before writing imports, check `tsconfig.json`'s `paths` for aliases and match the project's import style (aliased vs relative) — introducing a second import style for the same module is a review finding.
+- When adding a new exported type/function, check whether the project uses barrel files (`index.ts` re-exports) and add the re-export there. Match the file's existing export style: named vs default export, and `export type` vs `export` — a plain `export` of a type-only name breaks under `verbatimModuleSyntax`/`isolatedModules`.
+- Where `tsconfig.json` sets `verbatimModuleSyntax` or `isolatedModules`, use `import type` for type-only imports and `export type` for type-only re-exports — a plain `import` of a type is a compile error there.
+- Changing an exported type/interface's shape: update every consumer in the same change. Types have no runtime errors to catch a missed site — only `tsc` does — so a type change can "work" in isolation and break the next typecheck elsewhere. When renaming or deleting an exported symbol, prefer compiler-accurate reference search (the `find_references`/`go_to_definition` tools when available) over grep: grep misses aliased imports and re-exports.
+- Check `tsconfig.json`'s `target`/`lib` before relying on runtime globals — code using DOM globals fails to compile in a Node-`lib` project and vice versa.
+- Before writing a NEW test file, open an EXISTING one in the same test directory first and match its actual API. Do not assume Jest/Mocha/Vitest (`describe`/`it`/`expect`) — plenty of TypeScript projects (especially internal tools) use a plain `node:assert/strict` script run directly by the runtime, with no test framework installed at all. Writing `describe`/`it` against such a project fails to compile and wastes a whole verify cycle. Check the project's `package.json` `test`/`devDependencies` (or the test command you were told to run) to confirm what's actually available before assuming a specific framework's API — never `npm add` a test framework to make an assumed API work; match the existing convention instead.