# nt-lite development notes

nt-lite is a clean-design hobby kernel. It is not a stable compatibility platform. Prefer the right design over preserving old APIs, shims, or compatibility aliases.

## Principles

- Break old code when the new model is better.
- Do not keep compatibility paths unless they have a clear purpose.
- Plan the model before writing the patch.
- Make one architectural move at a time.
- Delete stale paths once the real path works.
- Prefer compile failures over wrappers that hide stale users.
- Keep the tree internally consistent.
- Keep one canonical API for each operation.
- A small patch can still represent the final model.
- Do not land temporary architecture just to make a feature appear to work.
- Put policy in the layer that owns it.
- Shared state should have one clear owner.

## Workflow

- Keep patches reviewable.
- Boot-test meaningful changes.
- Add diagnostics before optimizing.
- Use logs, counters, and assertions instead of guessing.
- Remove stale comments and dead code as part of the same cleanup.
- Treat a fallback as either a supported mode or delete it before it becomes permanent.
- Ask design questions before changing API shape, object lifetime, ownership, cancellation, persistence, or compatibility behavior.
- Do not add a side path to avoid updating callers.
- When changing an interface, update every caller in the same patch.
- When adding a build artifact, update build, packaging, copy, and runtime discovery paths in the same patch.
- Do not count apply checks or syntax-only checks as a real build.
- Be precise about what was actually validated.
- If behavior can be tested cheaply, include a focused runtime test or a visible diagnostic.
- Prefer counters that prove both success and non-use.

## Breaking changes

Breaking changes are allowed. When making one:

1. Define the new model.
2. Move every user to it.
3. Delete the old path.
4. Bump ABI or version constants when a contract changes.
5. Let stale users fail to compile.

## Patch expectations for AI agents

- Generate patches from the repository root.
- Paths must be rooted as `code/...`.
- `git apply <patch>` should work from the repository root.
- Do not require `--directory=code`.
- Keep generated artifacts out of the source tree unless requested.
- When asked to provide the full tree, also provide the patch.
- The patch is for review; the full tree is for reproducing the exact baseline.
- Avoid optimistic claims.
- Say exactly whether a change was apply-checked, syntax-checked, built, booted, or runtime-tested.
- Do not introduce compatibility aliases unless they are intentionally supported API.

## Comment style

- Comments explain why, not what the next line already says.
- Use `//` comments only.
- Use sentence case.
- End every sentence with a period.
- Every owned source file should start with a short file comment.
- Every function should have a comment, even if it is only a one-line summary.
- Keep the tone practical and technical.
- Humor is allowed rarely, but never instead of the real explanation.
- Debugging history belongs in comments only when it explains a lasting constraint.
- Document workarounds by saying what looks strange, why it is necessary, and what breaks if it is simplified.
- Avoid trailing comments except for flags, bitfields, register tables, and packed layouts.
- Keep real limitations as normal prose.

## Development lessons

- Ask before changing the shape of an API or the ownership model behind it.
- The right model matters more than minimizing the diff.
- A patch should be small enough to review, but not so small that it creates a temporary model.
- If a compatibility path is not meant to stay, do not add it.
- If the old path is replaced, remove it.
- Ergonomics matter. A clean API should not make common calls annoying.
- Debug by evidence, not by the subsystem that changed most recently.
- Poison values, fault addresses, counters, and reproduction steps are more useful than guesses.
- Performance fixes need tail-latency checks, not only average throughput.
- Diagnostics must reach every active output path that developers rely on.
- Runtime tests should clean up after themselves and say clearly when they use temporary data.
- A passing test should leave the system in a sane state, not only print `PASS`.
- Build integration is part of the feature.
- Packaging mistakes are real bugs, not clerical issues.
- When a change crosses layers, verify every layer that knows about the new object, file, syscall, or artifact.
- Prefer finishing the feature the user needs over endlessly polishing the audit around it.
- Do not hide uncertainty. Say what was checked and what still needs a real build or boot test.