docs(agents): add an AI usage policy and align the agent contracts - #25
Draft
amirhs1 wants to merge 1 commit into
Draft
docs(agents): add an AI usage policy and align the agent contracts#25amirhs1 wants to merge 1 commit into
amirhs1 wants to merge 1 commit into
Conversation
PolyPhys had an operating contract for coding agents but no governance document for people. A reader deciding whether to trust or cite the package had no statement of human accountability, and nothing recorded that AI-suggested values, formulas, and citations are verified rather than assumed. That gap matters for a package whose output reaches published work and is archived on Zenodo. Add a root AI-POLICY.md as the human-facing document: scope, human accountability, how AI is and is not used, scientific integrity, provenance, security and data handling, licensing, contributor expectations, and revision. It states that the maintainer is accountable for every merged line and that no AI system is an author. Keep the split explicit. AI-POLICY.md says what is permitted and who answers for it; AGENTS.md and CLAUDE.md say how the work is done and now defer to the policy without restating it. Carry three matching rules into AGENTS.md rather than leaving them only in the policy, because they bind agents at work: a citation must be confirmed to exist and to support its claim, an expected test value must be derived rather than adopted from a model, and research data must not reach a third-party service. Extend the canonical-sources list, which also omitted CHANGELOG.md, CITATION.cff, and docs/NAMING-CONVENTION.md. Add a short AI assistance section to the README and record the change in the changelog. Documentation only; no package code, tests, or packaging metadata are touched. Ran the README doctests, which pass. Closes #24 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #25 +/- ##
=======================================
Coverage 85.12% 85.12%
=======================================
Files 14 14
Lines 1795 1795
=======================================
Hits 1528 1528
Misses 267 267 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
AI-POLICY.md: the human-facing governance document stating how AIcoding assistants are used here, that the maintainer is accountable for every
merged line, and that no AI system is an author of the software or of a release.
AI-POLICY.mdsays what is permitted and who answersfor it;
AGENTS.mdandCLAUDE.mdsay how the work is done and now defer tothe policy without restating it.
AGENTS.mdbecause they bind agents at work — acitation must be confirmed to exist and to support its claim, an expected test
value must be derived rather than adopted from a model, and research data must
not reach a third-party service.
AGENTS.mdcanonical-sources list, which also omittedCHANGELOG.md,CITATION.cff, anddocs/NAMING-CONVENTION.md.## AI assistancesection to the README and a changelog entry.Closes #24
Checks
flake8 polyphysmypy polyphys/analyze polyphys/managepytest README.md --doctest-glob="README.md"— 1 passedpython -m buildif packaging metadata, package data, or package layout changedpython -m sphinx -W -b html docs/source docs/_buildifdocs/source/changedDocumentation only: no package code, tests, or packaging metadata are touched, so
the linting, typing, build, and Sphinx checks have nothing to act on. The README
doctests were run because the README changed; they pass.
Scientific Correctness
Notes
Deliberately out of scope, and worth a separate decision:
CONTRIBUTING.mddoes not exist, so contributor expectations live insection 8 of the policy for now. If a contributor guide is added later, that
section should move and the policy should link to it.
.github/PULL_REQUEST_TEMPLATE.mdwouldenforce section 8 at the point of contribution. Left out to keep this PR to the
authorized scope.
archived record is a release decision, not a documentation one.
docs/source/ai-policy.mdwould mean keeping two copies in sync; the README link is the single entry point
for now.
Points to review before marking ready:
that list if it is incomplete.
([release] Evaluate MDAKit packaging and a JOSS submission #22) and for anyone citing the package; it should say exactly what you want on
the record.
any AI service. That is stricter than current practice may be — confirm you want
it stated as a rule.