DECISIONS.md as short as a rebuild needs; SKILL.md proven as written

packages/agent-data/DECISIONS.md

@@ -2,83 +2,75 @@ Non-obvious decisions only, grouped by business-logic flow. Anything not listed
 to the implementer's judgment. Flag conflicts instead of silently deviating.
 
 ## The package
-- A **library, not a skill**: no `SKILL.md` and no command, because only code uses it.
-  Skills import this library; they never import each other.
-- Package name = branch name: `@gemstack/agent-data` is the library for the `agent-data`
-  branch, but no function here hardcodes it: every one that touches a branch takes the
-  branch as an argument.
-- `.branches/` holds a project's persistent checkouts, one directory per branch: the
-  agents' own, made by other packages, and the data branch's, made here. The directory
-  name is exported; the branch a caller names is checked out at `.branches/<branch>`. It
-  starts with a dot so a `*` glob skips it: every checkout inside is a full copy of the
-  project, and a type-checker or test runner that descends into N copies runs N times.
-  Hidden through `info/exclude`, never a committed `.gitignore`: the library must not
-  touch the project's tracked files. Writing the rule is best-effort: a git dir it cannot
-  write to still leaves the checkout standing. The rule goes in the common git dir: a
-  per-worktree `info/exclude` is never read, and one line there covers every checkout. A
-  checkout deleted by hand leaves git's registration behind: prune before adding, or the
-  add fails on the stale registration.
-- Every git call has a time budget by subcommand: a read 10s, network and `worktree add`
-  120s, everything else 30s. `worktree` goes by its second word (`add` slow, `list` a
-  read, the rest a write) and `branch` by its own words (bare or with a listing flag it
-  reads; `-D`, `-m` or a new branch name writes); an unlisted subcommand pays the write
-  budget rather than risk cutting a write short. A killed `push` may have half landed, so
-  a timeout is reported as a timeout, never as a rejected push.
+- A **library, not a skill**: no `SKILL.md`, no command. Skills import it; they never import
+  each other.
+- Named for the `agent-data` branch, but no function hardcodes it: every one that touches a
+  branch takes it as an argument.
+- `.branches/<branch>` holds a project's persistent checkouts, one per branch: the agents'
+  own (made by other packages) and the data branch's (made here). The directory name is
+  exported. Dotted so a `*` glob skips it: each checkout is a full copy, so a tool that
+  descends does N times the work.
+- Hidden through the common git dir's `info/exclude`, never a committed `.gitignore`: the
+  library must not touch tracked files; a per-worktree `info/exclude` is never read, and
+  one line there, written once, covers every checkout. Best-effort: the checkout stands
+  even when the rule could not be written. Prune before adding: a hand-deleted checkout
+  leaves a registration that fails the add.
+- Every git call has a time budget: a listed read 10s, network and `worktree add` 120s,
+  other writes 30s. `worktree` goes by its second word (`add` slow, `list` a read, the rest
+  a write), `branch` by its flags (bare or a listing flag reads; `-D`, `-m` or a new name
+  writes); an unlisted subcommand gets the write budget, so a write is never cut short at
+  the read budget. A killed `push` may have half landed, so a git call that outruns its
+  budget fails as a timeout, its own error kind, never as a plain failure. git's output
+  buffer is 16 MB (a large checkout's file listing); an overrun is not a timeout.
 
 ## The branch
-- A branch of the project's repository holds the agents' data — tickets, the queue — like
-  `gh-pages` holds a site; code branches hold only code. Pushed by every write, and pulled
-  independently of any write, so a machine that writes nothing still ends up with what the
-  others pushed.
-- One branch for all skills, each with its own folder or file on it. Not one branch per
-  skill: every extra branch would need its own checkout on disk and its own sync failure
-  to report.
-- A branch missing locally is adopted from origin's copy; one that exists nowhere is
-  created as an orphan branch, empty and with no parent commit, so no code commit is ever
-  in its history.
-- The branch name is written once, in `names`, as `DATA_BRANCH`; every other package
-  imports it. `names` is its own entry point and has no node imports, so browser-side code
-  can import it without the git code.
-- Read from anywhere in the repository, no checkout needed: a file comes from the
-  persistent checkout under `.branches/` when there is one, else the local branch, else
-  origin's copy; a directory listing always comes off a ref. A read can ask for a fresh
-  copy: fetch, then read origin's ref instead of the checkout, for a reader whose checkout
-  may trail what others pushed. A one-shot command opens the branch once: one fetch, then
-  every read off that one ref (origin's copy, or the local branch when origin has none);
-  it reads origin's copy because its own writes go straight to the remote and never move
-  the local branch. A read never fails: a missing file, a missing branch and a git that
-  could not run all read as absent, so a caller cannot tell an unreachable store from an
-  empty one.
+- A branch of the project's repository holds the agents' data (tickets, the queue) the way
+  `gh-pages` holds a site; code branches hold only code. Every write that changes something
+  pushes, and a pull is a cycle of its own, so a machine that writes nothing still gets what
+  the others pushed.
+- One branch for all skills, each with its own folder or file. Not one per skill: every
+  extra branch needs its own checkout and its own sync failure to report.
+- Missing locally, it is adopted from origin's copy; missing there too, it is born an orphan
+  branch, so no code commit is ever in its history.
+- The name is written once, in `names`, as `DATA_BRANCH`, and imported everywhere else.
+  `names` is its own entry point with no node imports, so browser code can import it.
+- A read works from anywhere in the repository, an agent's worktree included: the checkout
+  is looked for beside the real `.git`. A file is looked for in that checkout when there is
+  one, then on the local branch, then on origin's copy; a directory listing always comes off
+  a ref. A read can ask for a fresh copy: fetch, then origin's ref instead of the checkout,
+  for a reader whose checkout may trail. A one-shot command opens the branch once: one fetch
+  when there is an origin, every read off origin's copy (the local branch when there is no
+  `origin/<branch>`), because its own writes go straight to the remote and never move the
+  local branch. A read never fails: a missing file, a missing branch and a git that could
+  not run all read as absent.
 
 ## Flow: a write
 Fetch what others pushed → make the change → commit → push.
 
 - Two writers. A long-lived process (a daemon) writes in its own checkout,
-  `.branches/<branch>`, one write at a time; the pull takes its turn in the same queue: it
-  is that same cycle with an empty change. A command an agent runs writes in a throwaway
-  worktree outside the project, at the remote's tip (parentless when origin has no such
-  branch yet), pushes, and deletes it whether or not the push landed; it never touches the
-  process's checkout: that checkout's next write commits everything it finds there, and a
-  failed write resets it, so a second writer's files would land in the wrong commit or be
-  wiped. A command's write races at the push like the process's, twice in all; a push that
-  still fails throws, and nothing is left behind to retry. The process's write never
-  throws: its callers are background ticks.
-- A write is a re-runnable function, not a finished commit: a lost race just runs it again
-  on the new files. The commit message is the caller's too: fixed, or a function run after
-  the change, since a write that batches several edits only knows what it did once it is
-  done. The lost attempt's commit is wound back first, so the change lands once and not
-  twice. Never a force push. After two failed pushes the write reports the failure and the
-  commit stays local in the process's checkout. The next write or pull rebases it onto
-  what the remote has by then and pushes the stranded commit together with the new one;
-  when the rebase conflicts, the checkout is reset to origin's tip and every unpushed
-  commit goes with it: the remote wins, only the current change runs again, and what was
-  dropped is never reported.
-- An op is handed a directory and writes into it as it likes; `BranchFileFs` is the file
-  seam an op can take instead of the disk (the type and its node implementation ship here,
-  the op does the injecting, so it is testable off disk), and it creates parent
-  directories: git keeps no empty directory, so a skill's folder is gone with its last
-  file and absent on a branch just born.
-- The remote is always `origin`, and a repository without one counts as remote-less
-  whatever other remotes it has: the process's write commits locally and reports no error;
-  a command's write refuses, as an outcome it returns, not as a throw; the pull reports an
-  error: it has no remote to converge with.
+  `.branches/<branch>`, one write at a time per repository and branch, an in-memory lock:
+  two processes on one clone are not guarded. The pull is that same cycle with an empty
+  change, behind the same lock. A command an agent runs writes in a throwaway worktree
+  outside the project, at the remote's tip (parentless when origin has no such branch),
+  pushes, and deletes it whether or not the push landed. It never touches the process's
+  checkout: that checkout's next write commits everything it finds, and a failed write
+  resets it, new files included. Both try the push twice; the command's write then throws
+  with nothing left to retry, the process's never throws: its callers are background
+  ticks.
+- A write is a re-runnable function, not a finished commit: a lost race winds the attempt's
+  commit back and runs the function again on the new files, so the change lands once. The
+  message is the caller's: fixed, or a function run after the change, since a batch only
+  knows what it did once done; the library's own are `create the <branch> branch` for the
+  birth and `sync` for the pull. Never a force push. After two failed pushes the process's
+  write reports the failure and the commit stays local in its checkout; the next write or
+  pull rebases it onto the remote and pushes it with the new one. When that rebase conflicts
+  the checkout is reset to origin's tip: the remote wins, every unpushed commit is dropped
+  unreported, only the current change runs again.
+- An op is handed a directory and writes into it. `BranchFileFs` is the file seam an op can
+  take instead of the disk, for tests (type and node implementation ship here, the op
+  injects it); it creates parent directories: git keeps no empty directory, so a skill's
+  folder vanishes with its last file and is absent on a new branch.
+- The remote is always `origin`; a repository without one is remote-less whatever other
+  remotes it has. Then the process's write commits locally and reports no error, a command's
+  write refuses (an outcome, not a throw), and the pull reports an error: nothing to
+  converge with.