commit - 6bbfd8993925c09d266f90e608ed1246c903f19e
commit + ebc43bb87cebdd3c6aba7beb82ad437158539ffb
blob - 5b7f6456e2bd4a8183f26593fdbcb59748072d20
blob + 58422e0743aff078dc36e708f08019a5cec31aaa
--- AGENTS.md
+++ AGENTS.md
-## Agent skills
+# AGENTS.md
-### Issue tracker
+## Project
-Issues are tracked as local Markdown under `.scratch/<feature-slug>/`. See `docs/agents/issue-tracker.md`.
+fugu is an OpenBSD-native, privilege-separated AI coding agent. It is a personal CLI for one Owner, not a hosted service, team tool, API, proxy, daemon, or credential-sharing mechanism.
-### Triage labels
+This tree is OpenBSD-only by design. Do not add portability shims, alternate runtimes, SDK dependencies, or non-base library dependencies unless explicitly requested and justified by an ADR.
-Use the five default canonical triage label strings. See `docs/agents/triage-labels.md`.
+## Domain language
-### Domain docs
+Read `CONTEXT.md` before nontrivial work and use its vocabulary exactly. In particular:
-This repo uses the single-context layout. See `docs/agents/domain.md`.
+- Use **Owner**, not user/operator/customer/team when the human relationship matters.
+- Use **Lead**, **Turn**, **Generation**, **Projection**, **System baseline**, and **System epoch** precisely.
+- Do not use bare "context" in code or docs when a specific term applies. Prefer **Projection**, **Project context**, or **Effective window**.
+- Use **Journal**, **Artifact**, **Role**, **Custodian**, **Coordinator**, **Worker**, **Tool**, **Subagent**, **Provider**, and **Effort** as defined there.
+
+Check relevant ADRs in `docs/adr/` before changing architecture, persistence, Provider wiring, privilege separation, or Project context behavior.
+
+## Implementation style
+
+Write C as if it were going into OpenBSD base:
+
+- KNF/style(9): tabs at 8, return type on its own line for function definitions, `/* */` comments only.
+- Keep warnings clean under `-Wall -Wextra -Wformat=2`.
+- Prefer small single-purpose files and `static` by default.
+- Use lowercase underscore names with short module prefixes.
+- Carry lengths with buffers and strings across subsystem boundaries; preserve embedded NUL correctness where the API permits bytes.
+- Use `strlcpy`, `strlcat`, checked `snprintf`, `strtonum`, `getline`, `reallocarray`/`recallocarray`, `arc4random`, and existing `x*` allocation wrappers.
+- Do not use `strcpy`, `strcat`, `sprintf`, `atoi`, ad-hoc JSON escaping, `popen`, shared memory, direct OpenSSL APIs, or prompt-enforced security.
+- Man pages are mdoc(7), lint-clean under `mandoc -Tlint`.
+
+Match the local module's existing idioms over introducing a new abstraction.
+
+## Security model
+
+Security properties must be enforced by pledge(2), unveil(2), process boundaries, typed imsg exchanges, and Role authority. Do not rely on model instructions or UI convention for isolation.
+
+Keep the hub-and-spoke topology: the Coordinator owns orchestration and the Journal; Workers do role-specific work; credential Custodians keep credentials inside their process; Subagents remain read-only and ephemeral.
+
+Validate imsg type and length before use. Treat Provider, web, terminal, Tool, and file bytes as hostile unless the relevant Role boundary says otherwise.
+
+## Build and test
+
+Normal OpenBSD commands:
+
+```sh
+make obj
+make
+make regress
+make check
+```
+
+`make check` is the pre-commit gate. It performs a clean rebuild and full regress run. Use `make CHECK_JOBS=1 check` for serial diagnostics and `make VERBOSE=1 check` for live compiler/test output.
+
+Use `make FUGU_DEBUG=1 check` for the UBSan trap-mode debug gate. Credentialed network/package checks are explicit release targets only: `make live-check`, `make live-check-privileged`, and `make live-check-help`.
+
+Regression suites live under `regress/`; `regress/README` maps invariants to proof suites. Add or update regress coverage with behavior changes, especially for security, Journal replay, Provider translation, Tool authority, and byte-boundary handling.
+
+## Repository layout
+
+- `src/fugu/`: Coordinator and user-facing binary.
+- `src/common/`: shared modules.
+- `src/fugu-tty/`, `src/fugu-api/`, `src/fugu-web/`, `src/fugu-tool/`, `src/fugu-artifact/`, `src/fugu-editor/`: privilege-separated Workers.
+- `regress/`: OpenBSD regression suites.
+- `docs/adr/`: accepted architecture decisions.
+- `docs/design/`: milestone designs and release verification notes.
+- `handoff/`: normative clean-room specification and style charter.
+- `port/`: staged OpenBSD port.
+
+## Issue tracker and skills
+
+Issues are local Markdown under `.scratch/<feature-slug>/`. See `docs/agents/issue-tracker.md`.
+
+Use the five canonical triage labels from `docs/agents/triage-labels.md`:
+
+- `needs-triage`
+- `needs-info`
+- `ready-for-agent`
+- `ready-for-human`
+- `wontfix`
+
+This repo uses the single-context domain-doc layout. See `docs/agents/domain.md`.
