csv2journal Development Process #
This document defines how work is done in this repository. It binds both human contributors and AI agents. CLAUDE.md points here rather than duplicating it.
The product specification lives in REQUIREMENTS.md; the technical design in DESIGN_M1.md; the build order in 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. 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
// -- testsdivider so the boundary is mechanical:awk '/^\/\/ -- tests/{print NR-1; found=1; exit} END{if(!found) print NR}' src/foo.zigA 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 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, andui/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:
- Pick the next requirement ID from the active task file (§5).
- 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.
- Write the smallest implementation that makes it pass.
- Run the whole suite, then
nix flake check(§4). Refactor only while green. - Commit test and implementation together (§3).
Test naming is mechanical, so coverage can be checked by script:
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:
- Copy the file aside.
- Delete or invert one sharp rule — a bounds check, a comparison direction, a guard, a sort order.
- Run
zig build test— orzig build test-uifor the interface's JavaScript. It must fail. A mutant that survives means no test covers that rule. - 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 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 #
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 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.
<REQ-ID>: <imperative summary>
Prior to this change, <the problem or missing behavior>.
This change <how it addresses that>.
The two body paragraphs are separated by a blank line. Drop the <REQ-ID>: 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:
- Does the message explain why, not merely what?
- Is this one logical concern?
- Should preparatory refactoring be split into its own commit?
- Do the tests in this commit justify exactly the code in this commit?
- Do
zig build testandnix flake checkboth 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.
jj file annotate src/foo.zig # the change that last touched each line
jj show <change> # its message, test and implementation together
jj log -r 'files("src/foo.zig")' # every change to the file
jj file annotate -r '<change>-' 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, 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:
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, 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:
git add <new files>
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:
test {
_ = diag;
_ = decimal;
}
Then confirm the count actually moved:
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.