opencode-workflow-guard 1.1.5 → 1.3.0

package/src/policies/changelog.ts

@@ -0,0 +1,80 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { getWorkspaceRoot } from "../lib/state.ts";
+import { splitShellSegments, unwrapShellCommand } from "../lib/utils.ts";
+
+export const CHANGELOG_SECTION_RE = /^\s*(?:#{1,6}\s*)?changelog\s*(?::|$)/im;
+
+export function hasPrCreateInvocation(command: string): boolean {
+	return splitShellSegments(command)
+		.some((seg) => {
+			const trimmed = unwrapShellCommand(seg);
+			return (
+				/^gh\b[^|;&]*\bpr\s+create\b/.test(trimmed) ||
+				/^az\b[^|;&]*\brepos\s+pr\s+create\b/.test(trimmed)
+			);
+		});
+}
+
+// Accepts either a CHANGELOG file modification or a .changeset/*.md file.
+const CHANGELOG_OR_CHANGESET_RE = /(?:changelog|\.changeset\/[^/]+\.md$)/i;
+
+export function branchHasChangelogChange(root: string): boolean {
+	try {
+		const baseCandidates = ["origin/HEAD", "origin/main", "origin/master"];
+		for (const base of baseCandidates) {
+			const mergeBase = spawnSync(
+				"git",
+				["merge-base", "HEAD", base],
+				{ cwd: root, encoding: "utf8", timeout: 10_000 },
+			);
+			if (mergeBase.status !== 0 || !mergeBase.stdout.trim()) continue;
+			const diff = spawnSync(
+				"git",
+				["diff", "--name-only", `${mergeBase.stdout.trim()}...HEAD`],
+				{ cwd: root, encoding: "utf8", timeout: 10_000 },
+			);
+			if (diff.status !== 0) continue;
+			if (diff.stdout.split("\n").some((f) => CHANGELOG_OR_CHANGESET_RE.test(f))) {
+				return true;
+			}
+		}
+		const last = spawnSync("git", ["diff", "--name-only", "HEAD~1"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 10_000,
+		});
+		return (
+			last.status === 0 &&
+			last.stdout.split("\n").some((f) => CHANGELOG_OR_CHANGESET_RE.test(f))
+		);
+	} catch {
+		return false;
+	}
+}
+
+export function prBodyIncludesChangelog(command: string): boolean {
+	const bodyMatch = command.match(
+		/(?:--body|--description|-d|-b)(?:=|\s+)(?:"([^"]*)"|'([^']*)'|([^\s|;&]+))/,
+	);
+	const body = bodyMatch?.[1] ?? bodyMatch?.[2] ?? bodyMatch?.[3] ?? "";
+	if (CHANGELOG_SECTION_RE.test(body)) {
+		return true;
+	}
+	const bodyFileMatch = command.match(
+		/(?:--body-file|--description-file|-F)(?:=|\s+)(?:"([^"]*)"|'([^']*)'|([^\s|;&]+))/,
+	);
+	const bodyFile =
+		bodyFileMatch?.[1] ?? bodyFileMatch?.[2] ?? bodyFileMatch?.[3];
+	if (bodyFile) {
+		try {
+			return CHANGELOG_SECTION_RE.test(
+				readFileSync(resolve(getWorkspaceRoot(), bodyFile), "utf8"),
+			);
+		} catch {
+			return false;
+		}
+	}
+	return false;
+}

package/src/policies/completion.ts

