Branch management lives in its own package (#1725) - #1726
Merged
Conversation
The git side of an agent's checkout — the naming conventions and the .the-framework/branches/ layout, the git runner with its per-subcommand time budgets, creating/attaching/listing/renaming/removing a worktree, sharing the parent's dependency trees into it, the branch-name links, and the retention rule under which a checkout is reclaimed — moves out of the framework into packages/branch-management, published as @superskill/branch-management. Step 1 of #1725: a lift with no behaviour change; the framework imports the package as a workspace dependency. What the framework keeps is the agent's side: its record (may the branch be pushed, what did a cloud hand-off already push), the teardown and the sweep, the dashboard's list and buttons, and how each refusal is worded. The package's reclaimWorktree takes those as options and returns a reason code. Also folded in: pushAgentBranch/gitReason (agent-handoff) were the same push the rule needs, so there is one pushBranch now, in the package.
- The legacy the-framework/ prefix goes: agentBranchFor guesses tf-, the scratch sweep and isAgentBranch know one spelling, and the package's public API carries no compat layer (repo MEMORY.md: zero migration code). - The framework's own build/dev/typecheck/test scripts build the package first, so a fresh clone works without a root build; the package sets publishConfig.access public. - reclaimWorktree reads the tree once; the refusal union says which members carry a branch; git branch -D/-m/<new> run on the write budget. - cli-exec keeps only what gh uses: a flat budget, no maxBuffer, no isCliTimeout; the daemon test times out with the package's error. - The branch-links pass is one line at its call site; the barrel exports what has an importer; the framework proves it wires birthBranch and mayPush into the rule. - SPECs: root and packages/ name the new package; index.SPEC.md; worktree, cli-exec and agent-handoff wording caught up with #1724 and this lift.
This was referenced Aug 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Step 1 of #1725: the git side of an agent's checkout moves into its own package,
packages/branch-management, published as@superskill/branch-management. A lift with no behaviour change; the framework imports it as a workspace dependency.Into the package (
git mv, history kept):store/worktree.ts,store/worktree-deps.ts,branch-names.ts,branch-links.ts(the reconcile),git-exclude.ts, with their tests and SPECs. New in the package:git.ts— the git runner, its per-subcommand time budgets andGitTimeoutError(fromproject.ts/cli-exec.ts),gitReasonandpushBranch(fromagent-handoff.ts).reclaim.ts— the retention rule, cut out ofworktrees.ts: keep a dirty tree, push when allowed, remove once the remote has it, delete atf-branch that holds nothing, delete the birth branch when the kept branch contains it. Takes what only the caller knows as options (mayPush,heldBy,birthBranch) and returns a reason code.branch-names.tsnow also holdsFRAMEWORK_DIR,BRANCHES_DIRandisSafeAgentId— the layout is the convention.The framework keeps the agent's side:
worktrees.tsreads the record (publish-nothing handoff, cloud anchor), hands the rule its options and words each refusal as before; the sweep, teardown, Remove/Delete/Prune, handoff untouched.branch-links-pass.tsis the daemon's turn of the reconcile.cli-exec.tsstays forgh.Imports point at the package directly — no re-export shims.
project.tslost its git half;store/index.tsno longer re-exports the worktree API.Tests: package 91 (the moved ones plus
reclaim.test.tsandgit.test.ts); framework 1552 + 864 dashboard, all green;pnpm buildclean.Second commit, after a review pass: the legacy
the-framework/prefix is gone after all (repoMEMORY.md: zero migration code —agentBranchFornow guessestf-); the framework's own scripts build the package first so a fresh clone works;reclaimWorktreereads the tree once;git branch -D/-m/<new>get the write budget;cli-execkeeps only whatghuses; the branch-links pass is one line at its call site; the barrel exports what has an importer; SPECs caught up (root andpackages/name the package).Not in this PR (steps 2–3 of #1725): the CLI,
SKILL.md, droppingsetSessionName.Needs Rom:
@superskillis your npm org. Nothing is published yet;framework'sworkspace:*dependency will need@superskill/branch-management@0.0.xon the registry before the nextframeworkrelease.🤖 automated · Fable 5, effort high