@brainervirus/workit-core 8.9.1 → 8.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.9.1",
+  "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/skills/workit-fanout/references/brief.md

@@ -25,7 +25,7 @@ REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,
   each ACCEPTANCE line met / not met, rulings you made (`workit ledger ruling`),
   anything out of scope as a follow-up, not a diff.
 STANDING: <the standing orders, verbatim: `workit ledger standing add` records each one>
-  export WORKIT_SESSION_ID=<lead>-w<n>   (set by the lead; a verifier brief gets <lead>-v<n>)
+  export WORKIT_SESSION_ID=<lead>-w<n>   (set by the lead for a worker's commits; a verifier brief sets none: the host derives it)
 ```
 
 ## Worked example

package/skills/workit-fanout/references/orchestration.md

@@ -72,12 +72,22 @@ Which session id a verdict carries, per host:
 
 - Claude Code: subagents inherit your `WORKIT_SESSION_ID`, so the
   SubagentStart hook names each `verifier` and `reviewer` its own session
-  (`<lead>:<agent id>`), passed as `--session`; that one wins over any
-  `<lead>-v<n>` in a brief. An `implementer` uses the session its brief
-  exports for its workit commands.
-- Other hosts: the session the brief sets wins: `export
-  WORKIT_SESSION_ID=<lead>-w-<slice>` from `workit fanout brief` for a
-  worker, `<lead>-v<n>` (or `--as verifier`) for a verifier you start.
+  (`<lead>:<agent id>`), passed exactly as `--session`: the hook records the
+  ids it issues, and only those are accepted. An `implementer` uses the
+  session its brief exports for its workit commands.
+- Codex: the `workit-verifier` and `workit-reviewer` agents get the same
+  issued `--session` from SubagentStart; any other verifier passes
+  `--as verifier`.
+- OpenCode: a child session's shell already has
+  `WORKIT_SESSION_ID=<lead>:<child>`; Pi: a supervised worker's shell has
+  `<lead>:<worker session>`. Set nothing for a verifier there.
+- Cursor (no session id in the shell): the brief sets the verifier's
+  `WORKIT_SESSION_ID=<lead>:verifier-<random hex>`, a fresh suffix per
+  verifier. Cursor cannot check it: it is declared, not derived.
+- A worker's commits use `export WORKIT_SESSION_ID=<lead>-w-<slice>` from
+  `workit fanout brief`. A verdict under an id you made up (`<lead>-v1`,
+  `<lead>:v1`) is refused as `forged_session` on Claude Code, Codex,
+  OpenCode and Pi.
 
 A batch verifier takes several slices on one surface in one session: for
 each branch it checks out the head, runs that slice's VERIFY, and records its

package/skills/workit-implement/SKILL.md

@@ -33,8 +33,9 @@ description: Build a requested change in small verified steps - follow local pat
    `workit ledger verdict tests-verified --self --how "<what you ran>"`; it
    reads self-reviewed, never verified. High risk, a workspace with
    `verification: independent` (`workit grant show`) or a verified merge needs
-   a fresh verifier with its own session (`WORKIT_SESSION_ID=<yours>-v1`;
-   Claude Code: the `verifier` agent). Before saying done, reconcile
+   a fresh verifier with its own host-derived session (Claude Code and Codex:
+   the `verifier` agent; OpenCode: a child session; Pi: a supervised worker),
+   never a hand-minted id. Before saying done, reconcile
    every named deliverable against the target checkout and observe it (for a push:
    `workit verify-delivery push`).
 

package/skills/workit-review/SKILL.md

@@ -7,8 +7,10 @@ description: Independent review of a diff, branch or PR - intent fidelity and st
 
 Review the candidate, never the author's summary of it. A session that wrote a
 commit on the branch cannot record a passing verdict: if that is you, hand the
-review to a fresh agent with its own session (`WORKIT_SESSION_ID=<lead>-v<n>`;
-Claude Code: the `reviewer` or `verifier` agent).
+review to a fresh agent with its own host-derived session: Claude Code and
+Codex, the `reviewer` or `verifier` agent (`--session` from SubagentStart);
+OpenCode, a child session; Pi, a supervised worker. Never hand-mint one such
+as `<lead>-v1`: it is refused as `forged_session`.
 An author's `--self` verdict reads self-reviewed and never counts as
 independent; `type-check-only` never proves a behavior change.
 

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/methods.ts

@@ -115,7 +115,8 @@ Autonomy contract:
   satisfies a gate; an ad-hoc \`workit check -- <cmd>\` never does.
 - Author is not verifier: your own verdict is \`--self\`, shown as
   self-reviewed, never verified. High risk, \`verification: independent\` and
-  merge need a verifier with its own session (\`WORKIT_SESSION_ID=<lead>-v<n>\`).
+  merge need a verifier with its own host-derived session (a subagent's
+  \`<lead>:<child>\`, set by the host); never hand-mint one such as \`<lead>-v1\`.
 - A local-commit endpoint does not imply PR readiness, and a local commit alone
   is not evidence of a requested remote push. Before reporting delivery,
   reconcile every requested item and observe it (\`workit verify-delivery\`).

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;
 };