@mmerterden/multi-agent-pipeline 20.33.0 → 20.35.0

package/pipeline/scripts/validate-triage.mjs

@@ -11,6 +11,17 @@
 // Usage:
 //   node pipeline/scripts/validate-triage.mjs path/to/triage.json
 //   cat triage.json | node pipeline/scripts/validate-triage.mjs -
+//     [--reviewers a.json,b.json]   # every reviewer cannotVerify row needs a triage row
+//     [--reviewers-dir <dir>]       # same, for every reviewer-*.json in <dir>
+//     [--anonymized]                # the verdict was judged on anonymized input:
+//                                   # no finding may carry `reviewer`, labels only
+//
+// An accepted finding names its source as `reviewer` (a model family),
+// `foundBy` (an anonymized "Source A" label, or "security-auditor") or `tag`
+// (a deterministic gate finding). Triage judges anonymized findings and
+// carries `foundBy` through; anonymize-findings.mjs --restore writes the
+// family back afterwards, so a `reviewer` in the verdict itself means the
+// judge was told whose findings it graded.
 //
 // Exit codes:
 //   0  -  valid, safe to act on
@@ -21,9 +32,12 @@
 // Output: JSON result to stdout with shape:
 //   {"ok": bool, "code": N, "errors": [...], "warnings": [...], "corrected": {...}|null}
 
-import { readFileSync } from "node:fs";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 
 const ALLOWED_REVIEWERS = new Set(["fable", "opus", "sonnet", "gpt"]);
