From e6eed1793ab50bf732ccffd0a9c8d3f5a760bd7e Mon Sep 17 00:00:00 2001 From: lucas Date: Fri, 24 Apr 2026 09:07:06 -0400 Subject: [PATCH 1/2] docs: add website link to README Signed-off-by: lucas --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8b1b3b3..ad893c1 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,10 @@

-

pip install open-aura

+

+Website · +pip install open-aura +


From 9d88b72979e0d85bc2843404de1ef29c93878a2f Mon Sep 17 00:00:00 2001 From: lucas Date: Fri, 24 Apr 2026 09:10:45 -0400 Subject: [PATCH 2/2] docs: add agent contribution guidance Signed-off-by: lucas --- .github/PULL_REQUEST_TEMPLATE.md | 1 + AGENTS.md | 113 +++++++++++++++++++++++++++++++ CONTRIBUTING.md | 19 ++++++ README.md | 1 + SECURITY.md | 18 +++++ pyproject.toml | 1 + 6 files changed, 153 insertions(+) create mode 100644 AGENTS.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index abea236..ca84774 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -18,6 +18,7 @@ - [ ] Commits signed off (`-s`) and signed (GPG or Sigstore) - [ ] No secrets committed (double-check) - [ ] No raw LLM calls outside Pydantic AI +- [ ] If AI-assisted: disclosed, human-reviewed, and checked for security/licensing impact - [ ] If touching `aura.core.md`: rationale included below ## Additional notes diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5146236 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,113 @@ +# AGENTS.md + +This file gives coding agents the project-specific context they need to work safely in +Open AURA. It complements the human-facing README and contribution docs. + +## Project Overview + +Open AURA is a Python package and CLI for generating evidence-based weekly project +briefs from delivery signals. The core implementation lives in `openaura/`, tests live +in `tests/`, and bundled instructions/templates live under `openaura/instructions/` and +`openaura/templates/`. + +## Setup Commands + +- Create a virtual environment: `python -m venv .venv && source .venv/bin/activate` +- Install for development: `python -m pip install -e ".[dev]"` +- Run the CLI locally: `aura --help` + +## Required Checks + +Run the smallest relevant check while iterating, then run the full set before opening a +PR that changes code: + +- Lint: `python -m ruff check .` +- Format check: `python -m ruff format --check .` +- Type check: `python -m mypy openaura` +- Security lint: `python -m bandit -r openaura -ll` +- Tests and coverage: `python -m pytest --cov=openaura --cov-fail-under=80` +- Dependency audit: `python -m pip_audit --skip-editable` + +For docs-only changes, at minimum review the rendered Markdown where practical and run +`git diff --check`. + +## Code Style + +- Target Python 3.11 and newer. +- Use type hints and keep `mypy` strict-compatible. +- Use `pathlib` for filesystem paths. +- Keep connector failures graceful: return warnings instead of crashing the pipeline. +- Do not add raw provider SDK calls for LLMs; all model interactions go through + Pydantic AI. +- Keep dependencies small and justified. Prefer the standard library or existing + project dependencies. + +## Security Rules + +- Never commit secrets. Config files may name environment variables but must not contain + token values. +- Do not log secrets, credentials, personal data, or raw third-party API payloads unless + they have been deliberately redacted. +- Use `https://` for connector base URLs. +- Prefer safe Python APIs. Do not use `exec` or `eval` on untrusted input, and avoid + shell execution unless there is a clear need and arguments are safely structured. +- When adding dependencies, verify that the package exists, is maintained, and is + compatible with the Apache-2.0 license and this project's supply-chain expectations. + +## Agentic Development Policy + +Open AURA allows AI-assisted and agentic development, but a human contributor remains +responsible for every submitted change. + +- Human review is required before merge for all agentic changes. +- AI agents must not add DCO `Signed-off-by` trailers on behalf of a person. Only the + human submitter may certify the DCO. +- If a substantial change was AI-assisted, disclose it in the PR body or an + `Assisted-by:` commit trailer, for example: + `Assisted-by: Codex:gpt-5.4`. +- The human submitter must understand the change well enough to explain what it does, + why it is needed, how it was tested, and how it affects security and licensing. +- Human reviewers must explicitly consider license compatibility and security impact for + agentic changes, especially new dependencies, generated code, CI workflows, release + automation, and connector/authentication logic. +- Do not submit generated code that you cannot review, test, maintain, and defend. +- Treat AI suggestions like contributions from an unfamiliar collaborator: useful, but + not authoritative. + +## License and Security Review + +The repository is Apache-2.0 licensed. Do not alter `LICENSE` unless the maintainers +explicitly request a legal/license update. + +For AI-assisted changes: + +- Confirm generated content does not include third-party code with incompatible license + terms. +- Preserve required copyright, attribution, SPDX, and notice information when using + third-party material. +- Prefer original implementations over copied snippets. +- Include a security review note in the PR when changing authentication, secret handling, + CI/CD, release, networking, file I/O, or dependency behavior. + +## PR Expectations + +- Keep PRs focused and small enough for a human to review. +- Include a clear summary, testing notes, and any AI-assistance disclosure. +- Update tests when behavior changes. +- Update docs when user-facing behavior, CLI flags, configuration, or security posture + changes. +- Do not leave unrelated formatting churn in the diff. + +## Reference Guidance + +These instructions are informed by: + +- AGENTS.md: https://agents.md/ +- Linux kernel AI coding assistant guidance: + https://docs.kernel.org/process/coding-assistants.html +- Linux Foundation generative AI policy: + https://www.linuxfoundation.org/legal/generative-ai +- OpenSSF security-focused guide for AI code assistant instructions: + https://best.openssf.org/Security-Focused-Guide-for-AI-Code-Assistant-Instructions +- Red Hat guidance on AI-assisted open source contribution: + https://www.redhat.com/en/blog/accelerating-open-source-development-ai diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b723730..1d31dcf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,6 +59,23 @@ git commit -s -m "feat: ..." The CI enforces this. +## AI-assisted contributions + +AI-assisted and agentic development is allowed, but the human contributor is accountable +for the final contribution. + +- Human review is required before merge for any agentic change. +- AI agents must not add `Signed-off-by` trailers. Only the human submitter may certify + the DCO. +- Disclose substantial AI assistance in the PR body or with an `Assisted-by:` trailer, + for example: `Assisted-by: Codex:gpt-5.4`. +- Review AI-generated content for correctness, tests, maintainability, security impact, + and Apache-2.0 license compatibility before submitting. +- Do not submit generated code or docs that you cannot explain and maintain. +- If the change affects authentication, secrets, CI/CD, releases, dependencies, + networking, file I/O, or bundled instructions, include a short security and license + review note in the PR. + ## Signed commits We also require GPG- or Sigstore-signed commits on `main`. Set up commit signing @@ -72,6 +89,8 @@ We also require GPG- or Sigstore-signed commits on `main`. Set up commit signing - [ ] Updated `CHANGELOG` entry if user-facing - [ ] No new deps without a rationale in the PR description - [ ] No changes to `aura.core.md` without maintainer sign-off +- [ ] AI-assisted changes disclosed and reviewed by a human for security and licensing + impact ## Reporting security issues diff --git a/README.md b/README.md index ad893c1..a3b78ed 100644 --- a/README.md +++ b/README.md @@ -294,6 +294,7 @@ python -m pytest - [`openaura/instructions/aura.md.example`](openaura/instructions/aura.md.example) — user-editable project context template. - [`MANIFESTO.md`](MANIFESTO.md) — the AURA Protocol: 10 rules for accurate repo updates. +- [`AGENTS.md`](AGENTS.md) — coding-agent setup, checks, security, and human-review rules. - [`CONTRIBUTING.md`](CONTRIBUTING.md) — developer setup and PR expectations. - [`SECURITY.md`](SECURITY.md) — vulnerability disclosure policy. - [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) — community standards. diff --git a/SECURITY.md b/SECURITY.md index 7a64862..5016ace 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -65,6 +65,24 @@ Open AURA runs in CI and reads signals from external APIs. It: If you find a path where a secret leaks to logs, output briefs, or any third party, that is **always in scope** and qualifies for a security advisory regardless of severity. +## Agentic development security expectations + +Open AURA allows AI-assisted and agentic development, but generated changes are never +accepted on trust alone. A human contributor and human reviewer must review agentic +changes for security and licensing impact before merge. + +For agentic changes, reviewers should pay special attention to: + +- secret handling, logging, and redaction paths +- connector authentication and external API calls +- CI/CD, release, provenance, and signing workflows +- new or changed dependencies, including license compatibility +- file I/O, shell execution, network access, and generated templates + +AI agents must not certify the DCO or make license assertions on behalf of a human +contributor. The human submitter remains responsible for reviewing generated code, +ensuring Apache-2.0 compatibility, and documenting any relevant attribution or notices. + ## Hardening this project ships with - CodeQL scans on every push and PR. diff --git a/pyproject.toml b/pyproject.toml index e5affc4..44b072b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -68,6 +68,7 @@ include = [ "tests", "README.md", "MANIFESTO.md", + "AGENTS.md", "LICENSE", "SECURITY.md", "CONTRIBUTING.md",