Require two humans for bot authored PRs

.github/workflows/approvals.yml

@@ -0,0 +1,48 @@
+name: PR Approval Check
+
+on:
+  pull_request_review:
+    types: [submitted, dismissed]
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  check-approvals:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check required approvals
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const reviews = await github.rest.pulls.listReviews({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pr.number,
+            });
+
+            // Count unique human approvals (latest review per user)
+            const latestByUser = {};
+            for (const review of reviews.data) {
+              if (review.user.type === 'Bot') continue;
+              latestByUser[review.user.login] = review.state;
+            }
+            const approvalCount = Object.values(latestByUser)
+              .filter(state => state === 'APPROVED').length;
+
+            // Determine if PR author is a bot/GitHub Actions
+            const authorType = pr.user.type;        // 'Bot' vs 'User'
+            const authorLogin = pr.user.login;       // e.g. 'github-actions[bot]'
+            const isBot = authorType === 'Bot' || authorLogin.endsWith('[bot]');
+
+            const required = isBot ? 2 : 1;
+
+            console.log(`PR author: ${authorLogin} (${authorType}), isBot: ${isBot}`);
+            console.log(`Approvals: ${approvalCount} / ${required} required`);
+
+            if (approvalCount < required) {
+              core.setFailed(
+                `This PR needs ${required} human approval(s) but has ${approvalCount}. ` +
+                `(Author is ${isBot ? 'a bot' : 'human'})`
+              );
+            }

CONTRIBUTING.md

@@ -4,19 +4,15 @@ Welcome, and thank you for your interest in contributing to Vortex! We are delig
 
 We ask that you read the guidelines below in order to make the process as streamlined as possible.
 
-## AI Assistance Notice
+## AI Assistance
 
 > [!IMPORTANT]
-> The Vortex project allows AI-assisted contributions, which must be properly
-> disclosed in the pull request.
+> The Vortex project permits and embraces AI-assisted contributions. Contributors
+> should disclose usage of conversational or agentic AI tools in the PR description.
 >
-> If you are using any kind of AI assistance when contributing to Vortex, please
-> disclose this in your pull request, along with the extent to which it was used
-> (e.g. writing docs or code generation).
->
-> Contributors are required to be able to understand the AI-assisted output and
-> reason about it. Should a PR indicate no visible human accountability and
-> involvement we reserve the right to close it.
+> For the full AI policy — including disclosure requirements, review standards for
+> AI-generated PRs, and rules for autonomous agents — see the
+> [contributing guide](https://vortex.dev/project/contributing.html#ai-assistance).
 
 ## Code Contributions
 
@@ -35,7 +31,7 @@ The contribution process is outlined below:
 
 3. Open a PR to indicate that the change is ready for review.
    - Ensure that you sign your work via DCO (see below).
-   - Disclose LLM usage as described in [AI Assistance Notice](#ai-assistance-notice).
+   - Disclose LLM usage as described in [AI Assistance](#ai-assistance).
    - CI requires approval from external committers.
 
 ## Governance

docs/project/contributing.md

@@ -34,8 +34,73 @@ git commit -s
 
 ## AI Assistance
 
-AI-assisted contributions are permitted but must be disclosed in the pull request, along with the
-extent of use. Contributors must be able to understand and reason about AI-generated output.
+The Vortex project permits and embraces AI-assisted contributions. Today, most PRs involve some
+degree of AI assistance — whether through IDE autocomplete, conversational AI, or autonomous agents.
+This section describes our expectations around disclosure, review, and accountability.
+
+### Repository Setup
+
+The repository has [Claude Code](https://docs.anthropic.com/en/docs/claude-code) configured as a
+GitHub Action. Users with write access to the repository can mention `@claude` in PR comments or
+issue comments to trigger AI-powered code reviews, request changes, or generate PRs. Configuration
+for Claude's behavior lives in `CLAUDE.md` at the repository root.
+
+### Disclosure
+
+Contributors should disclose AI usage in the PR description when conversational or agentic AI tools
+(e.g., Claude, ChatGPT, Claude Code) were used to produce code, documentation, or tests. Standard
+IDE autocomplete (e.g., Copilot tab-completion) does not require disclosure.
+
+AI-translated content should note that it was translated with AI assistance.
+
+### Human vs. Agent PRs
+
+We distinguish between two kinds of AI-assisted PRs:
+
+- **Human PRs** — A human writes the PR, possibly with significant AI assistance. The human author
+  is accountable for the code quality and correctness, just as they would be for any handwritten
+  code. Standard review rules apply (one approving reviewer).
+
+- **Agent PRs** — An autonomous AI agent (e.g., triggered via `@claude` or a scheduled GitHub
+  Action) opens the PR with minimal human steering. Agent PRs require **two human reviewers**
+  before merge.
+
+The distinction is straightforward: if a human opened the PR, it's a human PR. If an automated
+agent opened it, it's an agent PR.
+
+### Review Standards
+
+AI-assisted code should receive extra scrutiny during review. AI tools can produce code that is
+superficially correct but subtly wrong — off-by-one errors, incorrect edge case handling, or tests
+that pass without actually exercising the intended behavior. Reviewers should pay particular
+attention to:
+
+- Correctness of logic, not just whether it compiles and passes CI.
+- Tests that genuinely validate behavior rather than merely achieving coverage.
+- Unnecessary complexity or over-abstraction.
+
+The project may use AI-powered review tools on PRs. Reviewers are free to use AI to assist their
+reviews without disclosure.
+
+### AI Agents
+
+AI agents (bots, scheduled actions, etc.) are permitted to:
+
+- Open pull requests, with a human assigned as the responsible party.
+- Post review comments on pull requests.
+
+AI agents must **not**:
+
+- Merge or approve pull requests.
+- Push code to protected branches.
+
+A human is accountable for all actions taken by an agent operating under their authority.
+
+### AI-Generated Tests
+
+AI-generated tests are welcome, but contributors must verify that tests actually exercise the
+intended behavior — not just pass. A green test suite produced by AI can give a false sense of
+coverage if the assertions are trivial or the setup doesn't reflect real conditions.
 
 ## Coding Style