Skip to content

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

Description

@amirhs1

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:

  1. Purpose and scope — governs this repository and its releases.
  2. 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.
  3. How AI is and is not used in this project.
  4. 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.
  5. Provenance and attribution — points at docs/NAMING-CONVENTION.md.
  6. Security and data handling — no credentials, private datasets, unpublished
    simulation data, or draft manuscripts into AI tools; no bypassing
    permissions, sandboxing, or branch protection.
  7. Licensing — generated output must be MIT-compatible.
  8. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:agentsClaude Code, Codex, or other AI-agent tooling and contractsarea:documentationREADME, Sphinx docs, changelog, or docstringstype:docsImprovements or additions to documentation

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions