pr-shepherd 0.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "pr-shepherd",
+  "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
+  "version": "0.1.0",
+  "author": {
+    "name": "Jonathan Ong",
+    "email": "jonathanrichardong@gmail.com"
+  },
+  "homepage": "https://github.com/jonathanong/pr-shepherd",
+  "repository": "https://github.com/jonathanong/pr-shepherd",
+  "license": "MIT",
+  "keywords": ["github", "pull-request", "ci", "code-review", "automation"],
+  "skills": "./skills/"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Ong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# pr-shepherd
+
+Autonomous PR CI monitor and review-comment resolver for Claude Code.
+
+## Goals
+
+- **Reduced context** — shifts more logic to the CLI instead of the agent
+- **Reduced GitHub rate limit exhaustion** — all GraphQL queries are batched
+- **Reduced agent tool calls** — batching comment resolutions means fewer tool calls and less context used
+- **No MCP** — less reasoning and much faster than using the GitHub MCP
+- **CI cancellation on failure** — avoids wasted CI runs when actionable failures exist
+- **Auto-resolution of all inline comments** — including bot and AI reviewer comments
+- **Automatic resolution of outdated comments** — happens before the agent is involved
+- **Automatic pagination and filtering** — resolved comments never reach the agent
+- **Aggressively hides bot comments** — keeps PR noise low
+- **Waits for pending Copilot reviews** — avoids premature marking as ready
+- **Rebases on conflict** — automatically rebases on the PR base branch when there are merge conflicts
+- **4-minute watch cadence** — keeps Claude's prompt cache warm (5-minute TTL)
+- **10-minute settle window** — waits after the PR is clean before exiting, in case of pending reviews
+- **Draft → ready-for-review** — automatically converts draft PRs when CI passes
+- **Skips non-PR CI checks** — only `pull_request` / `pull_request_target` events count toward readiness
+- **Intended as a PR merge blocker** — pair with a GitHub Actions required check that verifies all threads are resolved
+
+## Why it's built this way
+
+Claude's cloud autofix requires CI to verify changes for apps that can't run in the cloud. Running targeted tests locally and letting Claude Code drive is cheaper and avoids vendor lock-in. Skills are used (not subagents) because subagents load all CLAUDE.md context, increasing cost; skills inject into the main conversation instead.
+
+## Install
+
+```bash
+npm install pr-shepherd
+```
+
+### As a Claude Code plugin
+
+```bash
+# Install from marketplace
+claude /plugin marketplace add jonathanong/pr-shepherd
+claude /plugin install pr-shepherd
+```
+
+Then use:
+
+- `/pr-shepherd:monitor [PR]` — start continuous monitoring
+- `/pr-shepherd:check [PR]` — one-shot status check
+- `/pr-shepherd:resolve [PR]` — fetch, fix, and resolve review comments
+
+## Workflow
+
+```mermaid
+flowchart TD
+  U(["/pr-shepherd:monitor PR"]) --> SC["monitor skill"]
+  SC -->|CronList| EX{Loop exists<br/>for this PR?}
+  EX -->|yes| NOW[Run iterate once<br/>inline and act]
+  EX -->|no| CREATE["/loop 4m --max-turns 50 --expires 8h"]
+  CREATE --> CRON[(cron tick every 4m)]
+  NOW --> ITER
+  CRON --> ITER["pr-shepherd iterate PR --format=json"]
+
+  ITER --> S1{1. last commit<br/>age &lt; cooldown?}
+  S1 -->|yes| A_COOL([action: cooldown])
+  S1 -->|no| S2["2. runCheck — one GraphQL batch<br/>classify + deriveMergeStatus<br/>+ autoResolveOutdated"]
+
+  S2 --> S25{2.5 state != OPEN?}
+  S25 -->|yes| A_CAN([action: cancel])
+  S25 -->|no| S3["3. updateReadyDelay<br/>ready-since.txt"]
+  S3 --> S3C{shouldCancel?}
+  S3C -->|yes| A_CAN
+  S3C -->|no| S4{4. CONFLICTS or actionable<br/>threads/comments/CI/reviews?}
+  S4 -->|yes| S4X["gh run cancel actionable runIds"]
+  S4X --> A_FIX([action: fix_code])
+  S4 -->|no| S5{5. transient<br/>timeout/infra?}
+  S5 -->|yes| S5X["gh run rerun runId --failed"]
+  S5X --> A_RR([action: rerun_ci])
+  S5 -->|no| S6{6. flaky + BEHIND?}
+  S6 -->|yes| A_REB([action: rebase])
+  S6 -->|no| S7{7. READY + CLEAN<br/>+ isDraft + !copilot?}
+  S7 -->|yes| A_MR([action: mark_ready])
+  S7 -->|no| A_W([action: wait])
+
+  A_COOL --> DEC{skill acts on action}
+  A_CAN --> DEC
+  A_REB --> DEC
+  A_FIX --> DEC
+  A_RR --> DEC
+  A_MR --> DEC
+  A_W --> DEC
+
+  DEC -->|cancel| STOP["/loop cancel"]
+  DEC -->|rebase| REB["git fetch && rebase origin/BASE &&<br/>push --force-with-lease"]
+  DEC -->|fix_code| FIX["Edit files →<br/>git add + commit →<br/>fetch + rebase + push →<br/>pr-shepherd resolve --require-sha HEAD"]
+  FIX --> NEXT[Wait for next tick]
+  REB --> NEXT
+  DEC -->|other| NEXT
+  NEXT --> CRON
+```
+
+## CLI
+
+```sh
+pr-shepherd check [PR]                                # read-only PR status snapshot
+pr-shepherd resolve [PR] [--fetch | --resolve-thread-ids …]
+pr-shepherd iterate [PR] [--cooldown-seconds N] [--ready-delay Nm] [--last-push-time N]
+pr-shepherd status PR1 [PR2 …]                        # multi-PR table
+```
+
+Common flags:
+
+| Flag                  | Default | Description                     |
+| --------------------- | ------- | ------------------------------- |
+| `--format text\|json` | `text`  | Output format                   |
+| `--no-cache`          | false   | Bypass the 5-minute file cache  |
+| `--cache-ttl N`       | 300     | Cache TTL in seconds            |
+| `--ready-delay Nm`    | `10m`   | Settle window before loop exits |
+
+## Configuration
+
+Create a `.pr-shepherdrc.yml` in your project root (or any parent directory) to override defaults:
+
+```yaml
+iterate:
+  cooldownSeconds: 60 # wait longer after a push before reading CI
+  fixAttemptsPerThread: 5 # raise before escalating to manual review
+checks:
+  ciTriggerEvents:
+    - pull_request
+    - pull_request_target
+    - merge_group # add for merge-queue repos
+mergeStatus:
+  blockingReviewerLogins:
+    - copilot # add other review bots here
+actions:
+  autoRebase: false # disable for repos that enforce merge commits
+```
+
+See [docs/configuration.md](docs/configuration.md) for all options.
+
+## Requirements
+
+- Node.js ≥ 24.0.0
+- `gh` CLI authenticated (`gh auth login`)
+- `git`
+
+## Architecture
+
+See [docs/architecture.md](docs/architecture.md) and [docs/](docs/) for full reference docs.
+
+## Forking
+
+If you want to customize pr-shepherd for your own use or team, see [docs/forking.md](docs/forking.md).
+
+## License
+
+[MIT](LICENSE)

