@brainervirus/workit-core 8.9.1 → 8.11.0

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,8 @@ 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 {
   callKey,
@@ -90,16 +92,20 @@ 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);
+  // `ledger verdict` accepts `<lead>:<agent id>` only when this hook issued it.
+  // (An isolated judge's text is rebuilt with cwd "": the hook's own cwd then.)
+  if (session) recordIssuedSession(input.cwd || process.cwd(), session, own);
   return `${readOnly} Its own Workit session is ${own}: record verdicts with \`workit ledger verdict <result> --session ${own} ...\` so the ledger tells it apart from the author.`;
 };
 
@@ -135,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/hosts/codex.ts

@@ -362,5 +362,5 @@ export const codexAdapter: HostAdapter = {
   },
   render,
   addendum: (input) =>
-    `<workit-codex-mutations>Codex MCP is read-only: unattested callers cannot mutate. Run workit verbs with the workit CLI on the shell (node_modules/.bin/workit, or npx -y @brainervirus/workit-cli): check, git branch|commit|push, pr, ci, stack, ledger, handoff; task-family mutations take --json${input.session.id ? ` --actor ${input.session.id}` : ""}. workit acts as this thread (CODEX_THREAD_ID${input.session.id ? `=${input.session.id}` : ""}) unless WORKIT_SESSION_ID is set. A verifier or reviewer records workit ledger verdict under its own session, never the author's: a workit-verifier or workit-reviewer agent uses the --session its SubagentStart context names; any other uses one the lead assigns (WORKIT_HOST=codex_cli WORKIT_SESSION_ID=<lead>-v<n>). Merge and release need a workspace grant (workit grant show); a question answer is not host permission.</workit-codex-mutations>`,
+    `<workit-codex-mutations>Codex MCP is read-only: unattested callers cannot mutate. Run workit verbs with the workit CLI on the shell (node_modules/.bin/workit, or npx -y @brainervirus/workit-cli): check, git branch|commit|push, pr, ci, stack, ledger, handoff; task-family mutations take --json${input.session.id ? ` --actor ${input.session.id}` : ""}. workit acts as this thread (CODEX_THREAD_ID${input.session.id ? `=${input.session.id}` : ""}) unless WORKIT_SESSION_ID is set. A verifier or reviewer records workit ledger verdict under its own session, never the author's: a workit-verifier or workit-reviewer agent uses the --session its SubagentStart context names; any other passes --as verifier (an id derived from its own thread). A hand-minted id such as <lead>-v1 is refused as forged_session. Merge and release need a workspace grant (workit grant show); a question answer is not host permission.</workit-codex-mutations>`,
 };

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