opencode-workflow-guard 1.15.0 → 1.15.1

package/docs/policies.md

@@ -143,7 +143,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 
 ### 20. Merged Branch & Base Freshness Guard
 - Blocks pushing to branches already merged or associated with closed PRs in GitHub or Azure DevOps.
-- Blocks creating fresh feature branches when the local base branch is behind the remote, prompting the agent to pull latest changes first.
+- Blocks creating feature branches (`git switch -c`, `git checkout -b`) from a stale base: without an explicit start point, the current branch must be fresh against the remote default; an explicit start point that already contains the remote default (`origin/HEAD`) is accepted because the new branch is fresh by construction, and start points that cannot be resolved fail closed. Block reasons name the branch actually checked and remedies that work under the guard (rebase or ff-merge the branch, or branch from the remote default directly).
 - Tag push refspecs are exempt: publishing an existing tag (`git push origin v1.2.0`, `git push origin refs/tags/v1.2.0`) and creating tags (`git tag v1.2.0`, `git tag -a -m ...`) are release operations, not branch mutations - only tag deletions (`git tag -d`, `git push origin :refs/tags/v1.2.0`, `--delete`) stay blocked.
 
 ### 21. Documentation Review & Synchronization Guard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.15.0",
+  "version": "1.15.1",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",

package/src/lib/guard-dispatcher.ts

@@ -48,6 +48,7 @@ import {
 	GIT_WRITE_RE,
 	PUSH_TO_MAIN_RE,
 	branchGuardReason,
+	branchCreationStartPoint,
 	checkBranchBaseIsUpToDate,
 	checkMergeConflicts,
 	currentGitBranch,
@@ -366,9 +367,27 @@ export async function guardToolCallImpl(
 			}
 		}
 		if (GIT_BRANCH_CREATE_RE.test(normalizedCommand)) {
-			const behindCheck = checkBranchBaseIsUpToDate(effectiveRoot);
+			// A branch created from an explicit start point that already contains
+			// the remote default is fresh by construction; only creations without
+			// one (or with an unclassifiable shape — fail closed) inherit the
+			// current branch's staleness.
+			const creationStarts: Array<string | undefined> = [];
+			let classifiable = true;
+			for (const invocation of gitInvocations) {
+				if (!GIT_BRANCH_CREATE_RE.test(`git ${invocation.rest}`)) continue;
+				const parsed = branchCreationStartPoint(invocation.rest);
+				if (parsed === undefined) {
+					classifiable = false;
+					break;
+				}
+				creationStarts.push(parsed.start);
+			}
+			const behindCheck = checkBranchBaseIsUpToDate(
+				effectiveRoot,
+				classifiable && creationStarts.length > 0 ? creationStarts : undefined,
+			);
 			if (behindCheck.isBehind) {
-				logPolicyBlock(`[workflow-guard] blocked branch creation: base is behind remote ${behindCheck.baseRef}`);
+				logPolicyBlock(`[workflow-guard] blocked branch creation: ${behindCheck.reason ?? "base is behind remote"}`);
 				return block("git", "branch_base_behind", `Blocked: ${behindCheck.reason}`);
 			}
 		}

package/src/policies/git.ts

@@ -335,29 +335,152 @@ export function checkMergeConflicts(root: string): {
 	return { hasConflicts: false };
 }
 
