feat(conventions): substantive work isolates into git worktrees, merge user-ratified
Introduce the worktree convention the corpus previously lacked: any substantive work stream targeting main — in every mode, autonomous (/boss) and interactive alike — runs in a git worktree on its own branch (issue-N-<slug>), and the branch reaches main only through a user-ratified merge performed by the orchestrator (fast-forward preferred, push covered by the ratification, no pull request). Background sessions were already harness-isolated; this extends the same isolation to the sessions the harness does not guard. The convention depends on worktree.baseRef=head (the default 'fresh' bases branches on origin's routinely-stale tip under the no-autonomous-push discipline), now pinned in conventions.md. boss/SKILL.md gains the run-level mechanics (§ The run worktree): one worktree per run named after the reference issue, entered before the first dispatch; the merge is a user-reserved run-close act; the done-state notify names the branch as the review handle; closes #N fires at merge-and-push time. Iron Law, rollback-sandbox framing, user-reserved-act enumerations, rationalisations, and red flags updated to match. Corollary reconciliations after adversarial review: implement's 'there is no branch' narrowed to 'the loop creates no branch of its own'; specify's auto-signed-commits-on-main heading reworded to ratified-history framing; the sandbox bullets in conventions.md and the CLAUDE.md fragment note the anchor is the run branch's base. The skills meta-repo itself stays exempt (its CLAUDE.md: install symlinks resolve to the primary clone) and direct-on-main.
This commit is contained in:
+30
-2
@@ -139,12 +139,40 @@ too.
|
||||
recovery is forward-editing or `BLOCKED` (`implement/SKILL.md` Iron
|
||||
Law, issue #23).
|
||||
**One narrow `/boss` exception — the rollback sandbox:** inside an
|
||||
autonomous run the orchestrator anchors on the `main` HEAD it started
|
||||
from (the last user-ratified state) and MAY `git reset --hard` its
|
||||
autonomous run the orchestrator anchors on the HEAD it started
|
||||
from (the last user-ratified state; under the worktree bullet below
|
||||
that is the run branch's base, so a reset moves only the branch and
|
||||
can never reach `main`) and MAY `git reset --hard` its
|
||||
*own* commits *above* that anchor — autonomous, **unpushed** work only
|
||||
— back toward (never below) the anchor when it has run into a dead end.
|
||||
A pushed commit has left the sandbox and is forward-only (`git revert`).
|
||||
See `../boss/SKILL.md` § Direction freedom.
|
||||
- **Substantive work runs in a git worktree — merge is human-in-the-loop.**
|
||||
Any substantive work stream targeting `main` — a feature, a bug fix, a
|
||||
refactor; anything beyond a trivial mechanical edit — is isolated into
|
||||
a git worktree on its own branch before work starts, in every mode:
|
||||
autonomous (`/boss`, see `../boss/SKILL.md` § The run worktree) and
|
||||
interactive alike. (Background sessions are worktree-isolated by the
|
||||
harness already; this convention extends the same isolation to the
|
||||
sessions the harness does not guard.) The worktree branches from the
|
||||
current **local** HEAD — pin `worktree.baseRef: "head"` in settings;
|
||||
the harness default `fresh` bases the branch on origin's tip, which
|
||||
is routinely stale under this convention's no-autonomous-push
|
||||
discipline. Name the branch after the
|
||||
tracker issue where one exists (`issue-N-<slug>`); a live worktree
|
||||
branch is then also the visible being-worked-on signal in
|
||||
`git worktree list`. The branch reaches `main` only through a
|
||||
**user-ratified merge**: the user reviews the result, then the
|
||||
orchestrator merges — fast-forward preferred (rebase the branch onto
|
||||
`main` first if `main` has moved) — pushes (the ratification covers
|
||||
the push), and removes the worktree and
|
||||
deletes the branch. No pull request is opened, and the merge is never
|
||||
autonomous. `closes #N` markers consequently fire at merge-and-push
|
||||
time, when the commits reach the default branch.
|
||||
**One exception:** the skills meta-repo itself forbids worktree
|
||||
development outright (its `CLAUDE.md`: the install symlinks resolve to
|
||||
the primary clone, so worktree edits are silently ineffective) and
|
||||
stays direct-on-`main`.
|
||||
|
||||
These also appear in the universal-discipline fragment
|
||||
(`../templates/CLAUDE.md.fragment`) that each project's CLAUDE.md
|
||||
|
||||
Reference in New Issue
Block a user