coding-standards.md

Coding standards

The executable policies in ../../tsconfig.json, ../../.prettierrc.json, and ../../scripts/check-source.ts take precedence over this summary.

TypeScript

• Keep strict TypeScript enabled and satisfy all current compiler checks.
• Do not use the any or unknown types; the source checker rejects both tokens in TypeScript files.
• Prefer Zod schemas plus z.infer for values that cross runtime boundaries.
• Use explicit discriminated unions and exhaustive control flow for state and outcome variants.
• Use import type when an import exists only for type checking.
• Preserve ESM imports with explicit .ts extensions.
• Avoid broad type assertions. Narrow through schemas, control flow, or small typed test fakes.

Boundaries and dependencies

• Keep domain rules and state transitions in src/features/.
• Let features declare ports; concrete adapters in src/infrastructure/ implement them.
• Wire concrete dependencies only in src/app/ and the src/cli.ts composition root.
• Pass compact, validated Context Packets between stages; do not replay full transcripts.
• Keep automatic routing deterministic and explainable through route receipts.

Use constructor or function injection for clocks, IDs, terminals, process runners, ledgers, probes, and other effects that tests must control. Keep contracts focused on the behavior the feature needs rather than the full concrete implementation.

Validation and persistence

Parse untrusted input at the edge where it enters the system. This includes CLI arguments, environment-backed configuration, Codex protocol events, structured model output, and values loaded from SQLite.

Keep migrations and SQL inside SQLite adapters. Tests should exercise the public ledger API. When changing persisted state, update schema validation, migrations, reads, and writes together and cover reopen or resume behavior.

Processes, failures, and cleanup

• Spawn processes with argument arrays; never interpolate task text into a shell command.
• Propagate AbortSignal through long-running operations.
• Record validated JSONL events before surfacing process failure when partial evidence is required.
• Throw errors with actionable internal context at the failing boundary.
• Keep CLI failure output stable and avoid exposing credentials, prompts, or unvalidated process output.
• Release claims, timers, subscriptions, worktrees, and temporary files in finally blocks or equivalent guaranteed cleanup paths.

Tests

• Mirror source areas under tests/ and name files *.test.ts.
• Test observable behavior through exported functions, classes, schemas, and ports.
• Inject lightweight fakes for feature tests; use real SQLite or filesystem adapters only when testing those adapters.
• Cover success, validation failure, interruption, and recovery when the changed behavior supports those outcomes.
• Assert route receipts, state transitions, persisted evidence, terminal output, and exit codes where they are part of the contract.
• Keep tests deterministic with injected clocks, IDs, temporary paths, or controlled process runners.

Formatting and verification

Run:

bun run format
bun run check

bun run check is the handoff gate: formatting check, source policy, strict type checking, and the full test suite must pass.