pr-shepherd 0.2.0 → 0.4.0

package/{src/github/pagination.mts → bin/github/pagination.mjs}

@@ -9,19 +9,6 @@
  *   - Forward (`after` + `first`) — used by check contexts.
  *   - Backward (`before` + `last`) — used by reviewThreads (default GitHub order).
  */
-
-export interface PageInfo {
-  hasNextPage?: boolean;
-  hasPreviousPage?: boolean;
-  endCursor?: string | null;
-  startCursor?: string | null;
-}
-
-export interface Connection<T> {
-  pageInfo: PageInfo;
-  nodes: T[];
-}
-
 /**
  * Paginate forward through a GraphQL connection (`first` / `after` cursors).
  *
@@ -31,26 +18,19 @@ export interface Connection<T> {
  *                      `endCursor` of an already-fetched page to fetch only
  *                      the pages *after* it, avoiding a duplicate re-fetch.
  */
-export async function paginateForward<T>(
-  fetchFn: (cursor: string | null) => Promise<Connection<T>>,
-  initialCursor?: string | null,
-): Promise<T[]> {
-  const all: T[] = [];
-  let cursor: string | null = initialCursor ?? null;
-
-  for (;;) {
-    // eslint-disable-next-line no-await-in-loop
-    const conn = await fetchFn(cursor);
-
-    all.push(...conn.nodes);
-
-    if (!conn.pageInfo.hasNextPage || !conn.pageInfo.endCursor) break;
-    cursor = conn.pageInfo.endCursor;
-  }
-
-  return all;
+export async function paginateForward(fetchFn, initialCursor) {
+    const all = [];
+    let cursor = initialCursor ?? null;
+    for (;;) {
+        // eslint-disable-next-line no-await-in-loop
+        const conn = await fetchFn(cursor);
+        all.push(...conn.nodes);
+        if (!conn.pageInfo.hasNextPage || !conn.pageInfo.endCursor)
+            break;
+        cursor = conn.pageInfo.endCursor;
+    }
+    return all;
 }
-
 /**
  * Paginate backward through a GraphQL connection (`last` / `before` cursors).
  *
@@ -63,24 +43,18 @@ export async function paginateForward<T>(
  *                      `startCursor` of an already-fetched page to avoid
  *                      re-fetching it (fetch only the pages *before* it).
  */
-export async function paginateBackward<T>(
-  fetchFn: (cursor: string | null) => Promise<Connection<T>>,
-  initialCursor?: string | null,
-): Promise<T[]> {
-  const all: T[] = [];
-  let cursor: string | null = initialCursor ?? null;
-
-  for (;;) {
-    // eslint-disable-next-line no-await-in-loop
-    const conn = await fetchFn(cursor);
-
-    // Backward pagination returns items oldest-first within each page but pages
-    // go from newest-to-oldest. Prepend each page so final array is oldest-first.
-    all.unshift(...conn.nodes);
-
-    if (!conn.pageInfo.hasPreviousPage || !conn.pageInfo.startCursor) break;
-    cursor = conn.pageInfo.startCursor;
-  }
-
-  return all;
+export async function paginateBackward(fetchFn, initialCursor) {
+    const all = [];
+    let cursor = initialCursor ?? null;
+    for (;;) {
+        // eslint-disable-next-line no-await-in-loop
+        const conn = await fetchFn(cursor);
+        // Backward pagination returns items oldest-first within each page but pages
+        // go from newest-to-oldest. Prepend each page so final array is oldest-first.
+        all.unshift(...conn.nodes);
+        if (!conn.pageInfo.hasPreviousPage || !conn.pageInfo.startCursor)
+            break;
+        cursor = conn.pageInfo.startCursor;
+    }
+    return all;
 }

package/{src/github/queries.mts → bin/github/queries.mjs}

@@ -4,27 +4,18 @@
  * Query strings live in src/github/gql/*.gql.
  * Never inline raw GraphQL strings in .ts source files.
  */
-
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-
-const gql = (name: string): string =>
-  readFileSync(join((import.meta as { dirname: string }).dirname, "gql", name), "utf8");
-
+const gql = (name) => readFileSync(join(import.meta.dirname, "gql", name), "utf8");
 /** The primary batch query that fetches CI + comments + merge status in one round-trip. */
 export const BATCH_PR_QUERY = gql("batch-pr.gql");
-
 /** Resolve a single review thread. */
 export const RESOLVE_THREAD_MUTATION = gql("resolve-thread.gql");
-
 /** Minimize a PR comment (IssueComment). */
 export const MINIMIZE_COMMENT_MUTATION = gql("minimize-comment.gql");
-
 /** Dismiss a pull request review. */
 export const DISMISS_REVIEW_MUTATION = gql("dismiss-review.gql");
-
 /** Multi-PR status query for `shepherd status PR1 PR2 …`. */
 export const MULTI_PR_STATUS_QUERY = gql("multi-pr-status.gql");
-
 /** Paginated version — used when reviewThreads is truncated (totalCount > 100). */
 export const MULTI_PR_STATUS_QUERY_WITH_CURSOR = gql("multi-pr-status-paged.gql");

package/{src/index.mts → bin/index.mjs}

@@ -8,10 +8,8 @@
  *   pr-shepherd iterate [PR]
  *   pr-shepherd status PR1 [PR2 …]
  */
-
-import { main } from "./cli.mts";
-
+import { main } from "./cli.mjs";
 main(process.argv).catch((err) => {
-  process.stderr.write(`pr-shepherd error: ${err instanceof Error ? err.message : String(err)}\n`);
-  process.exit(1);
+    process.stderr.write(`pr-shepherd error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
 });

package/bin/merge-status/derive.mjs

@@ -0,0 +1,72 @@
+/**
+ * Derives a shepherd `MergeStatusResult` from raw PR data.
+ *
+ * `pr.state` is passed through unchanged; `iterate` handles the cancel action
+ * for non-OPEN (merged/closed) PRs — this function does not branch on it.
+ *
+ * Interpretation order for `status` — first match wins:
+ *   1. mergeable == CONFLICTING       → CONFLICTS
+ *   2. mergeStateStatus DIRTY         → CONFLICTS (GitHub merge conflicts)
+ *   3. copilotReviewInProgress        → BLOCKED
+ *   4. mergeStateStatus BEHIND        → BEHIND
+ *   5. mergeStateStatus BLOCKED / HAS_HOOKS → BLOCKED
+ *   6. mergeStateStatus UNSTABLE      → UNSTABLE
+ *   7. isDraft                        → DRAFT
+ *   8. mergeStateStatus UNKNOWN       → UNKNOWN
+ *   9. mergeStateStatus CLEAN         → CLEAN
+ */
+import { loadConfig } from "../config/load.mjs";
+export function deriveMergeStatus(pr) {
+    const copilotReviewInProgress = detectCopilotReview(pr);
+    let status;
+    if (pr.mergeable === "CONFLICTING") {
+        status = "CONFLICTS";
+    }
+    else if (copilotReviewInProgress) {
+        status = "BLOCKED";
+    }
+    else if (pr.mergeStateStatus === "DIRTY") {
+        // DIRTY means GitHub detected merge conflicts in the branch.
+        status = "CONFLICTS";
+    }
+    else if (pr.mergeStateStatus === "BEHIND") {
+        status = "BEHIND";
+    }
+    else if (pr.mergeStateStatus === "BLOCKED" || pr.mergeStateStatus === "HAS_HOOKS") {
+        status = "BLOCKED";
+    }
+    else if (pr.mergeStateStatus === "UNSTABLE") {
+        status = "UNSTABLE";
+    }
+    else if (pr.isDraft || pr.mergeStateStatus === "DRAFT") {
+        status = "DRAFT";
+    }
+    else if (pr.mergeStateStatus === "UNKNOWN") {
+        status = "UNKNOWN";
+    }
+    else {
+        status = "CLEAN";
+    }
+    return {
+        status,
+        state: pr.state,
+        isDraft: pr.isDraft,
+        mergeable: pr.mergeable,
+        reviewDecision: pr.reviewDecision,
+        copilotReviewInProgress,
+        mergeStateStatus: pr.mergeStateStatus,
+    };
+}
+// ---------------------------------------------------------------------------
+// Copilot review detection
+// ---------------------------------------------------------------------------
+function detectCopilotReview(pr) {
+    // A blocking bot review is "in progress" when:
+    //   1. Any reviewRequest has a login starting with one of the configured prefixes, OR
+    //   2. Any latestReview has such a login AND state == "PENDING"
+    const prefixes = loadConfig().mergeStatus.blockingReviewerLogins.map((l) => l.toLowerCase());
+    const isBlocking = (login) => prefixes.some((p) => login.toLowerCase().startsWith(p));
+    const requested = pr.reviewRequests.some((r) => isBlocking(r.login));
+    const pendingReview = pr.latestReviews.some((r) => isBlocking(r.login) && r.state === "PENDING");
+    return requested || pendingReview;
+}

package/bin/pr-shepherd

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("./index.mjs")

package/bin/reporters/agent.mjs

@@ -0,0 +1,41 @@
+/**
+ * Projections for the agent-facing iterate output.
+ *
+ * These strip fields that are always-false by the time items reach iterate
+ * (isResolved, isOutdated, isMinimized, createdAtUnix) and metadata that the
+ * monitor prompt never reads (detailsUrl, event, status, conclusion, category,
+ * logExcerpt). The original domain types are preserved for check command output.
+ */
+export function toAgentThread(t) {
+    return { id: t.id, path: t.path, line: t.line, author: t.author, body: t.body };
+}
+export function toAgentComment(c) {
+    return { id: c.id, author: c.author, body: c.body };
+}
+export function toAgentCheck(c) {
+    return { name: c.name, runId: c.runId, detailsUrl: c.detailsUrl, failureKind: c.failureKind };
+}
+/**
+ * Project and deduplicate checks so the agent makes one `gh run view` call
+ * per run (dedup by runId) and skips duplicate external status checks (dedup
+ * by name when runId is null).
+ */
+export function toAgentChecks(checks) {
+    const seenRunIds = new Set();
+    const seenNames = new Set();
+    const result = [];
+    for (const c of checks) {
+        if (c.runId !== null) {
+            if (seenRunIds.has(c.runId))
+                continue;
+            seenRunIds.add(c.runId);
+        }
+        else {
+            if (seenNames.has(c.name))
+                continue;
+            seenNames.add(c.name);
+        }
+        result.push(toAgentCheck(c));
+    }
+    return result;
+}

package/{src/reporters/json.mts → bin/reporters/json.mjs}

@@ -4,9 +4,6 @@
  * Slash commands parse this output to extract IDs, status, and actionable items
  * without string-scraping the human-readable text reporter.
  */
-
-import type { ShepherdReport } from "../types.mts";
-
-export function formatJson(report: ShepherdReport): string {
-  return JSON.stringify(report, null, 2);
+export function formatJson(report) {
+    return JSON.stringify(report, null, 2);
 }

package/bin/reporters/text.mjs

@@ -0,0 +1,111 @@
+/**
+ * Human-readable text reporter for shepherd check output.
+ */
+export function formatText(report) {
+    const lines = [];
+    // Header
+    lines.push(`\nPR #${report.pr} — ${report.repo}`);
+    lines.push(`Status: ${report.status}`);
+    lines.push("");
+    // Merge status
+    const ms = report.mergeStatus;
+    lines.push(`Merge Status: ${ms.status}`);
+    lines.push(`  mergeStateStatus:       ${ms.mergeStateStatus}`);
+    lines.push(`  mergeable:              ${ms.mergeable}`);
+    lines.push(`  reviewDecision:         ${ms.reviewDecision ?? "(none)"}`);
+    lines.push(`  isDraft:                ${ms.isDraft}`);
+    lines.push(`  copilotReviewInProgress:${ms.copilotReviewInProgress}`);
+    lines.push("");
+    // CI checks
+    const { passing, failing, inProgress, skipped } = report.checks;
+    const total = passing.length + failing.length + inProgress.length + skipped.length;
+    lines.push(`CI Checks: ${passing.length}/${total} passed`);
+    if (failing.length > 0) {
+        lines.push(`\nFailed Checks (${failing.length}):`);
+        for (const c of failing) {
+            const triaged = c;
+            const kind = triaged.failureKind ? ` [${triaged.failureKind}]` : "";
+            lines.push(`  - ${c.name}${kind}: ${c.conclusion ?? c.status}`);
+            if (triaged.logExcerpt) {
+                lines.push(indent(triaged.logExcerpt.split("\n").slice(-10).join("\n"), "    "));
+            }
+        }
+    }
+    if (inProgress.length > 0) {
+        lines.push(`\nIn Progress (${inProgress.length}):`);
+        for (const c of inProgress) {
+            lines.push(`  - ${c.name}: ${c.status}`);
+        }
+    }
+    if (skipped.length > 0) {
+        lines.push(`\nSkipped (${skipped.length}): ${skipped.map((c) => c.name).join(", ")}`);
+    }
+    if (report.checks.filtered.length > 0) {
+        lines.push(`\nFiltered (non-PR-trigger) (${report.checks.filtered.length}): ${report.checks.filtered.map((c) => c.name).join(", ")}`);
+        if (report.checks.blockedByFilteredCheck) {
+            lines.push("  Note: PR is BLOCKED and all filtered checks are non-PR-trigger — one of these filtered checks may be a required status check blocking merge.");
+        }
+        else if (report.mergeStatus.status === "BLOCKED") {
+            lines.push("  Note: one or more of these filtered checks may be a required status check blocking merge.");
+        }
+    }
+    lines.push("");
+    // Review threads
+    const { actionable: actionableThreads, autoResolved, autoResolveErrors } = report.threads;
+    if (autoResolved.length > 0) {
+        lines.push(`Auto-resolved outdated threads (${autoResolved.length}):`);
+        for (const t of autoResolved) {
+            lines.push(`  - threadId=${t.id} ${t.path ?? ""}:${t.line ?? "?"} (@${t.author})`);
+        }
+        lines.push("");
+    }
+    if (autoResolveErrors.length > 0) {
+        lines.push(`Auto-resolve errors (${autoResolveErrors.length}):`);
+        for (const e of autoResolveErrors) {
+            lines.push(`  - ${e}`);
+        }
+        lines.push("");
+    }
+    if (actionableThreads.length > 0) {
+        lines.push(`Actionable Review Threads (${actionableThreads.length}):`);
+        for (const t of actionableThreads) {
+            const label = t.path ? `${t.path}:${t.line ?? "?"}` : "(general)";
+            lines.push(`  - threadId=${t.id} ${label} (@${t.author})`);
+            lines.push(`    ${firstLine(t.body)}`);
+        }
+        lines.push("");
+    }
+    // PR comments
+    const { actionable: actionableComments } = report.comments;
+    if (actionableComments.length > 0) {
+        lines.push(`Actionable PR Comments (${actionableComments.length}):`);
+        for (const c of actionableComments) {
+            lines.push(`  - commentId=${c.id} (@${c.author}): ${firstLine(c.body)}`);
+        }
+        lines.push("");
+    }
+    // CHANGES_REQUESTED reviews
+    if (report.changesRequestedReviews.length > 0) {
+        lines.push(`Pending CHANGES_REQUESTED reviews (${report.changesRequestedReviews.length}):`);
+        for (const r of report.changesRequestedReviews) {
+            lines.push(`  - reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
+        }
+        lines.push("");
+    }
+    // Summary
+    const totalActionable = actionableThreads.length + actionableComments.length + report.changesRequestedReviews.length;
+    lines.push(`Summary: ${totalActionable === 0 ? "0 actionable — all threads resolved/minimized" : `${totalActionable} actionable item(s) remaining`}`);
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function firstLine(text) {
+    return (text.split("\n")[0] ?? "").trim().slice(0, 120);
+}
+function indent(text, prefix) {
+    return text
+        .split("\n")
+        .map((l) => prefix + l)
+        .join("\n");
+}

package/bin/types.mjs

@@ -0,0 +1,2 @@
+/** Shared type definitions for the shepherd CLI. */
+export {};

package/package.json

@@ -1,17 +1,15 @@
 {
   "name": "pr-shepherd",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
   "license": "MIT",
   "author": "Jonathan Ong",
   "type": "module",
   "bin": {
-    "pr-shepherd": "./src/index.mts"
+    "pr-shepherd": "bin/index.mjs"
   },
   "files": [
-    "src/**/*.mts",
-    "src/**/*.json",
-    "src/**/*.gql",
+    "bin/**",
     "skills/**",
     ".claude-plugin/**",
     "marketplace.json",
@@ -19,21 +17,23 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=22.0.0"
   },
   "dependencies": {
     "yaml": "^2.7.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "oxfmt": "latest",
-    "oxlint": "latest",
+    "oxfmt": "^0.45.0",
+    "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.4",
     "@vitest/coverage-v8": "^4.1.4"
   },
   "scripts": {
-    "prepublishOnly": "npm run typecheck && npm test",
+    "build": "node scripts/build.mjs",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint src/ skills/",
     "format": "oxfmt src/ skills/ docs/ README.md",

package/skills/check/SKILL.md

@@ -3,7 +3,7 @@ name: check
 description: "Check GitHub CI status and review comments for the current PR"
 argument-hint: "[PR number or URL ...]"
 user-invocable: true
-allowed-tools: ["Bash", "Read", "Grep"]
+allowed-tools: ["Bash"]
 ---
 
 # pr-shepherd check — PR Status
@@ -40,24 +40,22 @@ Parse the JSON output and report all three:
 
 ## Rebase policy
 
-```bash
-BASE_BRANCH=$(gh pr view <N> --json baseRefName --jq '.baseRefName')
-```
+The CLI already determines whether a rebase is warranted. Read `report.mergeStatus.status` directly:
 
-Rebase (`git fetch origin && git rebase origin/<BASE_BRANCH> && git push --force-with-lease`) when:
+- `CONFLICTS` — a rebase is required to resolve the merge conflict before the PR can land.
+- `BEHIND` — a rebase may be appropriate; a `flaky` failure while `BEHIND` is the canonical rebase signal. If all checks pass but the PR is `BEHIND`, a rebase is optional.
+- Any other status — no rebase needed.
 
-- Merge conflicts with main (`report.mergeStatus.status == 'CONFLICTS'`), OR
-- About to push commits and branch is behind main, OR
-- `failureKind == 'flaky'` AND branch is behind main
-
-Do NOT rebase when nothing to push, no conflicts, and no flaky failures.
+Do not re-derive these conditions from raw branch state. For automated monitoring that acts on these signals, use `/pr-shepherd:monitor` — it handles rebase decisions end-to-end.
 
 ## CI budget policy
 
-- **actionable**: Summarize errors. Fix in next step.
-- **infrastructure**: Re-run: `gh run rerun <runId> --failed`
-- **timeout**: Re-run: `gh run rerun <runId> --failed`
-- **flaky**: Do NOT cancel. Rebase if behind main.
+Each entry in `report.checks` carries a `failureKind` field. Read it directly rather than re-classifying failures:
+
+- `actionable` — the failure is code-level and needs a fix.
+- `infrastructure` — transient infra problem; re-run with `gh run rerun <runId> --failed`.
+- `timeout` — job exceeded the time limit; re-run with `gh run rerun <runId> --failed`.
+- `flaky` — known-flaky test; do NOT cancel. Rebase first if `mergeStatus.status` is `BEHIND`.
 
 ## Never declare ready to merge
 

package/skills/monitor/SKILL.md

@@ -76,11 +76,15 @@ Parse the `action` field and act:
   After fixing manually, rerun /pr-shepherd:monitor <PR> to resume.
 
 - `fix_code` → do the following, then stop this iteration (CI needs time):
-  1. For each item in `fix.threads`, `fix.comments`, `fix.checks`, and `fix.changesRequestedReviews`: read the referenced file/line and apply the fix (Edit/Write tools).
-  2. If files were changed, `git add <files> && git commit -m "<appropriate commit message>"`
-  3. `git fetch origin && git rebase origin/<BASE_BRANCH> && git push --force-with-lease` (dangerouslyDisableSandbox: true)
-  4. `HEAD_SHA=$(git rev-parse HEAD)`
-  5. `npx pr-shepherd resolve <PR_NUMBER> --resolve-thread-ids <IDs> --minimize-comment-ids <IDs> --dismiss-review-ids <IDs> --message "address review comments" --require-sha "$HEAD_SHA"` (dangerouslyDisableSandbox: true). Omit any flag whose ID list is empty.
+  1. For each item in `fix.threads` and `fix.comments`: read the referenced file/line and apply the fix (Edit/Write tools).
+  2. For each item in `fix.checks`:
+     - If `runId` is non-null: fetch the failure log with `gh run view <runId> --log-failed` (dangerouslyDisableSandbox: true), scan the output to identify the failure (e.g. grep for `FAIL` for test failures, `error:` for type/compile errors, lint rule names for lint failures), then read the relevant file and apply the fix (Edit/Write tools).
+     - If `runId` is null: the failed check is an external status check that cannot be inspected via run logs. Escalate — tell the user to open `detailsUrl` in the PR checks UI, inspect the failure manually, and rerun `/pr-shepherd:monitor <PR_NUMBER>` after addressing it. Do not attempt to fix these automatically.
+  3. For each item in `fix.changesRequestedReviews`: read the review body and apply the requested changes.
+  4. If files were changed, `git add <files> && git commit -m "<appropriate commit message>"`
+  5. `git fetch origin && git rebase origin/<BASE_BRANCH> && git push --force-with-lease` (dangerouslyDisableSandbox: true)
+  6. `HEAD_SHA=$(git rev-parse HEAD)`
+  7. `npx pr-shepherd resolve <PR_NUMBER> --resolve-thread-ids <IDs> --minimize-comment-ids <IDs> --dismiss-review-ids <IDs> --message "address review comments" --require-sha "$HEAD_SHA"` (dangerouslyDisableSandbox: true). Omit any flag whose ID list is empty.
 
 ````
 

package/src/cache/file-cache.mts

@@ -1,101 +0,0 @@
-/**
- * Simple filesystem-based cache for shepherd batch reads.
- *
- * Cache entries live in `${TMPDIR}/pr-shepherd-cache/<owner>-<repo>/<pr>/<shape>.json`.
- * TTL defaults to 5 minutes (configurable via PR_SHEPHERD_CACHE_TTL_SECONDS or --cache-ttl).
- *
- * Mutations are never cached — this module is read-path only.
- */
-
-import { readFile, writeFile, rename, mkdir, stat } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
-import { join, dirname } from "node:path";
-import { tmpdir } from "node:os";
-import { loadConfig } from "../config/load.mts";
-import { SAFE_SEGMENT } from "../util/path-segment.mts";
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-export interface CacheOptions {
-  ttlSeconds?: number;
-  disabled?: boolean;
-}
-
-/**
- * Read a value from the cache. Returns null on miss or expiry.
- */
-export async function cacheGet<T>(key: CacheKey, opts: CacheOptions = {}): Promise<T | null> {
-  if (opts.disabled) return null;
-
-  const ttl = opts.ttlSeconds ?? ttlFromEnv() ?? loadConfig().cache.ttlSeconds;
-  // A TTL of 0 (or negative) means "always expired" — skip the filesystem read entirely.
-  if (ttl <= 0) return null;
-
-  try {
-    const path = resolvePath(key);
-    const stats = await stat(path);
-    const ageSeconds = (Date.now() - stats.mtimeMs) / 1000;
-    if (ageSeconds >= ttl) return null;
-
-    const raw = await readFile(path, "utf8");
-    return JSON.parse(raw) as T;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Write a value to the cache (fire-and-forget — never throws).
- */
-export async function cacheSet<T>(key: CacheKey, value: T, opts: CacheOptions = {}): Promise<void> {
-  if (opts.disabled) return;
-
-  try {
-    const path = resolvePath(key);
-    const tmp = `${path}.${randomUUID()}.tmp`;
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(tmp, JSON.stringify(value), "utf8");
-    // Atomic rename — prevents a partial read if two processes write concurrently.
-    await rename(tmp, path);
-  } catch {
-    // Cache writes are best-effort.
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Cache key
-// ---------------------------------------------------------------------------
-
-export interface CacheKey {
-  owner: string;
-  repo: string;
-  pr: number;
-  shape: string;
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-function resolvePath(key: CacheKey): string {
-  for (const [field, value] of [
-    ["owner", key.owner],
-    ["repo", key.repo],
-    ["shape", key.shape],
-  ] as const) {
-    if (!SAFE_SEGMENT.test(value)) {
-      throw new Error(`Invalid cache key segment "${field}": ${value}`);
-    }
-  }
-  const base = process.env["PR_SHEPHERD_CACHE_DIR"] ?? join(tmpdir(), "pr-shepherd-cache");
-  return join(base, `${key.owner}-${key.repo}`, String(key.pr), `${key.shape}.json`);
-}
-
-function ttlFromEnv(): number | undefined {
-  const raw = process.env["PR_SHEPHERD_CACHE_TTL_SECONDS"];
-  if (!raw) return undefined;
-  const parsed = parseInt(raw, 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
-}