@brainervirus/workit-core 8.10.0 → 8.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.10.0",
+  "version": "8.12.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 for a worker's commits; a verifier brief sets none: the host derives it)
+  <identity line, per the lead's host: see "Identity and git rules per host" below>
 ```
 
 ## Worked example
@@ -97,17 +97,32 @@ is the slice's STUCK threshold in `workit fanout status`. `"fanIn":
 }
 ```
 
+## Identity and git rules per host
+
+`workit fanout brief` renders the identity line and RULES 1 and 3 for the
+lead's host (`WORKIT_HOST`, or the host's own session variable):
+
+| Lead's host | Identity line | RULES 1 and 3 |
+| --- | --- | --- |
+| Claude Code | `Session: your env already has WORKIT_SESSION_ID (the lead's id)`; no `export`, no hand-minted id (SubagentStart issues `<lead>:<agent id>` only to verifiers and reviewers, never to an implementer, so the worker's commits carry the lead's id) | plain git: `git fetch origin && git switch -c <branch> origin/<base>` and `git commit -m <msg> --trailer "Workit-Session: <the env WORKIT_SESSION_ID>" --trailer "<host attribution>" -- <paths in SCOPE>`, because worktree isolation refuses every `workit git` form |
+| OpenCode, Pi, Codex | `Session: your host already sets WORKIT_SESSION_ID in your shell`; export nothing (the host derives the id and an export cannot replace it) | `workit git branch <branch> --base <base>`, `workit git commit -m <msg> -- <paths in SCOPE>` |
+| Cursor, CI, a plain terminal | `export WORKIT_SESSION_ID=<lead>-w-<slice>` (`+try<n>` for a race attempt): declared, not checked | the same `workit git` forms |
+
+`MODE: resume` is `git switch <branch>` on every host (the branch exists; the
+lead removed the dead worker's worktree after its exit, so the switch
+succeeds), then continue from its head. A race attempt (`--attempt <n>`)
+follows its host's row with the branch `<branch>-try<n>`.
+
 ## Worker rules (`workit fanout brief` appends them as RULES)
 
-1. First command. `MODE: new`: `workit git branch <branch> --base <base>` (the
-   worktree may start on a name that breaks branch policy). `MODE: resume`:
-   `git switch <branch>` (the branch exists; the lead removed the dead
-   worker's worktree after its exit, so the switch succeeds), then continue
-   from its head.
+1. First command: create the branch (`MODE: new`; the worktree may start on a
+   name that breaks branch policy) or `git switch` to it (`MODE: resume`),
+   as the table above says for your host.
 2. Decide ambiguities yourself and record them:
    `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`.
    Stop only for an irreversible action, a security-sensitive one, or a side
    effect outside the worktree.
-3. Commit with `workit git commit -m "<msg>" -- <paths in SCOPE>`; push only if
-   the brief says so.
+3. Commit as the table says (`workit git commit -m "<msg>" -- <paths in SCOPE>`,
+   or plain git with the trailers on Claude Code); push only if the brief says
+   so.
 4. Never record a verdict on your own work.

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

@@ -73,8 +73,8 @@ 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 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.
+  ids it issues, and only those are accepted. An `implementer` is issued
+  none: it keeps your id in its env for its workit commands and commits.
 - Codex: the `workit-verifier` and `workit-reviewer` agents get the same
   issued `--session` from SubagentStart; any other verifier passes
   `--as verifier`.
@@ -84,8 +84,13 @@ Which session id a verdict carries, per host:
 - 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`,
+- A worker's commits: on Claude Code the lead's `WORKIT_SESSION_ID` already in
+  its env (SubagentStart issues no implementer id; plain git, no export, so the
+  lead authored those commits: a verifier or reviewer records the verdict, not
+  the lead); on OpenCode, Pi and Codex the id the host already
+  puts in its shell; on Cursor, CI and a plain terminal the brief's
+  `export WORKIT_SESSION_ID=<lead>-w-<slice>` (see `brief.md`, "Identity and
+  git rules per host"). A verdict under an id you made up (`<lead>-v1`,
   `<lead>:v1`) is refused as `forged_session` on Claude Code, Codex,
   OpenCode and Pi.
 

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/check-config.ts

@@ -47,6 +47,8 @@ export type CheckConfig = {
   gates: Partial<Record<"testing" | "verification", string[]>>;
   /** Set when the config exists but cannot be used; gates then fail closed. */
   error: string | null;
+  /** The raw `resources` block of workit.checks.json (heavy-check limits; core/resources.ts reads it). */
+  resources?: unknown;
 };
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -228,7 +230,7 @@ export function loadCheckConfig(cwd: string): CheckConfig {
       gates[gate as (typeof GATES)[number]] = names as string[];
     }
   }
-  return { source: CHECKS_FILE, root, checks, gates, error: null };
+  return { source: CHECKS_FILE, root, checks, gates, error: null, resources: parsed.resources };
 }
 
 const sameArgv = (left: readonly string[], right: readonly string[]): boolean =>

package/src/checks.ts

@@ -169,6 +169,13 @@ export type RunOptions = {
   onStderr?: (text: string) => void;
   /** For tests: the platform whose spawn rules apply (default: process.platform). */
   platform?: NodeJS.Platform;
+  /**
+   * POSIX only: argv that runs the command (e.g. a `systemd-run … --` scope
+   * prefix). A --shell command then runs as `<wrapper> /bin/sh -c <cmd>`.
+   */
+  wrapper?: readonly string[];
+  /** Called with the child's pid once it started (on POSIX also its process group id). */
+  onSpawn?: (pid: number) => void;
 };
 
 // cmd.exe metacharacters (the cross-spawn set).
@@ -272,7 +279,12 @@ export function runCheckCommand(argv: readonly string[], options: RunOptions): P
   const buffer = new TailBuffer(MAX_LOG_BYTES);
   const redactor = new StreamRedactor((text) => buffer.push(text));
   const env = options.env ?? process.env;
-  const plan = planSpawn(argv, { platform, env, cwd: options.cwd, shell: options.shell });
+  const wrapped = Boolean(options.wrapper?.length) && platform !== "win32";
+  const command = wrapped
+    ? [...options.wrapper!, ...(options.shell ? ["/bin/sh", "-c", argv[0]] : argv)]
+    : argv;
+  const shell = wrapped ? false : options.shell;
+  const plan = planSpawn(command, { platform, env, cwd: options.cwd, shell });
   return new Promise((resolve) => {
     let settled = false;
     let timedOut = false;
@@ -334,6 +346,7 @@ export function runCheckCommand(argv: readonly string[], options: RunOptions): P
       finish(null, null, (error as NodeJS.ErrnoException).code ?? (error as Error).message);
       return;
     }
+    if (child.pid) options.onSpawn?.(child.pid);
     if (!windows)
       for (const name of FORWARDED_SIGNALS) {
         const handler = () => {

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

@@ -105,9 +105,9 @@ Autonomy contract:
   ship), go to the effective endpoint in \`workit grant show\`: \`pr\` opens
   the PR; \`green\` babysits it without asking (workit-ship) to merge-ready,
   never merging; \`merged\` also lands it with \`workit pr merge\`.
-  Merge and release need a workspace grant, which only the user raises from
-  their own terminal (a blocked verb names how); never edit workspaces.json or
-  route around a grant_required.
+  Merge and release need a workspace grant only the user raises from their
+  own terminal (a blocked verb names how); never edit workspaces.json or route
+  around a grant_required.
 - Ask only for a product or preference choice, or for authority you lack, with
   your recommended answer. Facts are yours: read, run or prototype.
 - Label claims measured (run and seen this session), inferred, or guess.
@@ -116,17 +116,19 @@ Autonomy contract:
 - 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 host-derived session (a subagent's
-  \`<lead>:<child>\`, set by the host); never hand-mint one such as \`<lead>-v1\`.
+  \`<lead>:<child>\`); never hand-mint one (\`<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\`).
 
 CLI first: if a step has one right answer, use the \`workit\` verb instead of
 hand-running git, gh or glab (\`workit git|pr|ci|check\`; \`workit help\` lists
-the rest; without \`workit\` on PATH, \`npx -y @brainervirus/workit-cli\`).
+the rest; lacking \`workit\`, \`npx -y @brainervirus/workit-cli\`).
+Add Co-Authored-By via \`workit git commit --trailer "K: v" -- <paths>\`, never
+an amend.
 The task families (task, policy, evidence, finding, decision, worker, state)
 are optional continuity for tracked work; each branch has one implicit task,
-created by the first recording, and a solo edit needs no task. A decision
+and a solo edit needs no task. A decision
 records a user choice; it never authorizes an effect. Judge work once with
 \`workit policy assess --judge risk= behavior= product-choice= plan=\`.
 Across repositories, bind each item to its checkout, branch and endpoint,