kata: Instructions file for Codex

kata — agent guidance

Agent rules

• Always Commit: Do not leave accepted repository changes uncommitted at the end of a task. Commit the completed work, or explicitly say why no commit was made.
• Never Squash or Amend: Do not squash commits, amend commits, or otherwise rewrite git history unless the user explicitly asks for that history rewrite.
• Do not commit rejected experiments. Revert them or ask before preserving them.
• Never invoke the roborev review CLI command in any form unless the user explicitly asks for it. Use all other roborev CLI commands normally when they are appropriate for interacting with roborev. Never invoke a roborev skill (including roborev-fix or roborev-design-review-branch) unless the user explicitly asks for that skill.
• Test First: Write a failing test before the implementation, then make it pass, then refactor (red, green, refactor). Don't add production code without a failing test that requires it.
• Evidence-Gated Regression Tests: Before writing a regression test, reproduce the failure or name the explicit product contract it exercises. Do not encode an inferred cause or hypothetical failure. Browser-specific coverage requires a reproduced browser-specific failure; otherwise use the default test browser.
• Explicit Database Change Consent: Do not add, remove, or modify a production database migration or persisted database schema without the user's explicit consent in the current conversation. This includes canonical/bootstrap DDL, schema-version constants, migration assets and registries, migration or cutover runners, and changes to tables, columns, indexes, constraints, triggers, functions, extensions, or other persisted database objects. A feature request, backend-completion request, green test suite, unreleased or pre-alpha status, or editable-in-place schema snapshot does not imply this consent. Before editing, state the exact backend and proposed persisted-state changes and wait for approval. Ephemeral test-local DDL that does not define product persisted state is exempt. After approval, follow docs/development/postgres-migrations.md for PostgreSQL migration history and verification rules.
• No CHECK Constraints: Do not add CHECK constraints to the SQLite or PostgreSQL schema or to migrations. Validate values in Go before the store writes them, and share that validation with import and federation ingest. CHECK constraints that already exist stay until a separately approved migration removes them.
• No Private Project Data: Do not use private project, workspace, customer, host, or repository names in tests, docs, examples, planning documents, design notes, issue or bug reports, review responses, PR text, or generated fixtures. Use neutral placeholders such as spoke-project, hub-project, example-workspace, or daemon.example unless the user explicitly asks to preserve a real name in a user-facing operational command.
• No Testing/Verification Sections in PRs: Do not include a testing plan, test plan, verification, or verified section in pull request descriptions.
• User or Developer Benefit: Pull requests must have a user-facing benefit or improve the developer experience, and the body must say which one.
• English: Write issues and pull requests in English.
• No Unrequested GitHub Comments: Do not comment on GitHub issues or pull requests unless the user explicitly instructs you to post a comment.
• No Compiled-In Source Paths: Never locate files from a path returned by runtime.Caller or a stack trace; builds use -trimpath, so those paths are module-relative. Tests run from their package directory, so use paths relative to it. Trimmed test binaries also cannot fall back to the Go installation's time zone database, so test files that load named zones blank-import time/tzdata.
• No Bash Content-Assertion Tests: Do not add bash tests that assert shell script, workflow, or config behavior by grepping for implementation text. These are usually tautological: they prove only that the file contains the string the test searched for, not that the release, installer, or workflow works. Prefer exercising the command/tool behavior directly, using the tool's own validation command, or writing a real parser-backed test. If direct behavior coverage is not practical, document the manual check instead of adding a brittle shell content test.