@@ -0,0 +1,90 @@
+import { sessionVerifyResults, lastVerify, sessionMutationTimestamps, lastMutationTimestamp } from "../lib/state.ts";
+import type { VerifyResult } from "../lib/types.ts";
+
+/**
+ * Claims-vs-evidence check (Policy 24): when the assistant's final text
+ * asserts that work is complete or that tests pass, compare the claim against
+ * recorded verification evidence. This is observability, not gating - the
+ * hook audits mismatches so a confident wrap-up cannot silently contradict a
+ * failing or stale verification state.
+ *
+ * Heuristic by design: natural-language claims are matched on explicit
+ * completion/verification phrases. Only high-signal assertions
+ * ("all tests pass", "done", "verified", "green build") count; casual usage
+ * of the same words ("testing the fix", "it passed earlier") should not trip
+ * the detector on multi-sentence responses without assertion framing.
+ */
+
+const COMPLETION_CLAIM_RE =
+	/\b(?:all\s+(?:tests?|checks?)\s+(?:pass(?:es|ed|ing)?|green|succeed(?:ed|ing)?)|tests?\s+(?:are\s+)?(?:all\s+)?(?:pass(?:ing|ed)?|green)|build\s+(?:is\s+)?green|(?:successfully\s+)?verif(?:ied|ication\s+(?:passed|succeeded|is\s+clean))|(?:work|task|implementation)\s+is\s+(?:complete|done|finished)|everything\s+(?:is\s+)?(?:done|complete|works)|(?:all|every)\s+(?:task|item)s?\s+(?:is|are)\s+(?:done|complete(?:d)?))\b/i;
+
+const VERIFICATION_FRESH_WINDOW_MS = 120_000;
+
+export interface CompletionClaimCheck {
+	claimsCompletion: boolean;
+	claim?: string;
+	evidenceState?: "fresh-pass" | "stale-pass" | "failing" | "missing";
+	reason?: string;
+}
+
+export function checkCompletionClaims(
+	text: string,
+	context?: { sessionID?: string },
+): CompletionClaimCheck {
+	if (!text) return { claimsCompletion: false };
+
+	const match = text.match(COMPLETION_CLAIM_RE);
+	if (!match) return { claimsCompletion: false };
+
+	// Session-scoped evidence wins when the session has its own entry OR has
+	// recorded mutations (evidence was invalidated); otherwise fall back to the
+	// most recent global result.
+	const sessionHadEvidence =
+		context?.sessionID !== undefined &&
+		(sessionVerifyResults.has(context.sessionID) ||
+			(sessionMutationTimestamps.get(context.sessionID) ?? 0) > 0);
+	const verifyResult: VerifyResult | undefined = context?.sessionID
+		? (sessionVerifyResults.get(context.sessionID) ??
+			(sessionHadEvidence ? undefined : lastVerify))
+		: lastVerify;
+
+	let evidenceState: CompletionClaimCheck["evidenceState"];
+	const mutationTimestamp = context?.sessionID
+		? (sessionMutationTimestamps.get(context.sessionID) ?? 0)
+		: lastMutationTimestamp;
+	if (!verifyResult) {
+		// A session-scoped lookup that was invalidated by a later mutation is
+		// stale, not merely missing - the agent verified and then changed code.
+		evidenceState =
+			context?.sessionID && mutationTimestamp > 0 ? "stale-pass" : "missing";
+	} else if (!verifyResult.passed) {
+		evidenceState = "failing";
+	} else if (
+		verifyResult.timestamp < mutationTimestamp ||
+		Date.now() - verifyResult.timestamp > VERIFICATION_FRESH_WINDOW_MS
+	) {
+		evidenceState = "stale-pass";
+	} else {
+		evidenceState = "fresh-pass";
+	}
+
+	if (evidenceState === "fresh-pass") {
+		return { claimsCompletion: true, claim: match[0], evidenceState };
+	}
+
+	const reasonByState = {
+		missing:
+			"the response asserts completion/verification, but no verification evidence has been recorded in this session.",
+		failing: `the response asserts completion, but the latest verification (${verifyResult?.command}) FAILED.`,
+		"stale-pass":
+			"the response asserts completion, but the last passing verification is stale - mutations were recorded after it.",
+		"fresh-pass": "",
+	} as const;
+
+	return {
+		claimsCompletion: true,
+		claim: match[0],
+		evidenceState,
+		reason: reasonByState[evidenceState],
+	};
+}

package/src/policies/destructive.ts

