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:
2026-07-14 12:32:26 +02:00
parent bff2120f42
commit a1d6409163
5 changed files with 138 additions and 24 deletions
+30 -2
View File
@@ -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