signalint: Instructions file for Codex

AGENTS.md — Operating rules for Signalint

These are the standards for changing code in this repository. They apply to human contributors and coding agents alike.

Start with ARCHITECTURE.md for how the system fits together, and CONTRIBUTING.md for setup and the pull request process.

Coding standards

• TypeScript strict mode is mandatory. Never use any — use unknown and narrow, or define a proper type.
• Functions should do one thing. If a function exceeds ~40 lines, consider splitting it.
• Every module under src/engines/, src/cache/, src/cluster/, and src/memory/ must have a corresponding test file under test/ before it is considered done.
• All public functions and MCP tool handlers need a one-line JSDoc comment stating what they do and what they assume about their input.
• Match the response schema defined in src/schema.ts exactly. It is versioned (schemaVersion) and has external consumers. If you believe the schema needs to change, propose it — do not silently add or rename fields.
• Engine adapters are the only modules permitted to invoke external processes. Everything above them operates on NormalizedIssue objects.

Trust boundaries

Signalint treats every MCP tool argument as untrusted, because the model supplying it can be prompt-injected by repository content. When changing anything that handles tool input:

• Validate arguments through the strict schemas in src/toolArguments.ts.
• Resolve any client-supplied path through src/projectPaths.ts. Do not reimplement containment checks locally.
• Never pass client-supplied strings to a shell. Adapters spawn a resolved CLI entry point directly.

See SECURITY.md for the full threat model before changing this area.

Verification

Run all four checks before opening a pull request:

pnpm lint
pnpm typecheck
pnpm test
pnpm build

A change is done when a test actually passes, not when the code looks correct.