+const FOUND_BY_RE = /^(Source [A-Z]|security-auditor)$/;
+const ANONYMIZED = process.argv.includes("--anonymized");
 const ALLOWED_SEVERITIES = new Set(["blocking", "important", "suggestion"]);
 const ALLOWED_CONSENSUS_VERDICTS = new Set([
   "unanimous-pass",
@@ -35,9 +49,72 @@ const ALLOWED_VERIFICATION_RESULTS = new Set(["confirmed", "not-reproduced", "in
 const FINGERPRINT_RE = /^F:[0-9a-f]{8}$/;
 const OVER_REJECT_THRESHOLD = 0.8;
 const OVER_REJECT_MIN_FINDINGS = 5;
+const CANNOT_VERIFY_RESOLUTIONS = new Set(["verified", "finding", "out-of-scope"]);
+// A path (any run without spaces, quotes or parentheses that holds a letter),
+// then :line. A time of day has no letter, so it is not one.
+const FILE_LINE = /(?:^|[\s(`'"[])([^\s:`'"()]*\p{L}[^\s:`'"()]*):(\d+)\b/gu;
+const fileLines = (text) => [...String(text).matchAll(FILE_LINE)].map((m) => `${m[1]}:${m[2]}`);
+const PATH_EDGE = /[^\s(`'",;]/u;
+/** True when `text` names `at` (file:line) as a whole token, not inside a longer path. */
+function names(text, at) {
+  const t = String(text);
+  for (let i = t.indexOf(at); i !== -1; i = t.indexOf(at, i + 1)) {
+    const before = i === 0 ? "" : t[i - 1];
+    const after = t[i + at.length] ?? "";
+    if ((!before || !PATH_EDGE.test(before)) && !/\d/.test(after)) return true;
+  }
+  return false;
+}
+const normRequirement = (s) => String(s).toLowerCase().replace(/\s+/g, " ").trim();
+
+/** Reviewer files named by --reviewers, or found by --reviewers-dir; null when neither is given. */
+function reviewerFiles() {
+  const listAt = process.argv.indexOf("--reviewers");
+  const dirAt = process.argv.indexOf("--reviewers-dir");
+  if (listAt === -1 && dirAt === -1) return null;
+  const files = [];
+  if (listAt !== -1) {
+    const value = process.argv[listAt + 1];
+    if (!value || value.startsWith("--"))
+      throw new Error("--reviewers needs a comma-separated list");
+    files.push(...value.split(",").filter(Boolean));
+  }
+  if (dirAt !== -1) {
+    const dir = process.argv[dirAt + 1];
+    if (!dir || dir.startsWith("--")) throw new Error("--reviewers-dir needs a folder");
+    for (const name of readdirSync(dir).sort()) {
+      if (/^reviewer-.*\.json$/.test(name)) files.push(join(dir, name));
+    }
+  }
+  return files;
+}
+
+/** Requirements the reviewers could not verify from the diff, from their files. */
+function reviewerRequirements() {
+  const files = reviewerFiles();
+  if (files === null) return null;
+  const out = new Set();
+  for (const p of files) {
+    const doc = JSON.parse(readFileSync(p, "utf-8"));
+    for (const row of doc?.cannotVerify ?? []) {
+      if (typeof row?.requirement === "string") out.add(normRequirement(row.requirement));
+    }
+  }
+  return out;
+}
+
+/** The input path: the first argument that is neither a flag nor a flag's value. */
+function inputArg() {
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--reviewers" || args[i] === "--reviewers-dir") i++;
+    else if (!args[i].startsWith("--")) return args[i];
+  }
+  return undefined;
+}
 
 function readInput() {
-  const arg = process.argv[2];
+  const arg = inputArg();
   if (!arg) {
     console.error("error: provide a path or '-' for STDIN");
     process.exit(64); // EX_USAGE
@@ -108,11 +185,33 @@ function validateVerification(v, label, errors) {
   }
 }
 
+/** The finding's source kind, or null when none is valid. */
+function sourceOf(f) {
+  if (f?.foundBy !== undefined) return FOUND_BY_RE.test(String(f.foundBy)) ? "label" : null;
+  if (typeof f?.tag === "string" && f.tag) return "tag";
+  return ALLOWED_REVIEWERS.has(f?.reviewer) ? "reviewer" : null;
+}
+
+/** With --anonymized: every finding that names a reviewer, by list and index. */
+function identityLeaks(parsed) {
+  const out = [];
+  (parsed.accepted || []).forEach((f, i) => {
+    if (f && Object.hasOwn(f, "reviewer")) out.push(`accepted[${i}]`);
+  });
+  for (const key of ["deferred", "rejected"]) {
+    (parsed[key] || []).forEach((e, i) => {
+      if (e?.finding && Object.hasOwn(e.finding, "reviewer")) out.push(`${key}[${i}].finding`);
+    });
+  }
+  return out;
+}
+
 function validateAccepted(f, i, errors) {
   validateRawFinding(f, `accepted[${i}]`, errors);
-  if (!ALLOWED_REVIEWERS.has(f.reviewer)) {
+  const source = sourceOf(f);
+  if (source === null) {
     errors.push(
-      `accepted[${i}]: reviewer must be one of fable|opus|sonnet|gpt (got ${JSON.stringify(f.reviewer)}; haiku was removed in v2.1.0)`,
+      `accepted[${i}]: name the source as foundBy ("Source A".."Source Z" or "security-auditor"), tag, or reviewer fable|opus|sonnet|gpt (got reviewer ${JSON.stringify(f?.reviewer)}, foundBy ${JSON.stringify(f?.foundBy)})`,
     );
   }
   if (typeof f.fix !== "string" || f.fix.length < 4) {
@@ -213,6 +312,52 @@ function validate(raw) {
   parsed.accepted.forEach((f, i) => validateAccepted(f, i, errors));
   parsed.deferred.forEach((f, i) => validateClassified(f, "deferred", i, errors));
   parsed.rejected.forEach((f, i) => validateClassified(f, "rejected", i, errors));
+  if (ANONYMIZED) {
+    for (const at of identityLeaks(parsed)) {
+      errors.push(
+        `${at}: carries reviewer in an anonymized verdict; carry foundBy through, the family is restored after validation`,
+      );
+    }
+  }
+
+  // Every requirement a reviewer could not verify from the diff is settled here:
+  // checked in the unchanged code (verified), turned into a finding, or ruled
+  // out of scope, each with its evidence.
+  if (parsed.cannotVerify !== undefined && !Array.isArray(parsed.cannotVerify)) {
+    errors.push("cannotVerify must be an array when present");
+  }
+  const settled = new Set();
+  const list = (x) => (Array.isArray(x) ? x : []);
+  const kept = [...list(parsed.accepted), ...list(parsed.deferred).map((d) => d?.finding)]
+    .filter((f) => typeof f?.file === "string" && Number.isInteger(f?.line))
+    .map((f) => `${f.file}:${f.line}`);
+  (Array.isArray(parsed.cannotVerify) ? parsed.cannotVerify : []).forEach((row, i) => {
+    const label = `cannotVerify[${i}]`;
+    if (typeof row?.requirement !== "string" || row.requirement.trim().length < 4) {
+      errors.push(`${label}: requirement must be a string >= 4 chars`);
+      return;
+    }
+    if (!CANNOT_VERIFY_RESOLUTIONS.has(row.resolution)) {
+      errors.push(`${label}: resolution must be verified|finding|out-of-scope`);
+    }
+    if (typeof row.evidence !== "string" || row.evidence.trim().length < 4) {
+      errors.push(`${label}: evidence must say how it was settled`);
+    } else if (row.resolution === "verified" && !fileLines(row.evidence).length) {
+      errors.push(`${label}: a verified requirement cites the file:line it read`);
+    } else if (row.resolution === "finding" && !kept.some((at) => names(row.evidence, at))) {
+      errors.push(`${label}: evidence names no accepted or deferred finding (cite its file:line)`);
+    }
+    settled.add(normRequirement(row.requirement));
+  });
+  let required;
+  try {
+    required = reviewerRequirements();
+  } catch (err) {
+    errors.push(`--reviewers unreadable: ${err.message}`);
+  }
+  for (const req of required ?? []) {
+    if (!settled.has(req)) errors.push(`cannotVerify: reviewer requirement not settled: "${req}"`);
+  }
 
   // Optional consensus block (v3.1.0) + cross-check against the actual verdict
   // so the block is not merely decorative.

package/pipeline/scripts/work-items.mjs

@@ -7,6 +7,13 @@
  *                    /multi-agent:jira, /multi-agent:issue and Phase 0 run;
  *                    title, type, status, score, blockers, warnings, summary
  *                    and a description excerpt, scrubbed
+ *   reach            how far each open GitHub pull request reaches: its
+ *                    changed files (`gh pr view --json files`) looked up in
+ *                    the repository's own code graph, and the files that
+ *                    depend on them counted (graph-affected, depth 2). A
+ *                    repository without a graph, a Bitbucket pull request or
+ *                    a name that is not owner/repo is listed with its reason
+ *                    and costs no gh call
  *   prs              open pull requests on GitHub where you are asked to
  *                    review or are the author (`gh search prs`, the queries
  *                    /multi-agent:review lists). Bitbucket is reported as a
@@ -34,6 +41,7 @@
  * Usage:
  *   work-items.mjs maturity <key>
  *   work-items.mjs prs
+ *   work-items.mjs reach
  *   work-items.mjs verdict <task-id> [--post]
  *
  * MA_GH_BIN stands in for gh, MA_ISSUE_FETCHER and MA_POST_PR_REVIEW for the
@@ -57,6 +65,8 @@ import { runMain } from "../lib/fatal.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
 import { resolveTokenAsync } from "../lib/credential-resolve.mjs";
 import { homedir } from "node:os";
+import { affected } from "./graph-affected.mjs";
+import { loadGraph } from "./graph-query.mjs";
 
 export const CONTRACT_VERSION = "1.1.0";
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -349,6 +359,113 @@ export async function pullRequests({ env = process.env, redact = false } = {}) {
   return { contractVersion: CONTRACT_VERSION, items, sources };
 }
 
+const REACH_MAX = 20;
+const REACH_PARALLEL = 3;
+const REACH_DEPTH = 2;
+const FILES_MAX = 300;
+const NAME_PART = /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,100}$/;
+
+/** owner/repo with two plain parts; anything else never reaches gh. */
+function plainRepo(repo) {
+  const parts = String(repo).split("/");
+  return parts.length === 2 && parts.every((x) => NAME_PART.test(x));
+}
+
+async function inBatches(items, size, fn) {
+  const out = [];
+  for (let i = 0; i < items.length; i += size) {
+    out.push(...(await Promise.all(items.slice(i, i + size).map(fn))));
+  }
+  return out;
+}
+
+/** The changed file paths of one GitHub pull request, or null when gh could not say. */
+async function changedFiles(env, repo, number) {
+  const gh = env.MA_GH_BIN || "gh";
+  const r = await spawnAsync(
+    gh,
+    ["pr", "view", String(number), "--repo", repo, "--json", "files"],
+    {
+      env,
+      timeoutMs: TIMEOUT_MS,
+    },
+  );
+  if (r.error || r.status !== 0) return null;
+  try {
+    const files = JSON.parse(r.stdout)?.files;
+    return (Array.isArray(files) ? files : [])
+      .map((f) => f?.path)
+      .filter((path) => typeof path === "string" && path.length <= 1024)
+      .slice(0, FILES_MAX);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * How far each open pull request reaches, widest first. Changed paths are
+ * used only as keys into the local graph: nothing is read from disk by them
+ * and none is echoed back, only counts.
+ */
+export async function prReach({ env = process.env, list = null } = {}) {
+  const prs = list ?? (await pullRequests({ env }));
+  const envByLogin = new Map();
+  for (const a of await ghAccounts(env)) {
+    const aEnv = await accountEnv(env, a);
+    if (aEnv) envByLogin.set(a.login, aEnv);
+  }
+  const knowledge = join(env.HOME || homedir(), ".claude", "knowledge");
+  const graphs = new Map();
+  const graphFor = (project) => {
+    if (!graphs.has(project)) {
+      const path = join(knowledge, project, "code-graph.json");
+      let graph;
+      try {
+        graph = existsSync(path) ? loadGraph(path) : null;
+      } catch {
+        graph = null;
+      }
+      graphs.set(project, graph);
+    }
+    return graphs.get(project);
+  };
+  const candidates = prs.items
+    .filter((p) => p.source !== "github" || plainRepo(p.repo))
+    .slice(0, REACH_MAX);
+  const rows = await inBatches(candidates, REACH_PARALLEL, async (p) => {
+    const row = { source: p.source, repo: p.repo, number: p.number, project: null };
+    if (p.source !== "github") return { ...row, reach: null, reason: "not measured off GitHub" };
+    const project = p.repo.split("/")[1];
+    const graph = graphFor(project);
+    if (!graph) return { ...row, reach: null, reason: `no code graph for ${project}` };
+    const files = await changedFiles(envByLogin.get(p.account) ?? env, p.repo, p.number);
+    if (!files) return { ...row, project, reach: null, reason: "gh could not list its files" };
+    const ids = new Set(graph.nodes.filter((n) => n.kind === "file").map((n) => n.id));
+    const seeds = files.map((f) => `file:${f}`).filter((id) => ids.has(id));
+    const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+    const dependents = seeds.length
+      ? affected({ graph, seeds: seeds.map((id) => byId.get(id)), depth: REACH_DEPTH })
+      : [];
+    const reachedFiles = new Set(
+      dependents.filter((d) => d.node?.kind === "file").map((d) => d.id),
+    );
+    return {
+      ...row,
+      project,
+      changed: files.length,
+      inGraph: seeds.length,
+      reach: reachedFiles.size,
+    };
+  });
+  const updated = new Map(prs.items.map((p) => [`${p.repo}#${p.number}`, p.updatedAt ?? ""]));
+  rows.sort(
+    (a, b) =>
+      (b.reach ?? -1) - (a.reach ?? -1) ||
+      (updated.get(`${a.repo}#${a.number}`) < updated.get(`${b.repo}#${b.number}`) ? 1 : -1),
+  );
+  return { contractVersion: CONTRACT_VERSION, depth: REACH_DEPTH, items: rows };
+}
+
 function stateOf(taskId) {
   const { found, records } = selectRuns({ taskId });
   if (!found || !records.length) throw new WorkError("no-run", "no such run");
@@ -449,11 +566,12 @@ async function main(argv) {
     let out;
     if (cmd === "maturity" && arg) out = await issueMaturity(arg);
     else if (cmd === "prs" && !arg) out = await pullRequests();
+    else if (cmd === "reach" && !arg) out = await prReach();
     else if (cmd === "verdict" && arg && (flag === undefined || flag === "--post")) {
       out = flag ? await postReviewVerdict(arg) : reviewVerdictPreview(arg);
     } else {
       process.stderr.write(
-        "usage: work-items.mjs maturity <key> | prs | verdict <task-id> [--post]\n",
+        "usage: work-items.mjs maturity <key> | prs | reach | verdict <task-id> [--post]\n",
       );
       return 2;
     }

package/pipeline/scripts/worktree-prepare-all.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * @file worktree-prepare-all.mjs  -  the multi-repo worktree setup as one
+ * step: every repo gets its worktree, or none keeps one this step created.
+ *
+ * Phase 0 creates one worktree per repo of a multi-repo task. When the third
+ * repo's add fails, the first two must not stay behind on a half-made task.
+ * This runs worktree-prepare.sh serially in the given order and, on the first
+ * failure, rolls back what this call created, newest first:
+ *
+ *   - the worktree is removed without --force, so a worktree holding changes
+ *     is kept and reported instead of discarded;
+ *   - the branch is deleted only when worktree-prepare created it here
+ *     (newBranch) and it still points at origin/<base>, so a branch that
+ *     existed before, or gained a commit, is never deleted.
+ *
+ * A worktree that was reused (it existed before the call) is never touched.
+ *
+ * Usage:
+ *   worktree-prepare-all.mjs --repos <repos.json>
+ *     repos.json: [{project, path, branch, base, name?, email?}, ...]
+ *
+ * Output (stdout, JSON): {ok, results[], failed, rolledBack[], kept[]}
+ *   results     each repo's worktree-prepare.sh output, in order, up to the failure
+ *   failed      the failing repo's output, or null
+ *   rolledBack  [{project, worktreePath, branchDeleted}]
+ *   kept        [{project, worktreePath, reason}]  what the rollback left in place
+ *
+ * Exit: 0 every repo ready, 1 a repo failed (rollback done; see kept[]),
+ *       2 usage or a repos file that does not parse.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PREPARE = join(HERE, "worktree-prepare.sh");
+
+const git = (cwd, ...args) =>
+  execFileSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 60_000,
+  }).trim();
+
+function prepareOne(repo, prepare) {
+  try {
+    return prepareOnce(repo, prepare);
+  } catch (err) {
+    return {
+      ok: false,
+      out: {
+        project: repo.project,
+        worktreePath: repo.path,
+        branch: repo.branch,
+        baseBranch: repo.base,
+        action: "failed",
+        error: String(err?.message || err).slice(0, 500),
+      },
+    };
+  }
+}
+
+function prepareOnce(repo, prepare) {
+  const args = [
+    prepare,
+    "--project",
+    repo.project,
+    "--path",
+    repo.path,
+    "--branch",
+    repo.branch,
+    "--base",
+    repo.base,
+  ];
+  if (repo.name) args.push("--name", repo.name);
+  if (repo.email) args.push("--email", repo.email);
+  const r = spawnSync("bash", args, { encoding: "utf8", timeout: 300_000 });
+  let out;
+  try {
+    out = JSON.parse(r.stdout);
+  } catch {
+    out = null;
+  }
+  if (r.status === 0 && out && (out.action === "created" || out.action === "reused"))
+    return { ok: true, out };
+  return {
+    ok: false,
+    out: out ?? {
+      project: repo.project,
+      worktreePath: repo.path,
+      branch: repo.branch,
+      baseBranch: repo.base,
+      action: "failed",
+      error: (r.stderr || r.error?.message || `exit ${r.status}`).trim().slice(0, 500),
+    },
+  };
+}
+
+/** Undo one worktree this call created. Returns a rolledBack or kept record. */
+export function rollbackOne(res) {
+  const where = { project: res.project, worktreePath: res.worktreePath };
+  try {
+    git(res.project, "worktree", "remove", res.worktreePath);
+  } catch (err) {
+    return {
+      kept: {
+        ...where,
+        reason: `worktree not removed: ${String(err.stderr || err.message)
+          .trim()
+          .slice(0, 200)}`,
+      },
+    };
+  }
+  let branchDeleted = false;
+  if (res.newBranch === true) {
+    try {
+      const tip = git(res.project, "rev-parse", "--verify", `refs/heads/${res.branch}`);
+      const base = git(
+        res.project,
+        "rev-parse",
+        "--verify",
+        `refs/remotes/origin/${res.baseBranch}`,
+      );
+      if (tip === base) {
+        git(res.project, "branch", "-D", "--", res.branch);
+        branchDeleted = true;
+      }
+    } catch {
+      branchDeleted = false;
+    }
+  }
+  return { rolledBack: { ...where, branchDeleted } };
+}
+
+export function prepareAll(repos, { prepare = PREPARE } = {}) {
+  const results = [];
+  for (const repo of repos) {
+    const r = prepareOne(repo, prepare);
+    if (r.ok) {
+      results.push(r.out);
+      continue;
+    }
+    const rolledBack = [];
+    const kept = [];
+    for (const done of [...results].reverse()) {
+      if (done.action !== "created") continue;
+      const u = rollbackOne(done);
+      if (u.rolledBack) rolledBack.push(u.rolledBack);
+      else kept.push(u.kept);
+    }
+    return { ok: false, results, failed: r.out, rolledBack, kept };
+  }
+  return { ok: true, results, failed: null, rolledBack: [], kept: [] };
+}
+
+const FIELD = /^[^\0\n]+$/;
+
+export function readRepos(text) {
+  const list = JSON.parse(text);
+  if (!Array.isArray(list) || !list.length) throw new Error("repos must be a non-empty array");
+  for (const r of list) {
+    for (const k of ["project", "path", "branch", "base"]) {
+      if (typeof r?.[k] !== "string" || !FIELD.test(r[k]))
+        throw new Error(`each repo needs a string ${k}`);
+    }
+    for (const k of ["branch", "base"])
+      if (r[k].startsWith("-")) throw new Error(`${k} must not start with -`);
+    for (const k of ["name", "email"]) {
+      if (r[k] !== undefined && (typeof r[k] !== "string" || !FIELD.test(r[k]))) {
+        throw new Error(`${k} must be a string when given`);
+      }
+    }
+  }
+  return list;
+}
+
+function main() {
+  const i = process.argv.indexOf("--repos");
+  if (i < 0 || !process.argv[i + 1] || process.argv.length !== 4) {
+    console.error("usage: worktree-prepare-all.mjs --repos <repos.json>");
+    return 2;
+  }
+  let repos;
+  try {
+    repos = readRepos(readFileSync(process.argv[i + 1], "utf8"));
+  } catch (err) {
+    console.error(`worktree-prepare-all: ${err.message}`);
+    return 2;
+  }
+  const out = prepareAll(repos);
+  process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  return out.ok ? 0 : 1;
+}
+
+if (invokedDirectly(import.meta.url)) process.exit(main());

package/pipeline/scripts/worktree-prepare.sh

@@ -27,10 +27,13 @@
 #                       [--email <git user.email>]
 #
 # Output (stdout, JSON): {project, worktreePath, branch, baseBranch,
-#   action: created|reused|failed, pulled: true|false|null, error}
+#   action: created|reused|failed, pulled: true|false|null, newBranch, error}
+#   newBranch is true only when this call created the branch from origin/<base>,
+#   which is what tells worktree-prepare-all.mjs a rollback may delete it.
 #
 # Exit: 0 ready, 1 the add failed (nothing was created; the caller runs its
-#       rollback / collision flow), 2 usage.
+#       rollback / collision flow), 2 usage, a path outside <project>/.worktrees/,
+#       or a new branch outside the naming convention.
 set -uo pipefail
 
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -59,11 +62,43 @@ git -C "$PROJECT" rev-parse --git-dir >/dev/null 2>&1 || {
   exit 2
 }
 
+# The worktree lives in the project's own .worktrees/ directory, compared on
+# physical paths so a symlink cannot place it elsewhere.
+physical() { # nearest existing ancestor resolved, the rest appended
+  local p="$1" tail=""
+  while [ ! -e "$p" ] && [ "$p" != "/" ] && [ "$p" != "." ]; do
+    tail="/$(basename "$p")$tail"
+    p="$(dirname "$p")"
+  done
+  printf '%s%s' "$(cd "$p" 2>/dev/null && pwd -P)" "$tail"
+}
+WT_ROOT="$(physical "$PROJECT")/.worktrees/"
+case "$(physical "$WT")/" in
+  "$WT_ROOT"?*/) ;;
+  *)
+    echo "worktree-prepare: --path must be inside $PROJECT/.worktrees/ (got $WT)" >&2
+    exit 2
+    ;;
+esac
+# A branch this call creates follows the naming convention; an existing one
+# is re-entered as it is.
+if ! git -C "$PROJECT" show-ref --verify --quiet "refs/heads/$BRANCH" &&
+  ! git -C "$PROJECT" show-ref --verify --quiet "refs/remotes/origin/$BRANCH"; then
+  case "$BRANCH" in
+    feature/?* | bugfix/?* | hotfix/?* | release/?*) ;;
+    *)
+      echo "worktree-prepare: a new branch is named feature/<key>-<desc>, bugfix/<key>-<desc>, hotfix/<desc> or release/<version> (got $BRANCH)" >&2
+      exit 2
+      ;;
+  esac
+fi
+NEW_BRANCH=false
 report() { # $1 action, $2 pulled (true|false|null), $3 error
   jq -n --arg project "$PROJECT" --arg wt "$WT" --arg branch "$BRANCH" --arg base "$BASE" \
-    --arg action "$1" --argjson pulled "$2" --arg error "$3" \
+    --arg action "$1" --argjson pulled "$2" --argjson newBranch "$NEW_BRANCH" --arg error "$3" \
     '{project: $project, worktreePath: $wt, branch: $branch, baseBranch: $base,
-      action: $action, pulled: $pulled, error: (if $error == "" then null else $error end)}'
+      action: $action, pulled: $pulled, newBranch: $newBranch,
+      error: (if $error == "" then null else $error end)}'
 }
 
 # Physical path of $1, for comparing paths that may go through a symlink.
@@ -122,5 +157,6 @@ if ! err=$(git -C "$PROJECT" worktree add -q "${add_args[@]}" 2>&1); then
   report failed null "$err"
   exit 1
 fi
+[ "${add_args[1]}" = "-b" ] && NEW_BRANCH=true
 set_identity
 report created null ""