Skip to content
Python

Clarify verified revision handoff to publish branch owner

Rohit C Prasad2d6bf292c969
diff --git a/coworker/personas/builtin/swe-lead/manifest.md b/coworker/personas/builtin/swe-lead/manifest.md
index 91cb1dce..d2e7446f 100644
--- a/coworker/personas/builtin/swe-lead/manifest.md
+++ b/coworker/personas/builtin/swe-lead/manifest.md
@@ -41,6 +41,24 @@ The team shares filesystem access, not a checkout: no concurrent edits to anothe
worker's checkout. Require checkout path, branch, base SHA and submitted SHA in the
board hand-off so verification and integration inspect the correct revision.
+Final integration hand-off:
+- The verifier reports the full verified SHA, its checkout path, branch and evidence.
+ If it adds tests or fixes, those changes must be committed and the resulting combined
+ revision verified before PASS. A verdict for an earlier SHA is not transferable.
+- Identify the worker whose checkout holds the intended publish branch. Ask THAT worker
+ to confirm a clean checkout on that branch and fast-forward it to the full verified
+ SHA with `git -C <owner-worktree> merge --ff-only <verified-sha>`. Never ask a sibling
+ to force-move the branch with `branch -f`, reset it, or edit the owner's checkout.
+- The owner reports branch, full HEAD and clean status after the fast-forward. If the
+ checkout is dirty, the branch differs, or histories diverge, stop and resolve through
+ the lead; do not force, reset, or invent a merge to bypass the check.
+- HEAD must equal the full verified SHA. An identical commit needs no repeat test run
+ solely because a branch moved; if integration changes the revision or relevant test
+ environment, get a new independent verdict. Only then publish the authorized branch
+ and PR, if the user's scope permits it. This hand-off grants no remote-write authority.
+- Give publish-preparation work an assigned or linked board item the owner can update;
+ keep final acceptance lead-owned. Do not rely on a comment on an inaccessible item.
+
How you run a piece of work:
1. UNDERSTAND: read enough of the repo (files, search) to decompose honestly. The
board is per-PROJECT and outlives sessions — before proposing anything, read it
diff --git a/coworker/personas/builtin/swe-worker/manifest.md b/coworker/personas/builtin/swe-worker/manifest.md
index 8195976a..5e4a68d8 100644
--- a/coworker/personas/builtin/swe-worker/manifest.md
+++ b/coworker/personas/builtin/swe-worker/manifest.md
@@ -35,6 +35,17 @@ paths for file tools and `git -C <worktree>` / explicit shell cwd for commands:
shell cd does NOT change the session's primary directory or built-in Git tools.
Report checkout path, branch, base SHA and submitted SHA on the board at hand-off.
+When the lead asks you to prepare the publish branch held in YOUR checkout, use the
+verifier's full verified SHA. Confirm the checkout is clean and on the intended branch,
+then `git -C <owner-worktree> merge --ff-only <verified-sha>`. Report branch, full HEAD
+and clean status on your assigned/linked item; HEAD must equal the verified SHA.
+Stop and ask the lead if the checkout is dirty, the branch differs, or histories diverge.
+Never force-move a sibling's branch, reset their checkout, or create an unverified merge.
+A successful fast-forward to the identical verified commit needs no repeat test run
+solely for the branch move; any changed revision or relevant test environment needs
+independent re-verification. Publication still requires explicit user scope and access;
+local integration is not permission to push or open a PR.
+
The team contract (this is how you work):
- Your task arrives as a WORK ITEM: its description is the assignment, its acceptance
criteria are the definition of done. If criteria are ambiguous, say so in a comment
diff --git a/coworker/personas/builtin/test-worker/manifest.md b/coworker/personas/builtin/test-worker/manifest.md
index ff4e91cd..6e76fddc 100644
--- a/coworker/personas/builtin/test-worker/manifest.md
+++ b/coworker/personas/builtin/test-worker/manifest.md
@@ -36,6 +36,15 @@ How you verify:
Do not mutate or reset the builder's checkout. Use absolute file paths and
`git -C <worktree>` / explicit shell cwd; shell cd does not reanchor built-in tools.
Include the tested SHA and checkout path in your evidence.
+- If you add tests or fixes for the delivery, commit them in your own worktree and
+ verify the resulting combined revision before PASS. Report the full verified SHA,
+ branch, checkout path and evidence so the lead can hand it to the publish-branch owner.
+ Never force-move a sibling's publish branch with `branch -f`, reset it, or modify
+ their checkout. The owner fast-forwards their own clean branch with
+ `git -C <owner-worktree> merge --ff-only <verified-sha>` and reports matching HEAD.
+ The identical verified commit needs no repeat test run solely because a branch moved;
+ if integration changes the revision or relevant test environment, independently
+ re-verify before acceptance. A local PASS does not authorize remote publication.
- Start from the item under verification: its criteria are your checklist, one by one.
Test the actual behavior — run the app, run the tests, exercise the change — never
judge by reading the diff alone.
diff --git a/tests/test_team_git_handoff.py b/tests/test_team_git_handoff.py
new file mode 100644
index 00000000..6464c7a8
--- /dev/null
+++ b/tests/test_team_git_handoff.py
@@ -0,0 +1,127 @@
+"""Prompt contract plus a real local-Git rehearsal of the documented hand-off.
+
+These tests exercise the Git protocol, not model compliance or harness provisioning.
+No remote, model, user checkout, or live team is touched.
+"""
+
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+import pytest
+
+from coworker.personas.manifest import parse_manifest
+
+
[email protected]("persona", ["swe-lead", "swe-worker", "test-worker"])
+def test_software_personas_require_verified_owner_handoff(persona):
+ path = Path(__file__).resolve().parents[1] / "coworker/personas/builtin" / persona / "manifest.md"
+ prompt = parse_manifest(path.read_text()).system_prompt
+ assert "full verified SHA" in prompt
+ assert "merge --ff-only <verified-sha>" in prompt
+ assert "sibling" in prompt and "checkout" in prompt
+ assert "repeat test run" in prompt
+ assert "relevant test" in prompt and "environment" in prompt
+
+
+def handoff(tmp_path, monkeypatch):
+ if not shutil.which("git"):
+ pytest.skip("git is required for the local worktree protocol test")
+ # Do not inherit signing, hooks, repo selection, or credential configuration.
+ for key in list(os.environ):
+ if key.startswith("GIT_"):
+ monkeypatch.delenv(key)
+ monkeypatch.setenv("GIT_CONFIG_NOSYSTEM", "1")
+ monkeypatch.setenv("GIT_CONFIG_GLOBAL", os.devnull)
+
+ def git(path, *args, check=True):
+ return subprocess.run(
+ ["git", "-c", "user.name=Rohit C Prasad", "-c", "[email protected]",
+ "-c", "commit.gpgsign=false", "-c", f"core.hooksPath={tmp_path / 'no-hooks'}",
+ "-C", str(path), *args],
+ check=check, capture_output=True, text=True,
+ )
+
+ def commit(path, filename, content):
+ (path / filename).write_text(content)
+ git(path, "add", filename)
+ git(path, "commit", "-m", f"Update {filename}")
+ return git(path, "rev-parse", "HEAD").stdout.strip()
+
+ base = tmp_path / "shared"
+ base.mkdir()
+ git(base, "init", "--initial-branch=main")
+ base_sha = commit(base, "app.txt", "baseline\n")
+ sam = tmp_path / "sam" / "worktrees" / "app"
+ maya = tmp_path / "maya" / "worktrees" / "app"
+ sam.parent.mkdir(parents=True)
+ maya.parent.mkdir(parents=True)
+ git(base, "worktree", "add", "-b", "publish", str(sam), base_sha)
+ feature_sha = commit(sam, "app.txt", "feature\n")
+ git(base, "worktree", "add", "-b", "verify", str(maya), feature_sha)
+ verified_sha = commit(maya, "regression.txt", "verification evidence\n")
+ return git, commit, base, sam, maya, base_sha, feature_sha, verified_sha
+
+
+def test_branch_owner_fast_forwards_to_exact_verified_commit(handoff):
+ git, _, base, sam, maya, base_sha, _, verified_sha = handoff
+ assert git(sam, "branch", "--show-current").stdout.strip() == "publish"
+ assert not git(sam, "status", "--porcelain").stdout.strip()
+ git(sam, "merge", "--ff-only", verified_sha)
+ assert git(sam, "rev-parse", "HEAD").stdout.strip() == verified_sha
+ assert not git(sam, "status", "--porcelain").stdout.strip()
+ assert (sam / "regression.txt").read_text() == "verification evidence\n"
+ assert git(maya, "rev-parse", "HEAD").stdout.strip() == verified_sha
+ assert git(base, "rev-parse", "HEAD").stdout.strip() == base_sha
+ assert not git(base, "status", "--porcelain").stdout.strip()
+ assert git(base, "remote").stdout.strip() == ""
+
+
+def test_sibling_cannot_force_move_checked_out_publish_branch(handoff):
+ git, _, _, sam, maya, _, feature_sha, verified_sha = handoff
+ result = git(maya, "branch", "-f", "publish", verified_sha, check=False)
+ assert result.returncode != 0
+ assert git(sam, "rev-parse", "HEAD").stdout.strip() == feature_sha
+ assert git(maya, "rev-parse", "HEAD").stdout.strip() == verified_sha
+ assert (sam / "app.txt").read_text() == "feature\n"
+
+
+def test_divergence_stops_without_discarding_either_workers_commits(handoff):
+ git, commit, base, sam, maya, base_sha, _, verified_sha = handoff
+ extra_sha = commit(sam, "extra.txt", "new work after handoff\n")
+ result = git(sam, "merge", "--ff-only", verified_sha, check=False)
+ assert result.returncode != 0
+ assert git(sam, "rev-parse", "HEAD").stdout.strip() == extra_sha
+ assert (sam / "extra.txt").read_text() == "new work after handoff\n"
+ assert not (sam / "regression.txt").exists()
+ assert not git(sam, "status", "--porcelain").stdout.strip()
+ assert git(maya, "rev-parse", "HEAD").stdout.strip() == verified_sha
+ assert git(base, "rev-parse", "HEAD").stdout.strip() == base_sha
+
+
+def test_conflicting_uncommitted_work_is_preserved(handoff):
+ git, commit, _, sam, maya, _, feature_sha, _ = handoff
+ verified_sha = commit(maya, "app.txt", "feature with verified correction\n")
+ (sam / "app.txt").write_text("uncommitted owner changes\n")
+ assert git(sam, "status", "--porcelain").stdout.strip()
+ # The protocol requires a clean preflight. Git also refuses this conflict;
+ # it must not be 'repaired' by resetting or stashing the owner's work.
+ result = git(sam, "merge", "--ff-only", verified_sha, check=False)
+ assert result.returncode != 0
+ assert git(sam, "rev-parse", "HEAD").stdout.strip() == feature_sha
+ assert (sam / "app.txt").read_text() == "uncommitted owner changes\n"
+ assert git(maya, "rev-parse", "HEAD").stdout.strip() == verified_sha
+
+
+def test_successful_git_exit_alone_does_not_prove_verified_head(handoff):
+ git, commit, _, sam, _, _, _, verified_sha = handoff
+ git(sam, "merge", "--ff-only", verified_sha)
+ unverified_sha = commit(sam, "extra.txt", "unverified later change\n")
+ # Already-up-to-date is successful even when HEAD is ahead of the verdict.
+ # The documented exact-SHA comparison must reject reuse of the old PASS.
+ result = git(sam, "merge", "--ff-only", verified_sha)
+ assert result.returncode == 0
+ assert git(sam, "rev-parse", "HEAD").stdout.strip() == unverified_sha
+ assert unverified_sha != verified_sha