feat(S01): add ci-pr-review workflow and RULESET.md org setup guide

.github/workflows/ci-pr-review.yml

@@ -0,0 +1,87 @@
+name: CI — PR Review
+
+on:
+  pull_request:
+    types: [opened, reopened, ready_for_review, synchronize]
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+concurrency:
+  group: claude-review-${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  id-token: write
+
+jobs:
+  pr_agent_review:
+    if: >-
+      github.event_name == 'pull_request' &&
+      github.event.pull_request.draft == false &&
+      github.event.sender.type != 'Bot'
+    runs-on: ubuntu-latest
+    name: Claude — Auto Review
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          claude_args: "--model claude-opus-4-6"
+          prompt: |
+            Review PR #${{ github.event.pull_request.number }} in this repo.
+
+            Review against these standards:
+
+            ## Code Quality
+            - Minimal and pragmatic — no over-engineering
+            - Readability over cleverness
+            - No unnecessary config or "just in case" code
+
+            ## Security (OWASP Top 10)
+            - Input validation at system boundaries
+            - No hardcoded secrets, credentials, or API keys
+            - No injection vulnerabilities (SQL, XSS, command injection)
+
+            ## Testing
+            - Flag if code changes lack corresponding tests
+
+            ## Output Format
+            Format your response as a GitHub PR review comment in markdown with these sections:
+
+            ### Must Fix
+            Critical issues that must be resolved before merging. Number each item. If none, write "None."
+
+            ### Should Consider
+            Important improvements that should be addressed. Number each item. If none, write "None."
+
+            ### Minor
+            Non-blocking nits and style suggestions. Number each item. If none, write "None."
+
+            ### Summary
+            A brief 2-3 sentence summary of the PR changes and overall quality.
+
+  pr_agent_commands:
+    if: >-
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request &&
+       contains(github.event.comment.body, '@claude') && github.event.sender.type != 'Bot') ||
+      (github.event_name == 'pull_request_review_comment' &&
+       contains(github.event.comment.body, '@claude') && github.event.sender.type != 'Bot')
+    runs-on: ubuntu-latest
+    name: Claude — Slash Commands
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          claude_args: "--model claude-opus-4-6"

.gitignore

@@ -0,0 +1,40 @@
+
+# ── GSD baseline (auto-generated) ──
+.gsd/activity/
+.gsd/forensics/
+.gsd/runtime/
+.gsd/worktrees/
+.gsd/parallel/
+.gsd/auto.lock
+.gsd/metrics.json
+.gsd/completed-units.json
+.gsd/STATE.md
+.gsd/gsd.db
+.gsd/DISCUSSION-MANIFEST.json
+.gsd/milestones/**/*-CONTINUE.md
+.gsd/milestones/**/continue.md
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+*~
+.idea/
+.vscode/
+*.code-workspace
+.env
+.env.*
+!.env.example
+node_modules/
+.next/
+dist/
+build/
+__pycache__/
+*.pyc
+.venv/
+venv/
+target/
+vendor/
+*.log
+coverage/
+.cache/
+tmp/

.gsd/DECISIONS.md

@@ -0,0 +1,13 @@
+# Decisions Register
+
+<!-- Append-only. Never edit or remove existing rows.
+     To reverse a decision, add a new row that supersedes it.
+     Read this file at the start of any planning or research phase. -->
+
+| # | When | Scope | Decision | Choice | Rationale | Revisable? |
+|---|------|-------|----------|--------|-----------|------------|
+| D001 | M001 | arch | Workflow trigger strategy | `pull_request` + `issue_comment` (not `workflow_call`) | pr-agent needs PR context; org rulesets require `pull_request` trigger directly in the workflow file | No |
+| D002 | M001 | library | AI model for PR review | `anthropic/claude-opus-4-6` primary, `anthropic/claude-sonnet-4-6` fallback | User wants best reasoning model with extended thinking; Opus 4.6 is current top model | Yes — if newer model released |
+| D003 | M001 | arch | Org-wide distribution mechanism | GitHub org rulesets (not per-repo `workflow_call`) | Single source of truth without per-repo workflow files; rulesets enforce automatically | No |
+| D004 | M001 | convention | Workflow naming | `ci-pr-review.yml` | Consistent with existing `ci-*.yml` naming convention in the repo | No |
+| D005 | M001 | arch | Extended thinking | Enabled via `config.enable_claude_extended_thinking: "true"` | User explicitly wants max reasoning depth for reviews; Opus 4.6 adaptive thinking defaults to high effort | Yes — if cost becomes prohibitive |

