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