Tickets on the agent-data branch, the holder is AGENT_ID, DECISIONS.md read as a stranger

.the-framework/LAYOUT

@@ -1,5 +1,5 @@
 framework-dir: .the-framework
-tickets-branch: tickets
+data-branch: agent-data
 logs-branch: agents-logs
 archive-dir: agents
 events-file: events.jsonl

packages/agent-data/DECISIONS.md

@@ -2,40 +2,83 @@ 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**. A skill is a `SKILL.md` an agent reads, plus a command it
-  runs; this package has neither, because only code uses it. Skills never import each
-  other's code; this library is what every skill imports.
-- Package name = branch name: `@gemstack/agent-data` manages the `agent-data` branch, so it
-  is called the same.
-- `.branches/` holds every extra checkout of the project — each agent's, and the data
-  branch's — so its name is defined here. It starts with a dot to keep tools' `*` patterns
-  out of it: every checkout inside is a full working copy of the project. Hidden through
-  git's own exclude file, never a committed `.gitignore`: the project's files are not the
-  library's to change.
+- 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.
 
 ## 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 and pulled on every
-  change, so every machine sees the same files.
+  `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 that does not exist yet is born empty, with no parent commit, so no code commit
-  is ever in its history.
-- The branch name is written once, here, as `DATA_BRANCH`; every other package imports it.
+  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.
 
 ## Flow: a write
-Fetch what others pushed → make the change → commit → push. If the push is rejected
-because someone pushed in between, start over on top of their changes.
+Fetch what others pushed → make the change → commit → push.
 
-- A write is handed over as a small function ("add this line"), not as a finished
-  commit, so starting over is just running it again on the new files. Never a force
-  push. After two failed pushes the write reports the failure and the commit stays local.
-  The next write's fetch carries it when it still applies on top of the remote, and drops
-  it when it does not: the remote wins, only the current change runs again, and nobody is
-  told.
-- Two writers. A long-running process, the program that starts agents, writes in its own
-  checkout, `.branches/agent-data`, one write at a time. A command an agent runs writes in
-  a temporary copy of the branch, pushes, and deletes the copy; it never touches the
-  process's checkout, whose next write commits everything it finds there and resets it
-  when the write fails. A command's write that cannot be pushed fails; nothing of it waits.
+- 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.

packages/agent-data/SPEC.md

@@ -1,13 +1,13 @@
-A branch of a project's repository used as a file store, as an npm library: the one branch every skill a coding agent uses keeps its files on — `agent-data` — checked out once under the project's `.branches/`, written through one cycle every write goes through (sync with origin, apply the change, commit, push, and re-apply the change when the push loses a race), written one-shot from any clone, pulled eagerly, and readable from anywhere in the repository without holding a copy. The git runner and the exclude rule that machinery is built on ship with it, and so do the two names every consumer needs: the checkouts directory and the data branch.
+A branch of a project's repository used as a file store, as an npm library: `agent-data`, the one branch every skill a coding agent uses keeps its files on, checked out once under the project's `.branches/`. Every write goes through one cycle — sync with origin, apply the change, commit, push, re-apply when the push loses a race — from a long-lived process's checkout, or one-shot from any clone. It ships the git runner and the exclude rule that machinery is built on, plus the two names every consumer needs: the checkouts directory and the data branch.
 
 A library, not a skill: it is read by code, never by an agent, so it ships no `SKILL.md` and no command. It knows git and the filesystem, nothing else — the caller names the branch and decides what the files mean. Every skill that keeps files on the branch depends on it; no skill depends on another.
 
 ## Business logic — TL;DR
 
 - **The two names** (`names`) - `.branches`, the directory every checkout of a project lives under, and `agent-data`, the shared data branch: defined once, importable without pulling in git.
-- **Running git** (`git`) - one runner with a time budget per subcommand, a timeout told apart from a git failure, the checkout a directory is in, and a push whose failure is git's own reason.
+- **Running git** (`git`) - one runner with a time budget per subcommand, a timeout told apart from a git failure, whether a directory is in a working tree and which checkout it is in, and a push whose failure is git's own reason.
 - **Hidden from the project's git** (`git-exclude`) - a rule in git's own exclude list, never a tracked file, covering every worktree of the repository at once.
-- **A branch used as a file store** (`file-branch`) - a branch the caller names, holding files nobody edits in a working tree: born parentless or adopted from origin, checked out under `.branches/` for a long-lived process that funnels every write through one serialized cycle, written one-shot from any clone through a throwaway worktree, pulled eagerly, and readable from anywhere in the repository without holding a copy.
+- **A branch used as a file store** (`file-branch`) - a branch the caller names, holding files nobody edits in a working tree: born parentless or adopted from origin, written through one serialized cycle from a long-lived process's checkout or one-shot from any clone, readable from anywhere without holding a copy.
 - **The entry point** (`index`) - everything above in one place for a caller to import.
 
 ## Before modifying/creating SPEC.md files

packages/agent-data/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gemstack/agent-data",
   "version": "0.0.1",
-  "description": "A branch of the project's repository used as a file store for coding-agent skills: the agent-data branch, checked out under .branches/, every write one sync-commit-push cycle that re-applies on a lost race — from a long-lived process through its checkout, or one-shot from any clone.",
+  "description": "A branch of the project's repository used as a file store for coding-agent skills. Checked out under .branches/; every write is one sync-commit-push cycle that re-applies when it loses a race, from a long-lived process or one-shot from any clone.",
   "license": "MIT",
   "repository": {
     "type": "git",

packages/agent-data/src/file-branch.SPEC.md

@@ -26,7 +26,7 @@ A branch used as a file store: a branch of the project's repository holding file
 - **Conflicts resolve toward origin** - the checkout is nobody's working tree, so origin always wins and the local intent is re-applied on top.
 - **A failed operation leaves nothing half-written** - the checkout is put back to its committed state before the failure is reported.
 - **The eager pull** - the same cycle applying no change: it converges this machine with origin, pushes anything a failed cycle stranded, and creates the checkout if there is none.
-- **A repository with no remote** - fine for a funneled write, an error for the pull, a refusal for a detached write.
+- **A repository with no remote** - no `origin`, whatever other remotes it has: fine for a funneled write, an error for the pull, a refusal for a detached write.
 - **Reading from anywhere in the repository** - the persistent checkout when this location has one, else the branch's ref, else origin's copy of it, so a reader holds no copy of the files; a read can ask for a fresh copy instead.
 - **A reader that fetches once** - a reader opening many files fetches up front, picks one ref, and takes every read off it.
 - **A detached one-shot write** - a command in any clone writes through a throwaway worktree on origin's tip and pushes straight to the branch, never touching the persistent checkout.
@@ -120,7 +120,7 @@ It reports why it could not converge — a push origin rejected, or no origin to
 
 #### Business logic
 
-A repository with no remote is fine for a funneled write: the commit is safe locally, and the write reports that it did not push. It is an error for the pull, whose entire job is to meet the other machines, and it is refused outright for a detached write, which has nothing but the remote to write through. A repository nothing else can reach is a state the caller has to surface, not a mode this supports.
+A repository with no remote — no remote named `origin`; the module names `origin` in every fetch and push, so any other remote does not count — is fine for a funneled write: the commit is safe locally, and the write reports that it did not push. It is an error for the pull, whose entire job is to meet the other machines, and it is refused outright for a detached write, which has nothing but the remote to write through. A repository nothing else can reach is a state the caller has to surface, not a mode this supports.
 
 ### Reading from anywhere in the repository
 

packages/agent-data/src/file-branch.test.SPEC.md

@@ -7,7 +7,7 @@ What the tests cover: a branch used as a file store, checked against real git 
 - **The eager pull** - a machine converges on what another machine pushed, without writing anything of its own; on a repository with no remote the pull reports that as its error.
 - **Serialization** - three writes started at once run one whole cycle at a time rather than interleaving, and all three end up in the file.
 - **Reads** - from the persistent checkout; from an agent's worktree of the same repository, which reads the same file while holding no copy of it, and which names the repository it was made from as where the files live; a file the branch does not have reads as absent. Once another machine has moved origin on, the plain read still answers from the checkout while a fresh read answers from origin. A plain clone that never created the branch locally reads origin's copy and lists a directory off the ref, and a directory the branch does not have lists as none.
-- **A detached write** - it births the branch on origin when there is none, from a clone that gains no local branch of it; another machine's persistent checkout stays where it was until its own pull; when a push loses a race the operation is re-run against origin's fresher tip and both writers' files end up on origin; no throwaway worktree is left registered afterwards; an operation that writes nothing is no commit; and a repository with no remote is refused.
+- **A detached write** - it births the branch on origin when there is none, from a clone that gains no local branch of it; another machine's persistent checkout stays where it was until its own pull; when a push loses a race the operation is re-run against origin's fresher tip and both writers' files end up on origin; no throwaway worktree is left registered afterwards; an operation that writes nothing is no commit; and a repository with no remote is refused, a remote by any name other than `origin` counting as none.
 
 ## Before modifying/creating SPEC.md files
 

packages/agent-data/src/file-branch.test.ts

@@ -322,6 +322,9 @@ test('a detached write lands on origin from any clone without touching the persi
   const solo = await initRepo('file-branch-detached-solo-')
   try {
     assert.deepEqual(await writeFileBranchDetached(solo, BRANCH, 'x', async () => {}), { ok: false, reason: 'no-remote' })
+    // A remote by any other name does not count: every push here names `origin`.
+    await git(['remote', 'add', 'upstream', solo], solo)
+    assert.deepEqual(await writeFileBranchDetached(solo, BRANCH, 'x', async () => {}), { ok: false, reason: 'no-remote' })
   } finally {
     await rm(solo, RETRIED_RM)
   }

packages/agent-data/src/file-branch.ts

@@ -43,10 +43,14 @@ function resolveDeps(deps: FileBranchDeps): Resolved {
   return { git: deps.git ?? nodeGitRunner(), log: deps.log ?? (() => {}) }
 }
 
-/** Whether the repo has any remote to sync the branch with. */
+/**
+ * Whether the repo has `origin` to sync the branch with. Every fetch and push here names
+ * `origin`, so a repo whose only remote is called something else is remote-less to this module:
+ * the stated no-remote outcomes, not a push that fails twice.
+ */
 async function hasRemote(cwd: string, git: GitRunner): Promise<boolean> {
   try {
-    return (await git(['remote'], cwd)).trim().length > 0
+    return (await git(['remote'], cwd)).split('\n').some(line => line.trim() === 'origin')
   } catch {
     return false
   }

packages/framework/package.json

@@ -33,14 +33,14 @@
     "the-framework": "dist/bin.js"
   },
   "scripts": {
-    "build": "pnpm -C ../skill-tickets build && pnpm -C ../agent-driver build && node scripts/gen-prompts.mjs && tsc -p tsconfig.build.json && cd dashboard && vite build",
+    "build": "pnpm -C ../skill-branches build && pnpm -C ../skill-tickets build && pnpm -C ../agent-driver build && node scripts/gen-prompts.mjs && tsc -p tsconfig.build.json && cd dashboard && vite build",
     "preview": "pnpm build && node dist/bin.js",
-    "dev": "pnpm -C ../skill-tickets build && pnpm -C ../agent-driver build && node scripts/gen-prompts.mjs && tsc -p tsconfig.build.json --watch",
+    "dev": "pnpm -C ../skill-branches build && pnpm -C ../skill-tickets build && pnpm -C ../agent-driver build && node scripts/gen-prompts.mjs && tsc -p tsconfig.build.json --watch",
     "dev:dashboard": "cd dashboard && vite",
     "dev:daemon": "cd dashboard && FRAMEWORK_DEV_DAEMON=1 vite",
     "design:build": "tsx dashboard/design/build.mts",
-    "typecheck": "pnpm -C ../skill-tickets build && pnpm -C ../agent-driver build && node scripts/gen-prompts.mjs && tsc --noEmit && tsc --noEmit -p dashboard/tsconfig.json",
-    "test": "pnpm -C ../skill-tickets build && pnpm -C ../agent-driver build && node scripts/gen-prompts.mjs && tsc -p tsconfig.test.json && node scripts/run-tests.mjs && cd dashboard && vitest run",
+    "typecheck": "pnpm -C ../skill-branches build && pnpm -C ../skill-tickets build && pnpm -C ../agent-driver build && node scripts/gen-prompts.mjs && tsc --noEmit && tsc --noEmit -p dashboard/tsconfig.json",
+    "test": "pnpm -C ../skill-branches build && pnpm -C ../skill-tickets build && pnpm -C ../agent-driver build && node scripts/gen-prompts.mjs && tsc -p tsconfig.test.json && node scripts/run-tests.mjs && cd dashboard && vitest run",
     "clean": "rm -rf dist dist-test src/prompts.generated.ts",
     "gen:prompts": "node scripts/gen-prompts.mjs"
   },