# csv2journal Development Process This document defines how work is done in this repository. It binds both human contributors and AI agents. [CLAUDE.md](../CLAUDE.md) points here rather than duplicating it. The product specification lives in [REQUIREMENTS.md](REQUIREMENTS.md); the technical design in [DESIGN_M1.md](DESIGN_M1.md); the build order in [PLAN_M1.md](PLAN_M1.md). **This document contains no product requirements** and none of those documents contain process rules. The shape of the code itself — locality, duplication, the standard interfaces — is [STYLE.md](STYLE.md). This document says how work is done; that one says what the result has to look like. ## 1. Primary Constraint: Maintainable Without An LLM The author must be able to maintain this project unaided. Every rule below serves that goal: one person, returning after a month away, can read the code, understand why a commit exists, and change it safely — without asking a model to explain it back to them. Zig is a deliberate preference, not a neutral default. Idiomatic Zig, `comptime` included, is welcome where it is the natural expression. What is excluded is code the author has not read and understood, whoever or whatever produced it. - No source file exceeds ~400 lines of **implementation**. Test blocks do not count toward it: they are read one at a time rather than held in the head at once, and Zig keeps them beside the code they justify. Put them below a `// -- tests` divider so the boundary is mechanical: ```sh awk '/^\/\/ -- tests/{print NR-1; found=1; exit} END{if(!found) print NR}' src/foo.zig ``` A file approaching the limit is split along a seam already present in the requirements. - No function exceeds ~60 lines. - Abstraction is justified by a second caller, not by anticipation of one. - Code lives with the data it operates on, and nothing is written twice. [STYLE.md](STYLE.md) is the long form, written from the refactorings the author had to apply by hand after milestone one. - A module that cannot be unit-tested without touching the filesystem is a design smell, except for `discover.zig`, `snapshot.zig`, `finalize.zig`, and `ui/server.zig`, which exist to do I/O. ### When an agent writes the code A commit produced by an LLM is not done when the tests pass. It is done when the author has read it and could have written it themselves. If a change is too large or too intricate to review that way, it is too large: split it, or replace it with something simpler that passes the same tests. This is the point of the small-commit rule in §3. A commit that closes one requirement ID and carries the test that justifies it is reviewable in a sitting. A commit that lands a whole module is not, however green the suite is. ## 2. Test-Driven Development Tests are written **before** the code they justify. The loop: 1. Pick the next requirement ID from the active task file (§5). 2. Write a test named for that ID. Run it. **Watch it fail.** A test that has never failed has not been shown to test anything. 3. Write the smallest implementation that makes it pass. 4. Run the whole suite, then `nix flake check` (§4). Refactor only while green. 5. Commit test and implementation together (§3). Test naming is mechanical, so coverage can be checked by script: ```zig test "M1-CSV-003: crlf mode rejects a lone LF inside a quoted field" { ... } ``` Every normative requirement ID in REQUIREMENTS.md must eventually appear in at least one test name. Acceptance scenarios `M1-AC-001` … `M1-AC-021` are end-to-end tests. The cross-cutting ones live in `src/acceptance.zig`; the rest sit with the module whose behaviour they exercise, so that a scenario about discovery is next to discovery. An ID may appear in both. ### Mutation testing A green suite says nothing about whether its assertions bite. Once a module's tests pass, **break the implementation on purpose and check that a test notices**: 1. Copy the file aside. 2. Delete or invert one sharp rule — a bounds check, a comparison direction, a guard, a sort order. 3. Run `zig build test` — or `zig build test-ui` for the interface's JavaScript. It must fail. A mutant that *survives* means no test covers that rule. 4. Restore, and repeat for the next rule. A surviving mutant has exactly two honest answers. Either add the missing test, or **delete the logic** — if no test can tell the difference, the code may be unreachable. Both happened during milestone one: mutation testing found two tests that passed for the wrong reason, a `save()` that never recomputed whether finalization was available, and a guard in `finalizable()` that no input could distinguish, which was removed rather than kept. Two traps, both hit the hard way: - **Restore from the file you mutated, not from a copy made earlier.** A stale copy silently drops tests written since it was taken, and the suite goes green having lost them. - **Mutate implementation, never a test.** Deleting an assertion always "survives", because the assertion *is* the test. It proves nothing. This is the practical form of §1: a commit produced by an LLM is not done when the tests pass. ### Discipline - Do not write implementation code that no failing test demanded. - Do not weaken a test to make it pass. If a requirement is wrong, raise it in DESIGN_M1.md §11 and stop — do not silently reinterpret it. - A skipped or commented-out test is a broken build, not a TODO. ## 3. Version Control: jj This repository uses [jj](https://jj-vcs.github.io/) colocated over git. jj has **no staging area** and tracks the working copy automatically, so commits are shaped after the fact rather than staged beforehand. ### The cycle ```sh jj new -m "M1-CSV-003: reject a lone CR in lf mode" # start a new change # write the failing test, watch it fail # implement until green zig build test jj describe -m "$(cat <<'MSG' M1-CSV-003: reject a lone CR in lf mode Prior to this change, ... This change ... MSG )" jj new # begin the next change ``` Useful when a change came out mixed: | Command | Use | | --- | --- | | `jj split` | one change contains two logical concerns | | `jj squash` | fold the working copy into its parent | | `jj describe` | rewrite the current change's message | | `jj diff` / `jj show` | review before describing | | `jj log` | see the shape of history | An agent never pushes: no `jj git push`, no `git push`, not even when asked. Pushing is outward-facing, and the author does it. ### What one commit is **One commit = the failing test plus the implementation that makes it pass.** Every commit in history builds and passes both `zig build test` and `nix flake check` (§4). The red/green cycle happens in the working copy; it is not preserved as separate commits, because a committed red state breaks `jj bisect` and makes review noisier. Commit policy, adapted from [codex-committorum/commit_policy](https://github.com/JoBuRo/codex-committorum/tree/main/skills/commit_policy) and restated here in our own words: - One logical concern per commit. - Keep tests with the code they justify. - Do not mix behavior changes, refactors, and incidental cleanup. - Prefer several small commits over one mixed commit. - A commit that renames, changes logic, and reformats at once should be split unless there is a stated reason not to. ### Commit message The code shows *what* changed. The message explains *why the change exists*. ``` : Prior to this change, . This change . ``` The two body paragraphs are separated by a blank line. Drop the `:` prefix for commits that close no requirement, such as documentation. The summary starts with a capital letter: `Correct the module map`, `M1-CSV-001: Reject …`. **No trailers.** Commit messages carry no `Co-Authored-By`, `Signed-off-by`, tool attribution, or generation notice, whoever or whatever wrote the change. ### Keep it short A title, a sentence or two of "prior to this change", the same of "this change", and a short paragraph only for something genuinely surprising. Around fifteen lines is plenty. Reasoning a reader needs while *reading the code* belongs in a comment beside it. Reasoning about the design belongs in DESIGN_M1.md. A message that repeats either makes the history harder to scan rather than easier, and the history is read far more often than it is written. Before describing a change, ask: 1. Does the message explain why, not merely what? 2. Is this one logical concern? 3. Should preparatory refactoring be split into its own commit? 4. Do the tests in this commit justify exactly the code in this commit? 5. Do `zig build test` and `nix flake check` both pass at this commit? ### Finding out why code is the way it is Before changing code whose reason is not obvious, read the commit that wrote it. Each commit carries the test that justifies it and a message saying why, so the history usually answers the question. ```sh jj file annotate src/foo.zig # the change that last touched each line jj show # its message, test and implementation together jj log -r 'files("src/foo.zig")' # every change to the file jj file annotate -r '-' src/foo.zig # look past a move or refactor ``` A move or rename (`refa: …`) owns every line it touched. Annotate from its parent to reach the commit that introduced the logic. Follow any requirement ID or decision number into [REQUIREMENTS.md](REQUIREMENTS.md), [DESIGN_M1.md](DESIGN_M1.md) or `docs/adr/`. If none of these gives a reason, say so instead of inventing one. ## 4. Verification Two commands, and both must pass before a change is described: ```sh zig build test # fast; run constantly during the red/green cycle nix flake check # slower; run before committing ``` They do not overlap. `zig build test` never analyses `main()`, because nothing in the test binary references it — a broken entry point compiles clean and the suite stays green. `checks.build` in the flake links the executable and catches exactly that. `nix flake check` also proves the build works from the pinned toolchain and dependency set rather than from whatever happens to sit in the local Zig cache, which is the only way the Nix-supplied libyaml path (see nix/package.nix) is exercised. `nix flake check` also runs `zig build lint` (zlinter, configured in `build.zig`). Run that one directly while working: it is fast, and it mechanises much of [STYLE.md](STYLE.md), so finding out from the flake check is finding out late. The interface's JavaScript and CSS have their own steps, `zig build lint-ui` and `zig build test-ui`, which the flake check runs as well. They call `deno` and `biome`, which the dev shell provides (`nix develop`). Run `zig build test-ui` in the red/green cycle whenever the change touches `src/ui/*.js`. A change that passes `zig build test` alone is not verified. ### Stage new files before checking `nix flake check` reads the **git** tree. This repository is jj colocated, so a file jj already tracks stays invisible to Nix until git knows about it too, and `nix/package.nix` selects its source from that tree. An unstaged new file does not simply fail the check. It can make the check **pass wrongly**, because Nix builds the previous state and never sees the file at all. Before checking: ```sh git add nix flake check ``` Modifications to already-tracked files are picked up without staging; only additions are affected. ### Reference every new module from a test block Zig collects tests only from files reachable through a `test` block. A `pub const` import does not reach them. A module whose tests are never collected does not fail: the suite passes, silently reporting only the tests it did find. `src/root.zig` carries a block listing every module. Extend it whenever you add one: ```zig test { _ = diag; _ = decimal; } ``` Then confirm the count actually moved: ```sh zig build test --summary all # "Build Summary: N/N tests passed" ``` This matters more than it first appears. Functions taking `comptime` or `anytype` parameters are analysed only at their call sites, so when the sole call sites are uncollected tests, the function is never compiled at all. src/diag.zig was committed in T02 containing a `Diagnostic` built without its required `message` field — code that could not compile — and the suite stayed green because nothing referenced it. Adding the test block turned 6 passing tests into 16, and the first thing they reported was that failure. ### Before the first build in a fresh clone Write `.gitignore` **before** running `zig build` for the first time. jj snapshots the working copy automatically and has no staging area, so anything a build drops on disk — `.zig-cache/`, `zig-pkg/`, `zig-out/`, `result` — is tracked the moment it appears, and adding it to `.gitignore` afterwards does not untrack it. Recovering means `jj file untrack`, which is avoidable noise. ## 5. Task Files Work is tracked in `docs/tasks/`, one file per task, indexed by the milestone's build plan. Each file opens with: ``` # T02: decimal status: todo | done closes: M1-CSV-018, M1-CSV-019, M1-RULE-016, M1-HIST-008 depends: T01 ``` A task is `done` only when every requirement ID it claims has a passing test named for it, or — for a task that closes no requirement — when its own `## Done when` is satisfied. ### Moving `status` is its own commit **A task's working commits touch the code. Setting its `status` to `done` is a separate commit afterwards, and touches nothing else.** The reason is portability. A commit that fixes something should be able to move to another branch by itself, and a commit that mentions `docs/tasks/` cannot: whoever takes it inherits a file that means nothing where they are, and has to `jj split` it back out. Mainline does not need to know this directory exists. There is no `doing`. Under jj the working copy *is* a commit, so a status set on the way in would be snapshotted into the very commit that is supposed to carry only code — the thing the rule above exists to prevent. A task is `todo` until the work is committed, then `done`. DESIGN_M1.md's traceability matrix is authoritative for which module owns which requirement. Task files reference IDs; they do not redefine ownership. **Delete a milestone's task files once every task in it is done.** By then their content lives in the tests, the code and the design document, and what is left reads like a specification while being a historical plan — a finished task file still suggesting an approach that was later measured and rejected is a trap for whoever reads it next. Milestone one's were removed this way; `jj` history keeps them.