package/marketplace.json

@@ -0,0 +1,8 @@
+{
+  "name": "pr-shepherd",
+  "description": "Autonomous PR CI monitor and review-comment resolver",
+  "source": {
+    "source": "npm",
+    "package": "pr-shepherd"
+  }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pr-shepherd",
+  "version": "0.2.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"
+  },
+  "files": [
+    "src/**/*.mts",
+    "src/**/*.json",
+    "src/**/*.gql",
+    "skills/**",
+    ".claude-plugin/**",
+    "marketplace.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "oxfmt": "latest",
+    "oxlint": "latest",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4",
+    "@vitest/coverage-v8": "^4.1.4"
+  },
+  "scripts": {
+    "prepublishOnly": "npm run typecheck && npm test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src/ skills/",
+    "format": "oxfmt src/ skills/ docs/ README.md",
+    "format:check": "oxfmt --check src/ skills/ docs/ README.md",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "github",
+    "pull-request",
+    "ci",
+    "code-review",
+    "automation",
+    "claude",
+    "claude-code"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonathanong/pr-shepherd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jonathanong/pr-shepherd/issues"
+  },
+  "homepage": "https://github.com/jonathanong/pr-shepherd"
+}

package/skills/check/SKILL.md

@@ -0,0 +1,70 @@
+---
+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"]
+---
+
+# pr-shepherd check — PR Status
+
+## Arguments: $ARGUMENTS
+
+## Resolve PR number(s)
+
+1. If `$ARGUMENTS` contains PR numbers or GitHub PR URLs, extract the number(s).
+2. Otherwise, infer: `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number --jq '.[0].number'`
+3. If no PR found, report an error and stop.
+
+For each resolved PR number, check if it is already merged:
+
+```bash
+gh pr view <N> --json state --jq '.state'
+```
+
+If `MERGED`, output: `PR #N is already merged. Nothing to check.` and skip.
+
+## Run the check
+
+```bash
+npx pr-shepherd check <N> --format=json
+```
+
+## Reporting
+
+Parse the JSON output and report all three:
+
+- **Merge status** (`report.mergeStatus.status`): CLEAN | BEHIND | CONFLICTS | BLOCKED | UNSTABLE | DRAFT | UNKNOWN — never omit; include `copilotReviewInProgress` when true
+- **CI check results** (`report.checks`): passing count, failing names + kinds, in-progress names
+- **Unresolved review comments** (`report.threads.actionable` + `report.comments.actionable`): count + details with file paths and line numbers
+
+## Rebase policy
+
+```bash
+BASE_BRANCH=$(gh pr view <N> --json baseRefName --jq '.baseRefName')
+```
+
+Rebase (`git fetch origin && git rebase origin/<BASE_BRANCH> && git push --force-with-lease`) when:
+
+- 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.
+
+## 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.
+
+## Never declare ready to merge
+
+Unless ALL of:
+
+1. `report.mergeStatus.mergeStateStatus == 'CLEAN'`
+2. `report.status == 'READY'`
+3. `report.mergeStatus.copilotReviewInProgress == false`
+
+This is a one-shot check. For continuous monitoring, use `/pr-shepherd:monitor`.

