Active Branch Continuity Lock

Active Branch Continuity Lock

What

The active branch continuity lock keeps a website workstream on one named branch. It prevents a teammate or AI agent from losing context, starting another branch, and overwriting or stranding work.

Use it for every client cutover, delegated website build, long-lived review branch, and multi-session website or website SEO job.

The repo stores the branch name in .cutover/active-branch. A root AGENTS.md, tracked Git hooks, a setup script, and a verifier all read the same lock.

Who owns it

The Website Specialist installs and verifies the lock. Jakob approves website and website SEO branch-context changes. Nick still controls billing, destructive actions, and unclear cross-lane changes.

Steps

1. Check for a lock before any branch command

From the repo:

test ! -f .cutover/active-branch || sed -n '1p' .cutover/active-branch
git fetch origin --prune
git status --short --branch
git branch --show-current
if test -x scripts/verify-active-branch.sh; then
  scripts/verify-active-branch.sh
fi

If a lock exists, continue on that exact branch. Do not create or switch to another branch because chat, task, agent, or local context is unclear.

If the current branch or SHA does not match, stop and inspect the existing state. Do not reset, stash, rebase, cherry-pick, clean, delete, or force-push as a shortcut.

2. Install the lock on a new workstream

Create the intended working branch once. Then install the blocker before editing:

/home/nick/.hermes/skills/github/github-pr-workflow/scripts/install-active-branch-guard.sh \
  --repo "$PWD" \
  --branch "$(git branch --show-current)" \
  --approver jakob

The installer creates:

• .cutover/active-branch
• .cutover/approver
• the root AGENTS.md continuity rule
• tracked commit, checkout, merge, rebase, reference, and push hooks
• scripts/setup-git-hooks.sh
• scripts/verify-active-branch.sh

For Node repos, add these package scripts:

{
  "scripts": {
    "setup:git-hooks": "bash scripts/setup-git-hooks.sh",
    "verify:git-context": "bash scripts/verify-active-branch.sh"
  }
}

Run npm run setup:git-hooks after every new clone. Non-Node repos run scripts/setup-git-hooks.sh.

3. Verify the blocker

Run the context check:

npm run verify:git-context

Then prove an unauthorized branch is rejected:

set +e
git branch blocker-negative-test
rc=$?
set -e
test "$rc" -ne 0
test -z "$(git branch --list blocker-negative-test)"

Also test a wrong remote branch push through the tracked pre-push hook. Confirm no extra local or remote branch was created.

A test that returns Everything up-to-date is not enough. Git may skip the hook when no ref changes.

4. Keep agents and worktrees on the lock

Before Claude, Codex, or another worker starts:

1. Read .cutover/active-branch.
2. Run the verifier.
3. Point the worker at the locked worktree.
4. Tell the worker not to create or switch branches.
5. Verify the branch and SHA again when the worker finishes.

Do not create a second agent branch to recover missing context.

5. Change the lock only after exact approval

Do not edit .cutover/active-branch by hand.

A branch-context change requires the approver name plus a durable Discord or TaskTracker approval reference. After approval, use the installer with --replace-lock.

The new branch must already exist and be checked out. Preserve the old branch and worktree until the new context is verified.

6. Keep production approval separate

The branch lock prevents context drift. It does not approve a merge or production release.

Before pushing to main, merging, deploying production, or changing DNS, canonicals, redirects, robots, sitemaps, or indexing, obtain the exact approval required for that reviewed batch.

What the blocker stops

Configured checkouts reject:

• another local branch being created or updated
• commits or merge commits outside the lock
• checkout progression on another branch
• rebases without exact approval
• pushes to another remote branch name
• branch deletion without branch-context approval
• non-fast-forward pushes without history-rewrite approval
• direct pushes to main or master without exact batch approval

Known limit

Tracked hooks protect configured checkouts. A fresh or outside clone is protected only after scripts/setup-git-hooks.sh runs.

Use GitHub branch protection or rulesets when the repository plan supports them. If private-repo protection is unavailable on the current plan, do not make the repo public and do not change billing. Keep the tracked blocker and record the server-side limitation.

Definition of done

The branch lock is complete when:

1. The locked branch and authorized approver are tracked in the repo.
2. The root AGENTS.md, hooks, setup script, and verifier are committed.
3. core.hooksPath is .githooks in the active checkout.
4. The context verifier passes on the intended branch.
5. Unauthorized local branch creation is rejected.
6. A wrong-remote push is rejected.
7. No extra branch remains after testing.
8. Local and remote SHA match after the working branch is pushed.
9. The repo build and tests still pass.
10. The handoff states the locked branch, SHA, guard result, and whether GitHub server-side protection is available.