@brainervirus/workit-core 8.10.0 → 8.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.10.0",
+  "version": "8.11.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/autonomy.ts

@@ -13,7 +13,10 @@
 //   agent from raising its own ceiling by accident, not an adversarial one —
 //   a process that drives a pseudo-terminal or edits the file directly can
 //   still defeat it; the host's permission prompt is the hard boundary.
-// - `release` has no consuming verb yet; it is reserved, not enforced.
+// - `release` gates `workit git push --release`: pushing the git-flow
+//   production and develop branches (fast-forward only) and `v*` tags whose
+//   commit already landed (a tag never moves). Outside git-flow it pushes
+//   tags only. It needs `push` too.
 // - Defaults (D4) when a kind is absent: push, pr and rerun are allowed;
 //   merge and release need an explicit grant. The default ceiling is a stack
 //   opened, CI green and independently verified: "verified, ready".
@@ -25,7 +28,8 @@
 // - Explicitly configured grants require an account (design §2.0 Identity):
 //   a workspace with grants but no `vcs.account` cannot push, open or merge
 //   through a forge, so a personal grant never rides a work credential.
-// - Protected-branch pushes stay denied by the git verbs, and the host
+// - Protected-branch pushes stay denied by the git verbs (except the git-flow
+//   release push above), and the host
 //   permission prompt applies in addition: a host deny always wins.
 import { copyFileSync, existsSync } from "node:fs";
 import os from "node:os";

package/src/core/branch-policy.ts

