@bugmole/cli 0.5.0 → 0.6.0

package/src/registry/project-identity.ts

@@ -0,0 +1,206 @@
+/**
+ * What makes two projects "the same app", so one app is one project.
+ *
+ *  - A cloud project (its app is reachable on the public internet) is its
+ *    app's domain: the normalized host, e.g. `domain:shop.example.com`.
+ *  - A local project is its repository plus the app's folder inside it:
+ *    `repo:github.com/acme/shop#apps/web`. Two teammates who clone the same
+ *    repository compute the same key, and each app in a monorepo gets its own.
+ *
+ * The CLI computes the identity and the registry normalizes it again (it
+ * never trusts the client's form of it), then stores the key and its SHA-256
+ * for indexed lookups. Credentials in a git remote (`https://user:token@...`)
+ * are dropped here, before anything is sent or stored.
+ *
+ * Dependency-free on purpose: the Cloudflare Worker registry and the Node CLI
+ * both import it.
+ */
+
+export type ProjectIdentityKind = "domain" | "repo";
+
+export type ProjectIdentity = {
+  kind: ProjectIdentityKind;
+  /** The normalized, credential-free key: `domain:<host>` or `repo:<remote>#<appPath>`. */
+  key: string;
+  /** The app's origin (scheme, host, port), when one is known; informational, not part of the key. */
+  origin?: string | null;
+};
+
+/** What the CLI or dashboard sends; the registry normalizes it with parseProjectIdentity. */
+export type ProjectIdentityInput = {
+  kind?: unknown;
+  /** A git remote URL in any form git accepts (https, ssh, scp-like). */
+  remote?: unknown;
+  /** The app's folder relative to the repository root; "." for the root. */
+  appPath?: unknown;
+  /** The app's URL or origin. */
+  appUrl?: unknown;
+  /** A domain name, for kind "domain". */
+  domain?: unknown;
+};
+
+/** Hosts whose repository paths are case-insensitive, so `Acme/Shop` and `acme/shop` are one repo. */
+const CASE_INSENSITIVE_GIT_HOSTS = new Set(["github.com", "gitlab.com", "bitbucket.org", "dev.azure.com", "ssh.dev.azure.com", "codeberg.org"]);
+
+const PRIVATE_HOST = /^(localhost|.*\.localhost|.*\.local|.*\.test|.*\.internal|127\.|10\.|192\.168\.|169\.254\.|0\.0\.0\.0|\[?::1\]?$)/;
+
+/** Whether a host can only be reached from the machine or network it runs on. */
+export function isPrivateHost(rawHost: string): boolean {
+  const host = rawHost.toLowerCase().replace(/^\[|\]$/g, "");
+  if (PRIVATE_HOST.test(host) || host === "::1") return true;
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) {
+    const octets = /^172\.(\d{1,3})\./.exec(host);
+    if (octets && Number(octets[1]) >= 16 && Number(octets[1]) <= 31) return true;
+  }
+  return !host.includes(".");
+}
+
+/**
+ * A git remote as `host/path`: no scheme, user, password, token, port or
+ * `.git`; lowercase host. Null when it isn't a remote this can identify
+ * (a local path, an empty string).
+ *
+ *   https://user:tok@GitHub.com/Acme/Shop.git  -> github.com/acme/shop
+ *   git@github.com:acme/shop.git               -> github.com/acme/shop
+ *   ssh://git@gitlab.example.com:2222/a/b.git  -> gitlab.example.com/a/b
+ */
+export function normalizeGitRemote(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const raw = value.trim();
+  if (!raw) return null;
+  let host: string;
+  let repoPath: string;
+  const scpLike = /^(?:[^@/\s]+@)?([^:/\s]+):(?!\/)(.+)$/.exec(raw);
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+    let url: URL;
+    try {
+      // git+ssh://, ssh://, git://, http(s)://: URL parses them all once the scheme is plain.
+      url = new URL(raw.replace(/^[a-z0-9+.-]+:\/\//i, "https://"));
+    } catch {
+      return null;
+    }
+    if (/^file:/i.test(raw)) return null;
+    host = url.hostname;
+    repoPath = decodeURIComponent(url.pathname);
+  } else if (scpLike && !/^[a-z]:\\/i.test(raw)) {
+    host = scpLike[1];
+    repoPath = scpLike[2];
+  } else if (/^[a-z0-9-]+(\.[a-z0-9-]+)+\/[^\s]+$/i.test(raw)) {
+    // Already normalized (host/path), as the CLI sends it.
+    [host, repoPath] = [raw.slice(0, raw.indexOf("/")), raw.slice(raw.indexOf("/") + 1)];
+  } else {
+    return null;
+  }
+  host = host.toLowerCase().replace(/\.$/, "");
+  if (!host) return null;
+  repoPath = repoPath
+    .split(/[?#]/, 1)[0]
+    .replace(/\\/g, "/")
+    .replace(/\/+/g, "/")
+    .replace(/^\/+|\/+$/g, "")
+    .replace(/\.git$/i, "")
+    .replace(/\/+$/, "");
+  // Azure DevOps ssh remotes carry a "v3/" prefix the https form doesn't.
+  if (host === "ssh.dev.azure.com") {
+    host = "dev.azure.com";
+    repoPath = repoPath.replace(/^v3\//i, "");
+  }
+  if (!repoPath || repoPath.split("/").some((segment) => segment === "." || segment === "..")) return null;
+  if (CASE_INSENSITIVE_GIT_HOSTS.has(host)) repoPath = repoPath.toLowerCase();
+  return `${host}/${repoPath}`;
+}
+
+/** The app's folder inside the repository, as a clean relative POSIX path; "." for the root. */
+export function normalizeAppPath(value: unknown): string | null {
+  if (value === undefined || value === null) return ".";
+  if (typeof value !== "string") return null;
+  const cleaned = value.trim().replace(/\\/g, "/").replace(/\/+/g, "/").replace(/^(\.\/)+/, "").replace(/^\/+|\/+$/g, "");
+  if (!cleaned || cleaned === ".") return ".";
+  if (cleaned.split("/").some((segment) => segment === ".." || segment === ".")) return null;
+  return cleaned;
+}
+
+/** A plain hostname for identity: lowercase, no port, trailing dot or leading "www.". Null when it isn't one. */
+export function normalizeIdentityHost(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const host = value
+    .trim()
+    .toLowerCase()
+    .replace(/^[a-z][a-z0-9+.-]*:\/\//, "")
+    .replace(/^[^@/]*@/, "")
+    .replace(/[/?#].*$/, "")
+    .replace(/:\d+$/, "")
+    .replace(/\.$/, "")
+    .replace(/^www\./, "");
+  if (!/^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9-]{2,63}$/.test(host)) return null;
+  return host;
+}
+
+/** The origin of an app URL with any credentials dropped; null when it isn't an http(s) URL. */
+export function normalizeAppOrigin(value: unknown): string | null {
+  if (typeof value !== "string" || !value.trim()) return null;
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    return url.origin.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+/** A cloud project's identity from its app URL, or null for a private/local URL. */
+export function domainIdentityFromUrl(appUrl: unknown): ProjectIdentity | null {
+  const origin = normalizeAppOrigin(appUrl);
+  if (!origin) return null;
+  const hostname = new URL(origin).hostname;
+  if (isPrivateHost(hostname)) return null;
+  const host = normalizeIdentityHost(hostname);
+  return host ? { kind: "domain", key: `domain:${host}`, origin } : null;
+}
+
+/** A local project's identity from its git remote and the app's folder. */
+export function repoIdentity(remote: unknown, appPath: unknown, appUrl?: unknown): ProjectIdentity | null {
+  const normalizedRemote = normalizeGitRemote(remote);
+  const normalizedPath = normalizeAppPath(appPath);
+  if (!normalizedRemote || !normalizedPath) return null;
+  return { kind: "repo", key: `repo:${normalizedRemote}#${normalizedPath}`, origin: normalizeAppOrigin(appUrl) };
+}
+
+/**
+ * The registry's reading of what a client sent: a repo identity when there
+ * is a remote, otherwise a domain identity from the domain or public app URL.
+ * Null when nothing identifies the app (a new repo with no remote on
+ * localhost, say); "invalid" when the client sent something unusable.
+ */
+export function parseProjectIdentity(input: unknown): ProjectIdentity | null | "invalid" {
+  if (input === undefined || input === null) return null;
+  if (typeof input !== "object" || Array.isArray(input)) return "invalid";
+  const value = input as ProjectIdentityInput;
+  if (value.kind !== undefined && value.kind !== "repo" && value.kind !== "domain") return "invalid";
+  if (value.kind === "repo" || (value.kind === undefined && value.remote !== undefined)) {
+    return repoIdentity(value.remote, value.appPath, value.appUrl) ?? "invalid";
+  }
+  if (value.domain !== undefined) {
+    const host = normalizeIdentityHost(value.domain);
+    if (!host || isPrivateHost(host)) return "invalid";
+    return { kind: "domain", key: `domain:${host}`, origin: normalizeAppOrigin(value.appUrl) };
+  }
+  if (value.appUrl !== undefined) {
+    if (!normalizeAppOrigin(value.appUrl)) return "invalid";
+    return domainIdentityFromUrl(value.appUrl);
+  }
+  return value.kind === "domain" ? "invalid" : null;
+}
+
+/** The hex SHA-256 the registry indexes and compares identities by. */
+export async function identityHash(key: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(key));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** How the dashboard and CLI name an identity to a person. */
+export function describeIdentity(identity: Pick<ProjectIdentity, "kind" | "key">): string {
+  if (identity.kind === "domain") return identity.key.replace(/^domain:/, "");
+  const [remote, appPath] = identity.key.replace(/^repo:/, "").split("#");
+  return appPath && appPath !== "." ? `${remote} (${appPath})` : remote;
+}

package/src/registry/roles.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { actorProblem, normalizeRoleName, specRoleStatus, suggestRoles, suggestedRoleNames, usableRoleNames } from "./roles.js";
+
+test("role names become actor ids", () => {
+  assert.equal(normalizeRoleName("Signed-in Member"), "signed_in_member");
+  assert.equal(normalizeRoleName("  admin  "), "admin");
+  assert.equal(normalizeRoleName("9lives"), null);
+  assert.equal(normalizeRoleName(""), null);
+  assert.equal(normalizeRoleName("x".repeat(61)), null);
+});
+
+test("roles.yaml entries without a status are confirmed; the registry's decision wins", () => {
+  assert.equal(specRoleStatus({}), "confirmed");
+  assert.equal(specRoleStatus({ status: "suggested" }), "suggested");
+  const spec = [
+    { name: "user", status: specRoleStatus({}) },
+    { name: "admin", status: specRoleStatus({ status: "suggested" }) },
+    { name: "owner", status: specRoleStatus({}) },
+  ];
+  assert.deepEqual(usableRoleNames(spec), ["user", "owner"]);
+  const registry = [
+    { name: "owner", status: "rejected" as const },
+    { name: "admin", status: "confirmed" as const },
+    { name: "guest", status: "suggested" as const },
+  ];
+  assert.deepEqual(usableRoleNames(spec, registry).sort(), ["admin", "user"]);
+  assert.deepEqual(suggestedRoleNames(spec, registry), ["guest"]);
+});
+
+test("an unusable actor says why and what to do", () => {
+  const spec = [{ name: "user", status: "confirmed" as const }, { name: "admin", status: "suggested" as const }];
+  assert.equal(actorProblem("user", spec), null);
+  assert.match(actorProblem("admin", spec)!, /only suggested.*confirm it/);
+  assert.match(actorProblem("admin", spec, [{ name: "admin", status: "rejected" }])!, /rejected/);
+  assert.match(actorProblem("ghost", spec)!, /bugmole_role_propose/);
+  assert.match(actorProblem("ghost", spec)!, /Confirmed roles: user/);
+});
+
+test("suggestions come from sign-in walls, gated routes and menus, suggested spec roles and journey actors", () => {
+  const suggestions = suggestRoles({
+    nodes: [
+      { id: "screen:/", route: "/" },
+      { id: "screen:/login", route: "/login" },
+      { id: "screen:/admin/users", route: "/admin/users" },
+      { id: "action:mod", action: "Open moderation queue" },
+    ],
+    journeys: [{ id: "flow:checkout", name: "Checkout", actor: "Shopper" }],
+    specRoles: [{ name: "support_agent", description: "Support desk.", status: "suggested" }, { name: "user" }],
+  });
+  const byName = Object.fromEntries(suggestions.map((item) => [item.name, item]));
+  assert.equal(byName.guest.source, "sign_in_wall");
+  assert.match(byName.guest.evidence, /\/login/);
+  assert.equal(byName.member.source, "sign_in_wall");
+  assert.equal(byName.admin.source, "role_gated_route");
+  assert.equal(byName.moderator.source, "role_gated_menu");
+  assert.equal(byName.support_agent.source, "spec");
+  assert.equal(byName.shopper.source, "persona");
+  assert.equal(byName.user, undefined, "a confirmed spec role needs no suggestion");
+  assert.deepEqual(suggestRoles({ nodes: [{ id: "screen:/", route: "/" }] }), [], "nothing concrete, nothing suggested");
+});
+
+test("an auth blocker or a probe blocked behind sign-in is a sign-in wall too", () => {
+  assert.equal(suggestRoles({ blockers: [{ name: "login_required", type: "auth" }] })[0].source, "sign_in_wall");
+  assert.equal(suggestRoles({ nodes: [{ id: "screen:/orders", route: "/orders", runtimeProbe: { status: "blocked" } }] })[0].name, "guest");
+});

package/src/registry/roles.ts

@@ -0,0 +1,201 @@
+/**
+ * Roles: who a test journey is run as (a guest, a signed-in member, an
+ * admin). Shared by the registry Worker, the local registry stub, the
+ * planner, the pipeline, the MCP server and the dashboard, so it stays
+ * dependency-free.
+ *
+ * Bugmole proposes roles by itself — from sign-in walls, role-gated routes
+ * and menus, the project's spec/roles.yaml and the actors discovered
+ * journeys were walked as — but a proposal is only a suggestion. A person
+ * confirms, renames or rejects it, and only confirmed roles are used to
+ * plan test cases and runs. See docs/public/roles.md for why.
+ */
+
+export type RoleStatus = "suggested" | "confirmed" | "rejected";
+export const ROLE_STATUSES: readonly RoleStatus[] = ["suggested", "confirmed", "rejected"];
+
+/** Where a role came from. `person` means someone added it by hand. */
+export type RoleSource = "sign_in_wall" | "role_gated_route" | "role_gated_menu" | "spec" | "persona" | "agent" | "person";
+export const ROLE_SOURCES: readonly RoleSource[] = ["sign_in_wall", "role_gated_route", "role_gated_menu", "spec", "persona", "agent", "person"];
+
+export const ROLE_NAME_MAX = 60;
+export const ROLE_DESCRIPTION_MAX = 1000;
+export const ROLE_EVIDENCE_MAX = 2000;
+const ROLE_NAME = /^[a-z][a-z0-9_]*$/;
+
+export type RoleRecord = {
+  name: string;
+  description?: string | null;
+  status: RoleStatus;
+  source?: RoleSource | string;
+  evidence?: string | null;
+};
+
+export type RoleSuggestion = {
+  name: string;
+  description: string;
+  source: RoleSource;
+  evidence: string;
+};
+
+export function roleStatusOf(value: unknown): RoleStatus | null {
+  return typeof value === "string" && (ROLE_STATUSES as readonly string[]).includes(value) ? value as RoleStatus : null;
+}
+
+export function roleSourceOf(value: unknown): RoleSource | null {
+  return typeof value === "string" && (ROLE_SOURCES as readonly string[]).includes(value) ? value as RoleSource : null;
+}
+
+/**
+ * A role name as an actor id: lower case, words joined by underscores
+ * ("Signed-in member" → "signed_in_member"). Returns null when nothing
+ * usable is left or it is too long.
+ */
+export function normalizeRoleName(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const name = value.trim().toLowerCase().replace(/[\s-]+/g, "_").replace(/[^a-z0-9_]/g, "").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  if (!name || name.length > ROLE_NAME_MAX || !ROLE_NAME.test(name)) return null;
+  return name;
+}
+
+/**
+ * A role from spec/roles.yaml. An entry without `status` is confirmed: the
+ * file predates suggestions, and whoever checked it in chose it. Entries an
+ * agent adds are written `status: suggested` (bugmole_write_spec enforces it).
+ */
+export function specRoleStatus(entry: { status?: unknown } | null | undefined): RoleStatus {
+  return roleStatusOf(entry?.status) ?? "confirmed";
+}
+
+/**
+ * The roles a plan or a test case may be written for.
+ *
+ * A registry decision wins: a role a person rejected (or that still waits
+ * for them) in the dashboard is not usable just because roles.yaml lists
+ * it, and a role confirmed in the dashboard is usable even before anyone
+ * adds it to roles.yaml. Without a registry, roles.yaml decides.
+ */
+export function usableRoleNames(specRoles: RoleRecord[], registryRoles: RoleRecord[] = []): string[] {
+  const decided = new Map<string, RoleStatus>();
+  for (const role of specRoles) {
+    const name = normalizeRoleName(role.name) ?? role.name;
+    decided.set(name, role.status);
+  }
+  for (const role of registryRoles) {
+    const name = normalizeRoleName(role.name) ?? role.name;
+    decided.set(name, role.status);
+  }
+  return [...decided].filter(([, status]) => status === "confirmed").map(([name]) => name);
+}
+
+/** Roles still waiting for a person to confirm or reject them. */
+export function suggestedRoleNames(specRoles: RoleRecord[], registryRoles: RoleRecord[] = []): string[] {
+  const decided = new Map<string, RoleStatus>();
+  for (const role of [...specRoles, ...registryRoles]) decided.set(normalizeRoleName(role.name) ?? role.name, role.status);
+  return [...decided].filter(([, status]) => status === "suggested").map(([name]) => name);
+}
+
+/** Why an actor can't be used, or null when it can. */
+export function actorProblem(actor: string, specRoles: RoleRecord[], registryRoles: RoleRecord[] = []): string | null {
+  const usable = usableRoleNames(specRoles, registryRoles);
+  if (usable.includes(actor)) return null;
+  const all = [...specRoles, ...registryRoles];
+  const known = [...all].reverse().find((role) => (normalizeRoleName(role.name) ?? role.name) === actor);
+  const choices = usable.length ? usable.join(", ") : "(none confirmed yet)";
+  if (known?.status === "suggested") {
+    return `Role "${actor}" is only suggested. A person has to confirm it on the dashboard's Roles page (Manage → Roles) before it is used for test cases or runs. Confirmed roles: ${choices}.`;
+  }
+  if (known?.status === "rejected") {
+    return `Role "${actor}" was rejected by a person, so it isn't used for test cases or runs. Confirmed roles: ${choices}.`;
+  }
+  return `Role "${actor}" is not a confirmed role. Propose it with bugmole_role_propose and ask a person to confirm it. Confirmed roles: ${choices}.`;
+}
+
+type EvidenceNode = { id?: string; title?: string; route?: string; kind?: string; action?: string; actor?: string; metadata?: Record<string, unknown>; runtimeProbe?: { status?: string } };
+type EvidenceEdge = { label?: string; action?: string; to?: string };
+type EvidenceJourney = { id?: string; name?: string; actor?: string };
+
+export type RoleEvidence = {
+  nodes?: EvidenceNode[];
+  edges?: EvidenceEdge[];
+  journeys?: EvidenceJourney[];
+  /** Blockers from spec/blockers.yaml or recorded during exploration. */
+  blockers?: Array<{ name?: string; id?: string; type?: string; description?: string }>;
+  /** spec/roles.yaml entries. */
+  specRoles?: Array<{ name?: unknown; description?: unknown; status?: unknown }>;
+};
+
+const SIGN_IN_ROUTE = /(^|\/)(\(auth\)|login|log-in|signin|sign-in|signup|sign-up|register|auth|oauth)(\/|$)/i;
+/** Route segments that name who may use them, and the role each implies. */
+const GATED_SEGMENTS: Array<{ pattern: RegExp; role: string; description: string }> = [
+  { pattern: /(^|\/)(admin|administrator|superadmin)(\/|$)/i, role: "admin", description: "Administrator who can reach the admin area." },
+  { pattern: /(^|\/)(owner|owners)(\/|$)/i, role: "owner", description: "Owner who can reach owner-only screens." },
+  { pattern: /(^|\/)(staff|backoffice|back-office|ops|operations)(\/|$)/i, role: "staff", description: "Staff or operations user who can reach back-office screens." },
+  { pattern: /(^|\/)(moderator|moderation)(\/|$)/i, role: "moderator", description: "Moderator who can reach moderation screens." },
+  { pattern: /(^|\/)(vendor|seller|merchant)(\/|$)/i, role: "seller", description: "Seller or vendor who manages their own listings." },
+];
+const GATED_LABELS: Array<{ pattern: RegExp; role: string; description: string }> = [
+  { pattern: /\badmin(istration|istrator)?\b/i, role: "admin", description: "Administrator who sees the admin menu entry." },
+  { pattern: /\bstaff\b|\bback ?office\b/i, role: "staff", description: "Staff user who sees the back-office menu entry." },
+  { pattern: /\bmoderat(e|ion|or)\b/i, role: "moderator", description: "Moderator who sees the moderation menu entry." },
+];
+
+/**
+ * What roles the evidence implies, as suggestions for a person to decide.
+ * Deterministic and conservative: it only names a role something concrete
+ * points at, and says what that was in `evidence`.
+ */
+export function suggestRoles(evidence: RoleEvidence): RoleSuggestion[] {
+  const suggestions = new Map<string, RoleSuggestion>();
+  const add = (suggestion: RoleSuggestion) => {
+    if (!suggestions.has(suggestion.name)) suggestions.set(suggestion.name, suggestion);
+  };
+  const nodes = evidence.nodes ?? [];
+
+  const signIn = nodes.find((node) => typeof node.route === "string" && SIGN_IN_ROUTE.test(node.route));
+  const authBlocked = nodes.find((node) => node.runtimeProbe?.status === "blocked"
+    || (node.metadata as { runtimeProbe?: { status?: string } } | undefined)?.runtimeProbe?.status === "blocked"
+    || (node.metadata as { requiresAuth?: unknown } | undefined)?.requiresAuth === true);
+  const authBlocker = (evidence.blockers ?? []).find((blocker) =>
+    /auth|login|sign.?in|session/i.test(`${blocker.type ?? ""} ${blocker.name ?? blocker.id ?? ""}`));
+  const wall = signIn
+    ? `sign-in screen at ${signIn.route}`
+    : authBlocked
+      ? `${authBlocked.route ?? authBlocked.id} needs a signed-in session`
+      : authBlocker
+        ? `blocker "${authBlocker.name ?? authBlocker.id}" (${authBlocker.type ?? "auth"})`
+        : null;
+  if (wall) {
+    add({ name: "guest", description: "Visitor who is not signed in and only sees public screens.", source: "sign_in_wall", evidence: wall });
+    add({ name: "member", description: "Signed-in user who gets past the sign-in wall.", source: "sign_in_wall", evidence: wall });
+  }
+
+  for (const node of nodes) {
+    const route = typeof node.route === "string" ? node.route : "";
+    for (const gated of GATED_SEGMENTS) {
+      if (route && gated.pattern.test(route)) add({ name: gated.role, description: gated.description, source: "role_gated_route", evidence: `route ${route}` });
+    }
+  }
+  const labels = [
+    ...nodes.map((node) => node.action ?? ""),
+    ...(evidence.edges ?? []).flatMap((edge) => [edge.label ?? "", edge.action ?? ""]),
+  ].filter(Boolean);
+  for (const label of labels) {
+    for (const gated of GATED_LABELS) {
+      if (gated.pattern.test(label)) add({ name: gated.role, description: gated.description, source: "role_gated_menu", evidence: `menu or action "${label.slice(0, 80)}"` });
+    }
+  }
+
+  for (const entry of evidence.specRoles ?? []) {
+    const name = normalizeRoleName(entry?.name);
+    if (!name || specRoleStatus(entry as { status?: unknown }) !== "suggested") continue;
+    add({ name, description: typeof entry.description === "string" ? entry.description : `Role ${name} from spec/roles.yaml.`, source: "spec", evidence: "spec/roles.yaml lists it as suggested" });
+  }
+
+  for (const journey of evidence.journeys ?? []) {
+    const name = normalizeRoleName(journey.actor);
+    if (!name) continue;
+    add({ name, description: `The role the discovered journey "${journey.name ?? journey.id}" was walked as.`, source: "persona", evidence: `journey ${journey.id ?? journey.name} actor` });
+  }
+  return [...suggestions.values()];
+}

package/src/registry/task-scheduling.test.ts

@@ -2,12 +2,50 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import {
   MAX_TASK_ATTEMPTS,
+  approvalModeOf,
+  needsApproval,
+  workerApprovalMode,
+  workerMayTake,
   backoffUntil,
   isClaimableTask,
   isResumableTask,
   resumedTaskFields,
+  resumedApproval,
+  localWorkerConnected,
+  resumePlacement,
+  strandedTaskMessage,
+  LOCAL_WORKER_FRESH_MS,
+  IN_REVIEW,
+  completionStatus,
+  needsCompletionReview,
+  sentBackTaskFields,
 } from "./task-scheduling.js";
 
+test("completion review follows the same risk model as start approval", () => {
+  for (const type of ["code", "ui", "investigation", "discovery"]) {
+    assert.equal(completionStatus("manual", type), IN_REVIEW, `manual reviews ${type}`);
+    assert.equal(completionStatus("extreme", type), "completed", `extreme reviews nothing (${type})`);
+    assert.equal(needsCompletionReview("auto", type), needsApproval("auto", type));
+  }
+  assert.equal(completionStatus("auto", "code"), IN_REVIEW);
+  assert.equal(completionStatus("auto", "ui"), IN_REVIEW);
+  assert.equal(completionStatus("auto", "investigation"), "completed");
+  assert.equal(completionStatus("auto", "discovery"), "completed");
+});
+
+test("a task in review is neither claimable nor resumable, and sending it back requeues it with the note", () => {
+  const now = Date.UTC(2026, 0, 1, 12, 0, 0);
+  const inReview = { status: IN_REVIEW, attempts: 1, approvedAt: "2026-01-01T00:00:00Z", approvedBy: "ann@example.com" };
+  assert.equal(isClaimableTask(inReview, now), false);
+  assert.equal(isResumableTask(inReview, now), false);
+  const fields = sentBackTaskFields("Fix the overlap");
+  assert.equal(fields.status, "queued");
+  assert.equal(fields.attempts, 0);
+  assert.equal(fields.reviewNote, "Fix the overlap");
+  assert.match(fields.progressMessage, /Sent back from review: Fix the overlap/);
+  assert.equal(isClaimableTask({ ...inReview, ...fields }, now), true, "the kept approval lets a worker take it again");
+});
+
 const NOW = Date.UTC(2026, 0, 1, 12, 0, 0);
 
 test("a queued task with no history is claimable", () => {
@@ -98,3 +136,59 @@ test("a resumed task is immediately claimable again — the whole point of resum
   assert.equal(isClaimableTask(parked, NOW), false);
   assert.equal(isClaimableTask({ ...parked, ...resumedTaskFields() }, NOW), true);
 });
+
+test("approval modes: manual holds everything, auto holds code changes, extreme holds nothing", () => {
+  for (const type of ["code", "ui", "investigation", "discovery"]) assert.equal(needsApproval("manual", type), true, type);
+  assert.deepEqual(["code", "ui", "investigation", "discovery"].map((type) => needsApproval("auto", type)), [true, true, false, false]);
+  for (const type of ["code", "ui", "investigation", "discovery"]) assert.equal(needsApproval("extreme", type), false, type);
+  assert.equal(approvalModeOf("Manual"), null, "modes are exact");
+  assert.equal(workerApprovalMode({ BUGMOLE_APPROVAL: " manual " }), "manual");
+  assert.equal(workerApprovalMode({ BUGMOLE_APPROVAL: "yolo" }), undefined);
+});
+
+test("a task waiting for approval is never claimable, and a stricter worker waits for a person", () => {
+  const waiting = { status: "queued", taskType: "code", approvedAt: null, approvedBy: null };
+  assert.equal(isClaimableTask(waiting, NOW), false);
+  const autoApproved = { status: "queued", taskType: "code", approvedAt: "2026-01-01", approvedBy: "auto:extreme" };
+  assert.equal(isClaimableTask(autoApproved, NOW), true, "no worker mode: whatever the project allows");
+  assert.equal(isClaimableTask(autoApproved, NOW, "auto"), false, "an auto worker won't take a code change nobody approved");
+  assert.equal(workerMayTake({ ...autoApproved, approvedBy: "steve@theaiinc.com" }, "manual"), true, "a person's approval satisfies any worker");
+  assert.equal(workerMayTake({ status: "queued", taskType: "investigation", approvedAt: "x", approvedBy: "auto:auto" }, "auto"), true);
+  assert.equal(workerMayTake({ status: "queued", taskType: "investigation" }, undefined), true, "a registry without approval columns");
+});
+
+test("resuming keeps a person's approval and lets the current mode decide an automatic one", () => {
+  const human = { approvedAt: "2026-01-01", approvedBy: "steve@theaiinc.com", taskType: "code" };
+  assert.deepEqual(resumedApproval(human, "manual"), { approvedBy: "steve@theaiinc.com" });
+  const auto = { approvedAt: "2026-01-01", approvedBy: "auto:extreme", taskType: "code" };
+  assert.deepEqual(resumedApproval(auto, "auto"), { approvedBy: null }, "auto mode holds code changes");
+  assert.deepEqual(resumedApproval(auto, "extreme"), { approvedBy: "auto:extreme" });
+  const waiting = { approvedAt: null, approvedBy: null, taskType: "investigation" };
+  assert.deepEqual(resumedApproval(waiting, "auto"), { approvedBy: "auto:auto" }, "the project has since dropped the step");
+  assert.deepEqual(resumedApproval(waiting, "manual"), { approvedBy: null });
+});
+
+test("a machine counts as connected while its last task listing is recent", () => {
+  assert.equal(localWorkerConnected(null, NOW), false);
+  assert.equal(localWorkerConnected("not a date", NOW), false);
+  assert.equal(localWorkerConnected(new Date(NOW - 5_000).toISOString(), NOW), true);
+  assert.equal(localWorkerConnected(new Date(NOW - LOCAL_WORKER_FRESH_MS - 1).toISOString(), NOW), false);
+});
+
+test("resume sends cloud tasks to the cloud and refuses a machine-only task nothing on a cloud project will run", () => {
+  const recent = new Date(NOW - 5_000).toISOString();
+  const cloudProject = { storageMode: "managed", defaultExecutionMode: "cloud" };
+  assert.deepEqual(resumePlacement({ executionMode: "cloud", taskType: "discovery" }, cloudProject, NOW), { kind: "cloud" });
+  assert.deepEqual(resumePlacement({ executionMode: "self", taskType: "investigation" }, cloudProject, NOW), { kind: "stranded", canRunInCloud: false });
+  assert.deepEqual(resumePlacement({ executionMode: "self", taskType: "discovery" }, cloudProject, NOW), { kind: "stranded", canRunInCloud: true });
+  assert.deepEqual(resumePlacement({ executionMode: "self", taskType: "code" }, { ...cloudProject, localWorkerSeenAt: recent }, NOW), { kind: "machine" });
+  assert.deepEqual(
+    resumePlacement({ executionMode: "self", taskType: "discovery" }, { storageMode: "byo", defaultExecutionMode: "cloud" }, NOW),
+    { kind: "stranded", canRunInCloud: false },
+    "cloud by default, but cloud runs need Bugmole storage",
+  );
+  assert.deepEqual(resumePlacement({ executionMode: "self", taskType: "code" }, { storageMode: "byo", defaultExecutionMode: "self" }, NOW), { kind: "machine" }, "a machine project queues ahead of `bugmole serve`");
+  assert.match(strandedTaskMessage(false), /npx bugmole serve/);
+  assert.doesNotMatch(strandedTaskMessage(false), /Bugmole Cloud/);
+  assert.match(strandedTaskMessage(true), /resume it on Bugmole Cloud/);
+});