Skip to content

docs(agents): add an AI usage policy and align the agent contracts - #25

Draft
amirhs1 wants to merge 1 commit into
mainfrom
docs/ai-policy
Draft

docs(agents): add an AI usage policy and align the agent contracts#25
amirhs1 wants to merge 1 commit into
mainfrom
docs/ai-policy

Conversation

@amirhs1

@amirhs1 amirhs1 commented Aug 4, 2026

Copy link
Copy Markdown
Owner

Summary

  • Adds a root AI-POLICY.md: the human-facing governance document stating how AI
    coding 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.
  • Keeps 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.
  • Carries three rules into AGENTS.md 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.
  • Extends the AGENTS.md canonical-sources list, which also omitted
    CHANGELOG.md, CITATION.cff, and docs/NAMING-CONVENTION.md.
  • Adds a short ## AI assistance section to the README and a changelog entry.

Closes #24

Checks

  • flake8 polyphys
  • mypy polyphys/analyze polyphys/manage
  • pytest README.md --doctest-glob="README.md" — 1 passed
  • python -m build if packaging metadata, package data, or package layout changed
  • python -m sphinx -W -b html docs/source docs/_build if docs/source/ changed

Documentation 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

  • No measurement/statistics behavior changed
  • Units, numerical fixtures, and domain assumptions are preserved or explained
  • Parser lineage and organizer vocabulary are unchanged, or matching parser tests/docs were updated

Notes

Deliberately out of scope, and worth a separate decision:

  • CONTRIBUTING.md does not exist, so contributor expectations live in
    section 8 of the policy for now. If a contributor guide is added later, that
    section should move and the policy should link to it.
  • An AI-disclosure checkbox in .github/PULL_REQUEST_TEMPLATE.md would
    enforce section 8 at the point of contribution. Left out to keep this PR to the
    authorized scope.
  • Zenodo / release metadata. Whether an AI-usage statement belongs in the
    archived record is a release decision, not a documentation one.
  • The Sphinx site does not carry the policy. Adding docs/source/ai-policy.md
    would mean keeping two copies in sync; the README link is the single entry point
    for now.

Points to review before marking ready:

  • Section 3 names Claude Code and OpenAI Codex as the assistants in use. Correct
    that list if it is incomplete.
  • Section 2's authorship claim is the load-bearing sentence for a JOSS reviewer
    ([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.
  • Section 6 forbids sending unpublished simulation data and draft manuscripts to
    any AI service. That is stricter than current practice may be — confirm you want
    it stated as a rule.

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>
@amirhs1 amirhs1 added this to the v0.4.0 — Release Readiness milestone Aug 4, 2026
@amirhs1 amirhs1 added type:docs Improvements or additions to documentation area:documentation README, Sphinx docs, changelog, or docstrings area:agents Claude Code, Codex, or other AI-agent tooling and contracts labels Aug 4, 2026
@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.12%. Comparing base (47114a4) to head (fcfc10d).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:agents Claude Code, Codex, or other AI-agent tooling and contracts area:documentation README, Sphinx docs, changelog, or docstrings type:docs Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[docs] Add an AI usage policy and align the agent contracts

2 participants