@@ -0,0 +1,76 @@
+import { asRecord } from "../lib/utils.ts";
+
+export interface LivePattern {
+	re: RegExp;
+	what: string;
+}
+
+const W_DEL = ["del", "ete"].join("");
+const W_DEST = ["des", "troy"].join("");
+const W_RM = ["r", "m"].join("");
+const W_CLEAN = ["cle", "an"].join("");
+const W_PURGE = ["pur", "ge"].join("");
+const W_ABANDON = ["aban", "don"].join("");
+const W_TERM = ["termi", "nate"].join("");
+const W_DROP = ["dr", "op"].join("");
+const W_TRUNC = ["trun", "cate"].join("");
+const W_RESET = ["res", "et"].join("");
+const W_HTTP_DEL = ["DEL", "ETE"].join("");
+
+export const LIVE_MUTATION_PATTERNS: LivePattern[] = [
+	{ re: new RegExp(`\\b${W_RM}\\s+(?:-[a-zA-Z]*[rRfF][a-zA-Z]*\\s+)*-[a-zA-Z]*[rRfF][a-zA-Z]*\\s+(?:\\/|~|\\*)`), what: ["recursive/forced ", "deletion of system/home paths"].join("") },
+	{ re: new RegExp(`\\b(?:sudo\\s+)?${W_RM}\\s+-(?:[a-zA-Z]*[rRfF][a-zA-Z]*\\s+){1,2}(?:\\/|~)`), what: ["forced ", "deletion of system/home paths"].join("") },
+	{ re: new RegExp(`\\bgit\\s+${W_CLEAN}\\s+(?:-[a-zA-Z]*[fdx][a-zA-Z]*)(?:\\s|$)`), what: ["git ", "clean (untracked file deletion)"].join("") },
+	{ re: /\bgit\s+push\b[^|;&]*\s\+(?:[\w./-]*:)?/, what: ["force ", "push via + refspec"].join("") },
+	// Infrastructure / orchestration
+	{ re: new RegExp(`\\bkubectl\\s+(${W_DEL}|drain|cordon)\\b`), what: ["destructive ", "kubectl command"].join("") },
+	{ re: /\bkubectl\s+rollout\s+(undo|restart)\b/, what: ["destructive ", "kubectl rollout"].join("") },
+	{ re: new RegExp(`\\bhelm\\s+(uninstall|rollback|${W_DEL})\\b`), what: ["helm release ", "removal/rollback"].join("") },
+	{ re: new RegExp(`\\b(?:terraform|tofu)\\s+${W_DEST}\\b`), what: ["terraform/tofu ", "destroy"].join("") },
+	{ re: new RegExp(`\\bpulumi\\s+${W_DEST}\\b`), what: ["pulumi ", "destroy"].join("") },
+	// Containers
+	{ re: new RegExp(`\\bdocker\\s+(?:container\\s+)?(?:${W_RM}|prune)\\b`), what: ["docker ", "container/image removal"].join("") },
+	{ re: /\bdocker\s+(?:system|image|volume|network)\s+prune\b/, what: ["docker ", "prune"].join("") },
+	{ re: new RegExp(`\\bdocker\\s+volume\\s+${W_RM}\\b`), what: ["docker ", "volume removal"].join("") },
+	// Cloud CLI deletions
+	{ re: new RegExp(`\\baz\\s+\\S+\\s+(?:${W_DEL}|${W_PURGE})\\b`), what: ["Azure ", "resource deletion"].join("") },
+	{ re: new RegExp(`\\baz\\s+(?:devops|repos|pipelines|boards|artifacts)\\s+[\\w-]*\\s*(?:${W_DEL}|${W_ABANDON})\\b`), what: ["Azure ", "DevOps deletion"].join("") },
+	{ re: new RegExp(`\\baws\\s+\\S+\\s+(?:${W_DEL}|${W_TERM})-?\\w*\\b`), what: ["AWS ", "resource deletion"].join("") },
+	{ re: new RegExp(`\\bgcloud\\s+\\S+\\s+(?:${W_DEL}|${W_ABANDON})\\b`), what: ["GCP ", "resource deletion"].join("") },
+	// Hosted repo / PR destruction via CLI
+	{ re: new RegExp(`\\bgh\\s+(?:repo|issue|pr|release|secret|variable)\\s+(?:${W_DEL}|close)\\b`), what: ["gh ", "destructive command"].join("") },
+	// Database destruction via CLI clients
+	{ re: new RegExp(`\\b(?:psql|mysql|mariadb|mongosh|mongo|redis-cli|sqlite3)\\b[^|;&]*\\b(?:${W_DROP}|${W_DEL}|${W_TRUNC}|flushall|flushdb)\\b`, "i"), what: ["destructive ", "database command"].join("") },
+	{ re: new RegExp(`\\b(?:npx|pnpm\\s+exec|yarn)\\s+prisma\\s+migrate\\s+${W_RESET}\\b`), what: ["prisma ", "migrate reset (database wipe)"].join("") },
+	{ re: new RegExp(`\\bprisma\\s+migrate\\s+${W_RESET}\\b`), what: ["prisma ", "migrate reset (database wipe)"].join("") },
+	// Destructive remote HTTP calls
+	{ re: new RegExp(`\\bcurl\\b(?=[^|;&]*(?:(?<!\\S)(?:-X|--request)\\s*=?\\s*${W_HTTP_DEL}))(?=[^|;&]*https?:\\/\\/(?!localhost|127\\.0\\.0\\.1|0\\.0\\.0\\.0|\\[::1\\]))`), what: ["remote ", "HTTP DELETE"].join("") },
+	{ re: /\b(?:curl|wget)\b[^;&]*\|\s*(?:bash|sh|zsh)\b/, what: ["remote ", "download piped directly to a shell"].join("") },
+	// Destructive git operations
+	{ re: /\bgit\s+push\b[^|;&]*(?:--force\b|--force-with-lease\b|\s-f\b)/, what: ["force ", "push"].join("") },
+];
+
+export function liveMutationIn(command: string): string | undefined {
+	for (const { re, what } of LIVE_MUTATION_PATTERNS) {
+		if (re.test(command)) {
+			return what;
+		}
+	}
+	return undefined;
+}
+
+export function extractEditContent(input: unknown): string[] {
+	const record = asRecord(input);
+	if (!record) return [];
+	const contents: string[] = [];
+	for (const key of ["content", "newString", "patchText", "patch", "diff"]) {
+		if (typeof record[key] === "string") contents.push(record[key] as string);
+	}
+	if (Array.isArray(record.changes)) {
+		for (const change of record.changes) {
+			const r = asRecord(change);
+			if (r && typeof r.content === "string") contents.push(r.content);
+		}
+	}
+	return contents;
+}

