@dev-loops/core 1.0.0-rc.2 → 1.0.0-rc.3

package/src/github/issue-ops.mjs

@@ -0,0 +1,484 @@
+import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { runChild as defaultRunChild } from "../cli/primitives.mjs";
+import { parseJsonText } from "./review-threads.mjs";
+import { parseRepoSlug } from "./repo-slug.mjs";
+
+/**
+ * Core `gh issue` operations, extracted from the thin CLI wrappers under
+ * `scripts/github/*.mjs` (view/create/edit/comment/list-issue,
+ * detect-linked-issue-pr) so both the CLI scripts and the GitHub tracker
+ * adapter (`../tracker/github-adapter.mjs`) call one implementation instead
+ * of duplicating gh-command construction. The CLI scripts keep their own
+ * arg parsing/USAGE/runCli; this module owns the actual `gh` calls and output
+ * shaping. Mirrors the existing `../projects/move-queue-item.mjs` /
+ * `../projects/list-queue-items.mjs` split (core logic + thin CLI wrapper).
+ */
+
+const ISSUE_URL_NUMBER_PATTERN = /\/issues\/(\d+)(?:\D|$)/u;
+
+// ── view-issue ──────────────────────────────────────────────────────────
+
+export const VIEW_ISSUE_DEFAULT_FIELDS = "number,title,body,state,author,labels,url,createdAt,updatedAt";
+
+export async function viewIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  const fields = options.fields ?? VIEW_ISSUE_DEFAULT_FIELDS;
+  const result = await run(
+    ghCommand,
+    ["issue", "view", String(options.issue), "--repo", options.repo, "--json", fields],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue view failed: ${detail}`);
+  }
+  const issue = parseJsonText(result.stdout, { label: "gh issue view" });
+  if (issue === null || typeof issue !== "object" || Array.isArray(issue)) {
+    throw new Error("gh issue view did not return a JSON object");
+  }
+  return { ok: true, issue };
+}
+
+// ── create-issue ────────────────────────────────────────────────────────
+
+// Build the `gh issue create` args. A --body-file path is forwarded straight
+// to gh so large bodies avoid command-length limits.
+export function buildCreateArgs(options) {
+  const args = ["issue", "create", "--repo", options.repo, "--title", options.title];
+  if (options.body !== undefined) {
+    args.push("--body", options.body);
+  } else {
+    args.push("--body-file", options.bodyFile);
+  }
+  if (options.milestone !== undefined) {
+    args.push("--milestone", options.milestone);
+  }
+  for (const l of options.labels ?? []) {
+    args.push("--label", l);
+  }
+  for (const u of options.assignees ?? []) {
+    args.push("--assignee", u);
+  }
+  return args;
+}
+
+export async function createIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  const args = buildCreateArgs(options);
+  const result = await run(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue create failed: ${detail}`);
+  }
+  // gh prints the created issue URL to stdout.
+  const url = (result.stdout ?? "").trim();
+  const match = ISSUE_URL_NUMBER_PATTERN.exec(url);
+  if (!match) {
+    throw new Error(`gh issue create returned no parseable issue URL: ${url || "<empty>"}`);
+  }
+  return { ok: true, issueNumber: Number(match[1]), url };
+}
+
+// ── edit-issue ──────────────────────────────────────────────────────────
+
+export async function resolveEditBody(options) {
+  if (options.bodyFile === undefined) return options.body;
+  // Stdin (fd 0): fs/promises readFile does NOT accept an integer fd, so read
+  // it synchronously via the callback-style API (which does). A real path
+  // stays on the async promise read.
+  const body =
+    options.bodyFile === "-" ? readFileSync(0, "utf8") : await readFile(options.bodyFile, "utf8");
+  if (body.trim().length === 0) {
+    throw new Error(`--body-file ${options.bodyFile} is empty`);
+  }
+  return body;
+}
+
+// Build the `gh issue edit` args and the parallel `edited` list (which fields
+// were touched) so callers get a stable summary without re-reading the issue.
+export async function buildEditArgs(options) {
+  const args = ["issue", "edit", String(options.issue), "--repo", options.repo];
+  const edited = [];
+  if (options.title !== undefined) {
+    args.push("--title", options.title);
+    edited.push("title");
+  }
+  const body = await resolveEditBody(options);
+  if (body !== undefined) {
+    if (options.bodyFile !== undefined && options.bodyFile !== "-") {
+      args.push("--body-file", options.bodyFile);
+    } else {
+      args.push("--body", body);
+    }
+    edited.push("body");
+  }
+  for (const u of options.addAssignees ?? []) {
+    args.push("--add-assignee", u);
+  }
+  if ((options.addAssignees ?? []).length > 0) edited.push("add-assignee");
+  for (const u of options.removeAssignees ?? []) {
+    args.push("--remove-assignee", u);
+  }
+  if ((options.removeAssignees ?? []).length > 0) edited.push("remove-assignee");
+  if (options.milestone !== undefined) {
+    args.push("--milestone", options.milestone);
+    edited.push("milestone");
+  }
+  return { args, edited };
+}
+
+export async function editIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  const { args, edited } = await buildEditArgs(options);
+  const result = await run(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue edit failed: ${detail}`);
+  }
+  return { ok: true, repo: options.repo, issue: options.issue, edited };
+}
+
+// ── comment-issue ───────────────────────────────────────────────────────
+
+export async function resolveCommentBody(options) {
+  if (options.bodyFile === undefined) {
+    if (options.body.trim().length === 0) {
+      throw new Error("--body must not be empty");
+    }
+    return options.body;
+  }
+  const source = options.bodyFile === "-" ? 0 : options.bodyFile;
+  const body = await readFile(source, "utf8");
+  if (body.trim().length === 0) {
+    throw new Error(`--body-file ${options.bodyFile} is empty`);
+  }
+  return body;
+}
+
+export async function commentIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  const body = await resolveCommentBody(options);
+  const result = await run(
+    ghCommand,
+    ["issue", "comment", String(options.issue), "--repo", options.repo, "--body", body],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue comment failed: ${detail}`);
+  }
+  const commentUrl = result.stdout
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .pop() ?? null;
+  if (commentUrl === null || !/^https?:\/\//u.test(commentUrl)) {
+    throw new Error(`gh issue comment did not return a comment URL (got: ${result.stdout.trim() || "<empty>"})`);
+  }
+  return { ok: true, repo: options.repo, issue: options.issue, commentUrl };
+}
+
+// ── list-issues ─────────────────────────────────────────────────────────
+
+// Returns a well-typed issue, or null if the gh entry is missing/invalid in
+// any required field.
+export function normalizeIssue(raw) {
+  if (!Number.isInteger(raw?.number) || typeof raw?.title !== "string" || typeof raw?.state !== "string") {
+    return null;
+  }
+  return {
+    number: raw.number,
+    title: raw.title,
+    // gh reports issue state UPPERCASE (OPEN/CLOSED); normalize to lowercase.
+    state: raw.state.toLowerCase(),
+    labels: Array.isArray(raw?.labels)
+      ? raw.labels.map((l) => (typeof l?.name === "string" ? l.name : null)).filter((n) => n !== null)
+      : [],
+  };
+}
+
+export async function listIssues(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  const args = [
+    "issue",
+    "list",
+    "--repo",
+    options.repo,
+    "--state",
+    options.state ?? "open",
+    "--limit",
+    String(options.limit ?? 30),
+    "--json",
+    "number,title,state,labels",
+  ];
+  for (const label of options.labels ?? []) {
+    args.push("--label", label);
+  }
+  const result = await run(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue list failed: ${detail}`);
+  }
+  const payload = parseJsonText(result.stdout, { label: "gh issue list" });
+  if (!Array.isArray(payload)) {
+    throw new Error("gh issue list did not return a JSON array");
+  }
+  return { ok: true, issues: payload.map(normalizeIssue).filter((issue) => issue !== null) };
+}
+
+// ── detect-linked-issue-pr ──────────────────────────────────────────────
+
+export const LINKED_ISSUE_PR_QUERY = [
+  "query($owner:String!, $name:String!, $issue:Int!, $after:String) {",
+  "  repository(owner:$owner, name:$name) {",
+  "    issue(number:$issue) {",
+  "      timelineItems(first:100, after:$after, itemTypes:[CONNECTED_EVENT, CROSS_REFERENCED_EVENT]) {",
+  "        pageInfo {",
+  "          hasNextPage",
+  "          endCursor",
+  "        }",
+  "        nodes {",
+  "          __typename",
+  "          ... on ConnectedEvent {",
+  "            createdAt",
+  "            subject {",
+  "              __typename",
+  "              ... on PullRequest {",
+  "                number",
+  "                state",
+  "                url",
+  "                repository { nameWithOwner }",
+  "              }",
+  "            }",
+  "          }",
+  "          ... on CrossReferencedEvent {",
+  "            createdAt",
+  "            willCloseTarget",
+  "            source {",
+  "              __typename",
+  "              ... on PullRequest {",
+  "                number",
+  "                state",
+  "                url",
+  "                repository { nameWithOwner }",
+  "              }",
+  "            }",
+  "          }",
+  "        }",
+  "      }",
+  "    }",
+  "  }",
+  "}",
+].join("\n");
+
+function buildLinkedPrQueryArgs({ owner, name, issue, after }) {
+  const args = [
+    "api",
+    "graphql",
+    "--field",
+    `owner=${owner}`,
+    "--field",
+    `name=${name}`,
+    "-F",
+    `issue=${issue}`,
+    "--field",
+    `query=${LINKED_ISSUE_PR_QUERY}`,
+  ];
+  if (typeof after === "string" && after.length > 0) {
+    args.push("--field", `after=${after}`);
+  }
+  return args;
+}
+
+function readLinkedPrTimelineConnection(payload) {
+  const connection = payload?.data?.repository?.issue?.timelineItems;
+  if (!connection || typeof connection !== "object") {
+    throw new Error("Invalid linked-PR GraphQL payload: missing data.repository.issue.timelineItems");
+  }
+  const nodes = Array.isArray(connection.nodes) ? connection.nodes : [];
+  const pageInfo = connection.pageInfo ?? {};
+  return {
+    nodes,
+    hasNextPage: Boolean(pageInfo.hasNextPage),
+    endCursor: typeof pageInfo.endCursor === "string" ? pageInfo.endCursor : null,
+  };
+}
+
+function normalizeLinkedPrNode(node) {
+  if (!node || typeof node !== "object") {
+    return null;
+  }
+  if (node.__typename === "ConnectedEvent") {
+    return {
+      eventType: "CONNECTED_EVENT",
+      eventCreatedAt: node.createdAt,
+      pr: node.subject,
+    };
+  }
+  if (node.__typename === "CrossReferencedEvent") {
+    // Only a cross-reference that will CLOSE this issue owns its board status.
+    // A bare body-mention (willCloseTarget:false, e.g. "part of #X") must not
+    // create board-ownership linkage (#1130).
+    if (node.willCloseTarget !== true) {
+      return null;
+    }
+    return {
+      eventType: "CROSS_REFERENCED_EVENT",
+      eventCreatedAt: node.createdAt,
+      pr: node.source,
+    };
+  }
+  return null;
+}
+
+function compareStableStrings(left, right) {
+  if (left === right) {
+    return 0;
+  }
+  return left < right ? -1 : 1;
+}
+
+function normalizeRepoSlugForComparison(repo) {
+  return typeof repo === "string" ? repo.trim().toLowerCase() : "";
+}
+
+function normalizeOpenSameRepoCandidate(candidate, repo) {
+  const pr = candidate?.pr;
+  const number = pr?.number;
+  const state = pr?.state;
+  const url = pr?.url;
+  const nameWithOwner = pr?.repository?.nameWithOwner;
+  if (!Number.isInteger(number) || number <= 0) {
+    return null;
+  }
+  if (
+    state !== "OPEN"
+    || normalizeRepoSlugForComparison(nameWithOwner) !== normalizeRepoSlugForComparison(repo)
+  ) {
+    return null;
+  }
+  const createdAtMs = Date.parse(candidate.eventCreatedAt);
+  if (!Number.isFinite(createdAtMs)) {
+    return null;
+  }
+  return {
+    prNumber: number,
+    prUrl: typeof url === "string" ? url : null,
+    eventType: candidate.eventType,
+    eventCreatedAt: typeof candidate.eventCreatedAt === "string" ? candidate.eventCreatedAt : null,
+    createdAtMs,
+  };
+}
+
+function normalizeClosedUnmergedSameRepoCandidate(candidate, repo) {
+  const pr = candidate?.pr;
+  const number = pr?.number;
+  const state = pr?.state;
+  const url = pr?.url;
+  const nameWithOwner = pr?.repository?.nameWithOwner;
+  if (!Number.isInteger(number) || number <= 0) {
+    return null;
+  }
+  if (
+    state !== "CLOSED"
+    || normalizeRepoSlugForComparison(nameWithOwner) !== normalizeRepoSlugForComparison(repo)
+  ) {
+    return null;
+  }
+  const createdAtMs = Date.parse(candidate.eventCreatedAt);
+  if (!Number.isFinite(createdAtMs)) {
+    return null;
+  }
+  return {
+    prNumber: number,
+    prUrl: typeof url === "string" ? url : null,
+    eventType: candidate.eventType,
+    eventCreatedAt: typeof candidate.eventCreatedAt === "string" ? candidate.eventCreatedAt : null,
+    createdAtMs,
+  };
+}
+
+export function selectLinkedIssuePr(candidates) {
+  if (!Array.isArray(candidates) || candidates.length === 0) {
+    return null;
+  }
+  const sorted = [...candidates].sort((left, right) => {
+    const leftPriority = left.eventType === "CONNECTED_EVENT" ? 0 : 1;
+    const rightPriority = right.eventType === "CONNECTED_EVENT" ? 0 : 1;
+    if (leftPriority !== rightPriority) {
+      return leftPriority - rightPriority;
+    }
+    if (left.createdAtMs !== right.createdAtMs) {
+      return right.createdAtMs - left.createdAtMs;
+    }
+    if (left.prNumber !== right.prNumber) {
+      return right.prNumber - left.prNumber;
+    }
+    return compareStableStrings(String(left.prUrl ?? ""), String(right.prUrl ?? ""));
+  });
+  return sorted[0] ?? null;
+}
+
+export async function detectLinkedIssuePr({ repo, issue }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
+  const { owner, name } = parseRepoSlug(repo);
+  const candidates = [];
+  const closedUnmergedCandidates = [];
+  let after = null;
+  while (true) {
+    const result = await runChild(
+      ghCommand,
+      buildLinkedPrQueryArgs({ owner, name, issue, after }),
+      env,
+    );
+    if (result.code !== 0) {
+      const detail = result.stderr.trim() || `exit code ${result.code}`;
+      throw new Error(`gh command failed: ${detail}`);
+    }
+    const payload = parseJsonText(result.stdout);
+    const { nodes, hasNextPage, endCursor } = readLinkedPrTimelineConnection(payload);
+    for (const node of nodes) {
+      const normalizedNode = normalizeLinkedPrNode(node);
+      if (!normalizedNode) {
+        continue;
+      }
+      const normalizedCandidate = normalizeOpenSameRepoCandidate(normalizedNode, repo);
+      if (normalizedCandidate) {
+        candidates.push(normalizedCandidate);
+      }
+      const closedUnmergedCandidate = normalizeClosedUnmergedSameRepoCandidate(normalizedNode, repo);
+      if (closedUnmergedCandidate) {
+        closedUnmergedCandidates.push(closedUnmergedCandidate);
+      }
+    }
+    if (!hasNextPage) {
+      break;
+    }
+    if (!endCursor) {
+      throw new Error("Invalid linked-PR GraphQL payload: pageInfo.hasNextPage is true but endCursor is missing");
+    }
+    after = endCursor;
+  }
+  const selected = selectLinkedIssuePr(candidates);
+  const selectedClosedUnmerged = selectLinkedIssuePr(closedUnmergedCandidates);
+  if (!selected) {
+    return {
+      ok: true,
+      repo,
+      issue,
+      hasOpenLinkedPr: false,
+      prNumber: null,
+      prUrl: null,
+      hasPriorClosedUnmergedPr: selectedClosedUnmerged !== null,
+      priorClosedUnmergedPrNumber: selectedClosedUnmerged?.prNumber ?? null,
+      priorClosedUnmergedPrUrl: selectedClosedUnmerged?.prUrl ?? null,
+    };
+  }
+  return {
+    ok: true,
+    repo,
+    issue,
+    hasOpenLinkedPr: true,
+    prNumber: selected.prNumber,
+    prUrl: selected.prUrl,
+    selection: {
+      eventType: selected.eventType,
+      eventCreatedAt: selected.eventCreatedAt,
+    },
+  };
+}

package/src/github/ownership-helpers.mjs

@@ -0,0 +1,79 @@
+/**
+ * Shared deterministic single-contributor ownership classification for
+ * issue/PR assignees.
+ *
+ * Owner: packages/core — reusable pure logic consumed by the startup
+ * resolver (`resolve-dev-loop-startup.mjs`) and the Next Up pickup source
+ * (`resolve-active-board-item.mjs`). `classifyOwnership` never shells out —
+ * callers fetch assignees and the viewer's login via `gh`, then classify here.
+ */
+import { isCopilotLogin } from "./copilot-helpers.mjs";
+
+export const OWNERSHIP_STATE = Object.freeze({
+  ASSIGNED_TO_ME: "assigned_to_me",
+  ASSIGNED_TO_OTHER: "assigned_to_other",
+  ASSIGNED_TO_COPILOT: "assigned_to_copilot",
+  UNASSIGNED: "unassigned",
+});
+
+/**
+ * Classify assignee ownership of an issue/PR relative to the viewer.
+ *
+ * Copilot assignment is checked FIRST and short-circuits before any human
+ * comparison — the viewer login is never required to detect it, so a
+ * copilot-assigned artifact is unaffected by viewer-login resolution
+ * failures (matches the existing, unchanged Copilot-first flow).
+ *
+ * `assigned_to_me` requires the viewer to be the SOLE human assignee.
+ * `gh issue/pr edit --add-assignee` is not compare-and-swap, so two loopers
+ * racing to claim the same unassigned item can both end up co-assigned;
+ * membership-based classification would wave both through. A viewer
+ * co-assigned alongside another human is `assigned_to_other` (contested) —
+ * `foreignLogins` names the OTHER humans only (never the viewer), so error
+ * messages stay accurate. Login comparison is case-insensitive (GitHub
+ * logins are case-insensitive).
+ *
+ * @param {Array<{login?: string}>} assignees
+ * @param {string|null} [viewerLogin] - required only when a non-copilot
+ *   assignee is present; pass null/undefined when the caller skipped
+ *   resolving it (empty assignees, or a copilot assignee already found).
+ * @returns {{ state: string, foreignLogins: string[] }}
+ */
+export function classifyOwnership(assignees, viewerLogin = null) {
+  const logins = (Array.isArray(assignees) ? assignees : [])
+    .map((a) => a?.login)
+    .filter((login) => typeof login === "string" && login.length > 0);
+  if (logins.some(isCopilotLogin)) {
+    return { state: OWNERSHIP_STATE.ASSIGNED_TO_COPILOT, foreignLogins: [] };
+  }
+  if (logins.length === 0) {
+    return { state: OWNERSHIP_STATE.UNASSIGNED, foreignLogins: [] };
+  }
+  const viewerLoginLower = typeof viewerLogin === "string" && viewerLogin.length > 0
+    ? viewerLogin.toLowerCase()
+    : null;
+  const otherLogins = viewerLoginLower === null
+    ? logins
+    : logins.filter((login) => login.toLowerCase() !== viewerLoginLower);
+  if (viewerLoginLower !== null && otherLogins.length === 0) {
+    return { state: OWNERSHIP_STATE.ASSIGNED_TO_ME, foreignLogins: [] };
+  }
+  return { state: OWNERSHIP_STATE.ASSIGNED_TO_OTHER, foreignLogins: otherLogins };
+}
+
+/**
+ * Whether classifying these assignees requires a resolved viewer login (i.e.
+ * there is at least one non-copilot assignee to compare against). Lets
+ * callers skip the extra `gh api user` call for the common empty/copilot
+ * cases, which also keeps those cases immune to viewer-login resolution
+ * failures.
+ *
+ * @param {Array<{login?: string}>} assignees
+ * @returns {boolean}
+ */
+export function ownershipNeedsViewerLogin(assignees) {
+  const logins = (Array.isArray(assignees) ? assignees : [])
+    .map((a) => a?.login)
+    .filter((login) => typeof login === "string" && login.length > 0);
+  return logins.length > 0 && !logins.some(isCopilotLogin);
+}

package/src/loop/bash-command-classify.mjs

@@ -143,15 +143,16 @@ function shellSegments(command) {
 }
 
 /**
- * Leading prefix a `gh pr <verb>` segment may carry before the `gh` executable:
- * a run of `NAME=value` env assignments, optional `command`/`env`/`exec` wrapper
- * words, and an absolute/relative path on the gh binary (`/usr/bin/gh`).
+ * Leading prefix a command segment may carry before its real executable: a run of `NAME=value`
+ * env assignments, optional `command`/`env`/`exec` wrapper words, and an absolute/relative path on
+ * the binary (`/usr/bin/gh`, `/usr/bin/git`). Shared by every classifier in this file that must
+ * catch its verb behind these forms (`gh pr <verb>`, `git stash`, ...).
  *
  * Note: this is a pragmatic normalizer, not a full shell tokenizer. Subshell
  * `(gh pr create)`, `{ …; }` group, `-R=value` short-flag, and backslash-escaped
  * `\gh` forms are deliberately out of scope.
  */
-const GH_PR_VERB_PREFIX = "(?:[A-Za-z_][A-Za-z0-9_]*=\\S*\\s+)*(?:(?:command|env|exec)\\s+)*(?:\\S*/)?";
+const SHELL_EXEC_PREFIX = "(?:[A-Za-z_][A-Za-z0-9_]*=\\S*\\s+)*(?:(?:command|env|exec)\\s+)*(?:\\S*/)?";
 
 /**
  * Build the `gh <subcmd> <verb>` prefix matcher (subcmd = "pr" | "issue").
@@ -163,7 +164,36 @@ const GH_PR_VERB_PREFIX = "(?:[A-Za-z_][A-Za-z0-9_]*=\\S*\\s+)*(?:(?:command|env
  * match — their first token is `node`, not `gh`.
  */
 function ghSubcmdVerbRegex(subcmd, verb) {
-  return new RegExp(`^${GH_PR_VERB_PREFIX}gh\\s+${subcmd}\\s+${verb}(?:\\s|$)`, "i");
+  return new RegExp(`^${SHELL_EXEC_PREFIX}gh\\s+${subcmd}\\s+${verb}(?:\\s|$)`, "i");
+}
+
+/**
+ * A run of git global options that may appear between `git` and the subcommand: `-C <path>`,
+ * `-c <name>=<value>` (each consumes the following token as its value), `--git-dir=<path>`,
+ * `--work-tree=<path>`, or any other bare flag (`-x`, `--long-option`) that takes no value.
+ * Pragmatic normalizer, not a full git CLI parser.
+ */
+const GIT_GLOBAL_OPTION_RUN =
+  "(?:(?:-C|-c)\\s+\\S+\\s+|--(?:git-dir|work-tree)=\\S+\\s+|--?[A-Za-z][\\w-]*\\s+)*";
+
+/**
+ * Whether `command` contains a `git stash` invocation (any subcommand: bare, `push`, `pop`,
+ * `apply`, `save`, `list`, ...) in ANY shell segment — including behind the same env-assignment /
+ * `command`/`env`/`exec` wrapper / binary-path prefix (`GIT_DIR=.git git stash`, `command git
+ * stash`, `/usr/bin/git stash`) and git global options between `git` and `stash` (`git -C /tmp
+ * stash`, `git -c name=value stash pop`) that the sibling `gh` classifiers in this file already
+ * tolerate. Anchored per-segment, so `git stashed`, `git commit -m "git stash"`, or a path literal
+ * containing "git stash" never match. `refs/stash` is a single ref shared by every worktree over
+ * this repo's one `.git` directory, so a stash from one worktree can pop into another's — the
+ * PreToolUse gate blocks it outright on the target repo (see
+ * `skills/docs/worktree-guidance.md#never-git-stash-in-a-shared-git-layout`).
+ * @param {string} command @returns {boolean}
+ */
+export function commandContainsGitStash(command) {
+  const re = new RegExp(`^${SHELL_EXEC_PREFIX}git\\s+${GIT_GLOBAL_OPTION_RUN}stash(?:\\s|$)`, "i");
+  return command
+    .split(SHELL_SEGMENT_SEPARATOR)
+    .some((segment) => re.test(segment.trim()));
 }
 
 /** Build the `gh pr <verb>` prefix matcher — delegates to the generic subcmd matcher (DRY). */

package/src/loop/conductor-routing.mjs

@@ -17,7 +17,7 @@
  * - The evaluator is purely functional; no I/O or side effects
  * - Callers use evaluateConductorRouting as the single routing authority
  *
- * Integration boundary (see docs/conductor-routing-contract.md):
+ * Integration boundary (see skills/docs/conductor-routing-contract.md):
  * - This module starts after active-run identity and ownership are already resolved
  * - It consumes already-detected family-local lifecycle states as inputs
  * - It derives the routing outcome directly from states; it does not take a