✨ feat: add automated code review pipeline

.github/workflows/automated-code-review.yml

@@ -0,0 +1,50 @@
+name: Automated Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  review:
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run automated review
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_REVIEW_MODEL: ${{ vars.OPENAI_REVIEW_MODEL || 'gpt-5.5' }}
+          REVIEW_REPORT_TITLE: "Automated PR Code Review"
+          REVIEW_CADENCE: "pull-request"
+          REVIEW_BASE: ${{ github.event.pull_request.base.sha }}
+          REVIEW_HEAD: ${{ github.event.pull_request.head.sha }}
+          REVIEW_GITHUB_COMMENT: "1"
+          REVIEW_EXPORT_NOTION: ${{ vars.REVIEW_EXPORT_NOTION || '0' }}
+          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
+          NOTION_DATABASE_ID: ${{ secrets.NOTION_DATABASE_ID }}
+          NOTION_TITLE_PROPERTY: ${{ vars.NOTION_TITLE_PROPERTY || 'Name' }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: bun run review -- --fail-on P1
+
+      - name: Upload review report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: automated-code-review
+          path: review-output/

.github/workflows/scheduled-study-report.yml

@@ -0,0 +1,46 @@
+name: Scheduled Study Review Report
+
+on:
+  schedule:
+    - cron: "0 23 * * *"
+    - cron: "30 23 * * 4"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Publish scheduled review report
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_REVIEW_MODEL: ${{ vars.OPENAI_REVIEW_MODEL || 'gpt-5.5' }}
+          REVIEW_REPORT_TITLE: "Scheduled Study Code Review"
+          REVIEW_CADENCE: ${{ github.event.schedule == '30 23 * * 4' && 'weekly-friday' || 'daily-morning' }}
+          REVIEW_BASE: "HEAD~1"
+          REVIEW_HEAD: "HEAD"
+          REVIEW_EXPORT_NOTION: "1"
+          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
+          NOTION_DATABASE_ID: ${{ secrets.NOTION_DATABASE_ID }}
+          NOTION_TITLE_PROPERTY: ${{ vars.NOTION_TITLE_PROPERTY || 'Name' }}
+        run: bun run review
+
+      - name: Upload scheduled report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: scheduled-study-review-report
+          path: review-output/

.gitignore

@@ -12,6 +12,7 @@
 
 # testing
 /coverage
+/review-output
 
 # next.js
 /.next/

AGENTS.md

@@ -9,6 +9,14 @@ bugs, regressions, security issues, auth problems, CORS problems, token exposure
 missing validation, missing tests, broken API contracts, performance risks,
 and maintainability problems.
 
+## Primary Review Criteria
+
+Use these criteria as the first pass for every review:
+
+1. Meaningful variable and function naming
+2. Readability improvements through early returns when they reduce nesting
+3. Runtime performance and complexity risks
+
 ## Severity
 
 - P0: outage, data loss, critical security issue
@@ -23,4 +31,4 @@ and maintainability problems.
 - Separate existing failures from newly introduced failures.
 - Prefer concrete, fixable findings.
 - Include impact, suggested fix, and verification step.
-- Do not report generic style preferences.
+- Do not report generic style preferences.

docs/automated-code-review.md

@@ -0,0 +1,60 @@
+# Automated Code Review Pipeline
+
+This repository uses an LLM-backed review harness to review pull request diffs
+and publish structured feedback.
+
+## Flow
+
+1. A pull request is opened, synchronized, reopened, or marked ready for review.
+2. GitHub Actions checks out the repository and installs dependencies with Bun.
+3. `bun run review` collects the base/head diff and changed files.
+4. The harness runs local verification checks such as lint, typecheck, test, and build.
+5. `AGENTS.md` and `review-agents/*.md` are sent with the diff to the OpenAI Responses API.
+6. Findings are normalized into JSON and Markdown reports.
+7. The workflow creates or updates a single automated PR comment.
+8. Scheduled runs can publish the same report format to Notion.
+
+## Review Criteria
+
+The primary review criteria are:
+
+1. Meaningful variable and function naming
+2. Early returns where they improve readability and reduce nesting
+3. Runtime performance and complexity risks
+
+The harness also reviews bugs, regressions, security issues, auth/CORS risks,
+token exposure, missing validation, missing tests, broken API contracts, and
+maintainability risks.
+
+## Required Secrets
+
+- `OPENAI_API_KEY`: required for LLM review.
+- `NOTION_TOKEN`: required only when Notion publishing is enabled.
+- `NOTION_DATABASE_ID`: required only when Notion publishing is enabled.
+
+## Optional Variables
+
+- `OPENAI_REVIEW_MODEL`: defaults to `gpt-5.5`.
+- `REVIEW_EXPORT_NOTION`: set to `1` to publish scheduled or PR reports to Notion.
+- `NOTION_TITLE_PROPERTY`: defaults to `Name`.
+
+## Workflows
+
+- `.github/workflows/automated-code-review.yml` runs on pull requests and posts
+  a review comment.
+- `.github/workflows/scheduled-study-report.yml` runs every morning and once
+  again on Friday morning for a weekly study report cadence.
+
+## Local Verification
+
+Run the harness without calling OpenAI:
+
+```bash
+bun run review -- --skip-checks --skip-agents --base HEAD~1 --head HEAD
+```
+
+Run the full review locally after setting `OPENAI_API_KEY`:
+
+```bash
+bun run review -- --base HEAD~1 --head HEAD
+```

package.json

@@ -7,6 +7,7 @@
     "build": "bun next build",
     "start": "bun ext start",
     "lint": "bun biome check --apply .",
+    "review": "bun scripts/review-harness.ts",
     "test": "bun test ./src/**/*.test.ts",
     "format": "biome format --write",
     "prepare": "husky"

review-agents/architecture-reviewer.md

@@ -0,0 +1,13 @@
+You are the architecture and maintainability reviewer.
+
+Focus only on:
+- code structure and responsibility boundaries
+- duplicated logic introduced by the change
+- hard-to-maintain control flow
+- unclear variable or function naming that can cause misunderstanding
+- early return opportunities that reduce nested branches and improve readability
+- broken API contracts between modules
+
+Return only concrete, actionable findings.
+Do not report broad style preferences.
+Use P0/P1/P2/P3 severity.

review-agents/bug-reviewer.md

@@ -0,0 +1,13 @@
+You are the bug reviewer.
+
+Focus only on:
+- user-facing regressions
+- runtime exceptions
+- incorrect async or state handling
+- broken edge cases
+- invalid assumptions about nullable or optional data
+- behavior that differs from the apparent product intent
+
+Return only concrete, actionable findings.
+Separate existing failures from newly introduced failures.
+Use P0/P1/P2/P3 severity.

review-agents/performance-reviewer.md

@@ -0,0 +1,12 @@
+You are the performance reviewer.
+
+Focus only on:
+- unnecessary repeated network calls
+- expensive re-renders or unstable React dependencies
+- inefficient loops or data transformations
+- avoidable bundle or runtime cost
+- complexity risks introduced by the change
+
+Return only concrete, actionable findings.
+Do not report micro-optimizations without user-visible impact.
+Use P0/P1/P2/P3 severity.

review-agents/reporter.md

@@ -0,0 +1,10 @@
+You are the report quality reviewer.
+
+Focus only on:
+- whether findings include file, line, impact, suggested fix, and verification
+- whether existing failures are clearly separated from new failures
+- whether the final report is understandable enough to publish to a study log
+- whether high-severity findings are prioritized correctly
+
+Return only concrete, actionable findings about the review report or automation output.
+Use P0/P1/P2/P3 severity.