@cursor/july 0.1.55 → 0.1.62

package/templates/agentic-owners/agent/lib/owners/decision.ts

@@ -0,0 +1,485 @@
+// Vendored from the Agentic Owners policy core; see README.md in this
+// directory for the deliberate divergences.
+//
+// The agentic-owners **approval decision** — the deterministic policy that
+// turns the matched `.agentic-owners` rules plus the agent's risk tier into a
+// concrete verdict for the PR: self-approve, or request reviewers (never
+// `CHANGES_REQUESTED`).
+//
+// Rules (closest-match policy is already applied upstream in match.ts):
+//  1. A rule with `always_approve: true` is satisfied at every risk tier.
+//  2. Low risk (`very_low` / `low`) → approve, UNLESS a matched policy is a hard
+//     gate (`human_review_required: true`) that the author cannot self-review.
+//  3. Medium+ risk (`medium` / `medium_high` / `high`) → request review from the
+//     owners and do NOT approve, UNLESS the author's `self_review` authority
+//     covers EVERY review-capable matched rule (each one sets
+//     `self_review: true` and lists the author as a `user:` owner) — then
+//     approve (including when a covered rule is also a hard gate).
+//  4. Medium+ risk without full self_review coverage → request reviewers
+//     (from the agent's recommended set), excluding the author themselves.
+//  5. Host fail-closes downgrade a would-be approve to requesting reviewers:
+//     a governance touch always; incomplete evidence (empty / truncated diff,
+//     capped file list) unless the author's self_review coverage vouches for a
+//     truncation.
+//
+// Settled invariants: a hard `human_review_required` gate blocks auto-approve
+// for non-owners (and blocks low-risk auto-approve entirely), but an owner may
+// clear it when that same rule sets `self_review: true`. An unknown/unparsed
+// risk never auto-approves (fail-safe to requesting reviewers).
+
+import { ruleIsHardGate, ruleIsNotifyOnly } from "./policyMode.js";
+import type { AgenticOwnersPathRule } from "./types.js";
+
+export type ApprovalAction = "approve" | "request_reviewers";
+
+export type ApprovalRiskBucket = "low" | "medium_plus" | "unknown";
+
+/** Canonical model risk tiers, after boundary normalization. */
+export type NormalizedApprovalRisk =
+  | "very_low"
+  | "low"
+  | "medium"
+  | "medium_high"
+  | "high";
+
+/** Normalize and validate a model risk tier at its boundary. */
+export function normalizeApprovalRisk(
+  riskLevel: string | undefined
+): NormalizedApprovalRisk | undefined {
+  const normalized = riskLevel?.trim().toLowerCase();
+  switch (normalized) {
+    case "very_low":
+    case "low":
+    case "medium":
+    case "medium_high":
+    case "high":
+      return normalized;
+    default:
+      return undefined;
+  }
+}
+
+/** Bucket the agent's risk level for the approval decision. */
+export function approvalRiskBucket(
+  riskLevel: string | undefined
+): ApprovalRiskBucket {
+  switch (normalizeApprovalRisk(riskLevel)) {
+    case "very_low":
+    case "low":
+      return "low";
+    case "medium":
+    case "medium_high":
+    case "high":
+      return "medium_plus";
+    default:
+      return "unknown";
+  }
+}
+
+/**
+ * The resolved PR author, used to evaluate the `self_review` carve-out.
+ * Team membership is never resolved (repo-scoped credentials cannot read
+ * org teams), so ownership checks match `user:` owners only — team-owned
+ * rules stay fail-closed for the author.
+ */
+export type ApprovalAuthor = {
+  /** PR author GitHub login (no `@`), when resolvable. */
+  readonly handle?: string;
+};
+
+/**
+ * Host-observed quality of the evidence behind the model's risk verdict.
+ * Any gap fails closed inside {@link decideApproval}: a verdict formed over
+ * partial evidence never auto-approves (see the carve-outs there).
+ */
+export type ApprovalEvidence = {
+  /** No reviewable file carried a usable patch (no evidence at all). */
+  readonly diffEmpty: boolean;
+  /**
+   * The model saw only part of the diff: the fetch char budget cut it, or
+   * some file carried no patch (binary / oversized).
+   */
+  readonly diffTruncated: boolean;
+  /**
+   * `listFiles` returned fewer paths than the PR reports (GitHub caps the
+   * listing at 3000 files). Omitted paths never entered policy matching,
+   * so neither the matched rules nor self_review coverage are sound.
+   */
+  readonly filesTruncated: boolean;
+};
+
+export type ApprovalDecision = {
+  readonly action: ApprovalAction;
+  /** True only when `action === "approve"`. */
+  readonly approve: boolean;
+  /** True when any matched rule is a hard `human_review_required` gate. */
+  readonly humanReviewRequired: boolean;
+  /** True when an owner-author + `self_review` lifted the no-approve default. */
+  readonly selfReviewApplied: boolean;
+  readonly riskBucket: ApprovalRiskBucket;
+  /** Reviewers to request when `action === "request_reviewers"` (else `[]`). */
+  readonly requestReviewers: readonly string[];
+  /** One-line, human-readable rationale for the check / Slack / comment. */
+  readonly reason: string;
+};
+
+/** Cap matching the prompt's "max 2 reviewers" rule. */
+export const MAX_REQUESTED_REVIEWERS = 2;
+
+function normalizeHandle(handle: string): string {
+  return handle.trim().replace(/^@/, "").toLowerCase();
+}
+
+/**
+ * Whether `author` is a listed `user:` owner of `rule` (handle match,
+ * case-insensitive). Returns false when the author identity is unknown, and
+ * always false for team-only ownership — membership is never resolved, so
+ * team-owned rules fail closed for the author.
+ */
+export function authorOwnsRule(
+  rule: AgenticOwnersPathRule,
+  author: ApprovalAuthor | undefined
+): boolean {
+  if (author?.handle === undefined || author.handle.trim() === "") {
+    return false;
+  }
+  const handle = normalizeHandle(author.handle);
+  return rule.users.some((user) => normalizeHandle(user) === handle);
+}
+
+/**
+ * The first matched rule (closest-match order is preserved) for which the author
+ * is an owner AND `self_review` is enabled — i.e. the rule that authorizes the
+ * author to approve their own change. Undefined when none applies.
+ */
+function selfReviewRuleForAuthor(
+  matchedRules: readonly AgenticOwnersPathRule[],
+  author: ApprovalAuthor | undefined
+): AgenticOwnersPathRule | undefined {
+  return matchedRules.find(
+    (rule) => rule.selfReview && authorOwnsRule(rule, author)
+  );
+}
+
+/**
+ * Whether the author's `self_review` authority covers EVERY matched rule that
+ * could require review: each review-capable rule (not `always_approve`, not
+ * notify-only) sets `self_review: true` AND lists the author as an owner —
+ * with at least one such rule present.
+ *
+ * This is the signal both self_review carve-outs inside {@link decideApproval}
+ * consult. The medium+ lift uses it because `self_review` clears *that rule*:
+ * one owned rule must not stamp a PR whose other matched rules still require
+ * review. The unverified-evidence fail-close uses it for its owner-vouching
+ * carve-out: the author could approve their own change under every matched
+ * policy at any tier, so truncation of the model's evidence must not hold the
+ * PR for a non-author owner who does not exist.
+ *
+ * Fail-tight by construction: no matched rules → false; only `always_approve`
+ * / notify-only matches → false (no review requirement to satisfy); ANY
+ * review-capable rule without `self_review`, or not owned by this author
+ * (unknown identity included) → false.
+ */
+export function authorSelfReviewCoversMatchedRules(
+  matchedRules: readonly AgenticOwnersPathRule[],
+  author: ApprovalAuthor | undefined
+): boolean {
+  const reviewCapableRules = matchedRules.filter(
+    (rule) => !rule.alwaysApprove && !ruleIsNotifyOnly(rule)
+  );
+  return (
+    reviewCapableRules.length > 0 &&
+    reviewCapableRules.every(
+      (rule) => rule.selfReview && authorOwnsRule(rule, author)
+    )
+  );
+}
+
+/**
+ * The reviewer set to request when not approving: the agent's recommended
+ * reviewers, with the author removed (you cannot review your own PR), deduped
+ * and capped at {@link MAX_REQUESTED_REVIEWERS}.
+ */
+function reviewersToRequest({
+  recommendedReviewers,
+  author,
+}: {
+  recommendedReviewers: readonly string[];
+  author: ApprovalAuthor | undefined;
+}): string[] {
+  const authorHandle =
+    author?.handle !== undefined && author.handle.trim() !== ""
+      ? normalizeHandle(author.handle)
+      : undefined;
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const raw of recommendedReviewers) {
+    const reviewer = raw.trim();
+    if (reviewer === "") {
+      continue;
+    }
+    // Drop the author when they appear as a bare-user handle; team handles
+    // (org/team) are kept even if the author is on that team — the request goes
+    // to the team, not the individual.
+    if (
+      authorHandle !== undefined &&
+      !reviewer.includes("/") &&
+      normalizeHandle(reviewer) === authorHandle
+    ) {
+      continue;
+    }
+    const key = reviewer.toLowerCase();
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    out.push(reviewer);
+    if (out.length >= MAX_REQUESTED_REVIEWERS) {
+      break;
+    }
+  }
+  return out;
+}
+
+/**
+ * The approve reason when no matched rule requires review: every match is
+ * `always_approve`, notify-only, or a mix — worded to match which it was.
+ */
+function reasonForNoBlockingOwners(
+  matchedRules: readonly AgenticOwnersPathRule[]
+): string {
+  const anyNotifyOnly = matchedRules.some((rule) => ruleIsNotifyOnly(rule));
+  if (!anyNotifyOnly) {
+    return "all matched policies set always_approve";
+  }
+  const anyAlwaysApprove = matchedRules.some((rule) => rule.alwaysApprove);
+  return anyAlwaysApprove
+    ? "matched policies are notify-only or always_approve (no blocking owners)"
+    : "all matched policies are notify-only (no blocking owners)";
+}
+
+/**
+ * Compute the approval verdict from the matched policy + agent risk + author,
+ * then apply the host fail-closes over it: a governance touch or unverified
+ * evidence downgrades a would-be approve to requesting reviewers, so the
+ * caller only ever writes the returned decision.
+ *
+ * Pure and dependency-free so it is exhaustively unit-testable; the IO (author
+ * resolution, evidence observation, actuating the decision) lives in the
+ * callers.
+ */
+export function decideApproval(input: {
+  matchedRules: readonly AgenticOwnersPathRule[];
+  riskLevel: string | undefined;
+  author?: ApprovalAuthor;
+  recommendedReviewers?: readonly string[];
+  /** Host-observed evidence quality; omitted means complete evidence. */
+  evidence?: ApprovalEvidence;
+  /**
+   * True when the PR touches ownership-governance paths (the policy files
+   * this agent enforces, CODEOWNERS). The model's tier never carries
+   * approval authority over its own review routing — and self_review does
+   * not clear it (an owner must not self-approve a rewrite of their own
+   * gates).
+   */
+  governanceTouch?: boolean;
+}): ApprovalDecision {
+  const { matchedRules, riskLevel, author } = input;
+  const reviewRequiredRules = matchedRules.filter(
+    (rule) => !rule.alwaysApprove && !ruleIsNotifyOnly(rule)
+  );
+  const riskBucket = approvalRiskBucket(riskLevel);
+  const humanReviewRequired = reviewRequiredRules.some((rule) =>
+    ruleIsHardGate(rule)
+  );
+  const requestReviewers = reviewersToRequest({
+    recommendedReviewers: input.recommendedReviewers ?? [],
+    author,
+  });
+
+  const requestVerdict = (reason: string): ApprovalDecision => ({
+    action: "request_reviewers",
+    approve: false,
+    humanReviewRequired,
+    selfReviewApplied: false,
+    riskBucket,
+    requestReviewers,
+    reason,
+  });
+
+  const approveVerdict = (
+    reason: string,
+    selfReviewApplied: boolean
+  ): ApprovalDecision => ({
+    action: "approve",
+    approve: true,
+    humanReviewRequired,
+    selfReviewApplied,
+    riskBucket,
+    requestReviewers: [],
+    reason,
+  });
+
+  const decision = baseApprovalVerdict({
+    matchedRules,
+    reviewRequiredRules,
+    riskBucket,
+    humanReviewRequired,
+    author,
+    requestVerdict,
+    approveVerdict,
+  });
+  if (!decision.approve) {
+    return decision;
+  }
+
+  // Host fail-closes over a would-be approve. Each downgrades to requesting
+  // reviewers (never CHANGES_REQUESTED) while keeping the base attribution.
+  const hold = (reason: string): ApprovalDecision => ({
+    ...decision,
+    action: "request_reviewers",
+    approve: false,
+    requestReviewers,
+    reason,
+  });
+
+  if (input.governanceTouch === true) {
+    return hold(
+      "the change edits ownership governance — auto-approve disabled (fail closed)"
+    );
+  }
+
+  const evidence = input.evidence;
+  if (evidence === undefined) {
+    return decision;
+  }
+  if (evidence.filesTruncated) {
+    // Matching itself ran over a partial file list, so self_review coverage
+    // is unknowable — nothing clears this hold.
+    return hold(
+      "the changed-file list is incomplete (GitHub caps listed files) — auto-approve disabled (fail closed)"
+    );
+  }
+  // An empty or truncated diff never auto-approves — including the
+  // no-blocking-owners branch — except when the author's own self_review
+  // authority covers every matched rule (truncation only; an empty patch
+  // carries no evidence at all).
+  const selfReviewClearsEvidence =
+    authorSelfReviewCoversMatchedRules(matchedRules, author) &&
+    !evidence.diffEmpty;
+  if ((evidence.diffEmpty || evidence.diffTruncated) && !selfReviewClearsEvidence) {
+    return hold(
+      evidence.diffEmpty
+        ? "no usable patch hunks — auto-approve disabled (fail closed)"
+        : "diff truncated at the fetch budget — auto-approve disabled (fail closed)"
+    );
+  }
+  return decision;
+}
+
+/** The policy-only verdict, before the host fail-closes are applied. */
+function baseApprovalVerdict(input: {
+  matchedRules: readonly AgenticOwnersPathRule[];
+  reviewRequiredRules: readonly AgenticOwnersPathRule[];
+  riskBucket: ApprovalRiskBucket;
+  humanReviewRequired: boolean;
+  author: ApprovalAuthor | undefined;
+  requestVerdict: (reason: string) => ApprovalDecision;
+  approveVerdict: (
+    reason: string,
+    selfReviewApplied: boolean
+  ) => ApprovalDecision;
+}): ApprovalDecision {
+  const {
+    matchedRules,
+    reviewRequiredRules,
+    riskBucket,
+    humanReviewRequired,
+    author,
+    requestVerdict,
+    approveVerdict,
+  } = input;
+
+  if (matchedRules.length > 0 && reviewRequiredRules.length === 0) {
+    return approveVerdict(reasonForNoBlockingOwners(matchedRules), false);
+  }
+
+  // A hard human-review gate blocks unless every hard-gate rule is cleared by
+  // owner self_review on that same rule. Low-risk auto-approve never clears a
+  // hard gate without self_review.
+  const blockingHardGate = reviewRequiredRules.find(
+    (rule) =>
+      ruleIsHardGate(rule) && !(rule.selfReview && authorOwnsRule(rule, author))
+  );
+  if (blockingHardGate !== undefined) {
+    return requestVerdict("a matched policy requires human review");
+  }
+
+  // Low risk → approve (hard gates above already filtered; remaining
+  // hard+self_review rules are cleared by the owner carve-out).
+  if (riskBucket === "low") {
+    const selfReviewRule = selfReviewRuleForAuthor(reviewRequiredRules, author);
+    if (selfReviewRule !== undefined && humanReviewRequired) {
+      return approveVerdict(
+        `low risk, owner self_review (${selfReviewRule.sourcePath})`,
+        true
+      );
+    }
+    return approveVerdict("low risk, advisory policy", false);
+  }
+
+  // Medium+ → request reviewers, unless the author's self_review authority
+  // covers EVERY review-capable matched rule. self_review clears *that
+  // rule*: one owned rule must not stamp a PR whose other matched rules
+  // still require review.
+  if (riskBucket === "medium_plus") {
+    if (authorSelfReviewCoversMatchedRules(matchedRules, author)) {
+      return approveVerdict(
+        "medium+ risk, owner self_review covers every matched policy",
+        true
+      );
+    }
+    return requestVerdict("medium+ risk, no auto-approve");
+  }
+
+  // (Settled) Unknown / unparsed risk never auto-approves.
+  return requestVerdict("risk could not be determined (fail-safe hold)");
+}
+
+/** A recommended reviewer split into the user / team buckets GitHub requires. */
+export type SplitReviewers = {
+  /** Bare user logins (no `@`). */
+  users: string[];
+  /** Team slugs (the trailing segment of an `org/team` handle). */
+  teams: string[];
+};
+
+/**
+ * Split the decision's recommended reviewers into GitHub's `reviewers` (users)
+ * and `team_reviewers` (team slugs) buckets. A handle with a `/` is a team
+ * (`org/team`); GitHub's request API wants only the trailing slug, not the org.
+ * Dedupes case-insensitively while preserving order.
+ */
+export function splitReviewers(reviewers: readonly string[]): SplitReviewers {
+  const users: string[] = [];
+  const teams: string[] = [];
+  const seenUsers = new Set<string>();
+  const seenTeams = new Set<string>();
+  for (const raw of reviewers) {
+    const handle = raw.trim().replace(/^@/, "");
+    if (handle === "") {
+      continue;
+    }
+    if (handle.includes("/")) {
+      const slug = handle.slice(handle.lastIndexOf("/") + 1);
+      if (slug !== "" && !seenTeams.has(slug.toLowerCase())) {
+        seenTeams.add(slug.toLowerCase());
+        teams.push(slug);
+      }
+    } else if (!seenUsers.has(handle.toLowerCase())) {
+      seenUsers.add(handle.toLowerCase());
+      users.push(handle);
+    }
+  }
+  return { users, teams };
+}

