From afac50c55059048d6ca284ce6a524e1395843a9c Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Wed, 8 Apr 2026 17:33:21 -0700 Subject: [PATCH 1/4] docs(policy): add AI contribution policy --- AI_POLICY.md | 274 ++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 6 +- 2 files changed, 279 insertions(+), 1 deletion(-) create mode 100644 AI_POLICY.md diff --git a/AI_POLICY.md b/AI_POLICY.md new file mode 100644 index 0000000000..c5fcc1d036 --- /dev/null +++ b/AI_POLICY.md @@ -0,0 +1,274 @@ +# AI Contribution Policy + +This repository allows both AI-assisted contributions and limited autonomous AI contributions. + +Core rule: if you submit it, you own it. If you merge it, you approve it. + +## 1. Modes of AI contribution + +### AI-assisted contributions +AI-assisted pull requests are allowed by default when the contributor: +- understands every material change, +- can explain the change in their own words, +- discloses material AI use, +- runs the required local checks, +- keeps the PR small and reviewable, and +- responds to maintainers personally. + +### Autonomous AI contributions +Autonomous pull requests are allowed only for explicitly pre-approved issues and only within the limits of this policy. + +An autonomous PR is allowed only when all of the following are true: +- the linked issue is labeled `help wanted`, `ai-friendly`, and `ai:autonomous-ok`, +- the linked issue is not labeled `good first issue`, `security`, or `ai:autonomous-blocked`, +- the PR is labeled `ai:autonomous`, +- the PR includes the required AI disclosure block, +- the change stays within the autonomous scope limits in this policy, +- all required CI checks pass, and +- a human maintainer approves and merges the PR. + +Autonomous PRs that do not meet these conditions may be closed without detailed review. + +## 2. Definitions + +### AI-assisted +A human uses AI to help draft, refactor, test, review, or explain code, tests, docs, or issue text, and the human remains the author of record. + +### Autonomous +A bot or agent proposes and opens a PR with little or no human editing before the PR is opened. + +### Material AI use +AI generated or substantially rewrote content that remains in the final PR, or materially influenced the implementation. + +### Human merge owner +For every autonomous PR, one human must be clearly named in the PR body as the person accountable for review quality and merge decisions. + +## 3. Relationship to other repository files + +- `AGENTS.md` explains how agents should work in this repository. It is operational guidance for tools and agents. +- `AI_POLICY.md` is the governance policy for whether and how AI contributions are allowed. +- `CONTRIBUTING.md` is the contributor entry point and should link here. +- `SECURITY.md` controls vulnerability reporting and takes precedence for security issues. + +## 4. Issue labels and issue eligibility + +### Label meanings +- `ai-friendly`: the issue is narrow, deterministic, testable, and low-risk enough for AI help. +- `ai:autonomous-ok`: a maintainer explicitly allows autonomous PRs for this issue. +- `ai:autonomous-blocked`: autonomous PRs are not allowed. +- `help wanted`: maintainers are actively open to outside contributions. +- `good first issue`: reserved as a human learning and onboarding path. + +### Important rule for `good first issue` +`good first issue` is allowed for human contributors and AI-assisted work, but not for autonomous agents. + +### Maintainer checklist for marking an issue `ai-friendly` +Only mark an issue `ai-friendly` when all of the following are true: +- acceptance criteria are concrete, +- the expected diff is small and bounded, +- the change can be tested without secrets or private infrastructure, +- there is no unresolved architectural or product-design ambiguity, +- success can be validated by unit tests, targeted integration tests, or a narrow benchmark, +- the issue does not require dependency, release, auth, or security-sensitive changes. + +## 5. Scope limits for autonomous PRs + +### Allowed by default +Autonomous PRs may handle only low-risk work such as: +- documentation fixes, +- test additions or corrections, +- small bug fixes with focused regression tests, +- narrow refactors that do not change behavior, +- small developer-experience fixes, +- small performance improvements with measurable evidence. + +### Not allowed without explicit maintainer pre-approval +Autonomous PRs must not modify the following unless the issue explicitly authorizes it and a maintainer has pre-approved the scope: +- authentication or authorization logic, +- secret handling, +- security-sensitive code paths, +- dependency upgrades or lockfile churn, +- release or publishing logic, +- GitHub Actions or other CI workflows, +- packaging, installation, or environment bootstrap logic, +- broad API changes, +- multi-area refactors, +- connectors or integrations that require live credentials or paid external services to validate. + +### Reviewability limits +By default, autonomous PRs should stay under roughly: +- 5 changed files, and +- 300 net changed lines, +excluding generated snapshots or mechanical fixture updates. + +Anything larger requires explicit maintainer signoff before review. + +## 6. Disclosure and authorship + +### For AI-assisted PRs +If there was material AI use: +- include an `AI Disclosure` section in the PR body, +- describe what AI was used for, +- state what you personally reviewed or rewrote, +- state what you ran locally. + +### For autonomous PRs +The PR body must include: +- issue number, +- agent identity, +- human merge owner, +- tools/models used, +- summary of what the agent changed, +- local checks run, +- checks deferred to CI, +- known risks or uncertainty. + +### Commit attribution +For material AI use, add an `Assisted-by:` trailer to the relevant commit(s) or otherwise clearly disclose tool use in the PR body. + +Examples: +- `Assisted-by: Claude` +- `Assisted-by: ChatGPT` +- `Assisted-by: GitHub Copilot` + +## 7. Required quality workflow + +Both AI-assisted and autonomous contributions must follow this quality loop: + +1. Reproduce the bug or specify the intended behavior. +2. Add or update a test that fails before the fix, when applicable. +3. Make the smallest change that makes the test pass. +4. Add or tighten regression coverage so the failure does not come back. +5. Run lint, type checks, and relevant tests. +6. Do a DRY and simplification pass: + - remove duplication, + - improve naming, + - reduce unnecessary branching, + - split oversized functions if it improves clarity, + - avoid mixing cleanup with unrelated behavior changes. +7. Re-run lint, type checks, and relevant tests after each refactor pass. +8. Perform a security and robustness review: + - validate untrusted input, + - avoid logging secrets, + - avoid unsafe shell execution, + - avoid unsafe deserialization, + - check file system, network, and permission boundaries, + - confirm failures are handled intentionally. +9. If performance is part of the claim, include a benchmark or other measurable before/after evidence. + +Do not stop at "tests passed once." The expectation is to iterate until no known bugs remain and the implementation is as simple as it can be without changing behavior. + +## 8. Local vs CI testing requirements + +CI is a required gate, not a substitute for zero local validation. + +### Required local validation before ready-for-review +Run the best applicable local command(s) for the scope of your change. + +Recommended local commands for this repository: + +```bash +cd docker + +# Small CPU-scoped iteration +WITH_BUILD=0 ./test-cpu-local-minimal.sh + +# Lint + typecheck only +WITH_BUILD=0 WITH_TEST=0 ./test-cpu-local.sh + +# Full CPU validation before commit for non-trivial changes +./test-cpu-local.sh + +# GPU validation for GPU-affecting changes before merge +./test-gpu-local.sh +``` + +### Minimum expectations by change type +- Docs-only changes: explain why code execution was unnecessary. +- Small code changes: run at least the relevant minimal local test path. +- Behavioral changes or bug fixes: add/update tests and run the relevant local suite. +- GPU-affecting changes: run targeted GPU validation before merge. +- Connector or integration changes: run the narrowest relevant integration path available. + +### Required PR reporting +Every AI-assisted or autonomous PR must explicitly say: +- what was run locally, +- what was not run locally, +- what is expected to be covered by CI, +- any environment limitations that prevented broader local validation. + +## 9. Reviewer interaction rules + +- Write the PR description yourself or edit it until it reflects your own understanding. +- Be able to explain every non-trivial change. +- Do not use AI to post review replies on your behalf. +- Do not paste AI answers into review discussions without verifying and owning them. +- If maintainers ask for a narrower PR, split it. + +Review is a human conversation. + +## 10. Identity, approvals, and merge rules + +- AI-assisted PRs must have a human author of record. +- Autonomous PRs may be opened by a bot or agent account, but must name a human merge owner. +- No autonomous PR may self-approve or self-merge. +- Only a human maintainer may approve and merge an autonomous PR. +- Maintainers may require extra review for higher-risk areas. + +## 11. Rate limits for autonomous contributions + +To protect reviewer bandwidth, the default operating limits are: +- at most 1 open autonomous PR per agent at a time, +- at most 2 open autonomous PRs repo-wide at a time unless maintainers explicitly allow more, +- maintainers may pause or disable autonomous PRs at any time, +- maintainers may temporarily require human-authored follow-up if an agent repeatedly submits low-signal or low-quality work. + +## 12. Agent capability and security boundaries + +Unless a maintainer explicitly says otherwise in the issue, autonomous agents must not: +- access repository, org, or cloud secrets, +- modify `.github/workflows/`, release automation, publishing config, or security policy files, +- change dependency pins, lockfiles, or package publishing behavior, +- call unapproved remote services, +- exfiltrate code, data, logs, or test output, +- approve, merge, or close their own PRs, +- suppress, edit around, or bypass failing checks. + +If a task requires privileged credentials, secret material, or changes to trust boundaries, it is not autonomous-safe by default. + +## 13. Enforcement + +Maintainers may close a PR without detailed review if it: +- lacks required AI disclosure, +- is obviously not understood by the submitter, +- skips required local validation, +- is too large or too noisy to review, +- contains AI-generated review replies, +- ignores issue scope, +- crosses security or autonomy boundaries, +- repeatedly creates reviewer burden without enough signal. + +Repeated abuse may result in loss of contribution privileges. + +## 14. Suggested PR disclosure block + +```md +## AI Disclosure +- Mode: AI-assisted / Autonomous / No material AI use +- Tools used: +- Human author of record: +- Human merge owner: +- Linked issue: +- What AI changed: +- What I personally reviewed or rewrote: +- Local checks run: +- Deferred to CI: +- Known risks / uncertainty: +``` + +## 15. Policy intent + +This policy is pro-quality, pro-accountability, and pro-automation in bounded places. + +We want AI to reduce mechanical work. +We do not want AI to externalize reviewer cost, increase security risk, or lower the quality bar. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e18b2edff9..28e38557b3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,6 +8,10 @@ We follow [The Apache Software Foundation's code of conduct](https://www.apache. Developer communications should primarily live in GitHub issues and PRs, as this best helps with asynchronous communications and future reference +## AI policy + +See [AI_POLICY.md](AI_POLICY.md) for repository policy on AI-assisted and autonomous AI contributions. + ## Chat! When in doubt, [stop by the Slack channel](https://join.slack.com/t/graphistry-community/shared_invite/zt-53ik36w2-fpP0Ibjbk7IJuVFIRSnr6g) @@ -61,4 +65,4 @@ The commit types are `fix()`, `feat()`, `infra()`, `garden()` / `refactor()`, `d **Automation** * PRs must pass CI, including style checks -* Maintainers are responsible for publishing \ No newline at end of file +* Maintainers are responsible for publishing From 6b824044a0b55070cb784bcc55600aff3e431805 Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Wed, 8 Apr 2026 17:39:14 -0700 Subject: [PATCH 2/4] docs(agents): reference AI policy --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 7d74d31499..ca6c8d87e7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,10 @@ This file defines AI assistant guidance for this repository. +## Policy + +For AI contribution governance (AI-assisted vs autonomous contribution rules), see `AI_POLICY.md`. + ## Skill Locations Canonical skills live under: From d1c1d2b50eb14de8f3a51300f9e121b924e19f1c Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Wed, 8 Apr 2026 17:57:38 -0700 Subject: [PATCH 3/4] docs(policy): tighten and simplify AI contribution rules --- AI_POLICY.md | 341 +++++++++++++++++++++------------------------------ 1 file changed, 138 insertions(+), 203 deletions(-) diff --git a/AI_POLICY.md b/AI_POLICY.md index c5fcc1d036..e9812c43d7 100644 --- a/AI_POLICY.md +++ b/AI_POLICY.md @@ -1,261 +1,196 @@ # AI Contribution Policy -This repository allows both AI-assisted contributions and limited autonomous AI contributions. +This repository permits both AI-assisted and autonomous AI contributions. Core rule: if you submit it, you own it. If you merge it, you approve it. -## 1. Modes of AI contribution +## 1) Contribution modes -### AI-assisted contributions -AI-assisted pull requests are allowed by default when the contributor: -- understands every material change, -- can explain the change in their own words, -- discloses material AI use, -- runs the required local checks, -- keeps the PR small and reviewable, and -- responds to maintainers personally. +### AI-assisted +A human author uses AI to draft/refactor/test/review/explain changes and remains responsible for the final PR. -### Autonomous AI contributions -Autonomous pull requests are allowed only for explicitly pre-approved issues and only within the limits of this policy. +### Autonomous +An agent/bot opens a PR with little or no human editing before opening the PR. -An autonomous PR is allowed only when all of the following are true: -- the linked issue is labeled `help wanted`, `ai-friendly`, and `ai:autonomous-ok`, -- the linked issue is not labeled `good first issue`, `security`, or `ai:autonomous-blocked`, -- the PR is labeled `ai:autonomous`, -- the PR includes the required AI disclosure block, -- the change stays within the autonomous scope limits in this policy, -- all required CI checks pass, and -- a human maintainer approves and merges the PR. +## 2) Eligibility rules -Autonomous PRs that do not meet these conditions may be closed without detailed review. +### AI-assisted eligibility +Allowed by default when the contributor: +- understands all material changes, +- can explain non-trivial changes in their own words, +- provides AI disclosure (including harness and model), +- runs appropriate local validation, +- keeps the PR reviewable. -## 2. Definitions +### Autonomous eligibility +Baseline autonomous eligibility: +- linked issue has **one or more** of: `help wanted`, `good-first-issue`, `ai-friendly`, +- PR includes required autonomous AI disclosure, +- PR follows the required validation loop in this policy. -### AI-assisted -A human uses AI to help draft, refactor, test, review, or explain code, tests, docs, or issue text, and the human remains the author of record. +Standard repository merge gates still apply (required CI and human maintainer approval/merge). -### Autonomous -A bot or agent proposes and opens a PR with little or no human editing before the PR is opened. - -### Material AI use -AI generated or substantially rewrote content that remains in the final PR, or materially influenced the implementation. - -### Human merge owner -For every autonomous PR, one human must be clearly named in the PR body as the person accountable for review quality and merge decisions. - -## 3. Relationship to other repository files - -- `AGENTS.md` explains how agents should work in this repository. It is operational guidance for tools and agents. -- `AI_POLICY.md` is the governance policy for whether and how AI contributions are allowed. -- `CONTRIBUTING.md` is the contributor entry point and should link here. -- `SECURITY.md` controls vulnerability reporting and takes precedence for security issues. - -## 4. Issue labels and issue eligibility - -### Label meanings -- `ai-friendly`: the issue is narrow, deterministic, testable, and low-risk enough for AI help. -- `ai:autonomous-ok`: a maintainer explicitly allows autonomous PRs for this issue. -- `ai:autonomous-blocked`: autonomous PRs are not allowed. -- `help wanted`: maintainers are actively open to outside contributions. -- `good first issue`: reserved as a human learning and onboarding path. - -### Important rule for `good first issue` -`good first issue` is allowed for human contributors and AI-assisted work, but not for autonomous agents. - -### Maintainer checklist for marking an issue `ai-friendly` -Only mark an issue `ai-friendly` when all of the following are true: -- acceptance criteria are concrete, -- the expected diff is small and bounded, -- the change can be tested without secrets or private infrastructure, -- there is no unresolved architectural or product-design ambiguity, -- success can be validated by unit tests, targeted integration tests, or a narrow benchmark, -- the issue does not require dependency, release, auth, or security-sensitive changes. - -## 5. Scope limits for autonomous PRs - -### Allowed by default -Autonomous PRs may handle only low-risk work such as: -- documentation fixes, -- test additions or corrections, -- small bug fixes with focused regression tests, -- narrow refactors that do not change behavior, -- small developer-experience fixes, -- small performance improvements with measurable evidence. - -### Not allowed without explicit maintainer pre-approval -Autonomous PRs must not modify the following unless the issue explicitly authorizes it and a maintainer has pre-approved the scope: -- authentication or authorization logic, +Autonomous PRs may be closed without detailed review if these conditions are not met. + +## 3) Labels: current reality and optional controls + +### Current labels used in this repo +- `help wanted`: maintainers are open to outside contributions. +- `good-first-issue`: suitable onboarding scope; also allowed for autonomous work. +- `ai-friendly`: narrow, deterministic, low-risk, testable scope for AI-enabled contribution. +- `security`: security-sensitive work; requires extra maintainer caution. + +### Optional control labels (if maintainers add them) +If labels like `ai:autonomous-ok`, `ai:autonomous-blocked`, `ai:autonomous` are introduced later, maintainers may use them to tighten or route autonomous flow. Until then, they are not required for eligibility. + +## 4) Scope and risk boundaries for autonomous PRs + +### Usually allowed +- docs fixes, +- focused test additions/corrections, +- small bug fixes with regression tests, +- narrow refactors without behavior change, +- small DX fixes, +- small measured performance improvements. + +### Not autonomous-safe by default (needs explicit maintainer pre-approval) +- authn/authz logic, - secret handling, -- security-sensitive code paths, -- dependency upgrades or lockfile churn, -- release or publishing logic, -- GitHub Actions or other CI workflows, -- packaging, installation, or environment bootstrap logic, +- security-sensitive paths, +- dependency/lockfile churn, +- release/publishing logic, +- CI/workflow logic, +- packaging/bootstrap changes, - broad API changes, - multi-area refactors, -- connectors or integrations that require live credentials or paid external services to validate. +- integrations requiring live credentials/paid external services. + +## 5) PR size and stacking expectations -### Reviewability limits -By default, autonomous PRs should stay under roughly: -- 5 changed files, and -- 300 net changed lines, -excluding generated snapshots or mechanical fixture updates. +Prefer small PRs. For AI-generated change streams, prefer stacked PRs when it improves reviewability. -Anything larger requires explicit maintainer signoff before review. +Default autonomous target: +- about 5 changed files or fewer, +- about 300 net changed lines or fewer, +excluding generated fixtures/snapshots. -## 6. Disclosure and authorship +Larger changes should be pre-approved before deep review. -### For AI-assisted PRs -If there was material AI use: -- include an `AI Disclosure` section in the PR body, -- describe what AI was used for, -- state what you personally reviewed or rewrote, -- state what you ran locally. +## 6) Disclosure requirements -### For autonomous PRs -The PR body must include: -- issue number, +### Material AI use (AI-assisted) +PR must include: +- tools/harness used, +- model(s) used, +- what AI changed, +- what human reviewed/rewrote, +- what was run locally, +- what was deferred to CI. + +### Autonomous PRs (mandatory) +PR must include: +- linked issue, - agent identity, +- tools/harness used, +- model(s) used, - human merge owner, -- tools/models used, -- summary of what the agent changed, +- change summary, - local checks run, - checks deferred to CI, -- known risks or uncertainty. +- known risks/uncertainty, +- attached execution plan (see section 7). ### Commit attribution -For material AI use, add an `Assisted-by:` trailer to the relevant commit(s) or otherwise clearly disclose tool use in the PR body. +For material AI use, include `Assisted-by:` trailer(s) in relevant commits or equivalent explicit PR disclosure. + +## 7) Plan requirement for AI work -Examples: -- `Assisted-by: Claude` -- `Assisted-by: ChatGPT` -- `Assisted-by: GitHub Copilot` +When viable, use `ai/prompts/PLAN.md` as the plan template. -## 7. Required quality workflow +Requirements: +- Keep plan file under `plans//plan.md`. +- Do **not** commit the plan file. +- Attach the plan to the PR (for example, paste plan content in PR comment/body or upload as PR attachment). -Both AI-assisted and autonomous contributions must follow this quality loop: +Purpose: make it auditable that specification conformance, testing, security review, and DRY/professionalism checks were performed. -1. Reproduce the bug or specify the intended behavior. -2. Add or update a test that fails before the fix, when applicable. -3. Make the smallest change that makes the test pass. -4. Add or tighten regression coverage so the failure does not come back. -5. Run lint, type checks, and relevant tests. -6. Do a DRY and simplification pass: +## 8) Required validation loop (repeat-until-stable) + +Do not run checks once and stop. Iterate until fresh analysis produces no significant new actions. + +Required loop: +1. Confirm spec/acceptance criteria. +2. Audit AI suggestions; verify and prioritize before acting. +3. Use red->green flow when applicable: + - reproduce failure or define intended behavior, + - add/update failing test first, + - make smallest fix, + - add/tighten regression coverage. +4. Run lint/type/tests relevant to scope. +5. Run DRY/professionalism pass: - remove duplication, - - improve naming, - - reduce unnecessary branching, - - split oversized functions if it improves clarity, - - avoid mixing cleanup with unrelated behavior changes. -7. Re-run lint, type checks, and relevant tests after each refactor pass. -8. Perform a security and robustness review: + - improve naming/clarity, + - avoid unnecessary branching, + - split oversized logic when it improves readability. +6. Run security/robustness pass: - validate untrusted input, - - avoid logging secrets, - - avoid unsafe shell execution, - - avoid unsafe deserialization, - - check file system, network, and permission boundaries, - - confirm failures are handled intentionally. -9. If performance is part of the claim, include a benchmark or other measurable before/after evidence. + - avoid secret leakage, + - avoid unsafe shell/deserialization, + - verify filesystem/network/permission boundaries, + - ensure intentional error handling. +7. Re-run checks after refactors. +8. Repeat steps 2-7 until no significant new findings remain. -Do not stop at "tests passed once." The expectation is to iterate until no known bugs remain and the implementation is as simple as it can be without changing behavior. +## 9) Local vs CI validation -## 8. Local vs CI testing requirements +CI is required, but not a substitute for local validation. -CI is a required gate, not a substitute for zero local validation. +PR must explicitly state: +- what ran locally, +- what did not run locally, +- what CI is expected to validate, +- environment limits that blocked broader local validation. -### Required local validation before ready-for-review -Run the best applicable local command(s) for the scope of your change. - -Recommended local commands for this repository: +Repository-recommended local commands: ```bash cd docker -# Small CPU-scoped iteration +# Small CPU iteration WITH_BUILD=0 ./test-cpu-local-minimal.sh -# Lint + typecheck only +# Lint + typecheck WITH_BUILD=0 WITH_TEST=0 ./test-cpu-local.sh -# Full CPU validation before commit for non-trivial changes +# Full CPU validation ./test-cpu-local.sh -# GPU validation for GPU-affecting changes before merge +# GPU-affecting changes ./test-gpu-local.sh ``` -### Minimum expectations by change type -- Docs-only changes: explain why code execution was unnecessary. -- Small code changes: run at least the relevant minimal local test path. -- Behavioral changes or bug fixes: add/update tests and run the relevant local suite. -- GPU-affecting changes: run targeted GPU validation before merge. -- Connector or integration changes: run the narrowest relevant integration path available. - -### Required PR reporting -Every AI-assisted or autonomous PR must explicitly say: -- what was run locally, -- what was not run locally, -- what is expected to be covered by CI, -- any environment limitations that prevented broader local validation. - -## 9. Reviewer interaction rules - -- Write the PR description yourself or edit it until it reflects your own understanding. -- Be able to explain every non-trivial change. -- Do not use AI to post review replies on your behalf. -- Do not paste AI answers into review discussions without verifying and owning them. -- If maintainers ask for a narrower PR, split it. - -Review is a human conversation. - -## 10. Identity, approvals, and merge rules - -- AI-assisted PRs must have a human author of record. -- Autonomous PRs may be opened by a bot or agent account, but must name a human merge owner. -- No autonomous PR may self-approve or self-merge. -- Only a human maintainer may approve and merge an autonomous PR. -- Maintainers may require extra review for higher-risk areas. - -## 11. Rate limits for autonomous contributions - -To protect reviewer bandwidth, the default operating limits are: -- at most 1 open autonomous PR per agent at a time, -- at most 2 open autonomous PRs repo-wide at a time unless maintainers explicitly allow more, -- maintainers may pause or disable autonomous PRs at any time, -- maintainers may temporarily require human-authored follow-up if an agent repeatedly submits low-signal or low-quality work. - -## 12. Agent capability and security boundaries - -Unless a maintainer explicitly says otherwise in the issue, autonomous agents must not: -- access repository, org, or cloud secrets, -- modify `.github/workflows/`, release automation, publishing config, or security policy files, -- change dependency pins, lockfiles, or package publishing behavior, -- call unapproved remote services, -- exfiltrate code, data, logs, or test output, -- approve, merge, or close their own PRs, -- suppress, edit around, or bypass failing checks. +## 10) Human review and merge rules -If a task requires privileged credentials, secret material, or changes to trust boundaries, it is not autonomous-safe by default. +- AI-assisted PRs require a human author of record. +- Autonomous PRs require a named human merge owner. +- No autonomous PR self-approval or self-merge. +- Only human maintainers approve/merge autonomous PRs. +- Maintainers may pause/limit autonomous flow at any time. -## 13. Enforcement +## 11) Enforcement -Maintainers may close a PR without detailed review if it: -- lacks required AI disclosure, -- is obviously not understood by the submitter, -- skips required local validation, -- is too large or too noisy to review, -- contains AI-generated review replies, -- ignores issue scope, -- crosses security or autonomy boundaries, -- repeatedly creates reviewer burden without enough signal. +Maintainers may close PRs without detailed review when they are out of scope, undisclosed, low-signal, too large/noisy, or violate this policy/security boundaries. -Repeated abuse may result in loss of contribution privileges. +Repeated abuse may lead to loss of contribution privileges. -## 14. Suggested PR disclosure block +## 12) Suggested disclosure block ```md ## AI Disclosure - Mode: AI-assisted / Autonomous / No material AI use -- Tools used: +- Agent identity: +- Tools/harness used: +- Model(s) used: - Human author of record: - Human merge owner: - Linked issue: @@ -263,12 +198,12 @@ Repeated abuse may result in loss of contribution privileges. - What I personally reviewed or rewrote: - Local checks run: - Deferred to CI: +- Plan attached (path or PR comment link): - Known risks / uncertainty: ``` -## 15. Policy intent +## 13) Policy intent This policy is pro-quality, pro-accountability, and pro-automation in bounded places. -We want AI to reduce mechanical work. -We do not want AI to externalize reviewer cost, increase security risk, or lower the quality bar. +AI should reduce mechanical work without shifting reviewer burden, increasing security risk, or lowering quality standards. From c63edbbe683b994e35975008a23bdb9a5561ed9e Mon Sep 17 00:00:00 2001 From: Leo Meyerovich Date: Wed, 8 Apr 2026 19:32:08 -0700 Subject: [PATCH 4/4] docs(policy): make PR size guidance change-type based --- AI_POLICY.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/AI_POLICY.md b/AI_POLICY.md index e9812c43d7..6873836ab5 100644 --- a/AI_POLICY.md +++ b/AI_POLICY.md @@ -69,12 +69,19 @@ If labels like `ai:autonomous-ok`, `ai:autonomous-blocked`, `ai:autonomous` are Prefer small PRs. For AI-generated change streams, prefer stacked PRs when it improves reviewability. -Default autonomous target: -- about 5 changed files or fewer, -- about 300 net changed lines or fewer, -excluding generated fixtures/snapshots. +Reviewability targets are change-type dependent, not a single hard cap. -Larger changes should be pre-approved before deep review. +For docs-only, test-only, and narrow bug-fix PRs: +- prefer very small diffs, +- as a guideline, keep fixes focused (often <100 LOC implementation) with targeted tests/docs (can be larger, for example up to ~500 LOC), and +- keep file count small when possible. + +For feature PRs: +- larger diffs may be appropriate, +- split work into coherent, reviewable slices (stacked PRs when helpful), +- keep each slice tied to explicit acceptance criteria and validation. + +If a PR becomes too large/noisy to review effectively, maintainers may request it be split before deep review. ## 6) Disclosure requirements