hermes
a350afc053
The readme served two roles: design-decision source of truth and
work-status tracker. The status section grew into a plan the
orchestrator must navigate, so it moves to its own file with task
IDs, dependency edges, statuses, and per-item acceptance criteria.
readme.md remains authoritative for decisions (stack, formats,
workflow); workflow step 7 and AGENTS.md pointers now name
roadmap.md for status. Cross-references verified.
Also records: stale feature/epsilon-parser branch pointer (676e55e,
2 behind main) deleted locally; recreate from main when B1 starts.
68 lines
3.1 KiB
Markdown
68 lines
3.1 KiB
Markdown
# AGENTS.md — working rules for coding agents on RustyRPN
|
|
|
|
readme.md is the single source of truth for design decisions. The
|
|
roadmap lives in Documentation/roadmap.md.
|
|
Read at minimum these before starting work:
|
|
|
|
- readme.md §Workflow — the TDD loop you are expected to follow
|
|
- readme.md §General guidelines for AI — hard prohibitions
|
|
- readme.md §Data formats — input formats, edge cases, and where test
|
|
fixtures live
|
|
- Documentation/roadmap.md — what is green, red, or unstarted
|
|
|
|
## Environment
|
|
|
|
- Rust stable (edition 2024, MSRV 1.85) via rustup; on this machine the
|
|
shims are at `/opt/homebrew/opt/rustup/bin` (in PATH via ~/.zprofile).
|
|
- All cargo commands run from `Application/`:
|
|
`cargo test`, `cargo fmt --check`, `cargo clippy`.
|
|
- Workspace members: `src/core` (rpn-core, domain logic),
|
|
`src/cli` (rpn-cli, binary `rpnc`). `src/server` and `src/web` are
|
|
planned but not scaffolded yet.
|
|
|
|
## Current state (verify against Documentation/roadmap.md; update both when it changes)
|
|
|
|
- core/config: implemented, tests green.
|
|
- core/db: tests committed and RED (they reference functions that do
|
|
not exist yet — the crate does not compile its test target). The first
|
|
task is the minimal implementation to turn them green. Do not weaken or
|
|
rewrite these tests to make them pass; they encode agreed behaviour.
|
|
- cli: `fn main() {}`. Command surface specified in Documentation/cli.md.
|
|
- feature/epsilon-parser: does not exist yet. Create it from `main`
|
|
when parser work starts (a stale early pointer was deleted
|
|
2026-10-08). Workflow step 2 (spec + test checklist agreed with the
|
|
maintainer) must complete before any failing test is written.
|
|
|
|
## Test data
|
|
|
|
- Real samples: `Application/data/test_input/` — gitignored, never
|
|
committed, never embed their values in test files or fixtures output.
|
|
- Committed sanitized fixtures: `Application/data/fixtures/`
|
|
(epsilon / tsdrms / subfranchise). Parser tests should use these.
|
|
Regenerate with `python3 Application/scripts/sanitize_samples.py`;
|
|
after any change to fixtures run
|
|
`python3 Application/scripts/check_fixture_leaks.py` and require exit 0.
|
|
- `Documentation/schema.sql` is the v1 domain schema; it is also the
|
|
embedded migration (test-asserted in core/db).
|
|
|
|
## Git rules
|
|
|
|
- Work on a named feature branch; commit per passing test (workflow step
|
|
5.3). Commit messages are the project's code documentation: format
|
|
`area: imperative summary`, body explaining *why*.
|
|
- Never commit or push to `main` without the maintainer's explicit
|
|
approval. Never rewrite history.
|
|
- Never commit: config files (except config.template.toml), anything under
|
|
data/ except data/fixtures/, secrets, real customer data.
|
|
|
|
## Definition of done for a task
|
|
|
|
1. `cargo test` green (all crates), `cargo fmt --check` and
|
|
`cargo clippy` clean for files you touched.
|
|
2. Every checklist item from the task's spec verified — by a test or by
|
|
a command you actually ran, not by inspection alone.
|
|
3. Documentation/roadmap.md updated in the same branch (and readme.md
|
|
if a design decision changed).
|
|
4. A short summary for the maintainer: what changed, what is still red,
|
|
suggested next step.
|