@@ -13,7 +13,7 @@ const PREFIXES = {
  * Local branch names plus origin's remote-tracking ones (`origin/develop`
  * counts as `develop`; a fork or mirror remote's branches do not).
  */
-const branchNames = (workspaceRoot: string): Set<string> => {
+export const branchNames = (workspaceRoot: string): Set<string> => {
   const r = spawnSync(
     "git",
     ["for-each-ref", "--format=%(refname)", "refs/heads", "refs/remotes/origin"],
@@ -32,6 +32,13 @@ const branchNames = (workspaceRoot: string): Set<string> => {
   );
 };
 
+/**
+ * The git-flow production branch: main when it exists (locally or on
+ * origin), else master, else main.
+ */
+export const productionBranchOf = (names: ReadonlySet<string>): string =>
+  names.has("main") ? "main" : names.has("master") ? "master" : "main";
+
 export const detectBranchPolicy = (workspaceRoot: string) => {
   const names = branchNames(workspaceRoot);
   const develop = names.has("develop");

package/src/core/branch.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import path from "node:path";
-import { repoBranchPreset } from "./branch-policy";
+import { branchNames, productionBranchOf, repoBranchPreset } from "./branch-policy";
 import { matchCommitFlavor } from "./commit-flavors";
 import { gitContext } from "./git";
 import {
@@ -142,14 +142,105 @@ export type CommitMessagePolicyCheck =
       error: string;
     };
 
+/** Prefixes agents reach for, mapped to the git-flow kind that means the same. */
+const KIND_SYNONYMS: Readonly<Record<string, string>> = {
+  fix: "bugfix",
+  fixes: "bugfix",
+  bug: "bugfix",
+  bugs: "bugfix",
+  bugfixes: "bugfix",
+  feat: "feature",
+  features: "feature",
+  chore: "feature",
+  docs: "feature",
+  doc: "feature",
+  refactor: "feature",
+  test: "feature",
+  tests: "feature",
+  ci: "feature",
+  build: "feature",
+  perf: "feature",
+  style: "feature",
+  deps: "feature",
+  task: "feature",
+  enhancement: "feature",
+  hot: "hotfix",
+  hotfixes: "hotfix",
+  releases: "release",
+  rel: "release",
+};
+
+/** The `<kind>/` prefixes an allowed-pattern list names (`feature/*` -> feature). */
+export const allowedKinds = (allowed: readonly RegExp[]): string[] => [
+  ...new Set(
+    allowed
+      // RegExp#source escapes the slash: `^feature\/.*$`.
+      .map((pattern) => /^\^([\w.-]+)\\?\/\.\*\$$/u.exec(pattern.source)?.[1]?.toLowerCase())
+      .filter((kind): kind is string => Boolean(kind)),
+  ),
+];
+
+const editDistance = (a: string, b: string): number => {
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i++) {
+    let previous = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const saved = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+      previous = saved;
+    }
+  }
+  return row[b.length];
+};
+
+/**
+ * The allowed name closest to `name`: its prefix mapped through the usual
+ * synonyms (fix/ -> bugfix/, chore/ -> feature/), else the kind within two
+ * edits, else feature/ (or the first kind); the rest of the name is kept.
+ * Null when the policy names no kinds.
+ */
+export const suggestBranchName = (name: string, kinds: readonly string[]): string | null => {
+  if (!kinds.length) return null;
+  const slash = name.indexOf("/");
+  const prefix = slash > 0 ? name.slice(0, slash).toLowerCase() : "";
+  const rest = (slash > 0 ? name.slice(slash + 1) : name) || "name";
+  const synonym = KIND_SYNONYMS[prefix];
+  const near = kinds
+    .map((kind) => ({ kind, distance: editDistance(prefix, kind) }))
+    .filter((entry) => prefix && entry.distance <= 2)
+    .toSorted((a, b) => a.distance - b.distance)[0]?.kind;
+  const kind =
+    (synonym && kinds.includes(synonym) ? synonym : null) ??
+    near ??
+    (kinds.includes("feature") ? "feature" : kinds[0]);
+  return `${kind}/${rest}`;
+};
+
+const kindList = (kinds: readonly string[]) => kinds.map((kind) => `${kind}/`).join(", ");
+
+/** ` (fix/ is bugfix/, chore/ is feature/)`, naming only the kinds this policy allows. */
+const aliasNote = (kinds: readonly string[]): string => {
+  const notes = [
+    ["fix", "bugfix"],
+    ["chore", "feature"],
+  ]
+    .filter(([, kind]) => kinds.includes(kind))
+    .map(([alias, kind]) => `${alias}/ is ${kind}/`);
+  return notes.length ? ` (${notes.join(", ")})` : "";
+};
+
 export const validateBranchNamePolicy = (
   name: string,
   policy: BranchNamePolicy,
   source: string,
 ): BranchNamePolicyCheck => {
   const allowed = policy.allowed.map((pattern) => `/${pattern.source}/${pattern.flags}`);
+  const kinds = allowedKinds(policy.allowed);
   if (policy.protected.has(name.toLowerCase())) {
-    const correction = `choose a non-protected branch matching one of: ${allowed.join(", ")}`;
+    const correction = kinds.length
+      ? `choose a non-protected branch of an allowed kind (${kindList(kinds)}), e.g. ${kinds[0]}/<slug>: workit git branch --kind ${kinds[0]} --slug <slug>`
+      : `choose a non-protected branch matching one of: ${allowed.join(", ")}`;
     return {
       ok: false,
       rule: "protected_ref",
@@ -160,7 +251,11 @@ export const validateBranchNamePolicy = (
     };
   }
   if (!policy.allowed.some((pattern) => pattern.test(name))) {
-    const correction = `choose a branch matching one of: ${allowed.join(", ")}`;
+    const suggestion = suggestBranchName(name, kinds);
+    const correction =
+      suggestion && policy.allowed.some((pattern) => pattern.test(suggestion))
+        ? `use ${JSON.stringify(suggestion)}; the allowed kinds are ${kindList(kinds)} (workit git branch ${suggestion})`
+        : `choose a branch matching one of: ${allowed.join(", ")}`;
     return {
       ok: false,
       rule: "allowed_pattern",
@@ -272,6 +367,178 @@ export const resolveBranchPolicyFor = (workspaceRoot: string, profileName?: stri
 export const resolveCommitPolicyFor = (workspaceRoot: string, profileName?: string) =>
   effectiveWorkspacePolicy(workspaceRoot, "commit", profileName).commitPolicy;
 
+// ---------------------------------------------------------------------------
+// git-flow routes: where each branch kind starts and lands
+
+export const BRANCH_KINDS = ["feature", "bugfix", "release", "hotfix"] as const;
+export type BranchKind = (typeof BRANCH_KINDS)[number];
+
+/** The git-flow kind a branch name's prefix names (`release/4.1.0` -> release), or null. */
+export const branchKindOf = (name: string | null | undefined): BranchKind | null => {
+  const prefix = name?.split("/", 1)[0]?.toLowerCase() ?? "";
+  return name?.includes("/") && (BRANCH_KINDS as readonly string[]).includes(prefix)
+    ? (prefix as BranchKind)
+    : null;
+};
+
+export type GitFlow = {
+  /** The integration branch: the workspace's `developBranch`, else develop. */
+  develop: string;
+  /** The production branch: main, else master. */
+  production: string;
+  /** The develop branch exists locally or on origin. */
+  developExists: boolean;
+};
+
+export type FlowRoute = {
+  kind: BranchKind;
+  /** Where a new branch of this kind starts. */
+  base: string;
+  /** Where its PR lands. */
+  target: string;
+  /** The branch that must receive the landed work afterwards (release/hotfix -> develop). */
+  mergeBack: string | null;
+};
+
+/**
+ * The repository's git-flow branches when the resolved branch policy is the
+ * gitflow preset; null for github-flow, trunk-based or custom (they route
+ * every kind to the default target). `integration` is the resolved default
+ * target: used as develop when the workspace names no developBranch and it
+ * is not the production branch.
+ */
+export const gitFlowOf = (root: string, integration?: string | null): GitFlow | null => {
+  try {
+    if (resolveBranchPolicyFor(root).preset !== "gitflow") return null;
+    const selected = resolveRuntimeWorkspacePolicy(
+      root,
+      "branch",
+      process.env.WORKFLOW_PROFILE?.trim() || undefined,
+    ).policy as WorkspaceBranchPolicy | undefined;
+    const names = branchNames(root);
+    const production = productionBranchOf(names);
+    const develop =
+      selected?.developBranch?.trim() ||
+      (integration && integration.toLowerCase() !== production ? integration : "develop");
+    return { develop, production, developExists: names.has(develop) };
+  } catch {
+    return null;
+  }
+};
+
+/** git-flow: feature, bugfix and release start from develop; hotfix from production. */
+export const flowRoute = (flow: GitFlow, kind: BranchKind): FlowRoute =>
+  kind === "hotfix"
+    ? { kind, base: flow.production, target: flow.production, mergeBack: flow.develop }
+    : kind === "release"
+      ? { kind, base: flow.develop, target: flow.production, mergeBack: flow.develop }
+      : { kind, base: flow.develop, target: flow.develop, mergeBack: null };
+
+/**
+ * What `workit git push --release` may push, per preset: git-flow its
+ * production and develop branches; github-flow, trunk-based and custom no
+ * branch (only tags). `production` is the branch a release tag's commit must
+ * already be on (git-flow production, else the default target). Empty when
+ * the policy cannot be read.
+ */
+export const releaseBranchesOf = (
+  cwd: string,
+): { preset: string; branches: string[]; production: string | null } => {
+  try {
+    const resolved = resolveBranchPolicyFor(cwd);
+    const flow = resolved.preset === "gitflow" ? gitFlowOf(cwd) : null;
+    // Outside git-flow a protected trunk only moves through a reviewed PR:
+    // --release pushes tags there, nothing else.
+    return {
+      preset: resolved.preset,
+      branches: flow ? [flow.production, flow.develop] : [],
+      production: flow ? flow.production : resolved.defaultTargetBranch,
+    };
+  } catch {
+    return { preset: "unknown", branches: [], production: null };
+  }
+};
+
+/** A branch `workit git push --release` may push here. */
+export const releaseBranch = (cwd: string, branch: string): boolean =>
+  releaseBranchesOf(cwd).branches.some((name) => name.toLowerCase() === branch.toLowerCase());
+
+/** `origin/develop`, `refs/remotes/origin/develop`, `refs/heads/develop` -> develop. */
+export const shortBranch = (ref: string): string =>
+  ref.replace(/^refs\/heads\//u, "").replace(/^(?:refs\/remotes\/)?origin\//u, "");
+
+/**
+ * A git-flow mismatch: an explicit base or PR target that is the other
+ * long-lived branch than the kind's route (a feature from main, a hotfix
+ * from develop). Only once develop exists, so a main-only repository on the
+ * gitflow preset keeps working. Null when it fits.
+ */
+export const flowMismatch = (
+  flow: GitFlow | null,
+  kind: BranchKind | null,
+  ref: string,
+  role: "base" | "target",
+): string | null => {
+  if (!flow || !kind || !flow.developExists) return null;
+  const route = flowRoute(flow, kind);
+  const expected = role === "base" ? route.base : route.target;
+  const given = shortBranch(ref).toLowerCase();
+  const longLived = [flow.develop, flow.production].map((name) => name.toLowerCase());
+  // A release or hotfix PR into develop is the git-flow back-merge.
+  const backMerge = role === "target" && route.mergeBack?.toLowerCase() === given;
+  if (!longLived.includes(given) || given === expected.toLowerCase() || backMerge) return null;
+  return role === "base"
+    ? `gitflow_base: git-flow starts ${kind}/* from ${expected}, not ${shortBranch(ref)}`
+    : `gitflow_target: git-flow lands ${kind}/* on ${expected}, not ${shortBranch(ref)}`;
+};
+
+/**
+ * One line for an agent about to create a branch at `cwd`: the allowed kinds
+ * and where each starts. Plain text (no `workit git` command), so it fits an
+ * agent that runs git itself. Null when the policy cannot be read.
+ */
+export const branchGuidance = (cwd: string): string | null => {
+  try {
+    const patterns = branchPolicySnapshotFor(cwd).namePolicy.allowed;
+    const kinds = allowedKinds(patterns);
+    const kindShaped = new Set(kinds.map((kind) => branchGlobPattern(`${kind}/*`).source));
+    const anyName = patterns.some((pattern) => pattern.source === "^.*$");
+    const others = patterns
+      .filter((pattern) => !kindShaped.has(pattern.source))
+      .map((pattern) => globOf(pattern));
+    const allowed = anyName
+      ? "Any non-protected branch name is allowed here."
+      : `${kinds.length ? `Allowed branch kinds here: ${kindList(kinds)}${aliasNote(kinds)}` : "Allowed branch names here:"}${others.length ? `${kinds.length ? "; also" : ""} names matching ${others.join(", ")}` : ""}; anything else is denied.`;
+    const resolved = vcsConfig("resolve", cwd);
+    const integration =
+      resolved.ok === false ? null : String(resolved.defaultTargetBranch ?? "") || null;
+    const flow = resolved.releaseTrack?.track ? null : gitFlowOf(cwd, integration);
+    if (flow?.developExists)
+      return `${allowed} git-flow: feature/, bugfix/ and release/ start from origin/${flow.develop}, hotfix/ from origin/${flow.production}; feature/ and bugfix/ land on ${flow.develop}, release/ and hotfix/ on ${flow.production}.`;
+    // Name only a base that exists: a preset default (custom's develop,
+    // github-flow's main) may not.
+    const names = branchNames(cwd);
+    const configured = String(resolved.baseBranch ?? integration ?? "") || null;
+    const trunk = productionBranchOf(names);
+    const base =
+      configured && names.has(configured)
+        ? `Branch from origin/${configured}.`
+        : names.has(trunk)
+          ? `Branch from origin/${trunk}${configured ? ` (the default target ${configured} does not exist here)` : ""}.`
+          : "No base branch exists here yet; pass the base explicitly.";
+    return `${allowed} ${base}`;
+  } catch {
+    return null;
+  }
+};
+
+/** An allowed pattern back as its glob (`^fix-.*$` -> fix-*). */
+const globOf = (pattern: RegExp): string =>
+  pattern.source
+    .replace(/^\^|\$$/gu, "")
+    .replaceAll(".*", "*")
+    .replace(/\\(.)/gu, "$1");
+
 const policy = (root: string) => resolveBranchPolicyFor(root);
 const allowedBranch = (root: string, name: string) =>
   policy(root).allowed.some((r) => r.test(name));

package/src/core/route-intent.ts

@@ -1,37 +1,165 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { inWorkitWorkspace, rawInvocations } from "../hooks/raw-git";
+import type { ShellDialect } from "../hooks/shell-words";
 import { validateBranchNameFor, type BranchNamePolicyCheck } from "./branch";
 
-// ponytail: recognize direct literal Git forms only; expand coverage if users need shell AST support.
-export const shellBranchTarget = (command: string): string | null => {
-  if (
-    !command.trim() ||
-    /[\r\n;&|<>`'"$()\\*?{}~!#]/u.test(command) ||
-    command.includes("[") ||
-    command.includes("]")
-  )
-    return null;
-
-  const args = command.trim().split(/\s+/u);
-  if (args[0] !== "git") return null;
-  const option = args[2];
+/** A name a shell cannot settle before running (`$X`, `` `cmd` ``): never judged. */
+const UNKNOWABLE = /[$`*?[\]{}~]/u;
+
+const SWITCH_CREATE = new Set(["-c", "--create", "-C", "--force-create", "--orphan"]);
+const CHECKOUT_CREATE = new Set(["-b", "-B", "--orphan"]);
+const WORKTREE_CREATE = new Set(["-b", "-B"]);
+/** `git branch` options that list, delete or configure: no branch is created. */
+const BRANCH_NO_CREATE = new Set(
+  ["-d", "-D", "--delete", "-l", "--list", "-a", "--all", "-r", "--remotes", "--show-current"]
+    .concat(["-v", "-vv", "--verbose", "--contains", "--no-contains", "--merged", "--no-merged"])
+    .concat(["--points-at", "--sort", "--format", "--column", "--no-column", "-u"])
+    .concat(["--set-upstream-to", "--unset-upstream", "--edit-description", "-i", "--ignore-case"]),
+);
+/** `git branch -m|-c [<old>] <new>`: a rename or copy creates `<new>`. */
+const BRANCH_RENAME = new Set(["-m", "-M", "--move", "-c", "-C", "--copy"]);
+
+/** The value of `flag` in `args` (`-c x`, `-cx`, `--create=x`), or null. */
+const flagValue = (args: readonly string[], flags: ReadonlySet<string>): string | null => {
+  for (let index = 1; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--") return null;
+    if (flags.has(arg)) return args[index + 1] ?? null;
+    const eq = arg.indexOf("=");
+    if (arg.startsWith("--") && eq > 0 && flags.has(arg.slice(0, eq))) return arg.slice(eq + 1);
+    // An attached short value: `-cchore/x`.
+    if (!arg.startsWith("--") && arg.length > 2 && flags.has(arg.slice(0, 2))) return arg.slice(2);
+  }
+  return null;
+};
+
+/** `git worktree add` options that take a value. */
+const WORKTREE_VALUES = new Set(["--reason"]);
+
+/**
+ * `git worktree add [-b|-B <b>] <path> [<commit-ish>]`: the -b name, or, with
+ * only a path (no -b, -B, --detach or commit-ish), the branch git names after
+ * the path's last component.
+ */
+const worktreeTarget = (args: readonly string[]): string | null => {
+  const named = flagValue(args, WORKTREE_CREATE);
+  if (named !== null) return named;
+  const positionals: string[] = [];
+  for (let index = 1; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--detach" || arg === "-d") return null;
+    if (WORKTREE_VALUES.has(arg)) index++;
+    else if (!arg.startsWith("-")) positionals.push(arg);
+  }
+  if (positionals.length !== 1) return null;
+  const base = positionals[0].split(/[\\/]/u).findLast(Boolean) ?? "";
+  return base && base !== "." && base !== ".." ? base : null;
+};
+
+/** The branch `git branch …` creates (plain, rename or copy), or null. */
+const branchCommandTarget = (args: readonly string[]): string | null => {
+  let rename = false;
+  const positionals: string[] = [];
+  for (let index = 1; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--") {
+      positionals.push(...args.slice(index + 1));
+      break;
+    }
+    const flag = arg.split("=", 1)[0];
+    if (BRANCH_NO_CREATE.has(flag)) return null;
+    if (BRANCH_RENAME.has(flag)) rename = true;
+    else if (!arg.startsWith("-")) positionals.push(arg);
+  }
+  if (positionals.length < 1 || positionals.length > 2) return null;
+  return rename ? (positionals.at(-1) ?? null) : positionals[0];
+};
+
+/**
+ * The branch one git invocation creates: `switch -c|-C|--create <b>`,
+ * `checkout -b|-B <b>`, `branch [-m|-c] <b> [start]` and `worktree add -b|-B
+ * <b>`, wherever the option stands. `args` start at the subcommand (after
+ * git's global options). Null when it creates none.
+ */
+export const gitBranchCreation = (args: readonly string[]): string | null => {
+  const [sub, second] = args;
   const target =
-    args[1] === "switch" &&
-    ["-c", "--create", "-C", "--force-create"].includes(option ?? "") &&
-    (args.length === 4 || args.length === 5)
-      ? args[3]
-      : args[1] === "checkout" &&
-          ["-b", "-B"].includes(option ?? "") &&
-          (args.length === 4 || args.length === 5)
-        ? args[3]
-        : args[1] === "branch" && (args.length === 3 || args.length === 4)
-          ? args[2]
-          : null;
-  return target && !target.startsWith("-") ? target : null;
+    sub === "switch"
+      ? flagValue(args, SWITCH_CREATE)
+      : sub === "checkout"
+        ? flagValue(args, CHECKOUT_CREATE)
+        : sub === "branch"
+          ? branchCommandTarget(args)
+          : sub === "worktree" && second === "add"
+            ? worktreeTarget(args.slice(1))
+            : null;
+  return target && !target.startsWith("-") && !UNKNOWABLE.test(target) ? target : null;
+};
+
+export type ShellBranchTarget = {
+  branch: string;
+  /** The directory git runs in, relative to the hook's cwd; undefined when unknowable. */
+  dir: string | null | undefined;
+};
+
+/**
+ * Every branch a shell command creates, through the raw-git tokenizer: `&&`,
+ * `;` and `|` chains, `cd`/`pushd` and `git -C`, env prefixes and wrappers,
+ * quoted names and `bash -c` scripts.
+ */
+export const shellBranchTargets = (
+  command: string,
+  dialect: ShellDialect = "posix",
+): ShellBranchTarget[] => {
+  if (!/\bgit\b/u.test(command)) return [];
+  const found: ShellBranchTarget[] = [];
+  for (const invocation of rawInvocations(command, dialect)) {
+    if (invocation.tool !== "git") continue;
+    const branch = gitBranchCreation(invocation.args);
+    if (branch) found.push({ branch, dir: invocation.dir });
+  }
+  return found;
 };
 
+/** The first branch a shell command creates, or null. */
+export const shellBranchTarget = (command: string): string | null =>
+  shellBranchTargets(command)[0]?.branch ?? null;
+
+/** The branch already exists in `dir`: resetting or checking it out is not a new name. */
+const localBranchExists = (dir: string, branch: string): boolean =>
+  spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], {
+    cwd: dir,
+    stdio: "ignore",
+    timeout: 5_000,
+  }).status === 0;
+
+/**
+ * The branch policy verdict for every new branch a shell command creates,
+ * each checked in the directory git runs in (a linked worktree resolves to
+ * its main checkout's workspace). A command that runs in the hook's cwd is
+ * judged there. One that changes directory is judged only when that
+ * directory is known, already exists and is in a Workit workspace: a scratch
+ * repository (`cd "$(mktemp -d)"`, `git init x && cd x`, a fresh clone) is
+ * not the cwd workspace's business. A name that already exists locally is
+ * skipped (`git branch -f legacy HEAD`). Null when no new branch is judged;
+ * the first violation otherwise.
+ */
 export const shellBranchPolicyViolation = (
   root: string,
   command: string,
+  dialect: ShellDialect = "posix",
 ): BranchNamePolicyCheck | null => {
-  const target = shellBranchTarget(command);
-  return target === null ? null : validateBranchNameFor(root, target);
+  let judged = false;
+  for (const target of shellBranchTargets(command, dialect)) {
+    if (target.dir === undefined) continue;
+    const dir = target.dir === null ? root : path.resolve(root, target.dir);
+    if (target.dir !== null && (!existsSync(dir) || !inWorkitWorkspace(dir))) continue;
+    if (localBranchExists(dir, target.branch)) continue;
+    judged = true;
+    const check = validateBranchNameFor(dir, target.branch);
+    if (!check.ok) return check;
+  }
+  return judged ? { ok: true } : null;
 };

package/src/forge/github.ts

@@ -27,7 +27,7 @@ const CONTEXTS = `contexts(first: 100, after: $contexts) { pageInfo { hasNextPag
 
 export const PR_STATUS_QUERY = `query($owner: String!, $name: String!, $number: Int!, $threads: String, $contexts: String) { repository(owner: $owner, name: $name) { pullRequest(number: $number) { ${PR_FIELDS} ${THREADS} commits(last: 1) { nodes { commit { oid statusCheckRollup { state ${CONTEXTS} } } } } } } }`;
 
-export const FIND_PR_QUERY = `query($owner: String!, $name: String!, $head: String!) { repository(owner: $owner, name: $name) { pullRequests(headRefName: $head, first: 20, orderBy: { field: CREATED_AT, direction: DESC }) { nodes { number url state headRefName headRefOid headRepositoryOwner { login } } } } }`;
+export const FIND_PR_QUERY = `query($owner: String!, $name: String!, $head: String!) { repository(owner: $owner, name: $name) { pullRequests(headRefName: $head, first: 20, orderBy: { field: CREATED_AT, direction: DESC }) { nodes { number url state baseRefName headRefName headRefOid headRepositoryOwner { login } } } } }`;
 
 const READY_MUTATION = `mutation($id: ID!) { markPullRequestReadyForReview(input: { pullRequestId: $id }) { pullRequest { isDraft } } }`;
 const DRAFT_MUTATION = `mutation($id: ID!) { convertPullRequestToDraft(input: { pullRequestId: $id }) { pullRequest { isDraft } } }`;
@@ -351,6 +351,7 @@ export function createGitHubForge(options: {
               number: number;
               url: string;
               state: string;
+              baseRefName?: string;
               headRefName: string;
               headRefOid: string | null;
               headRepositoryOwner: { login: string } | null;
@@ -365,11 +366,21 @@ export function createGitHubForge(options: {
       const ours = nodes.filter(
         (node) =>
           node.headRefName === head &&
+          (!match.base || node.baseRefName === undefined || node.baseRefName === match.base) &&
           ((match.owner !== null &&
             node.headRepositoryOwner?.login.toLowerCase() === match.owner.toLowerCase()) ||
             (match.sha !== null && node.headRefOid === match.sha)),
       );
-      const pick = ours.find((node) => node.state === "OPEN") ?? ours[0];
+      const open = ours.filter((node) => node.state === "OPEN");
+      // No base named and open PRs into several bases (a git-flow release
+      // into main and its back-merge into develop): never guess.
+      if (!match.base && new Set(open.map((node) => node.baseRefName)).size > 1)
+        return failure(
+          "blocked",
+          `ambiguous_pr: ${head} has open pull requests ${open.map((node) => `#${node.number} -> ${node.baseRefName}`).join(", ")}`,
+          `pass --pr <n>, e.g. --pr ${open[0].number}`,
+        );
+      const pick = open[0] ?? ours[0];
       if (!pick) return success(null);
       const ref: PrRef = {
         number: pick.number,

package/src/forge/gitlab.ts

@@ -327,10 +327,18 @@ export function createGitLabForge(options: {
       const matches = list.data.filter(
         (mr) =>
           mr.source_branch === head &&
+          (!match.base || mr.target_branch === undefined || mr.target_branch === match.base) &&
           ((match.projectId !== null && mr.source_project_id === match.projectId) ||
             (match.sha !== null && mr.sha === match.sha)),
       );
-      const pick = matches.find((mr) => mr.state === "opened") ?? matches[0];
+      const open = matches.filter((mr) => mr.state === "opened");
+      if (!match.base && new Set(open.map((mr) => mr.target_branch)).size > 1)
+        return failure(
+          "blocked",
+          `ambiguous_pr: ${head} has open merge requests ${open.map((mr) => `!${mr.iid} -> ${mr.target_branch}`).join(", ")}`,
+          `pass --pr <n>, e.g. --pr ${open[0].iid}`,
+        );
+      const pick = open[0] ?? matches[0];
       return success(
         pick
           ? {

package/src/forge/pr-ops.ts

@@ -22,7 +22,7 @@ import {
   type AutonomySource,
   type DefaultEndpoint,
 } from "../autonomy";
-import { isProtectedTarget } from "../core/branch";
+import { branchKindOf, flowRoute, gitFlowOf, isProtectedTarget } from "../core/branch";
 import { vcsConfig } from "../core/vcs-config";
 import { workspaceReleaseTracks } from "../core/release-tracks";
 import { deleteRemoteBranch } from "../git/ops";
@@ -211,6 +211,7 @@ async function verifiedHead(
   sha: string,
   first: PrRef,
   sleep: Sleep,
+  base: string,
 ): Promise<ForgeResult<PrRef>> {
   let ref = first;
   for (const delay of [0, ...VERIFY_DELAYS_MS]) {
@@ -220,6 +221,7 @@ async function verifiedHead(
       owner: resolved.headRepo.split("/")[0] ?? null,
       projectId: resolved.headProjectId,
       sha,
+      base,
     });
     if (!found.ok) return found;
     if (found.data && found.data.number === first.number) ref = found.data;
@@ -258,10 +260,13 @@ export async function createPullRequest(
       "pass --base <branch>",
     );
 
+  // Head AND base: a release branch with an open PR into main still gets
+  // its back-merge PR into develop.
   const existing = resolved.forge.findPr(branch, {
     owner: resolved.headRepo.split("/")[0] ?? null,
     projectId: resolved.headProjectId,
     sha,
+    base: input.base,
   });
   if (!existing.ok) return existing;
   let created = false;
@@ -281,7 +286,7 @@ export async function createPullRequest(
     ref = made.data;
     created = true;
   }
-  const verified = await verifiedHead(resolved, branch, sha, ref, sleep);
+  const verified = await verifiedHead(resolved, branch, sha, ref, sleep, input.base);
   if (!verified.ok) return verified;
   const row = appendObserved(cwd, {
     type: "pr.created",
@@ -366,13 +371,26 @@ export type MergeOutcome = {
 /**
  * The merge-back a merge into `base` owes: the track whose production branch
  * `base` is, by ownership alone (no --track, no WORKFLOW_RELEASE_TRACK, no
- * history). Best effort: a config problem never stops the pr.merged record.
+ * history); without tracks, a git-flow release/* or hotfix/* landing on the
+ * production branch owes develop. Best effort: a config problem never stops
+ * the pr.merged record.
  */
-const mergeBackFor = (cwd: string, base: string): { track: string | null; branches: string[] } => {
+const mergeBackFor = (
+  cwd: string,
+  base: string,
+  head: string,
+): { track: string | null; branches: string[] } => {
   try {
-    const owners = workspaceReleaseTracks(cwd).tracks.filter(
-      (track) => track.productionBranch === base,
-    );
+    const read = workspaceReleaseTracks(cwd);
+    if (!read.tracks.length) {
+      const flow = gitFlowOf(cwd);
+      const kind = branchKindOf(head);
+      const route = flow && kind ? flowRoute(flow, kind) : null;
+      return route?.mergeBack && route.target === base
+        ? { track: "git-flow", branches: [route.mergeBack] }
+        : { track: null, branches: [] };
+    }
+    const owners = read.tracks.filter((track) => track.productionBranch === base);
     if (owners.length !== 1) return { track: null, branches: [] };
     return {
       track: owners[0].name,
@@ -604,7 +622,7 @@ export async function mergePullRequest(
     deletedBranch =
       deleted.ok || (gone && gone.ok && gone.sha === null) ? true : { error: deleted.error };
   }
-  const mergeBack = mergeBackFor(cwd, doc.base);
+  const mergeBack = mergeBackFor(cwd, doc.base, branch);
   const row = appendObserved(cwd, {
     type: "pr.merged",
     actor: input.actor,

package/src/forge/types.ts

@@ -42,6 +42,11 @@ export type PrMatch = {
   projectId: number | null;
   /** A PR whose head is exactly this commit is ours whatever its owner. */
   sha: string | null;
+  /**
+   * Only a PR into this base: one head may have PRs into several bases (a
+   * git-flow release into main and its back-merge into develop).
+   */
+  base?: string | null;
 };
 
 /** One CI check (GitHub check run / commit status, GitLab job or bridge). */

package/src/git/ops.ts

@@ -21,11 +21,19 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import {
+  branchKindOf,
   classifyBranchDirt,
+  flowMismatch,
+  flowRoute,
+  gitFlowOf,
   isProtectedTarget,
+  releaseBranch,
+  releaseBranchesOf,
   resolveCommitPolicyFor,
   validateBranchNameFor,
   validateCommitMessageFor,
+  type BranchKind,
+  type FlowRoute,
 } from "../core/branch";
 import { detectCommitFlavor, matchCommitFlavor } from "../core/commit-flavors";
 import { pushTargetIsStable } from "../core/pr-create";
@@ -221,12 +229,14 @@ export type BranchOutcome = {
   notes: string[];
   /** The release track the base and name came from; null without tracks. */
   releaseTrack: ResolvedReleaseTrack | null;
+  /** The git-flow route the base came from; null outside git-flow or with a release track. */
+  flow: FlowRoute | null;
 };
 
 export type BranchInput = {
   /** An explicit branch name; else `kind` + `slug` through the track's naming. */
   name?: string;
-  kind?: "feature" | "bugfix" | "hotfix";
+  kind?: BranchKind;
   slug?: string;
   base?: string | null;
   carry?: boolean;
@@ -272,6 +282,21 @@ export function gitBranch(cwd: string, input: BranchInput): ForgeResult<BranchOu
   if (!policy.ok) return failure("blocked", policy.error, policy.correction);
   if (resolveRef(cwd, `refs/heads/${name}`))
     return failure("failed", `branch_exists: ${name} already exists`, `git switch ${name}`);
+  // git-flow (no release track): the kind decides the base, and an explicit
+  // base that is the other long-lived branch is refused.
+  const kind = input.kind ?? branchKindOf(name);
+  const flow =
+    resolved.ok !== false && !releaseTrack?.track
+      ? gitFlowOf(cwd, String(resolved.defaultTargetBranch ?? "") || null)
+      : null;
+  const route = flow && kind ? flowRoute(flow, kind) : null;
+  const mismatch = explicitBase ? flowMismatch(flow, kind, explicitBase, "base") : null;
+  if (mismatch && route)
+    return failure(
+      "blocked",
+      mismatch,
+      `workit git branch ${input.kind ? `--kind ${kind} --slug ${input.slug}` : name}  # without --base it starts from ${route.base}`,
+    );
 
   let base = explicitBase;
   let defaultTarget: string | null = null;
@@ -287,12 +312,16 @@ export function gitBranch(cwd: string, input: BranchInput): ForgeResult<BranchOu
     defaultTarget = String(resolved.defaultTargetBranch ?? "") || null;
     defaultBase = String(resolved.baseBranch ?? "") || defaultTarget;
   }
-  base ??= defaultBase;
+  base ??= route?.base ?? defaultBase;
   if (!base)
     return failure("invalid_input", "no default target branch is configured; pass --base <branch>");
   if (base.startsWith("-")) return failure("invalid_input", "--base must not start with -");
 
   const notes: string[] = [...(releaseTrack?.warnings ?? [])];
+  if (route?.mergeBack)
+    notes.push(
+      `git-flow: ${route.kind}/* lands on ${route.target} (workit pr create targets it), then ${route.target} merges back into ${route.mergeBack}`,
+    );
   const remotes = remoteNames(cwd);
   const remote = remotes.includes("origin") ? "origin" : pushRemoteName(cwd);
   const localTip = resolveRef(cwd, `refs/heads/${base}`);
@@ -351,6 +380,7 @@ export function gitBranch(cwd: string, input: BranchInput): ForgeResult<BranchOu
     carried: dirt !== "clean",
     notes,
     releaseTrack,
+    flow: route,
   });
 }
 
@@ -691,8 +721,10 @@ export function pushPreflight(
   if (isProtectedTarget(cwd, branch))
     return failure(
       "blocked",
-      `protected_branch: ${branch} is protected by the workspace branch policy; workit never pushes to it`,
-      "workit git branch <feature/name>  # push a feature branch and open a PR",
+      `protected_branch: ${branch} is protected by the workspace branch policy; workit git push never pushes to it`,
+      releaseBranch(cwd, branch)
+        ? `workit git push --release ${branch}  # finishing a release or hotfix; needs the release grant`
+        : "workit git branch <feature/name>  # push a feature branch and open a PR",
     );
   const sha = resolveRef(cwd, `refs/heads/${branch}`);
   if (!sha) return failure("not_found", `branch ${branch} has no commit to push`);
@@ -992,6 +1024,229 @@ export function executePush(
   });
 }
 
+// ---------------------------------------------------------------------------
+// release push: finishing a git-flow release or hotfix
+
+export type ReleaseRef = {
+  kind: "branch" | "tag";
+  /** The short name (`main`, `v4.1.0`). */
+  name: string;
+  /** The full ref (`refs/heads/main`, `refs/tags/v4.1.0`). */
+  ref: string;
+  /** The commit it points at (a tag peeled). */
+  sha: string;
+};
+
+export type ReleasePushPlan = Omit<PushPlan, "branch" | "sha"> & {
+  refs: ReleaseRef[];
+  /** The branch a pushed tag's commit must already be on (or a branch in this push). */
+  production: string | null;
+};
+
+/** A release tag: `v` and a digit (`v4.1.0`, `v2`). */
+const RELEASE_TAG = /^v\d/u;
+
+/**
+ * What `workit git push --release` may push: the git-flow production and
+ * develop branches and `v*` tags, nothing else, each by its local ref. Everything else stays on the feature-branch
+ * path (`workit git push`, `workit pr create`).
+ */
+export function releasePushPreflight(
+  cwd: string,
+  names: readonly string[],
+): ForgeResult<ReleasePushPlan> {
+  const progress = operationInProgress(cwd);
+  if (progress) return inProgressFailure(progress.operation, "push");
+  const wanted = [...new Set(names)];
+  if (!wanted.length) return failure("invalid_input", "name the release refs to push");
+  const { preset, branches, production } = releaseBranchesOf(cwd);
+  const refs: ReleaseRef[] = [];
+  for (const raw of wanted) {
+    if (raw.startsWith("-") || raw.includes(":"))
+      return failure("invalid_input", `${raw} is not a ref name (refspecs are not accepted)`);
+    const tagName = raw.replace(/^refs\/tags\//u, "");
+    const branchName = raw.replace(/^refs\/heads\//u, "");
+    const tag = raw.startsWith("refs/heads/") ? null : resolveRef(cwd, `refs/tags/${tagName}`);
+    const branch = raw.startsWith("refs/tags/")
+      ? null
+      : resolveRef(cwd, `refs/heads/${branchName}`);
+    if (tag && branch)
+      return failure(
+        "invalid_input",
+        `${raw} names both a branch and a tag`,
+        `workit git push --release refs/heads/${raw}  # or refs/tags/${raw}`,
+      );
+    if (tag) {
+      if (!RELEASE_TAG.test(tagName))
+        return failure(
+          "blocked",
+          `release_push_refused: tag ${tagName} is not a release tag (v<version>)`,
+          "git tag -a v<version> -m <message>  # then: workit git push --release v<version>",
+        );
+      refs.push({ kind: "tag", name: tagName, ref: `refs/tags/${tagName}`, sha: tag });
+      continue;
+    }
+    if (!branch) return failure("not_found", `${raw} is not a local branch or tag`);
+    if (!branches.some((name) => name.toLowerCase() === branchName.toLowerCase()))
+      return failure(
+        "blocked",
+        branches.length
+          ? `release_push_refused: ${branchName} is not a git-flow release branch (${branches.join(", ")})`
+          : `release_push_refused: the ${preset} policy lands ${branchName} only through a reviewed PR; workit git push --release pushes v<version> tags there, not branches`,
+        branches.length
+          ? "workit git push  # a feature, bugfix, release or hotfix branch, then: workit pr create"
+          : `workit pr create --base ${branchName}  # then tag the merged commit and: workit git push --release v<version>`,
+      );
+    refs.push({ kind: "branch", name: branchName, ref: `refs/heads/${branchName}`, sha: branch });
+  }
+  const remote = pushRemoteName(cwd, refs.find((ref) => ref.kind === "branch")?.name ?? null);
+  if (!remote)
+    return failure(
+      "not_found",
+      "no push remote is configured for this repository",
+      "git remote add origin <url>",
+    );
+  const raw = pushUrl(cwd, remote);
+  if (!raw)
+    return failure(
+      "blocked",
+      `remote "${remote}" has no single push URL`,
+      `git remote get-url --push --all ${remote}  # keep exactly one push URL`,
+    );
+  const local = parseRemoteUrl(raw)?.protocol === "file";
+  if (!local && !pushTargetIsStable(cwd, raw))
+    return failure(
+      "blocked",
+      `push_target_rewritten: the push URL of "${remote}" is rewritten by a url.*.insteadOf rule, so the destination is not the one checked`,
+      "git config --get-regexp '^url\\.'  # remove the rewrite for this remote",
+    );
+  return success({ refs, remote, url: redactRemote(raw), rawUrl: raw, local, production });
+}
+
+export type ReleasePushOutcome = {
+  remote: string;
+  url: string;
+  refs: Array<ReleaseRef & { previous: string | null; pushed: boolean }>;
+  recorded: { id: string } | { error: string };
+};
+
+/**
+ * Push the planned release refs in one atomic push: a branch only fast
+ * forward, a tag only when the remote lacks it (a release tag never moves),
+ * never forced. Success only when every remote tip observed afterwards is the
+ * local one; recorded as one `release.pushed` row.
+ */
+export function executeReleasePush(
+  cwd: string,
+  plan: ReleasePushPlan,
+  input: {
+    actor: LedgerActor;
+    grant: string;
+    timeoutMs?: number;
+    identity?: Record<string, unknown>;
+  },
+): ForgeResult<ReleasePushOutcome> {
+  const previous = new Map<string, string | null>();
+  for (const ref of plan.refs) {
+    const before = remoteRefTip(cwd, plan.rawUrl, ref.ref);
+    if (!before.ok) return failure(before.code, before.error);
+    previous.set(ref.ref, before.sha);
+    if (before.sha === null || before.sha === ref.sha) continue;
+    if (ref.kind === "tag")
+      return failure(
+        "blocked",
+        `tag_exists: ${plan.remote} already has ${ref.name} at ${before.sha.slice(0, 12)}, not ${ref.sha.slice(0, 12)}; a release tag never moves`,
+        `git tag -d ${ref.name}  # tag the next version instead`,
+      );
+    if (!git(cwd, ["merge-base", "--is-ancestor", before.sha, ref.sha]).ok)
+      return failure(
+        "failed",
+        `non_fast_forward: ${plan.remote}/${ref.name} (${before.sha.slice(0, 12)}) is not part of local ${ref.name}; a release push never rewrites it`,
+        `git fetch ${plan.remote} ${ref.name} && git switch ${ref.name} && git merge --ff-only ${plan.remote}/${ref.name}  # then: workit git push --release ${ref.name}`,
+      );
+  }
+  // A release tag marks a commit the production branch already has (or a
+  // branch this push moves): never an unmerged feature commit.
+  const tags = plan.refs.filter((ref) => ref.kind === "tag");
+  if (tags.length) {
+    let productionTip: string | null = null;
+    if (plan.production) {
+      const tip = remoteRefTip(cwd, plan.rawUrl, `refs/heads/${plan.production}`);
+      if (!tip.ok) return failure(tip.code, tip.error);
+      productionTip = tip.sha;
+    }
+    const contains = (tip: string, sha: string) =>
+      git(cwd, ["merge-base", "--is-ancestor", sha, tip]).ok;
+    for (const tag of tags) {
+      const released =
+        (productionTip !== null && contains(productionTip, tag.sha)) ||
+        plan.refs.some((ref) => ref.kind === "branch" && contains(ref.sha, tag.sha));
+      if (!released)
+        return failure(
+          "blocked",
+          `tag_unreleased: ${tag.name} (${tag.sha.slice(0, 12)}) is not on ${plan.remote}/${plan.production ?? "the production branch"}${plan.refs.some((ref) => ref.kind === "branch") ? " or a branch in this push" : ""}; a release tag marks a commit that already landed`,
+          `land it through a PR first (workit pr create), git fetch ${plan.remote}, then tag the merged commit`,
+        );
+    }
+  }
+  const pending = plan.refs.filter((ref) => previous.get(ref.ref) !== ref.sha);
+  if (pending.length) {
+    const run = gitNetwork(
+      cwd,
+      [
+        "push",
+        "--porcelain",
+        "--atomic",
+        "--no-follow-tags",
+        "--recurse-submodules=no",
+        plan.remote,
+        ...pending.map((ref) =>
+          ref.kind === "tag" ? `${ref.ref}:${ref.ref}` : `${ref.sha}:${ref.ref}`,
+        ),
+      ],
+      input.timeoutMs ?? PUSH_TIMEOUT_MS,
+    );
+    if (!run.ok)
+      return run.timedOut
+        ? failure("unavailable", `git push to ${plan.url} timed out`)
+        : failure("failed", `git push to ${plan.url} failed:\n${gitOutput(run)}`);
+  }
+  for (const ref of plan.refs) {
+    const after = remoteRefTip(cwd, plan.rawUrl, ref.ref);
+    if (!after.ok) return failure(after.code, `push sent but not verified: ${after.error}`);
+    if (after.sha !== ref.sha)
+      return failure(
+        "failed",
+        `push_unverified: ${plan.remote} ${ref.ref} is at ${after.sha?.slice(0, 12) ?? "(absent)"}, not ${ref.sha.slice(0, 12)}`,
+      );
+  }
+  const refs = plan.refs.map((ref) => ({
+    ...ref,
+    previous: previous.get(ref.ref) ?? null,
+    pushed: pending.includes(ref),
+  }));
+  const row = appendObserved(cwd, {
+    type: "release.pushed",
+    actor: input.actor,
+    remote: plan.remote,
+    url: plan.url,
+    refs: refs.map(({ ref, sha, previous: before, pushed }) => ({
+      ref,
+      sha,
+      previous: before,
+      pushed,
+    })),
+    grant: input.grant,
+    ...(input.identity ? { identity: input.identity } : {}),
+  });
+  return success({
+    remote: plan.remote,
+    url: plan.url,
+    refs,
+    recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },
+  });
+}
+
 /**
  * Delete a remote branch only while it still points at `expectedTip`
  * (`--force-with-lease=refs/heads/<b>:<tip> --delete`). `lease` is false when

package/src/hooks/handle.ts

@@ -6,6 +6,7 @@ import {
   turnContextText,
 } from "./context";
 import type { HostDescriptor, Support } from "./descriptor";
+import { branchGuidance } from "../core/branch";
 import { recordIssuedSession } from "../host-session";
 import { shellPolicy } from "./policy";
 import {
@@ -91,13 +92,14 @@ const subagentStartText = (
   const isolated =
     descriptor.subagents.worktreeIsolation === "native" &&
     (role === "implementer" || CLAUDE_WORKTREE.test(input.cwd));
+  const guide = role === "implementer" ? branchGuidance(input.cwd) : null;
   if (role === "implementer" && isolated)
-    return `Workit observed ${who} working in its own git worktree: it may edit and commit there, within its brief's scope. ${ISOLATED_GIT} Use a policy-compliant branch (e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
+    return `Workit observed ${who} working in its own git worktree: it may edit and commit there, within its brief's scope. ${ISOLATED_GIT} Plain git is expected here, and the branch name is still policy-checked: a raw \`git switch -c\`, \`git checkout -b\`, \`git branch\` or \`git worktree add -b\` onto a protected or non-compliant name is denied, so use a policy-compliant branch.${guide ? ` ${guide}` : " (e.g. feature/<slug>)"} Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
   if (isolated)
     return `${ISOLATED_GIT}\n${subagentStartText({ ...input, cwd: "" }, descriptor, event)}`;
   if (role === "implementer")
     // No host isolation: the lead makes the worktree, and workit git works there.
-    return `Workit observed ${who} as an implementer: it edits and commits only in its own git worktree (the lead makes one with \`workit fanout worktree create <slice>\`), never in the lead's checkout, within its brief's scope. Before the first commit, switch to a policy-compliant branch with \`workit git branch <branch> --base <base>\` (e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
+    return `Workit observed ${who} as an implementer: it edits and commits only in its own git worktree (the lead makes one with \`workit fanout worktree create <slice>\`), never in the lead's checkout, within its brief's scope. Before the first commit, switch to a policy-compliant branch with \`workit git branch <branch> --base <base>\` (or \`--kind <kind> --slug <slug>\`, which picks the base); branch policy hooks still deny protected or non-compliant branches, raw git included.${guide ? ` ${guide}` : " (e.g. feature/<slug>)"} Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
   const readOnly = `Workit observed ${who} as read-only/agent-guided.`;
   if (role !== "judge" || !event.agentId) return readOnly;
   const own = subagentSession(session, event.agentId);
@@ -139,7 +141,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
       const skillRead = skillReadIn(event.command, event.dialect);
       if (skillRead) recordSkillLoad(input, skillRead, "read");
       const canDeny = usable(descriptor.shellPolicy.deny);
-      const policy = canDeny ? shellPolicy(input.cwd, event.command) : NONE;
+      const policy = canDeny ? shellPolicy(input.cwd, event.command, event.dialect) : NONE;
       if (policy.kind !== "none") return policy;
       // Without a post-tool event, the previous raw commit is recorded now.
       const postTool = usable(descriptor.events["shell.post"].support);

package/src/hooks/policy.ts

@@ -1,13 +1,19 @@
 import { shellBranchPolicyViolation } from "../core/route-intent";
 import type { HookDecision } from "./protocol";
+import type { ShellDialect } from "./shell-words";
 
 /**
- * Branch policy for one shell command: only direct literal branch creation
- * onto a noncompliant name is denied. Every other command keeps the host's own
- * permission decision. The reason carries the policy's correction.
+ * Branch policy for one shell command: a raw branch creation (`git switch -c`,
+ * `checkout -b`, `branch`, `worktree add -b`, in any chain, directory or
+ * wrapper) onto a noncompliant name is denied. Every other command keeps the
+ * host's own permission decision. The reason carries the policy's correction.
  */
-export const shellPolicy = (cwd: string, command: string): HookDecision => {
-  const policy = shellBranchPolicyViolation(cwd, command);
+export const shellPolicy = (
+  cwd: string,
+  command: string,
+  dialect: ShellDialect = "posix",
+): HookDecision => {
+  const policy = shellBranchPolicyViolation(cwd, command, dialect);
   return policy && !policy.ok
     ? { kind: "deny", reason: `branch_policy_denied: ${policy.error}`, unblock: null }
     : { kind: "none" };

package/src/hooks/raw-git.ts

@@ -24,7 +24,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { resolveBranchPolicyFor } from "../core/branch";
+import { releaseBranch, resolveBranchPolicyFor, validateBranchNameFor } from "../core/branch";
 import { resolveRuntimeWorkspaceVcs } from "../core/workspaces";
 import { pushRemoteName } from "../git/rev";
 import { appendHookObserved, readLedger } from "../ledger";
@@ -230,6 +230,18 @@ export type RawAction =
       blindForce: boolean;
       /** The remote named on the command line; null pushes to the default one. */
       remote: string | null;
+      /** Tags named as `refs/tags/<t>` destinations (bare names are told apart later). */
+      tags?: string[];
+      /** `--tags`: every tag goes along. */
+      allTags?: true;
+      /** `--delete`/`-d`: the refspecs are deleted, not pushed. */
+      deletes?: true;
+      /** Names deleted by a colon refspec (`:chore/old`). */
+      deleted?: string[];
+      /** `--all`/`--branches`: every local branch. */
+      allBranches?: true;
+      /** `--mirror`: every ref, deletions included. */
+      mirror?: true;
     }
   | { kind: "merge"; forge: "gh" | "glab" }
   | { kind: "pr-create"; forge: "gh" | "glab" }
@@ -242,6 +254,10 @@ const pushAction = (args: string[]): RawAction | null => {
   let force = false;
   let lease = false;
   let wholesale = false;
+  let allTags = false;
+  let deletes = false;
+  let allBranches = false;
+  let mirror = false;
   let remote: string | null = null;
   const positionals: string[] = [];
   for (let index = 1; index < args.length; index++) {
@@ -256,26 +272,51 @@ const pushAction = (args: string[]): RawAction | null => {
     else if (PUSH_VALUE_OPTIONS.has(arg)) index++;
     else if (arg === "--force" || /^-[a-zA-Z]*f[a-zA-Z]*$/.test(arg)) force = true;
     else if (arg.startsWith("--force-with-lease") || arg === "--force-if-includes") lease = true;
-    else if (["--all", "--mirror", "--branches", "--tags"].includes(arg)) wholesale = true;
+    else if (arg === "--delete" || arg === "-d") deletes = true;
+    else if (arg === "--tags") allTags = wholesale = true;
+    else if (arg === "--all" || arg === "--branches") allBranches = wholesale = true;
+    else if (arg === "--mirror") mirror = wholesale = true;
     else if (!arg.startsWith("-")) positionals.push(arg);
   }
   // `--repo` names the remote; positionals are then all refspecs.
   const specs = remote === null ? positionals.slice(1) : positionals;
   remote ??= positionals[0] ?? null;
   const targets: Array<string | null> = [];
+  const tags: string[] = [];
+  const deleted: string[] = [];
   for (const raw of specs) {
     if (raw.startsWith("+")) force = true;
     const spec = raw.replace(/^\+/, "");
     const colon = spec.indexOf(":");
     const destination = colon >= 0 ? spec.slice(colon + 1) : spec;
     if (!destination) continue;
-    if (destination === "HEAD") targets.push(null);
-    else if (destination.startsWith("refs/heads/")) targets.push(destination.slice(11));
-    else if (!destination.startsWith("refs/")) targets.push(destination);
+    const name =
+      destination === "HEAD"
+        ? null
+        : destination.startsWith("refs/heads/")
+          ? destination.slice(11)
+          : destination.startsWith("refs/")
+            ? undefined
+            : destination;
+    if (destination.startsWith("refs/tags/")) tags.push(destination.slice(10));
+    if (name === undefined) continue;
+    targets.push(name);
+    if (colon === 0 && name !== null) deleted.push(name);
   }
   // No refspec pushes the current branch (push.default simple/current).
   if (specs.length === 0 && !wholesale) targets.push(null);
-  return { kind: "push", targets, blindForce: force && !lease, remote };
+  return {
+    kind: "push",
+    targets,
+    blindForce: force && !lease,
+    remote,
+    ...(tags.length ? { tags } : {}),
+    ...(allTags ? { allTags: true as const } : {}),
+    ...(deletes ? { deletes: true as const } : {}),
+    ...(deleted.length ? { deleted } : {}),
+    ...(allBranches ? { allBranches: true as const } : {}),
+    ...(mirror ? { mirror: true as const } : {}),
+  };
 };
 
 /** Options whose next word is their value (never an option or subcommand). */
@@ -432,12 +473,88 @@ const headSha = (repo: Repo): string | null => {
 
 const quote = (text: string) => `\`${text}\``;
 
-const refusal = (action: RawAction, branch: string | null): string => {
+const refusal = (action: RawAction, branch: string | null, dir?: string): string => {
   if (action.kind === "merge")
     return `workit: raw ${quote(action.forge === "gh" ? "gh pr merge" : "glab mr merge")} bypasses the merge grant and the verdict gate. Run ${quote("workit pr merge")} instead (it checks both; ${quote("workit help pr")}).`;
+  // Finishing a release (git-flow main/develop, the github-flow trunk, a
+  // custom protected branch): the push has its own granted verb.
+  const plainPush = action.kind === "push" && !action.blindForce && !action.deletes;
+  if (dir && branch && plainPush && releaseBranch(dir, branch))
+    return `workit: raw ${quote("git push")} onto ${branch}, a protected release branch, bypasses workit's protected-branch check. To finish a release or hotfix, push it with ${quote(`workit git push --release ${branch} [--release v<version>]`)}: it pushes ${branch} (fast-forward only) and the release tag, verifies the remote and records it, under the ${quote("release")} grant (if refused, ask the user to run ${quote("workit grant set <workspace> release=true")}). Feature work goes through ${quote("workit git push")} and ${quote("workit pr merge")}.`;
   return `workit: raw ${quote("git push")}${action.kind === "push" && action.blindForce ? " --force" : ""} onto ${branch}, a protected branch or the default target, bypasses workit's protected-branch check. Push your feature branch with ${quote("workit git push")} (${quote("workit git push --force-with-lease")} to rewrite it) and land it with ${quote("workit pr merge")}.`;
 };
 
+type PushAction = Extract<RawAction, { kind: "push" }>;
+
+/** The local branches and tags, and the remote's branches as last fetched: one git call. */
+type RefFacts = { heads: Set<string>; tags: Set<string>; remoteHeads: Set<string> };
+
+const refFacts = (repo: Repo, remote: string): RefFacts => {
+  const facts: RefFacts = { heads: new Set(), tags: new Set(), remoteHeads: new Set() };
+  const listed = spawnSync(
+    "git",
+    ["for-each-ref", "--format=%(refname)", "refs/heads", "refs/tags", `refs/remotes/${remote}`],
+    { cwd: repo.dir, encoding: "utf8", timeout: 5_000 },
+  );
+  const remotePrefix = `refs/remotes/${remote}/`;
+  for (const ref of (listed.stdout ?? "").split("\n")) {
+    if (ref.startsWith("refs/heads/")) facts.heads.add(ref.slice(11));
+    else if (ref.startsWith("refs/tags/")) facts.tags.add(ref.slice(10));
+    else if (ref.startsWith(remotePrefix)) facts.remoteHeads.add(ref.slice(remotePrefix.length));
+  }
+  return facts;
+};
+
+/** A bare refspec naming a local tag and no local branch pushes the tag. */
+const isTag = (facts: RefFacts, name: string): boolean =>
+  facts.tags.has(name) && !facts.heads.has(name);
+
+/**
+ * A raw tag push (`git push origin v1.0`, `refs/tags/v1.0`, `--tags`) skips
+ * the release grant: denied with the workit command. `--follow-tags` only
+ * nudges (it pushes annotated tags the pushed commits already reach).
+ */
+const tagRefusal = (action: PushAction, facts: RefFacts): string | null => {
+  const tags = [
+    ...(action.tags ?? []),
+    ...action.targets.filter((name): name is string => name !== null && isTag(facts, name)),
+  ];
+  if (!tags.length && !action.allTags) return null;
+  const named = tags.length ? tags.join(" --release ") : "v<version>";
+  return `workit: raw ${quote(`git push${action.allTags ? " --tags" : ""}`)} of ${tags.length ? `tag ${tags.join(", ")}` : "tags"} bypasses the release grant. Push a release tag with ${quote(`workit git push --release ${named}`)} (v<version> tags whose commit the production branch already has; a tag never moves), under the ${quote("release")} grant (if refused, ask the user to run ${quote("workit grant set <workspace> release=true")}).`;
+};
+
+/** The remote already has the branch (ls-remote, bounded; unreachable answers yes: fail open). */
+const remoteHas = (repo: Repo, remote: string, branch: string): boolean => {
+  const listed = spawnSync("git", ["ls-remote", "--heads", remote, `refs/heads/${branch}`], {
+    cwd: repo.dir,
+    encoding: "utf8",
+    timeout: 3_000,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+  });
+  return listed.status !== 0 || (listed.stdout ?? "").trim() !== "";
+};
+
+/**
+ * A branch name that would be new on the remote and that the workspace policy
+ * does not allow, with the closest allowed name. An existing remote branch
+ * (`dependabot/…`, a legacy name) is never judged: pushing it is not a new
+ * name. `--all`/`--branches` expand to every local branch.
+ */
+const offPolicyPush = (action: PushAction, repo: Repo, facts: RefFacts, remote: string) => {
+  const names = action.allBranches
+    ? [...facts.heads]
+    : action.targets.map((target) => target ?? repo.branch);
+  for (const branch of names) {
+    if (!branch || action.deleted?.includes(branch) || isTag(facts, branch)) continue;
+    if (facts.remoteHeads.has(branch)) continue;
+    const check = validateBranchNameFor(repo.dir, branch);
+    if (check.ok || check.rule !== "allowed_pattern" || remoteHas(repo, remote, branch)) continue;
+    return `workit: raw ${quote("git push")} onto ${branch}: ${check.error}`;
+  }
+  return null;
+};
+
 const nudgeFor = (action: RawAction, host: HookInput["host"], session: string): string | null => {
   switch (action.kind) {
     case "commit": {
@@ -550,12 +667,23 @@ export function rawGitPre(
     for (const { action, repo } of actionsIn(input.cwd, command, dialect)) {
       store ??= repo.location.dir;
       if (action.kind === "merge") return deny(refusal(action, null));
-      if (action.kind === "push")
+      if (action.kind === "push" && toPushRemote(repo, action.remote)) {
+        if (action.mirror)
+          return deny(
+            `workit: raw ${quote("git push --mirror")} rewrites and deletes every remote ref, protected branches and tags included. Push one branch with ${quote("workit git push")}.`,
+          );
         for (const target of action.targets) {
           const branch = target ?? repo.branch;
-          if (branch && guardedBranch(repo.dir, branch) && toPushRemote(repo, action.remote))
-            return deny(refusal(action, branch));
+          if (branch && guardedBranch(repo.dir, branch))
+            return deny(refusal(action, branch, repo.dir));
         }
+        const remote = action.remote ?? pushRemoteName(repo.dir, repo.branch) ?? "origin";
+        const facts = refFacts(repo, remote);
+        const tagDeny = tagRefusal(action, facts);
+        if (tagDeny) return deny(tagDeny);
+        const nameDeny = action.deletes ? null : offPolicyPush(action, repo, facts, remote);
+        if (nameDeny) return deny(nameDeny);
+      }
       const nudge = nudgeFor(action, input.host, input.session.id);
       if (nudge && !nudges.has(nudgeKind(action))) nudges.set(nudgeKind(action), nudge);
     }