bug AGENTS.md

Project Agent Guidelines

Module Testing Standard

• Use docker-based test execution for module containers.
• For module container packages, set scripts.test to build and run tests in Docker using each module's Dockerfile.test.
• Prefer this pattern for module test commands:

docker build -f ./Dockerfile.test -t bug-module-test ../../../.. && docker run --rm --name bug-module-test-run bug-module-test npx jest --runInBand --config ./jest.config.cjs

Module Container Quick Check Profile

• Purpose: run a quick agentic pre-commit check in chat before major module container changes are committed.
• Use trigger phrase in chat: Run the module container quick check before commit.

Implementation Defaults

• Rule: keep worker restart checks aligned to real config dependencies.
• Rule: default to simple, readable implementations over maximum efficiency; only optimize for performance when there is a clear, measured requirement.
• Rule: prefer the simplest safe fix first, with minimal code changes.
• Rule: prefer inlined one-off literal values in module runtime files instead of file-level constants when the value is used once and naming does not add clarity.
• Rule: prefer no backward compatibility in new code; avoid aliases/shims/migration layers unless explicitly requested.
• Rule: never add regression tests for changes unless a task explicitly asks for them.

API and Service Patterns

• Rule: in module containers, prefer service-layer throw-on-error and keep routes thin; let express-async-handler propagate thrown/rejected errors via middleware instead of route-level { error } handling.
• Rule: in module containers, services should return raw payloads (object/array/value), not { data: ... }; route handlers should wrap service results in API response envelopes.
• Rule: status-check services are the exception to the general throw-on-error pattern; they should catch operational errors, log them, and return [] instead of throwing.

Worker Architecture