-export function checkBranchBaseIsUpToDate(root: string): {
+const BRANCH_CREATION_VALUELESS_FLAGS = new Set([
+	"-f",
+	"--force",
+	"--discard-changes",
+	"-m",
+	"--merge",
+	"-q",
+	"--quiet",
+	"--no-track",
+]);
+
+// Classifies the optional start-point operand of an already-matched branch
+// creation invocation (`git switch -c|--create` / `git checkout -b`). Returns
+// the explicit start point when present, `{ start: undefined }` when the
+// invocation creates a branch from the current HEAD, and `undefined` when the
+// shape cannot be confidently classified — the caller must then fail closed to
+// the HEAD-based staleness check. Indeterminate tokens (variables, quotes,
+// unknown or value-taking flags) are never classified.
+export function branchCreationStartPoint(rest: string): { start?: string } | undefined {
+	const tokens = rest.split(/\s+/).filter(Boolean);
+	let sawCreate = false;
+	let named = false;
+	for (const token of tokens) {
+		const indeterminate = /[$`"']/.test(token);
+		if (!sawCreate) {
+			if (token === "switch" || token === "checkout") continue;
+			if (token === "-c" || token === "--create" || token === "-b") {
+				sawCreate = true;
+				continue;
+			}
+			if (token.startsWith("--create=")) {
+				sawCreate = true;
+				named = true;
+				continue;
+			}
+			if (!token.startsWith("--") && token.length > 2 && (token.startsWith("-c") || token.startsWith("-b"))) {
+				sawCreate = true;
+				named = true;
+				continue;
+			}
+			if (token.startsWith("-")) {
+				if (BRANCH_CREATION_VALUELESS_FLAGS.has(token)) continue;
+				return undefined;
+			}
+			return undefined;
+		}
+		if (!named) {
+			if (token.startsWith("-")) {
+				if (BRANCH_CREATION_VALUELESS_FLAGS.has(token)) continue;
+				return undefined;
+			}
+			if (indeterminate) return undefined;
+			named = true;
+			continue;
+		}
+		if (token.startsWith("-")) {
+			if (BRANCH_CREATION_VALUELESS_FLAGS.has(token)) continue;
+			return undefined;
+		}
+		if (indeterminate) return undefined;
+		return { start: token };
+	}
+	return sawCreate ? { start: undefined } : undefined;
+}
+
+// A branch created from an explicit start point that already contains the
+// remote default is fresh by construction, so the current branch's staleness
+// is irrelevant for it; every provided start point must resolve and contain
+// the base, and any missing start point keeps the HEAD-based check. Start
+// points that cannot be resolved fail closed. Block reasons name what was
+// actually checked and remedies that work under the guard.
+function evaluateBranchCreationStarts(
+	root: string,
+	base: string,
+	startPoints: ReadonlyArray<string>,
+): { isBehind: true; baseRef: string; reason: string } | undefined {
+	for (const startPoint of startPoints) {
+		const resolved = spawnSync("git", ["rev-parse", "--verify", "--quiet", startPoint], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (resolved.status !== 0 || !resolved.stdout.trim()) {
+			return {
+				isBehind: true,
+				baseRef: base,
+				reason: `the explicit start point '${startPoint}' could not be resolved as a commit, so freshness cannot be classified (fail closed). Use a literal branch name or ref as the start point.`,
+			};
+		}
+		const startSha = resolved.stdout.trim();
+		const contains = spawnSync("git", ["merge-base", "--is-ancestor", base, startSha], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (contains.status !== 0) {
+			const behind = spawnSync("git", ["rev-list", `${startSha}..${base}`, "--count"], {
+				cwd: root,
+				encoding: "utf8",
+				timeout: 5_000,
+			});
+			const behindCount = parseInt((behind.stdout ?? "").trim(), 10);
+			return {
+				isBehind: true,
+				baseRef: base,
+				reason: `the explicit start point '${startPoint}' is ${isNaN(behindCount) ? "" : `${behindCount} `}commit(s) behind ${base}. Create the branch from ${base}, or from any ref that contains it, instead.`,
+			};
+		}
+	}
+	return undefined;
+}
+
+export function checkBranchBaseIsUpToDate(
+	root: string,
+	startPoints?: ReadonlyArray<string | undefined>,
+): {
 	isBehind: boolean;
 	count?: number;
 	baseRef?: string;
 	reason?: string;
 } {
+	const classified = startPoints && startPoints.length > 0 ? startPoints : undefined;
 	for (const base of ["origin/HEAD", "origin/main", "origin/master"]) {
 		const res = spawnSync("git", ["rev-list", `HEAD..${base}`, "--count"], {
 			cwd: root,
 			encoding: "utf8",
 			timeout: 5_000,
 		});
-		if (res.status === 0 && res.stdout.trim()) {
-			const count = parseInt(res.stdout.trim(), 10);
-			if (!isNaN(count) && count > 0) {
-				return {
-					isBehind: true,
-					count,
-					baseRef: base,
-					reason: `Local base branch is ${count} commit(s) behind remote (${base}). Run 'git pull' or 'git fetch' on main before creating a fresh feature branch to prevent upstream conflicts.`,
-				};
-			}
+		if (res.status !== 0 || !res.stdout.trim()) continue;
+		const count = parseInt(res.stdout.trim(), 10);
+		if (isNaN(count)) continue;
+		const explicit = (classified ?? []).filter((startPoint): startPoint is string => startPoint !== undefined);
+		if (explicit.length > 0) {
+			const startBlock = evaluateBranchCreationStarts(root, base, explicit);
+			if (startBlock) return startBlock;
+		}
+		if (count > 0 && (!classified || classified.some((startPoint) => startPoint === undefined))) {
+			const branch = currentGitBranch(root) || "detached HEAD";
+			return {
+				isBehind: true,
+				count,
+				baseRef: base,
+				reason: `current branch '${branch}' is ${count} commit(s) behind remote default (${base}), so a branch created from it starts stale. Update this branch first (git rebase ${base} or git merge --ff-only ${base}), or create the new branch from ${base} directly.`,
+			};
 		}
+		return { isBehind: false };
 	}
 	return { isBehind: false };
 }

package/src/workflow-guard-ui.ts

@@ -2,7 +2,7 @@
  * Workflow Guard TUI companion plugin for OpenCode V2 (CLI plugin API).
  *
  * - Registers the `/guard-options` palette + slash command to toggle project options.
- * - Renders the Workflow Guard badge in the home and prompt footer status slots.
+ * - Renders the Workflow Guard badge in the prompt footer status slot.
  *
  * The V1 entrypoint (`WorkflowGuardTui`) remains for OpenCode 1.x TUI clients.
  */
@@ -277,7 +277,6 @@ export const WorkflowGuardTuiV2 = (ctx: TuiContext) => {
 			},
 		});
 	};
-	registerBadgeSlot("home.footer.status");
 	registerBadgeSlot("prompt.footer.status");
 	diagRender("probe-after-setup");
 

package/test/test.mts

@@ -1600,22 +1600,19 @@ const fakeV2TuiCtx = {
 	ui: { slot: (claim: { append: string; render: () => unknown }) => { v2SlotClaims.push(claim); } },
 };
 await WorkflowGuardTuiV2(fakeV2TuiCtx as any);
-check("v2 tui companion registers home and prompt status slots", v2SlotClaims.filter((claim) => claim.append === "home.footer.status" || claim.append === "prompt.footer.status").length === 2);
+check("v2 tui companion registers only the prompt footer status slot", v2SlotClaims.filter((claim) => claim.append === "home.footer.status" || claim.append === "prompt.footer.status").length === 1 && v2SlotClaims.some((claim) => claim.append === "prompt.footer.status"));
 const diagLogPath = join(process.env.XDG_STATE_HOME!, "opencode", "workflow-guard-ui.log");
 const diagLogText = () => readFileSync(diagLogPath, "utf8");
 check("v2 tui companion logs module load and setup with app version", diagLogText().includes("module load:") && diagLogText().includes("setup: app=9.9.9-test"));
-const v2HomeRender = v2SlotClaims.find((claim) => claim.append === "home.footer.status")!.render;
+const v2StatusRender = v2SlotClaims.find((claim) => claim.append === "prompt.footer.status")!.render;
 // In a plain Node process there is no OpenTUI renderer, so badge() throws the
 // same "No renderer found" the long-running-session bug produced in the TUI.
-check("v2 slot render returns null instead of throwing when the render context is unavailable", v2HomeRender() === null);
-check("v2 slot failure log records probes and stack", diagLogText().includes("render home.footer.status FAILED (1/3)") && diagLogText().includes("owner=null") && diagLogText().includes("useContext(RendererContext): MISSING") && diagLogText().includes("  stack: "));
-for (let i = 0; i < 6; i++) v2HomeRender();
-const v2FailuresLogged = diagLogText().split("\n").filter((line) => line.includes("render home.footer.status FAILED (")).length;
+check("v2 slot render returns null instead of throwing when the render context is unavailable", v2StatusRender() === null);
+check("v2 slot failure log records probes and stack", diagLogText().includes("render prompt.footer.status FAILED (1/3)") && diagLogText().includes("owner=null") && diagLogText().includes("useContext(RendererContext): MISSING") && diagLogText().includes("  stack: "));
+for (let i = 0; i < 6; i++) v2StatusRender();
+const v2FailuresLogged = diagLogText().split("\n").filter((line) => line.includes("render prompt.footer.status FAILED (")).length;
 check("v2 slot failure logging is bounded to 3 per success epoch", v2FailuresLogged === 3);
 check("v2 slot failure suppression notice is logged once", diagLogText().split("still failing after 3 logged failures").length === 2);
-const v2PromptRender = v2SlotClaims.find((claim) => claim.append === "prompt.footer.status")!.render;
-check("v2 prompt status slot also degrades to null on render failure", v2PromptRender() === null);
-
 
 // ── Adversarial tests & hardened invariants ──
 console.log("- Adversarial tests & hardened invariants -");
@@ -3123,6 +3120,39 @@ spawnSync("git", ["update-ref", "refs/remotes/origin/main", "HEAD"], { cwd: conf
 const baseUpToDateCheck = checkBranchBaseIsUpToDate(conflictRepo);
 check("checkBranchBaseIsUpToDate passes when equal to remote", !baseUpToDateCheck.isBehind);
 
+// Policy 20: branch creation start-point awareness. Advance the simulated
+// remote past the current branch so HEAD is stale, then verify that an
+// explicit fresh start point clears the gate while startless and
+// indeterminate creations still fail (closed).
+spawnSync("git", ["switch", "-c", "wg-origin-advance"], { cwd: conflictRepo });
+writeFileSync(join(conflictRepo, "file.txt"), "remote advance content\n");
+spawnSync("git", ["commit", "-am", "remote advance"], { cwd: conflictRepo });
+spawnSync("git", ["update-ref", "refs/remotes/origin/main", "HEAD"], { cwd: conflictRepo });
+spawnSync("git", ["switch", "feat/conflict-branch"], { cwd: conflictRepo });
+const staleHeadCheck = checkBranchBaseIsUpToDate(conflictRepo);
+check(
+	"checkBranchBaseIsUpToDate attributes the stale current branch and working remedies",
+	staleHeadCheck.isBehind &&
+		staleHeadCheck.baseRef === "origin/main" &&
+		(staleHeadCheck.reason ?? "").includes("'feat/conflict-branch'") &&
+		(staleHeadCheck.reason ?? "").includes("git rebase origin/main"),
+);
+const freshStartCheck = checkBranchBaseIsUpToDate(conflictRepo, ["origin/main"]);
+check("checkBranchBaseIsUpToDate accepts an explicit start point containing the remote default", !freshStartCheck.isBehind);
+const staleStartSha = spawnSync("git", ["rev-parse", "HEAD"], { cwd: conflictRepo, encoding: "utf8" }).stdout!.trim();
+const staleStartCheck = checkBranchBaseIsUpToDate(conflictRepo, [staleStartSha]);
+check("checkBranchBaseIsUpToDate blocks an explicit stale start point", staleStartCheck.isBehind && (staleStartCheck.reason ?? "").includes("start point"));
+const unresolvableCheck = checkBranchBaseIsUpToDate(conflictRepo, ["$WG_START_REF"]);
+check("checkBranchBaseIsUpToDate fails closed on an unresolvable start point", unresolvableCheck.isBehind && (unresolvableCheck.reason ?? "").includes("could not be resolved"));
+const mixedStartCheck = checkBranchBaseIsUpToDate(conflictRepo, ["origin/main", undefined]);
+check("checkBranchBaseIsUpToDate keeps the head check when a creation lacks a start point", mixedStartCheck.isBehind && (mixedStartCheck.reason ?? "").includes("'feat/conflict-branch'"));
+check("git switch -c without a start point is blocked on a stale branch", blocked(await shell("git switch -c wg-start-stale")));
+check("git switch -c origin/main with a stale branch is allowed", !blocked(await shell("git switch -c wg-start-fresh origin/main")));
+check("git checkout -b origin/main with a stale branch is allowed", !blocked(await shell("git checkout -b wg-checkout-fresh origin/main")));
+check("wrapper git switch -c origin/main keeps the fresh start point exemption", !blocked(await shell("env git switch -c wg-wrapper-fresh origin/main")));
+check("variable start point fails closed on a stale branch", blocked(await shell("git switch -c wg-start-var $WG_REF")));
+check("plain git branch is not treated as guarded branch creation", !blocked(await shell("git branch wg-plain-branch origin/main")));
+
 // Lockfile synchronization tests
 const lockRepo = mkdtempSync(join(tmpdir(), "wg-lock-repo-"));
 spawnSync("git", ["init", "-b", "main"], { cwd: lockRepo });