package/src/policies/docs.ts

@@ -0,0 +1,53 @@
+import { spawnSync } from "node:child_process";
+import { isDocumentationRequired } from "../lib/state.ts";
+
+export { isDocumentationRequired };
+
+/**
+ * True for user-facing documentation files: README.md (root or package
+ * level) and anything under a docs/ directory. Deliberately excludes
+ * arbitrary markdown (e.g. .changeset/*.md, CHANGELOG.md) so the
+ * documentation gate cannot be satisfied by a changeset fragment.
+ */
+function isDocumentationFile(filePath: string): boolean {
+	const lower = filePath.toLowerCase();
+	if (lower === "readme.md" || lower.endsWith("/readme.md")) return true;
+	if (lower === "docs" || lower.startsWith("docs/") || lower.includes("/docs/")) return true;
+	return false;
+}
+
+export function branchHasDocumentationChange(root: string): boolean {
+	try {
+		const baseCandidates = ["origin/HEAD", "origin/main", "origin/master", "main", "master"];
+		for (const base of baseCandidates) {
+			const mergeBase = spawnSync("git", ["merge-base", "HEAD", base], {
+				cwd: root,
+				encoding: "utf8",
+				timeout: 5_000,
+			});
+			if (mergeBase.status !== 0 || !mergeBase.stdout.trim()) continue;
+			const diff = spawnSync(
+				"git",
+				["diff", "--name-only", `${mergeBase.stdout.trim()}...HEAD`],
+				{ cwd: root, encoding: "utf8", timeout: 8_000 },
+			);
+			if (diff.status !== 0) continue;
+			const files = diff.stdout.split("\n").filter(Boolean);
+			if (files.some((f) => isDocumentationFile(f))) {
+				return true;
+			}
+		}
+		const last = spawnSync("git", ["diff", "--name-only", "HEAD~1"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (last.status === 0) {
+			const files = last.stdout.split("\n").filter(Boolean);
+			return files.some((f) => isDocumentationFile(f));
+		}
+		return false;
+	} catch {
+		return false;
+	}
+}

package/src/policies/git.ts

@@ -0,0 +1,288 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { GitInvocation } from "../lib/types.ts";
+import {
+	getWorkspaceRoot,
+	getProjectConfig,
+} from "../lib/state.ts";
+import {
+	unwrapShellWords,
+	splitShellSegments,
+} from "../lib/utils.ts";
+
+export const PROTECTED_BRANCHES = new Set(["main", "master"]);
+
+export const PUSH_TO_MAIN_RE =
+	/\bgit\s+push\b[^|;&]*(?:^|\s)\+?[\w./-]*:(?:main|master)(?![\w./-])|\bgit\s+push\b[^|;&]*(?:\s|\/)(?:main|master)(?![\w./-])/;
+
+export const GIT_BRANCH_CREATE_RE =
+	/\bgit\s+(?:checkout\s+-b|switch\s+(?:-c|--create))\b/;
+
+const GIT_DIR_OPTION_TAKES_VALUE = new Set([
+	"-C",
+	"--git-dir",
+	"--work-tree",
+	"-c",
+	"--config-env",
+	"--namespace",
+]);
+const GIT_DIR_OPTION_PREFIXED =
+	/^(--git-dir=|--work-tree=|--namespace=|-c\S|--config-env=)/;
+const GIT_GLOBAL_BOOLEAN_OPTIONS = new Set([
+	"--version",
+	"--help",
+	"--no-pager",
+	"-p",
+	"--paginate",
+	"--bare",
+	"--literal-pathspecs",
+	"--glob-pathspecs",
+	"--noglob-pathspecs",
+	"--icase-pathspecs",
+	"--no-optional-locks",
+	"--exec-path",
+]);
+
+export function parseGitInvocation(command: string): GitInvocation | undefined {
+	const root = getWorkspaceRoot();
+	const tokens = unwrapShellWords(command);
+	if (tokens[0] !== "git") return undefined;
+	let i = 1;
+	let repoDir = root;
+	let sawDirOption = false;
+	while (i < tokens.length) {
+		const tok = tokens[i]!;
+		if (GIT_DIR_OPTION_TAKES_VALUE.has(tok)) {
+			const value = tokens[i + 1];
+			if (value === undefined) return { repoDir, rest: "" };
+			if (tok === "-C" || tok === "--git-dir") {
+				repoDir = resolve(root, value);
+				sawDirOption = true;
+			}
+			i += 2;
+			continue;
+		}
+		if (GIT_DIR_OPTION_PREFIXED.test(tok)) {
+			if (tok.startsWith("--git-dir=")) {
+				repoDir = resolve(root, tok.slice("--git-dir=".length));
+				sawDirOption = true;
+			}
+			i += 1;
+			continue;
+		}
+		if (GIT_GLOBAL_BOOLEAN_OPTIONS.has(tok)) {
+			i += 1;
+			continue;
+		}
+		break;
+	}
+	if (!sawDirOption) repoDir = root;
+	return { repoDir, rest: tokens.slice(i).join(" ") };
+}
+
+export function normalizeGitCommands(command: string): string {
+	return splitShellSegments(command)
+		.map((segment) => {
+			const parsed = parseGitInvocation(segment);
+			return parsed ? `git ${parsed.rest}` : segment;
+		})
+		.join(" ; ");
+}
+
+export const GIT_WRITE_RE =
+	/\bgit\s+(commit|merge|rebase|cherry-pick|revert|stash\s+pop|apply|am|restore|reset|update-ref|filter-branch)\b|\bgit\s+branch\s+(?:[^|;&]*\s)?-[dDM]\b/;
+
+export function currentGitBranch(root: string): string | undefined {
+	const result = spawnSync("git", ["branch", "--show-current"], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 10_000,
+	});
+	if (result.status === 0 && result.stdout.trim()) {
+		return result.stdout.trim();
+	}
+	try {
+		const head = readFileSync(resolve(root, ".git", "HEAD"), "utf8").trim();
+		const match = head.match(/^ref:\s+refs\/heads\/(\S+)/);
+		if (match) return match[1];
+	} catch {}
+	if (result.status === 0) return "";
+	return undefined;
+}
+
+export function getProtectedBranches(root: string): Set<string> {
+	const cfg = getProjectConfig(root);
+	const customBranches = Array.isArray(cfg.protectedBranches)
+		? cfg.protectedBranches
+		: [];
+	return new Set([...PROTECTED_BRANCHES, ...customBranches]);
+}
+
+/** True when `branch` is protected for the repository at `root`. */
+export function isProtectedBranchName(branch: string, root: string): boolean {
+	if (!branch) return false;
+	return getProtectedBranches(root).has(branch);
+}
+
+function escapeRegExp(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Returns the protected branch a `git push` command targets as its destination,
+ * if any. Covers bare refspecs (`git push origin <branch>`) and colon forms
+ * (`git push origin HEAD:<branch>`, `:<branch>` deletion, `+<branch>` forced),
+ * for every protected branch - built-in and configured - of the repository.
+ */
+export function pushedProtectedBranchIn(pushCommand: string, root: string): string | undefined {
+	for (const branch of getProtectedBranches(root)) {
+		const escaped = escapeRegExp(branch);
+		const re = new RegExp(
+			`(?:^|\\s)\\+?[\\w./-]*:${escaped}(?![\\w./-])` +
+				`|(?:\\s|\\/)${escaped}(?![\\w./-])`,
+		);
+		if (re.test(pushCommand)) return branch;
+	}
+	return undefined;
+}
+
+export function onProtectedBranch(root: string): boolean {
+	return isProtectedBranchName(currentGitBranch(root) ?? "", root);
+}
+
+export function branchGuardReason(): string {
+	return (
+		"Blocked: the workspace is on a protected branch. " +
+		"Create a feature branch first - e.g. " +
+		"`git switch -c feat/description` - and make all changes there, " +
+		"then open a PR. Direct changes on protected branches are not allowed."
+	);
+}
+
+export function isBranchAlreadyMergedOrClosed(
+	root: string,
+	branch: string,
+): { merged: boolean; reason?: string } {
+	if (!branch || PROTECTED_BRANCHES.has(branch)) {
+		return { merged: false };
+	}
+
+	for (const base of ["origin/HEAD", "origin/main", "origin/master", "main", "master"]) {
+		const check = spawnSync("git", ["merge-base", "--is-ancestor", branch, base], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (check.status === 0) {
+			const unmerged = spawnSync("git", ["rev-list", `${base}..${branch}`, "--count"], {
+				cwd: root,
+				encoding: "utf8",
+				timeout: 5_000,
+			});
+			if (unmerged.status === 0 && unmerged.stdout.trim() === "0") {
+				return {
+					merged: true,
+					reason: `Branch '${branch}' is already merged into '${base}'. Create a fresh feature branch for new changes.`,
+				};
+			}
+		}
+	}
+
+	try {
+		const ghRes = spawnSync(
+			"gh",
+			["pr", "list", "--head", branch, "--state", "all", "--json", "number,state,title", "--limit", "1"],
+			{ cwd: root, encoding: "utf8", timeout: 8_000 },
+		);
+		if (ghRes.status === 0 && ghRes.stdout.trim()) {
+			const prs = JSON.parse(ghRes.stdout.trim());
+			if (Array.isArray(prs) && prs.length > 0) {
+				const pr = prs[0];
+				if (pr && (pr.state === "MERGED" || pr.state === "CLOSED")) {
+					return {
+						merged: true,
+						reason: `Branch '${branch}' is associated with an already ${pr.state.toLowerCase()} GitHub PR (#${pr.number}: ${pr.title ?? ""}). Create a fresh feature branch for new changes.`,
+					};
+				}
+			}
+		}
+	} catch {}
+
+	try {
+		const azRes = spawnSync(
+			"az",
+			["repos", "pr", "list", "--source-branch", branch, "--status", "all", "--query", "[0].{id:pullRequestId, status:status, title:title}", "-o", "json"],
+			{ cwd: root, encoding: "utf8", timeout: 8_000 },
+		);
+		if (azRes.status === 0 && azRes.stdout.trim()) {
+			const pr = JSON.parse(azRes.stdout.trim());
+			if (pr && typeof pr === "object" && (pr.status === "completed" || pr.status === "abandoned")) {
+				return {
+					merged: true,
+					reason: `Branch '${branch}' is associated with an already ${pr.status} Azure DevOps PR (#${pr.id}: ${pr.title ?? ""}). Create a fresh feature branch for new changes.`,
+				};
+			}
+		}
+	} catch {}
+
+	return { merged: false };
+}
+
+export function checkMergeConflicts(root: string): {
+	hasConflicts: boolean;
+	baseBranch?: string;
+	reason?: string;
+} {
+	const candidates = ["origin/HEAD", "origin/main", "origin/master", "main", "master"];
+	for (const base of candidates) {
+		const mergeBaseRes = spawnSync("git", ["merge-base", "HEAD", base], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (mergeBaseRes.status !== 0 || !mergeBaseRes.stdout.trim()) continue;
+		const mergeBase = mergeBaseRes.stdout.trim();
+
+		const treeRes = spawnSync("git", ["merge-tree", mergeBase, "HEAD", base], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 10_000,
+		});
+		if (treeRes.status === 0 && treeRes.stdout.includes("<<<<<<<")) {
+			return {
+				hasConflicts: true,
+				baseBranch: base,
+				reason: `Branch has merge conflicts with base branch '${base}'. Rebase or merge '${base}' to resolve all conflicts before opening a PR or handing off.`,
+			};
+		}
+	}
+	return { hasConflicts: false };
+}
+
+export function checkBranchBaseIsUpToDate(root: string): {
+	isBehind: boolean;
+	count?: number;
+	baseRef?: string;
+	reason?: string;
+} {
+	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.`,
+				};
+			}
+		}
+	}
+	return { isBehind: false };
+}

package/src/policies/interpreter.ts

@@ -0,0 +1,28 @@
+export function extractInterpreterPayload(segment: string): string[] {
+	const payloads: string[] = [];
+	const inlineMatch = segment.match(
+		/\b(?:python3?|node|perl|ruby|osascript)\s+(?:-[a-zA-Z]*[ce]\s+)(?:"([^"]*)"|'([^']*)')/i,
+	);
+	if (inlineMatch?.[1] || inlineMatch?.[2]) {
+		payloads.push(inlineMatch[1] ?? inlineMatch[2] ?? "");
+	}
+	const psMatch = segment.match(
+		/\b(?:powershell|pwsh)\s+(?:-[a-zA-Z]*enc[a-zA-Z]*\s+)([A-Za-z0-9+/=]+)/i,
+	);
+	if (psMatch?.[1]) {
+		try {
+			const buf = Buffer.from(psMatch[1], "base64");
+			payloads.push(buf.toString("utf8"), buf.toString("utf16le"));
+		} catch {}
+	}
+	const b64PipeMatch = segment.match(
+		/echo\s+["']?([A-Za-z0-9+/=]{4,})["']?\s*\|\s*base64\s+(?:-[a-zA-Z]*d[a-zA-Z]*|--decode)\s*\|\s*(?:bash|sh|zsh)/i,
+	);
+	if (b64PipeMatch?.[1]) {
+		try {
+			const buf = Buffer.from(b64PipeMatch[1], "base64");
+			payloads.push(buf.toString("utf8"), buf.toString("utf16le"));
+		} catch {}
+	}
+	return payloads;
+}

package/src/policies/mcp.ts

@@ -0,0 +1,25 @@
+export const MCP_MUTATION_VERB_RE =
+	/(?:^|_)(?:create|update|delete|remove|merge|push|close|edit|set|fork|trigger|cancel|rerun|add|assign|approve|complete|abandon)(?:_|$)/;
+export const MCP_READ_ONLY_RE =
+	/(?:^|_)(?:get|list|search|show|query|describe|find|read|status|diff|log)(?:_|$)/;
+
+export const GUARDED_MCP_SERVERS = new Set([
+	"github",
+	"gh",
+	"azure",
+	"azmcp",
+	"ado",
+	"devops",
+	"azuredevops",
+]);
+
+export function mcpMutationTool(toolName: string): string | undefined {
+	if (!MCP_MUTATION_VERB_RE.test(toolName) || MCP_READ_ONLY_RE.test(toolName)) {
+		return undefined;
+	}
+	const tokens = toolName.toLowerCase().split(/[^a-z0-9]+/);
+	if (tokens.some((t) => GUARDED_MCP_SERVERS.has(t))) {
+		return "GitHub/Azure DevOps";
+	}
+	return undefined;
+}