package/templates/agentic-owners/agent/lib/owners/handles.ts

@@ -0,0 +1,54 @@
+// Vendored from the Agentic Owners policy core; see README.md in this
+// directory. The source's `reviewersConventionHandle` (a Canon-specific
+// `<org>/<slug>-reviewers` convention) and its Graphite mention-sentinel
+// repair (a Graphite-PR-page round-trip artifact this template never sees)
+// are dropped: this template resolves bare team slugs against the watched
+// repository's owner.
+
+/**
+ * Validate and normalize a reviewer handle before it enters a candidate list, a
+ * model prompt, or a GitHub review-request API. Returns `@login` for a user,
+ * `org/team` for a team, or `undefined` for a shape GitHub would reject (so
+ * the caller drops it).
+ *
+ * Repairs the malformed shapes seen in the wild rather than emitting them: a
+ * duplicated leading org (`anysphere/anysphere/x` → `anysphere/x`, gen21
+ * shadow review) is collapsed, and a stray leading `@` / trailing dot / mixed
+ * case is normalized. A team handle with more than one meaningful `/` segment
+ * that is not a simple org duplication is rejected.
+ */
+export function sanitizeReviewerHandle(raw: string): string | undefined {
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    return undefined;
+  }
+  if (trimmed.includes("/")) {
+    const segments = trimmed
+      .replace(/^@/, "")
+      .replace(/\.+$/, "")
+      .toLowerCase()
+      .split("/")
+      .map((segment) => segment.trim())
+      .filter((segment) => segment !== "");
+    // A GitHub team handle is always exactly `org/team`. Collapse a duplicated
+    // leading org (the shape a double-prefix bug produces) before validating.
+    while (segments.length > 2 && segments[0] === segments[1]) {
+      segments.shift();
+    }
+    if (segments.length !== 2) {
+      return undefined;
+    }
+    const [org, team] = segments;
+    if (
+      org === undefined ||
+      team === undefined ||
+      !/^[a-z0-9][a-z0-9-]*$/.test(org) ||
+      !/^[a-z0-9][a-z0-9._-]*$/.test(team)
+    ) {
+      return undefined;
+    }
+    return `${org}/${team}`;
+  }
+  const login = trimmed.replace(/^@/, "").toLowerCase();
+  return /^[a-z0-9][a-z0-9-]*$/.test(login) ? `@${login}` : undefined;
+}