.gsd/PROJECT.md

@@ -0,0 +1,30 @@
+# ChillWhales Org Automation
+
+## What This Is
+
+The `chillwhales/.github` org repo — single source of truth for shared GitHub Actions workflows, composite actions, and org-wide automation. Existing reusable workflows handle CI build/lint/test, quality checks, and publish validation. The goal is to expand this with org-wide workflows enforced via GitHub rulesets, starting with automated PR review.
+
+## Core Value
+
+One place to define workflows that run across every repo in the org — no per-repo duplication, no drift.
+
+## Current State
+
+- Three reusable `workflow_call` workflows: `ci-build-lint-test.yml`, `ci-quality.yml`, `ci-publish-validation.yml`
+- Two composite actions: `setup-pnpm`, `build-and-upload`
+- Used by `lsp-indexer` repo via `workflow_call`
+- No org-wide ruleset-enforced workflows yet
+
+## Architecture / Key Patterns
+
+- Workflows use `workflow_call` trigger with configurable inputs for reuse
+- Composite actions extract common step sequences
+- pnpm-based Node.js ecosystem
+
+## Capability Contract
+
+See `.gsd/REQUIREMENTS.md` for the explicit capability contract, requirement status, and coverage mapping.
+
+## Milestone Sequence
+
+- [ ] M001: Org-Wide PR Review Workflow — Automated code review via qodo-ai/pr-agent + Claude Opus 4.6 with extended thinking, enforced org-wide via GitHub rulesets

.gsd/REQUIREMENTS.md