package/skills/monitor/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: monitor
+description: "Start continuous CI monitoring — marks PR ready for review when all checks pass"
+argument-hint: "[PR number or URL] [every <interval>] [--ready-delay <duration>]"
+user-invocable: true
+allowed-tools:
+  ["Bash", "Read", "Grep", "Edit", "Write", "Glob", "Skill", "CronCreate", "CronList", "CronDelete"]
+---
+
+# pr-shepherd monitor — Continuous PR Monitor
+
+## Arguments: $ARGUMENTS
+
+## Resolve PR number
+
+1. Strip any trailing `every <N> <unit>` interval clause from `$ARGUMENTS` first.
+2. Extract `--ready-delay <duration>` if present (e.g. `--ready-delay 15m`). Default: `10m`.
+3. If the remaining text contains a PR number or GitHub PR URL, extract the number.
+4. Otherwise, infer: `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number --jq '.[0].number'`
+5. If no PR found, report an error and stop.
+
+## Detect base branch
+
+```bash
+BASE_BRANCH=$(gh pr view <PR_NUMBER> --json baseRefName --jq '.baseRefName')
+```
+
+Default to `main` if the command fails.
+
+## Start the loop
+
+**Before starting:** List existing cron jobs with `CronList`.
+
+- If any job's prompt contains `# pr-shepherd-loop:pr=<PR_NUMBER>`, **do not cancel+recreate** — perform one iteration now by following the logic in the CronCreate prompt below, then return.
+
+**Run the loop:**
+
+Invoke `/loop <INTERVAL> --max-turns 50 --expires 8h` via the Skill tool. Use the interval from the argument if provided (e.g. `every 30 minutes` → `30m`), otherwise use `4m`. The loop prompt should be:
+
+````
+# pr-shepherd-loop:pr=<PR_NUMBER>
+Run the following in a single Bash invocation (dangerouslyDisableSandbox: true):
+  npx pr-shepherd iterate <PR_NUMBER> --ready-delay <READY_DELAY> --no-cache --last-push-time "$(git log -1 --format=%ct HEAD)" --format=json
+
+Exit codes 0, 1, 2, and 3 are all valid signals — always try to parse stdout as JSON first. If the command exits non-zero and stdout is not parseable JSON (e.g. a crash), log the first line of stderr and continue (do not cancel the loop).
+
+Parse the `action` field and act:
+
+- `cooldown` → log: `SKIP: CI still starting`
+- `wait` → log: `WAIT: <summary.passing> passing, <summary.inProgress> in-progress (merge state: <mergeStateStatus>, <remainingSeconds>s cooldown remaining)`
+- `rerun_ci` → log: `RERAN <N> CI checks: <reran joined by space>`
+- `mark_ready` → log: `MARKED READY: PR <pr>`
+- `cancel` → invoke `/loop cancel` and stop
+- `rebase` → run (dangerouslyDisableSandbox: true):
+  ```bash
+  if ! git diff --quiet || ! git diff --cached --quiet; then
+    echo "SKIP rebase: dirty worktree (uncommitted changes present)"
+    exit 0
+  fi
+  git fetch origin && git rebase origin/<BASE_BRANCH> && git push --force-with-lease
+  ```
+
+- `escalate` → invoke `/loop cancel` via Skill tool, then print:
+
+  ⚠️ /pr-shepherd:monitor paused — needs human direction
+
+  Triggers: <escalate.triggers joined by ", ">
+  <escalate.suggestion>
+
+  Items needing attention:
+  <for each thread in escalate.unresolvedThreads: "- threadId=<id> <path ?? '(no location)'>:<line ?? '?'> (@<author>): <body first line>">
+  <if escalate.changesRequestedReviews.length > 0: for each "- reviewId=<id> (@<author>): <body first line>">
+  <if escalate.attemptHistory: "Fix attempts: " + each "threadId=<id> attempted <N> times">
+
+  Run /pr-shepherd:check <PR> to see current state.
+  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.
+
+````
+
+**Do NOT call ScheduleWakeup** — the cron job handles its own recurrence. Calling ScheduleWakeup with a `/loop` prompt would create a duplicate cron job on the next fire.
+
+The default 4-minute interval is chosen for two reasons:
+
+1. CI checks typically take 2-3 minutes to complete so concurrent agents won't stack.
+2. 4 minutes keeps iterations within the 5-minute prompt cache TTL.
+
+## Each iteration
+
+The loop prompt above handles each iteration directly — no subagent is spawned. The same iterate command can be run manually at any time:
+
+```bash
+npx pr-shepherd iterate <PR_NUMBER> --ready-delay <READY_DELAY> --no-cache --last-push-time "$(git log -1 --format=%ct HEAD)" --format=json
+```
+
+To stop monitoring manually, use `/loop cancel` or close the session.
+
+## Handling multiple PRs
+
+To monitor several PRs simultaneously, run `/pr-shepherd:monitor <PR>` once per PR.
+Each call creates its own cron job. Before creating a new loop, run `CronList`
+to verify a loop for that PR doesn't already exist.

