Beagle SCM

BEE-026: //repo-TKT-123 — a ticket worktree, submodules included

The work loop (/meta/work) gives every ticket its own worktree. For git repos the default name is //repo-TKT-123: repo is a MAIN repo of the registry, the rest (most often) a ticket code, the tree lives at $SRC_ROOT/repo-TKT-123 — the BEE-023 $SRC_ROOT leg, so no registration is needed. Creation RECURSES INTO SUBMODULES (ruling gritzko 2026-08-19): git worktree add leaves them empty, so each submodule gets a worktree of ITS repo at the same relative path inside the new tree, and so on down.

Input

Context

• Have: BEE-009 — a linked worktree is not a repo; the index is the original's (indexDir folds to the common dir), the registry never lists the worktree.
• Have: index/mount.js subsOf(root) names a repo's submodules and serves(root, rel) the worktree that holds a path (BEE-020).
• Have: index/refs.js commonDir and the .git FILE reading a linked worktree/submodule needs.
• Missing: any verb in bee that WRITES outside .git/be/; merge/install/hook touch .git/config and hooks only.
• be's $be get //TKT/ is the analogue (/meta/work §"Typical CLI commands"); bee has no get.

Goals

• A verb that turns //repo-TKT-123 into a tree: git worktree add -b TKT-123 $SRC_ROOT/repo-TKT-123 <main HEAD> from the registry's repo, the branch named by the tail; an existing branch TKT-123 is checked out, not re-created.
• Recursion: for each subsOf(main) entry (and theirs), git worktree add of the submodule's own repo at $SRC_ROOT/repo-TKT-123/<sub path>, pinned to the gitlink commit the parent's HEAD records; the parent's .git/modules/<sub> stays the common dir, so the sub worktree shares the index too.
• Name split: repo is the LONGEST registry name that prefixes the word and is followed by - (//bee-journal-BEE-023 is bee-journal + BEE-023); the tail need not be a ticket code.
• Report ONE line on success: the tree path, the branch, the submodule count; refuse when the tree exists (//repo-TKT-123 already resolves via BEE-023) or the name has no registry prefix.
• After creation bee //repo-TKT-123 <verb> works through BEE-023 with no further step.

Constraints

• Writes happen through git worktree add in a child process, never by composing .git files by hand; no git plumbing is reimplemented.
• $SRC_ROOT is the only destination; no path argument, no cp -r (/meta/work §"Things NOT TO DO").
• The worktree is NOT registered (BEE-009): it is reachable by the $SRC_ROOT leg and indexes through the original.
• Removal is git's (git worktree remove / rm -rf + prune), not bee's; the loop says worktrees are discarded freely.

WIP

Design decisions

• RULED: the default name is //repo-TKT-123, repo from the registry.
• RULED: submodules get their own worktrees, recursively.
• RULED (gritzko 2026-08-19): the verb is fork — bee fork //bee-BEE-023; get was the draft name.
• OPEN: when the tail IS a ticket code, should the verb refuse if //bee-journal/todo/BEE/BEE-023.mkd does not exist? Default: no — the tail is free text.
• A submodule whose gitlink commit is not fetched is a refusal naming the sub, not a half-built tree: the parent worktree is removed again on that failure.

TODOs

• name split over mount.list() names, longest-prefix rule; $SRC_ROOT destination
• git worktree add of the main repo; branch exists vs new
• recursion over subsOf, gitlink commit per sub, nested subs; rollback on a sub failure
• SIDE verb row in main.js + usage line; one report line
• test/fork/run.sh (the name test/worktree is BEE-009's): main repo, a sub and a nested sub, create, branch exists, missing gitlink
• README.mkd usage row
• /meta/work gets the git-flavoured command list once the verb name is ruled

Blockers and bummers

• Blocked on BEE-023 for the $SRC_ROOT leg that makes the result addressable; creation itself does not wait on it.

Outcome