# AGENTS.md

## Scope and completion

- Be concise. For questions, give the direct answer. A prompt that ends with
  `?` is read-only.
- For action requests, complete implementation and verification within the
  requested scope. Before fixing a reported issue, explain your understanding
  and proposed fix, then proceed with authorized work.
- Use repository evidence for routine decisions. Ask when missing information
  affects design, correctness, scope, or authorization. Continue independent
  work while waiting. Do not invent language semantics or API contracts.
- Preserve unrelated edits. API contract changes require explicit permission.
  Compatibility with unmerged feature work is not required.
- Report what changed, checks run, and any remaining limits. Fix failures caused
  by your changes before declaring completion. If work remains blocked or
  deferred, record concrete items in the existing TODO file, or `TODO.md`.

## Work records in `.ai/`

Maintain these records during work that permits file edits. Read-only tasks
must not create or update logs or TODO files.

- Bugs: when you discover a bug, record it in `.ai/issues/<bug-name>.md`.
  Include observed behavior, expected behavior, and reproduction steps or
  supporting evidence.
- Decisions: when you make your own decision, add the decision and its
  reason to `.ai/decisions/` as a new file with format `YYYY-MM-DD-SLUG`.
- Suggestions: when you identify a potential improvement to the Radiance
  language or tooling that would have helped with the current task, create a
  file under `.ai/suggestions/`. Explain the improvement and how it would have helped.
- Design questions: record one question per line in `.ai/questions.txt`.
- Design findings: record one relevant finding per line in `.ai/learnings.txt`.

Question and finding logs are required for design tasks, not routine
implementation. Bug, decision, and suggestion logs apply to both.

## Git

- Read-only inspection is allowed. Git operations that change repository state
  require an explicit request. Leave changes uncommitted unless asked to commit.
- Sign every commit. Create a new commit unless explicitly asked to amend.
  Include documentation and other non-source files only when asked.
- Large features require a new worktree under `../worktrees/`. If its creation
  is not authorized, ask before implementation and continue read-only research.
- Read `CONTRIBUTING` before writing commit messages.

## Radiance implementation

Radiance is a self-hosted systems language compiler targeting RV64. It runs in
an external RISC-V emulator on Linux x86-64. Read representative source and
relevant specifications when working with unfamiliar syntax; Rust semantics
are not evidence of Radiance behavior.

- Read `STYLE` before changing source; it defines code and documentation style.
- Correctness and safety are requirements. Among correct designs, prioritize
  code simplicity and size, then execution speed and memory use, then generated
  code quality. Use production-quality solutions without workarounds.
- Fix root causes. Preserve valid changes and tests that expose a compiler bug.
- Reason from RV64: registers are 64-bit. Choose narrower operations from type
  and instruction semantics, and verify their cost on this target.
- Handle errors through the established API: `throw` for recoverable failures,
  `panic` for impossible invariants. Optionals can represent expected absence;
  they must not hide errors.
- Use camelCase for Radiance functions, methods, and variables. Prefer optionals
  to sentinels, `if-let` or `let-else` for matching, and `append` for slice growth.
- Use ASCII in source comments and strings, and simple English in technical
  documentation. Document all top-level declarations and record/union fields,
  plus non-obvious private code.
- Comments describe stable purpose, invariants, and non-obvious constraints.
  Do not narrate migrations or review history. Preserve comments during code
  simplification. Describe clean cutovers by supported behavior and files changed.

## Tests

- For features and bug fixes, write a failing test first at the appropriate
  level: std, lowering, or assembly. Verify that it fails for the intended reason,
  apply the implementation, and verify that it passes.
- Cover affected branches, boundaries, errors, and relevant language interactions
  such as guards, `if-let`, `let-else`, and `while-let`. Include adversarial
  executable cases for safety changes where applicable.
- Use `assert` for expected values. Nonzero exit expectations are for tests of
  failure or exit behavior. Remove tests for functionality the user asks to remove.
- Run focused tests during development and `make test` after the final source,
  test, or build change. Repeat successful checks only after further changes or
  to investigate an unresolved concern.
- For documentation-only changes, verify content, paths, commands, and formatting;
  no compiler tests are needed. Distinguish checks performed from untested claims.

## Build and test entry points

Use Make to compile: its recipes supply required memory and stack settings.
Use timeouts for builds, tests, scripts, and emulator runs. These limits are
starting points; investigate timeouts before increasing them. Export
`RAD_EMULATOR` when selecting an emulator so Make and scripts use the same one.

```bash
timeout 300 make           # Build bin/radiance.rv64.dev from the seed
timeout 600 make test      # Seed format, std, and binary tests
timeout 300 make std-test  # Standard library tests
timeout 300 make bin-test  # All IL and executable checks
```

For one executable fixture, replace `NAME` with its basename:

```bash
timeout 300 make test/runner.rv64 test/tests/NAME.rv64
timeout 10 test/run test/tests/NAME.rad
```

For an IL-only fixture, build only `test/runner.rv64` before `test/run`.
The harness runs existing binaries; it does not build them.

## Task-specific references

- Compiler work: `compiler/radiance.rad` is the entry point; `lib/std/lang/`
  contains scanner, parser, resolver, lowering, and code generation modules.
  RV64 backend and assembler code is in `lib/std/arch/rv64/`.
- Tests: read nearby fixtures and `test/run` for supported checks. `.ril` files
  check IL; `//! returns: N` requests an executable check. Success fixtures use
  `@default fn main`, assertions, and a zero return. Inspect generated IL before
  accepting a new snapshot.
- Session fixtures: `//! session-support` uses `test/support/std.lib`. Keep
  individual golden checks below one second. Test production std behavior in std
  unit suites. Module lists are in `std.lib` and `std.lib.test`.
- Backend debugging: locate the first incorrect stage, from AST and resolution
  through IL, assembly, and execution. Use Make recipes with the existing
  `RADIANCE` settings for diagnostic compilation.
- Bootstrap changes: read `seed/README`. The seed must compile checked-in source.
  Update it only when needed, through `timeout 600 make seed` or the documented
  alternate-seed workflow with a timeout. `make test` checks seed image format,
  not fixed-point reproducibility.

Use the current Makefile, scripts, and source to resolve stale command examples.