package/skills/resolve/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: resolve
+description: "Resolve all inline review comments on the current PR"
+argument-hint: "[PR number or URL] [--thread-id ID | --comment-id ID] [--require-sha SHA]"
+user-invocable: true
+allowed-tools: ["Bash", "Read", "Grep", "Edit", "Write", "Glob", "Skill"]
+---
+
+# pr-shepherd resolve — Fix and Resolve Review Comments
+
+Resolve unresolved review threads and minimize PR comments on the current PR — from ALL authors.
+
+## Arguments: $ARGUMENTS
+
+## Steps
+
+1. **Resolve PR number and get context:**
+
+   Parse `$ARGUMENTS`:
+   1. Extract and remove any `--thread-id ID` or `--comment-id ID` flags.
+   2. Extract and remove any `--require-sha SHA` flag.
+   3. Look for a PR number or GitHub PR URL in the remaining text.
+   4. If not found, infer: `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number --jq '.[0].number'`
+   5. If no PR found, report an error and stop.
+
+   ```bash
+   BRANCH=$(git rev-parse --abbrev-ref HEAD)
+   LAST_PUSH=$(git log -1 --format=%ct HEAD)
+   BASE_BRANCH=$(gh pr view <N> --json baseRefName --jq '.baseRefName')
+   ```
+
+   Check if the PR is already merged:
+
+   ```bash
+   gh pr view <N> --json state --jq '.state'
+   ```
+
+   If `MERGED`, invoke `/loop cancel` via Skill tool (to stop any active loop), output merged message, and stop.
+
+2. **Fetch comments:**
+
+   ```bash
+   npx pr-shepherd resolve <N> --fetch --last-push-time "$LAST_PUSH" --format=json
+   ```
+
+   The CLI auto-resolves outdated threads.
+   Parse the JSON for `actionableThreads`, `actionableComments`, `changesRequestedReviews`.
+
+3. **Triage each actionable item.** For each unresolved thread or visible comment:
+   - Read the comment body to understand what it's asking
+   - For review threads: read the referenced file and line
+   - Classify as: **Fixed** (already addressed), **Not relevant**, **Outdated**, or **Actionable** (real issue, not yet fixed)
+
+4. **Fix actionable items.** For each Actionable item:
+   - Read the relevant file(s) and apply the fix (Edit/Write tools)
+   - Re-classify as **Fixed**
+   - If too complex: leave as Actionable, report to user
+
+5. **Commit and push** (only if code was changed):
+   - `git add <file1> <file2> …` (NOT `git add -A`)
+   - `git commit -m "<appropriate commit message>"`
+   - `git fetch origin && git rebase origin/$BASE_BRANCH && git push --force-with-lease`
+   - Cancel stale CI runs: `gh run list --branch "$BRANCH" --status in_progress --json databaseId --jq '.[].databaseId' | xargs -I{} gh run cancel {}`
+
+6. **Resolve all verified items** — **only after the push:**
+
+   ```bash
+   npx pr-shepherd resolve <N> \
+     --resolve-thread-ids <comma-separated-IDs> \
+     --minimize-comment-ids <comma-separated-IDs> \
+     --dismiss-review-ids <comma-separated-IDs> \
+     --message "Addressed in $(git rev-parse HEAD)" \
+     --require-sha $(git rev-parse HEAD)
+   ```
+
+   The `--require-sha` flag ensures pr-shepherd verifies GitHub has the new commit before resolving.
+
+7. **Report results** from the CLI output.
+
+## Rules
+
+- NEVER resolve threads before pushing fixes (use `--require-sha`).
+- NEVER blindly resolve items — always read and verify first.
+- Resolve from ALL authors — bots, AI reviewers, and humans alike.
+- `--message` is required when using `--dismiss-review-ids`. The CLI will throw if it is missing.

package/src/cache/file-cache.mts

@@ -0,0 +1,101 @@
+/**
+ * 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;
+}