Move AGENTS.md sections into docs folder
This commit is contained in:
@@ -0,0 +1,73 @@
|
||||
# Boards on Disk
|
||||
|
||||
The two board layouts, the pointer file, and how a board is found from a working directory.
|
||||
|
||||
## Shared Boards
|
||||
- **A project's board is on one of two layouts, and `src/board.rs` is the whole of the
|
||||
second one.** The local layout is the `.worklane` directory a project has always had.
|
||||
The shared layout answers `.worklane` being gitignored and not a git repo so a clone
|
||||
elsewhere has no board: the project commits a `.worklane.toml` naming its board by
|
||||
uuid, one boards repo is cloned once per machine, and `.worklane` in the project
|
||||
becomes a *symlink* into it. The symlink is the point: with no `.worklane` directory
|
||||
`cat .worklane/backlog/*.md` and `ls .worklane/reviewing` would stop working, and that
|
||||
is the belief the whole file format exists to serve. Because the link is transparent,
|
||||
`find_worklane_dir` gains no resolution code at all (c6a61b4 AC 14).
|
||||
- **The machine config lives at `$XDG_CONFIG_HOME/worklane/config.toml`** (default
|
||||
`~/.config`, empty counts as unset). It carries a `[boards]` section holding the *url*
|
||||
of the boards repo and an optional `dir` overriding where the boards directory sits —
|
||||
the config is *this machine's* answer, and the pointer carries no server address, so a
|
||||
client repo never holds an internal hostname. The boards directory itself defaults to
|
||||
`$XDG_DATA_HOME/worklane/boards` (`~/.local/share` without it).
|
||||
- **The pointer is `.worklane.toml`, committed at the project root:**
|
||||
`[worklane] board = "<uuid>"`, and nothing else. Read and written by `read_pointer` /
|
||||
`write_pointer`. `write_pointer` leaves a pointer that already names the same board
|
||||
alone — it is a committed file and rewriting it writes nothing new, which is what keeps
|
||||
"init symlinks it and creates nothing" true for a fresh clone.
|
||||
- **A board directory is `<uuid>_<slug>`, named after the ticket files.** The slug is
|
||||
`util::slug` of the project's directory name, and resolution (`resolve_board`) is a
|
||||
uuid prefix match, the bargain the ticket filenames already make: the directory stays
|
||||
readable to `ls`, identity is stable, and renaming a board breaks no committed pointer.
|
||||
- **The decision table is `decide_init`, one match.** The reason it is a table rather
|
||||
than a fallback is that no branch may fall through into creating a board, so each row
|
||||
returns its own outcome. The rows:
|
||||
- no pointer, no `[boards]` config → local `.worklane`, exactly as `init` always made
|
||||
it (AC 12);
|
||||
- no pointer, config present → create the board, write the pointer, symlink `.worklane`
|
||||
to it (AC 4);
|
||||
- pointer present, board found → symlink it and create nothing (AC 5);
|
||||
- pointer present, board absent → refuse. A committed pointer is proof the board exists
|
||||
somewhere, so a missing board is an unsynced machine, and creating a second board
|
||||
there produces two boards with one name and a manual merge — the worst outcome in the
|
||||
design. The refusal says so and names `init --create` as the only way to make one
|
||||
(AC 6/7). The fetch-and-look-again half of the ticket is deferred: nothing pulls the
|
||||
boards repo yet, and the refusal names it rather than doing it. **`--create` is the
|
||||
`create` field on `Command::Init`**, the escape hatch under that row;
|
||||
- the boards directory itself missing → a distinct refusal saying the boards repo is
|
||||
not cloned here (AC 8);
|
||||
- the correct symlink already in place → no change, nothing written (AC 9);
|
||||
- a symlink to a *different* board → refuse rather than repoint it: changing what a
|
||||
project is on without asking is how two machines come to disagree about the work
|
||||
(AC 10);
|
||||
- a symlink that dangles → refuse rather than replace it without asking;
|
||||
- a real `.worklane` directory under a pointer → refuse and name the adopt path
|
||||
(aa80db4), never walk over it (AC 11).
|
||||
- **The three symlink states are told apart by `classify_worklane`:** `Absent`,
|
||||
`RealDir`, `Symlink`, `Dangling` and `NotADirectory`. The `Symlink` comparison is
|
||||
canonicalized, the `Dangling` one is lexical (a dangling link cannot be canonicalized)
|
||||
and checks for the relative spelling this tool writes or the absolute board path.
|
||||
- **The symlink target is relative** to the link's own parent, so it uses no home
|
||||
directory path and the link is portable in that limited sense; an absolute target
|
||||
appearing anywhere is how a home directory leaks into a write. Because a relative
|
||||
target depends on how deep a repo sits, `init` still runs once per project per machine,
|
||||
which is the price of transparent access.
|
||||
- **Everything under `.worklane` is layout-agnostic.** `create_board_contents` makes the
|
||||
same status directories, `campaigns/` and `tags.md` for a local and a shared board,
|
||||
and every reader below `find_worklane_dir` works through the link unchanged.
|
||||
|
||||
## Finding the Board
|
||||
- **`find_worklane_dir` classifies the entry before it follows it.** `exists()` follows a link, so a `.worklane` that was a dangling symlink answered the same as no `.worklane` at all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently. `classify` reads `symlink_metadata` first and answers one of four, `Absent`, `Board`, `Dangling` or `NotADirectory`, and **`Absent` is the only one the walk carries on from**. A `.worklane` that is there but unusable is this project's board and is reported, not handed upward
|
||||
- Anything other than `NotFound` from `symlink_metadata` is an error rather than an `Absent`. Reading a filesystem that could not answer as nothing-there is how the walk-past worked in the first place
|
||||
- The dangling failure **names the target and says the boards repo may not be cloned**, and deliberately does not say to run `worklane init`. Once the boards live outside the project a dangling link is an ordinary state, what you have before the boards repo is cloned and after a board directory is renamed, so "no board found, run init" points at the wrong problem
|
||||
- **A link that resolves is indistinguishable from a real directory, and what comes back is the link rather than its target.** `.worklane/backlog/*.md` has to read the same either way and nothing downstream learns whether the board is local, which is the property the shared-boards layout rests on
|
||||
- A regular file at that path is an error as well. It is a plausible future pointer form, and reading it as one is that change's decision to make; stepping over it and writing to a board above is the one answer that is wrong today
|
||||
|
||||
Reference in New Issue
Block a user