|
| 1 | +# Multicast Project AI Usage Policy |
| 2 | + |
| 3 | +## 1. Purpose and Scope |
| 4 | + |
| 5 | +This policy governs the use of AI tools, particularly CodeRabbitAI, GH Copilot, and Codecov-ai-reviewer, within the Multicast project's development workflow. It establishes guidelines for responsible AI integration while maintaining the project's security, quality, and integrity. |
| 6 | + |
| 7 | +## 2. AI Role Definitions |
| 8 | + |
| 9 | +### 2.1 Permitted AI Roles :information_desk_person: |
| 10 | + |
| 11 | + * 2.1.A Assistive Code Review: |
| 12 | + * AI may provide feedback on code quality, style compliance, and potential issues |
| 13 | + * 2.1.B Assistive Project-Management Delegation: |
| 14 | + * AI may provide feedback when requested on GHI (GitHub issues), as well as open new, or comment on existing, GHI, to track suggested improvements to the project content. |
| 15 | + * 2.1.C Documentation Improvement: |
| 16 | + * AI may suggest improvements to documentation clarity and completeness |
| 17 | + * 2.1.D Test Coverage Analysis: |
| 18 | + * AI may identify areas lacking test coverage |
| 19 | +Code Generation Assistance: AI may suggest code implementations when requested |
| 20 | + |
| 21 | +> [!CAUTION] |
| 22 | +> However, AI may **NOT** apply changes, nor code suggestions, by themselves, to any protected branch (That is reserved for qualified human contributors). |
| 23 | +
|
| 24 | +### 2.2 Prohibited AI Roles :no_entry_sign: |
| 25 | + |
| 26 | + * 2.2.A Sole Developer: |
| 27 | + * AI (especially LLM type AI) is not well suited for innovation; No vibe-coding, the direction and development of the project CAN-NOT meaningfully come from AI. |
| 28 | + * 2.2.B Sole Approver: |
| 29 | + * AI approval alone is insufficient for merging any PR. |
| 30 | + |
| 31 | +> [!WARNING] |
| 32 | +> Only project admin may sufficiently act as a Sole Approver, and _even_ that is discouraged. |
| 33 | + * 2.2.C Security Gatekeeper: |
| 34 | + * AI cannot be the only mechanism for security validation |
| 35 | + * 2.2.D Unrestricted Auto-Merge: |
| 36 | + * AI cannot trigger auto-merge without human verification |
| 37 | + |
| 38 | +## 3. PR Review Process |
| 39 | + |
| 40 | +### 3.1 Required Human Review |
| 41 | + |
| 42 | + * 3.1.A Human Review |
| 43 | + * All PRs MUST receive at least one human review from an authorized maintainer |
| 44 | + * 3.1.B Verify or Resolve |
| 45 | + * Human reviews must verify (or conversely reject) the AI's suggestions. |
| 46 | + * Discussions are encouraged in both cases, as Humans and AI alike, may later consider relevant project content in future reviews. |
| 47 | + * 3.1.C Very Large PRs |
| 48 | + * For PRs exceeding 99 changed files, at least two human reviews are recommended. |
| 49 | +> [!NOTE] |
| 50 | +> Currently there is only one core maintainer. Hoping to change this. |
| 51 | +
|
| 52 | + * 3.1.D Review Conventions and Instructions |
| 53 | + * The project's code review conventions are currently enumerated in the living document: [CEP-4](https://gist.github.com/reactive-firewall/cc041f10aad1d43a5ef15f50a6bbd5a5) (convention enhancement proposal no.4) |
| 54 | + |
| 55 | +## 3.2 AI Review Requirements |
| 56 | + |
| 57 | +### 3.2 AI Assisted Code Review |
| 58 | + |
| 59 | + * 3.2.A AI Review Purpose |
| 60 | + * AI reviews are supplementary and do not replace human review |
| 61 | + * 3.2.B AI Troubleshooting |
| 62 | + * When AI review is triggered but fails (e.g., due to throttling), the PR must be marked as requiring additional attention |
| 63 | + * AI approval comments should not be used to bypass branch protection rules |
| 64 | + |
| 65 | +### 3.3 Large PR Handling |
| 66 | + |
| 67 | + * 3.3.A Less is More |
| 68 | + * PRs with more than 100 changed files should be split into smaller PRs when possible |
| 69 | +When splitting is not feasible, PR authors must provide a summary highlighting the most critical changes for human reviewers |
| 70 | + |
| 71 | +## 4. Security Considerations |
| 72 | + |
| 73 | +### 4.1 Verification and Validation |
| 74 | + |
| 75 | + * 4.1.A Review Line-by-Line |
| 76 | + * Absolutely, NO "Vibe-coding" is acceptable for this project. ALL AI-suggestions MUST be understood by at least one core maintainer (same as all other reviewed code needs to be) |
| 77 | +> [!TIP] |
| 78 | +> > Good code is its own best documentation. As you're about to add a comment, ask yourself, "How can I improve the code so that this comment isn't needed?" Improve the code and then document it to make it even clearer. |
| 79 | +> - Steve McConnell |
| 80 | +
|
| 81 | + * All AI-suggested code changes must be verified by a human maintainer (see 3.1.B). |
| 82 | + * 4.1.B Signed Commits |
| 83 | + * Code signing with different keys for human vs. AI contributions is required. |
| 84 | + * 4.1.C Security Assessments |
| 85 | + * AI-suggested security fixes must undergo additional human security review. |
| 86 | + |
| 87 | +### 4.2 Branch Protection |
| 88 | + |
| 89 | + * 4.2.A Stable and master branches must maintain protection rules requiring: |
| 90 | + * Minimum of one human approval |
| 91 | + * Signed commits |
| 92 | + * Passing CI checks |
| 93 | + * Force-pushing to protected branches is prohibited |
| 94 | + |
| 95 | +### 4.3 CWE-655 Mitigation |
| 96 | + |
| 97 | + * 4.3.A dual-approval system |
| 98 | + * The project implements a dual-approval system to help prevent single points of failure. |
| 99 | + * AI approvals are tracked separately from human approvals in the review process. Humans |
| 100 | +must be responsible for the actual merge of pull-requests. |
| 101 | + * Every user (eg. AI, or human) must have a distinct code-signing identity (see 4.1.B). |
| 102 | + * Only human controlled identities may merge branches, or commit to the default branch directly. |
| 103 | + |
| 104 | +## 5. Implementation and Compliance |
| 105 | + |
| 106 | +### 5.1 Configuration Management |
| 107 | + |
| 108 | + * 5.1.A CoderabbitAI Configuration |
| 109 | + * The `.coderabbit.yaml` file is the source of truth for CodeRabbitAI configuration. |
| 110 | + * 5.1.B Dependabot Configuration |
| 111 | + * The `.github/dependabot.yml` file is the source of truth for @dependabot configuration. |
| 112 | + * 5.1.C Changes |
| 113 | + * Changes to these configurations require PR approval from at least one core maintainer. |
| 114 | + * 5.1.D Audits |
| 115 | + * Regular audits of AI configuration will be conducted to ensure alignment with this policy. |
| 116 | + |
| 117 | +### 5.2 Monitoring and Reporting |
| 118 | + |
| 119 | + * 5.2.A Monitoring |
| 120 | + * Periodic audits of PR approvals will verify compliance with this policy |
| 121 | + * 5.2.B Reporting |
| 122 | + * Security incidents related to AI usage must be reported via project security channels |
| 123 | + |
| 124 | +### 5.3 Developer Training |
| 125 | + |
| 126 | + * 5.3.A Contributors should understand the limitations of AI tools in the review process |
| 127 | + * 5.3.B Clear communication about when and how to utilize AI assistance will be provided |
| 128 | + * 5.3.C New contributors will be directed to this policy as part of onboarding |
| 129 | + |
| 130 | +## 6. Exceptions |
| 131 | + |
| 132 | +## 6.1 Exceptions to this policy require: |
| 133 | + |
| 134 | + * 6.1.A Documented justification |
| 135 | + * 6.1.B Approval from at least two core maintainers |
| 136 | + * 6.1.C Time-limited scope with defined expiration |
| 137 | + * 6.1.D Post-implementation security review |
| 138 | + |
| 139 | +## 7. Policy Review |
| 140 | + |
| 141 | +### 7.1 This policy will be reviewed: |
| 142 | + |
| 143 | + * 7.1.A After any security incident involving AI tools |
| 144 | + * 7.1.B When significant changes to project AI integration are proposed |
0 commit comments