From 77559e5b475fbfc67d749131ef2cc37177d7cadb Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 4 Oct 2026 22:10:14 +0200 Subject: [PATCH] docs: define code structure documentation and verification standards --- AGENTS.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2b8aaef --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,66 @@ +# Working on tiny-wb + +## Structure and dependencies + +- Keep the binary entry point small: configuration, diagnostics, terminal lifetime, + and application startup belong there. +- Separate configuration/persistence, protocol decoding, transport, acquisition, + CSV export, shared scan state, and terminal presentation by responsibility. + Do not recreate a miscellaneous `structs` module. +- Protocol and export code must be usable without a terminal or physical device. + Accept `Read`/`Write` implementations or explicit data instead of opening files + or serial ports inside parsers. Keep model rules separate from transport rules. +- Pass typed settings explicitly. Put user-adjustable defaults in + `config/default.toml`; keep wire-format invariants in the protocol module. + Validate settings before connecting or creating output, including units, + bounds, empty collections, and non-finite numbers. +- Preserve existing configuration compatibility or document a tested migration. + Unknown keys and invalid supplied values must produce actionable errors. +- Prefer small concrete types and functions over speculative abstraction. + Introduce a trait only when multiple implementations or an actual test seam + justify it. Avoid adding dependencies for small standard-library operations. +- Propagate I/O errors, use complete writes, bound receive buffers, and never + interpret binary payload as text. Do not use `unsafe` for protocol ordering. + +## Documentation and comments + +- Update user-visible behavior, configuration examples, architecture/source maps, + protocol notes, and verification instructions in the same task as code changes. + Link to the authoritative document instead of duplicating detailed guidance. +- Add module documentation explaining its responsibility and boundaries. Public + APIs need Rustdoc covering units, invariants, errors, and meaningful examples. + Private comments should explain intent, non-obvious constraints, or tradeoffs; + do not narrate straightforward statements or retain commented-out code. +- Keep names and terminology consistent: MHz in user settings/CSV, Hz on the + wire, dBm for levels, milliseconds for configurable delays and timeouts. +- Separate observed behavior, upstream protocol evidence, and unverified hardware + assumptions. Preserve source links and verification dates for device facts. + Never claim a simulated transcript is a hardware integration test. +- Document limitations candidly. Avoid vague TODOs; explain the missing behavior, + its consequence, and what evidence would justify the next change. +- Keep README concise; use `docs/` for operational and architectural details. + Generated reports and badge SVGs stay ignored. + +## Verification + +- Add focused regression tests for changed behavior, especially malformed input, + boundary values, partial reads/writes, timeouts, absent ports, persistence, and + failure cleanup. Use in-memory transcripts and isolated temporary directories. +- Run formatting, locked checks/tests, Clippy with warnings denied, documentation, + the release build, and the declared MSRV check. Use the exact commands in + `docs/security-and-ci.md`; run security gates when changing dependencies. +- Run `cargo coverage` after changing Rust behavior. Raise the documented floor + only from measured results; never exclude production code to satisfy a target. +- Run `python3 scripts/test-badges.py` after CI/badge changes. Verify documentation + links and configuration examples after moving files or changing settings. +- Report unavailable hardware, Jenkins, platform, or publication checks explicitly. + Do not start Jenkins or publish shared assets as part of local verification. + +## Commits + +- Preserve unrelated work. Make one commit per coherent task with a concise + imperative subject (`refactor:`, `feat:`, `fix:`, `test:`, `docs:`, or `ci:`). +- Include tests and directly related documentation with their implementation. + Keep an independent CI change or contributor policy in its own commit. +- Inspect each staged diff; never commit generated files, local configuration, + logs, credentials, or build products. Do not push unless requested.