Problem
PolyPhys has an operating contract for coding agents (AGENTS.md, CLAUDE.md)
that tells agents how to work. It has no governance document that tells
humans how AI is used in this project, who is accountable for the result, and
what AI is never permitted to touch.
That gap matters for a package that produces published research results and is
archived on Zenodo. A reader deciding whether to trust or cite PolyPhys — or a
reviewer evaluating a possible JOSS submission (#22) — has no statement of human
accountability to read, and no assurance that AI-suggested numerical values,
formulas, or citations are verified rather than asserted.
Proposal
Add a root AI-POLICY.md as the human-facing governance document, and keep it
strictly separate from the agent-facing contract:
|
AI-POLICY.md |
AGENTS.md / CLAUDE.md |
| Audience |
humans |
agents |
| Answers |
who is accountable, what is disclosed, what is forbidden |
how to do the work |
Cross-link once in each direction; do not restate rules across files.
Policy sections:
- Purpose and scope — governs this repository and its releases.
- Human accountability — the maintainer is accountable for every merged line;
AI tools do not merge, approve, release, or alter protections; AI is not an
author and will not appear in CITATION.cff or AUTHORS.rst.
- How AI is and is not used in this project.
- Scientific integrity — expected values come from derivation, a published
reference, or a reproducible computation, never from model assertion;
doctest output comes from running the code; citations are verified to exist
and to support the claim; no unverified AI-generated result enters published
work.
- Provenance and attribution — points at
docs/NAMING-CONVENTION.md.
- Security and data handling — no credentials, private datasets, unpublished
simulation data, or draft manuscripts into AI tools; no bypassing
permissions, sandboxing, or branch protection.
- Licensing — generated output must be MIT-compatible.
- Contributors — disclose material AI assistance; you remain responsible for
what you submit.
Scope
- Add
AI-POLICY.md.
- Revise
AGENTS.md: add the policy to the canonical-sources list (which today
also omits AGENTS.md itself, CHANGELOG.md, CITATION.cff, and
docs/NAMING-CONVENTION.md), make the policy binding on agents, strengthen
the citation rule to require verified sources, and add a no-exfiltration rule.
- Revise
CLAUDE.md: one pointer to the policy; it stays thin.
- Add a short
## AI assistance section to README.md.
Out of scope
CONTRIBUTING.md (does not exist yet; contributor rules live in the policy
for now).
- Whether an AI-usage statement belongs in the Zenodo release metadata — a
separate release decision.
- Any change to package code, tests, or packaging metadata.
Problem
PolyPhys has an operating contract for coding agents (
AGENTS.md,CLAUDE.md)that tells agents how to work. It has no governance document that tells
humans how AI is used in this project, who is accountable for the result, and
what AI is never permitted to touch.
That gap matters for a package that produces published research results and is
archived on Zenodo. A reader deciding whether to trust or cite PolyPhys — or a
reviewer evaluating a possible JOSS submission (#22) — has no statement of human
accountability to read, and no assurance that AI-suggested numerical values,
formulas, or citations are verified rather than asserted.
Proposal
Add a root
AI-POLICY.mdas the human-facing governance document, and keep itstrictly separate from the agent-facing contract:
AI-POLICY.mdAGENTS.md/CLAUDE.mdCross-link once in each direction; do not restate rules across files.
Policy sections:
AI tools do not merge, approve, release, or alter protections; AI is not an
author and will not appear in
CITATION.cfforAUTHORS.rst.reference, or a reproducible computation, never from model assertion;
doctest output comes from running the code; citations are verified to exist
and to support the claim; no unverified AI-generated result enters published
work.
docs/NAMING-CONVENTION.md.simulation data, or draft manuscripts into AI tools; no bypassing
permissions, sandboxing, or branch protection.
what you submit.
Scope
AI-POLICY.md.AGENTS.md: add the policy to the canonical-sources list (which todayalso omits
AGENTS.mditself,CHANGELOG.md,CITATION.cff, anddocs/NAMING-CONVENTION.md), make the policy binding on agents, strengthenthe citation rule to require verified sources, and add a no-exfiltration rule.
CLAUDE.md: one pointer to the policy; it stays thin.## AI assistancesection toREADME.md.Out of scope
CONTRIBUTING.md(does not exist yet; contributor rules live in the policyfor now).
separate release decision.