@@ -0,0 +1,159 @@
+# Requirements
+
+This file is the explicit capability and coverage contract for the project.
+
+## Active
+
+### R001 — Org-wide automated PR review without per-repo workflow files
+- Class: core-capability
+- Status: active
+- Description: A single workflow in the `.github` org repo runs pr-agent reviews across all org repos without needing workflow files in each repo.
+- Why it matters: Eliminates duplication, ensures consistent review quality, single source of truth.
+- Source: user
+- Primary owning slice: M001/S01
+- Supporting slices: none
+- Validation: mapped
+- Notes: Enforced via GitHub org rulesets pointing at the centralized workflow.
+
+### R002 — Reviews powered by Claude Opus 4.6 with extended thinking
+- Class: core-capability
+- Status: active
+- Description: PR reviews use `anthropic/claude-opus-4-6` as primary model with extended thinking enabled via `secrets.ANTHROPIC_KEY`.
+- Why it matters: Best available reasoning for thorough code review — the user explicitly wants the strongest model with deep thinking.
+- Source: user
+- Primary owning slice: M001/S01
+- Supporting slices: none
+- Validation: mapped
+- Notes: Opus 4.6 defaults to high effort with adaptive thinking, effectively max reasoning depth.
+
+### R003 — Fallback to Claude Sonnet 4.6 on primary failure
+- Class: continuity
+- Status: active
+- Description: If Opus 4.6 fails (rate limit, timeout), falls back to `anthropic/claude-sonnet-4-6`.
+- Why it matters: Reviews shouldn't silently fail because the primary model is temporarily unavailable.
+- Source: inferred
+- Primary owning slice: M001/S01
+- Supporting slices: none
+- Validation: mapped
+- Notes: none
+
+### R004 — Triggers on PR open/sync/reopen on any non-default branch
+- Class: primary-user-loop
+- Status: active
+- Description: Workflow fires on `pull_request` events (opened, reopened, synchronize, ready_for_review) targeting any branch.
+- Why it matters: Every push to a feature branch with an open PR gets reviewed automatically.
+- Source: user
+- Primary owning slice: M001/S01
+- Supporting slices: none
+- Validation: mapped
+- Notes: Uses `pull_request` trigger since pr-agent needs PR context. `synchronize` fires on every push to the PR branch.
+
+### R005 — Auto-review + auto-describe + auto-improve on trigger
+- Class: primary-user-loop
+- Status: active
+- Description: On each trigger event, pr-agent automatically runs review, describe, and improve commands.
+- Why it matters: No manual invocation needed — reviews happen automatically on every meaningful PR event.
+- Source: user
+- Primary owning slice: M001/S01
+- Supporting slices: none
+- Validation: mapped
+- Notes: none
+
+### R006 — Comment-triggered slash commands
+- Class: core-capability
+- Status: active
+- Description: Developers can invoke `/review`, `/improve`, `/describe`, etc. by commenting on the PR.
+- Why it matters: On-demand re-review or specific tool invocation without re-pushing.
+- Source: inferred
+- Primary owning slice: M001/S01
+- Supporting slices: none
+- Validation: mapped
+- Notes: Requires `issue_comment` trigger in the workflow.
+
+### R007 — Draft PRs excluded from automatic review
+- Class: quality-attribute
+- Status: active
+- Description: Draft PRs do not trigger automatic review. Only non-draft PRs are reviewed.
+- Why it matters: Avoids noisy reviews on work-in-progress PRs.
+- Source: inferred
+- Primary owning slice: M001/S01
+- Supporting slices: none
+- Validation: mapped
+- Notes: Uses `github.event.pull_request.draft == false` condition.
+
+### R008 — Ruleset setup instructions documented for org admin
+- Class: operability
+- Status: active
+- Description: A clear doc explains how to configure the GitHub org ruleset to point at this workflow so it runs across all repos.
+- Why it matters: The workflow file alone isn't enough — someone needs to wire the ruleset in the org settings UI.
+- Source: inferred
+- Primary owning slice: M001/S01
+- Supporting slices: none
+- Validation: mapped
+- Notes: Includes ANTHROPIC_KEY org secret setup.
+
+## Validated
+
+(none yet)
+
+## Deferred
+
+(none)
+
+## Out of Scope
+
+### R030 — Per-repo workflow customization or overrides
+- Class: constraint
+- Status: out-of-scope
+- Description: Individual repos cannot override or customize the review workflow behavior.
+- Why it matters: Prevents scope creep — single source of truth means uniform behavior.
+- Source: user
+- Primary owning slice: none
+- Supporting slices: none
+- Validation: n/a
+- Notes: If needed later, could use per-repo `.pr_agent.toml` config files.
+
+### R031 — Non-Anthropic model backends
+- Class: anti-feature
+- Status: out-of-scope
+- Description: No support for OpenAI, Gemini, or other model providers.
+- Why it matters: Keeps config simple and focused on the user's chosen provider.
+- Source: user
+- Primary owning slice: none
+- Supporting slices: none
+- Validation: n/a
+- Notes: none
+
+### R032 — Auto-merge or status-check gating on review outcome
+- Class: anti-feature
+- Status: out-of-scope
+- Description: PR review results do not block merge or trigger auto-merge.
+- Why it matters: Review is advisory, not a gate.
+- Source: inferred
+- Primary owning slice: none
+- Supporting slices: none
+- Validation: n/a
+- Notes: none
+
+## Traceability
+
+| ID | Class | Status | Primary owner | Supporting | Proof |
+|---|---|---|---|---|---|
+| R001 | core-capability | active | M001/S01 | none | mapped |
+| R002 | core-capability | active | M001/S01 | none | mapped |
+| R003 | continuity | active | M001/S01 | none | mapped |
+| R004 | primary-user-loop | active | M001/S01 | none | mapped |
+| R005 | primary-user-loop | active | M001/S01 | none | mapped |
+| R006 | core-capability | active | M001/S01 | none | mapped |
+| R007 | quality-attribute | active | M001/S01 | none | mapped |
+| R008 | operability | active | M001/S01 | none | mapped |
+| R030 | constraint | out-of-scope | none | none | n/a |
+| R031 | anti-feature | out-of-scope | none | none | n/a |
+| R032 | anti-feature | out-of-scope | none | none | n/a |
+
+## Coverage Summary
+
+- Active requirements: 8
+- Mapped to slices: 8
+- Validated: 0
+- Unmapped active requirements: 0