# 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.