From 136f4bda068f454d50c51c58832f8079d89dded7 Mon Sep 17 00:00:00 2001 From: OpenCode Date: Wed, 8 Jul 2026 13:21:19 +0700 Subject: [PATCH] Add 10 curricula, maps, and governance docs Closes #565, Closes #566, Closes #568, Closes #569, Closes #572, Closes #573, Closes #574, Closes #575, Closes #576, Closes #580 --- docs/evidence/CURRICULUM_AGENT.md | 30 +++++++++++++++++++ .../evidence/CURRICULUM_BENCHMARK_REVIEWER.md | 18 +++++++++++ docs/evidence/CURRICULUM_MAINTAINER.md | 20 +++++++++++++ docs/evidence/CURRICULUM_RELEASE_OPERATOR.md | 19 ++++++++++++ docs/evidence/CURRICULUM_REVIEWER.md | 26 ++++++++++++++++ docs/evidence/DOCS_ARCHIVE_INDEX_GUIDE.md | 22 ++++++++++++++ .../DOCS_DEPRECATION_NOTICE_TEMPLATE.md | 13 ++++++++ docs/evidence/DOCS_IMPROVEMENT_SCORECARD.md | 15 ++++++++++ docs/evidence/DOC_MAP_TRUST_LAYER.md | 11 +++++++ docs/evidence/LEARNING_PATH_OVERVIEW.md | 20 +++++++++++++ tests/test_curricula_batch.py | 20 +++++++++++++ 11 files changed, 214 insertions(+) create mode 100644 docs/evidence/CURRICULUM_AGENT.md create mode 100644 docs/evidence/CURRICULUM_BENCHMARK_REVIEWER.md create mode 100644 docs/evidence/CURRICULUM_MAINTAINER.md create mode 100644 docs/evidence/CURRICULUM_RELEASE_OPERATOR.md create mode 100644 docs/evidence/CURRICULUM_REVIEWER.md create mode 100644 docs/evidence/DOCS_ARCHIVE_INDEX_GUIDE.md create mode 100644 docs/evidence/DOCS_DEPRECATION_NOTICE_TEMPLATE.md create mode 100644 docs/evidence/DOCS_IMPROVEMENT_SCORECARD.md create mode 100644 docs/evidence/DOC_MAP_TRUST_LAYER.md create mode 100644 docs/evidence/LEARNING_PATH_OVERVIEW.md create mode 100644 tests/test_curricula_batch.py diff --git a/docs/evidence/CURRICULUM_AGENT.md b/docs/evidence/CURRICULUM_AGENT.md new file mode 100644 index 00000000..520ccfc4 --- /dev/null +++ b/docs/evidence/CURRICULUM_AGENT.md @@ -0,0 +1,30 @@ +# Agent Contributor Curriculum + +For AI agents contributing to the repository. + +## Prerequisites +- Read AGENTS.md (primary operating contract) +- Read AGENT_TASKS.json (safe task routing) + +## Stage 1: Safe tasks (docs, tests, schemas) +- Fix broken doc links +- Add tests for existing functionality +- Improve documentation clarity +- Add schemas for artifacts + +## Stage 2: Normal tasks (CI, benchmarks) +- Improve CI workflows +- Add benchmark scripts +- Add concept cards +- Add runbooks and checklists + +## Stage 3: Review-required tasks +- Changes to calibration pipeline +- Changes to safety policy +- Changes to scoring weights +- Any change that affects claims or releases + +## Forbidden +- Releasing candidates without human review +- Changing safety policy without human review +- Making scientific claims without evidence diff --git a/docs/evidence/CURRICULUM_BENCHMARK_REVIEWER.md b/docs/evidence/CURRICULUM_BENCHMARK_REVIEWER.md new file mode 100644 index 00000000..2b06b4db --- /dev/null +++ b/docs/evidence/CURRICULUM_BENCHMARK_REVIEWER.md @@ -0,0 +1,18 @@ +# Benchmark Reviewer Curriculum + +For reviewing benchmark-related changes. + +## Prerequisites +- Complete the Reviewer Curriculum first + +## Skills +- Can interpret AUROC, AUPRC, recall, and precision metrics +- Understands charge-inflation caveat +- Can assess whether a benchmark regression is significant +- Can verify that benchmark gates pass +- Can assess whether a new benchmark has documented caveats + +## Related +- `docs/evidence/METRICS_CURRENT.md` +- `docs/evidence/BENCHMARK_GOVERNANCE.md` +- `docs/evidence/CONCEPT_CARD_BENCHMARK_CAVEAT.md` diff --git a/docs/evidence/CURRICULUM_MAINTAINER.md b/docs/evidence/CURRICULUM_MAINTAINER.md new file mode 100644 index 00000000..16be798d --- /dev/null +++ b/docs/evidence/CURRICULUM_MAINTAINER.md @@ -0,0 +1,20 @@ +# Maintainer Curriculum + +For project maintainers. + +## Prerequisites +- Complete the Reviewer Curriculum + +## Skills +- Can review PRs of any risk class +- Can merge PRs and manage the release process +- Can resolve documentation disputes (see ESCALATION_POLICY.md) +- Can approve new document creation +- Can manage issues and milestones +- Understands the full project architecture +- Can assess whether a change needs design review first + +## Related +- `docs/evidence/DOCS_ROLE_DEFINITIONS.md` +- `docs/evidence/DOCS_ESCALATION_POLICY.md` +- `docs/evidence/DOCS_GOVERNANCE_CHARTER.md` diff --git a/docs/evidence/CURRICULUM_RELEASE_OPERATOR.md b/docs/evidence/CURRICULUM_RELEASE_OPERATOR.md new file mode 100644 index 00000000..d12997af --- /dev/null +++ b/docs/evidence/CURRICULUM_RELEASE_OPERATOR.md @@ -0,0 +1,19 @@ +# Release Operator Curriculum + +For contributors who prepare and execute releases. + +## Prerequisites +- Complete the Reviewer Curriculum + +## Skills +- Can run `make full-reproducibility-report` and interpret the output +- Can run all pre-release checks (doc links, claims, tests) +- Can build the lab batch pack +- Can complete the PUBLICATION_PACK.md checklist +- Understands the release status definitions +- Can create a release tag and publish release notes + +## Related +- `docs/review/RELEASE_DRY_RUN_GUIDE.md` +- `docs/review/RELEASE_DRY_RUN_WALKTHROUGH.md` +- `docs/evidence/CONCEPT_CARD_RELEASE_STATUS.md` diff --git a/docs/evidence/CURRICULUM_REVIEWER.md b/docs/evidence/CURRICULUM_REVIEWER.md new file mode 100644 index 00000000..5e361cd7 --- /dev/null +++ b/docs/evidence/CURRICULUM_REVIEWER.md @@ -0,0 +1,26 @@ +# Reviewer Curriculum + +A staged learning path for code and documentation reviewers. + +## Stage 1: Can review low-risk PRs +- Understand the difference between computational and biological evidence +- Can run `check_claims.py` and identify overclaiming language +- Can run `check_doc_links.py` and fix broken links +- Can verify PRs against the PR review rubric + +## Stage 2: Can review medium-risk PRs +- Understand the benchmark limitations and caveats +- Can assess whether a PR's scope matches its description +- Can verify that tests pass and cover the changed code +- Can assess whether a PR is safe to merge + +## Stage 3: Can review high-risk PRs +- Understand the calibration pipeline and gate +- Can assess safety policy implications +- Can verify that changes are backward-compatible +- Can assess whether a PR needs design review first + +## Related + +- `docs/evidence/PR_REVIEW_RUBRIC.md` +- `docs/evidence/DOCS_ROLE_DEFINITIONS.md` diff --git a/docs/evidence/DOCS_ARCHIVE_INDEX_GUIDE.md b/docs/evidence/DOCS_ARCHIVE_INDEX_GUIDE.md new file mode 100644 index 00000000..3a89b819 --- /dev/null +++ b/docs/evidence/DOCS_ARCHIVE_INDEX_GUIDE.md @@ -0,0 +1,22 @@ +# Docs Archive Index Guide + +When archiving documents, maintain this index. + +## Archive Location +Archived docs go in `docs/archive/` with a date prefix. + +## Index Format +```csv +original_path,archive_path,archived_date,reason,superseded_by +``` + +## Required Information +- Original document path +- Archive path with date +- Date of archiving +- Reason for archiving (deprecated, superseded, obsolete) +- If superseded, the path to the replacement document + +## Search +The archive index should be searchable. Consider adding it to PROJECT_INDEX.md +with an `(archived)` marker. diff --git a/docs/evidence/DOCS_DEPRECATION_NOTICE_TEMPLATE.md b/docs/evidence/DOCS_DEPRECATION_NOTICE_TEMPLATE.md new file mode 100644 index 00000000..b6f642f8 --- /dev/null +++ b/docs/evidence/DOCS_DEPRECATION_NOTICE_TEMPLATE.md @@ -0,0 +1,13 @@ +# Docs Deprecation Notice Template + +Use this template when deprecating a document. + +```markdown +> **DEPRECATED — [Date]** +> +> This document has been deprecated. It is preserved for historical reference +> only and should not be cited or used as a current source of truth. +> +> **Replacement:** [Link to replacement document] +> **Reason:** [Brief explanation of why it was deprecated] +``` diff --git a/docs/evidence/DOCS_IMPROVEMENT_SCORECARD.md b/docs/evidence/DOCS_IMPROVEMENT_SCORECARD.md new file mode 100644 index 00000000..6944c586 --- /dev/null +++ b/docs/evidence/DOCS_IMPROVEMENT_SCORECARD.md @@ -0,0 +1,15 @@ +# Docs Improvement Scorecard + +Score your documentation improvement efforts. + +| Category | Score (0-5) | Notes | +|----------|:-----------:|-------| +| Link health | | 0 = many broken links, 5 = 0 broken | +| Claim safety | | 0 = overclaiming, 5 = clean | +| Freshness | | 0 = all stale, 5 = all current | +| Index coverage | | 0 = not indexed, 5 = fully indexed | +| Onboarding clarity | | 0 = unclear, 5 = 15-min quickstart works | +| Concept card coverage | | 0 = none, 5 = all types covered | +| Runbook coverage | | 0 = none, 5 = all workflows covered | + +**Target:** 30/35 or higher for release readiness. diff --git a/docs/evidence/DOC_MAP_TRUST_LAYER.md b/docs/evidence/DOC_MAP_TRUST_LAYER.md new file mode 100644 index 00000000..1ad37ca5 --- /dev/null +++ b/docs/evidence/DOC_MAP_TRUST_LAYER.md @@ -0,0 +1,11 @@ +# Documentation Map: Trust Layer + +| Document | Purpose | Location | +|----------|---------|----------| +| TRUST_CENTER.md | Trust architecture overview | docs/trust/TRUST_CENTER.md | +| SAFETY.md | Safety policy | SAFETY.md | +| RESPONSIBLE_USE.md | Allowed and forbidden uses | RESPONSIBLE_USE.md | +| DATA_GOVERNANCE.md | Data licensing and policy | docs/trust/DATA_GOVERNANCE.md | +| RELEASE_CHECKLIST.md | Release process | docs/trust/RELEASE_CHECKLIST.md | +| RISK_REGISTER.md | Operational risks | docs/trust/RISK_REGISTER.md | +| SAFETY_DOC_AUDIT.md | Safety doc audit | docs/trust/SAFETY_DOC_AUDIT.md | diff --git a/docs/evidence/LEARNING_PATH_OVERVIEW.md b/docs/evidence/LEARNING_PATH_OVERVIEW.md new file mode 100644 index 00000000..6136f866 --- /dev/null +++ b/docs/evidence/LEARNING_PATH_OVERVIEW.md @@ -0,0 +1,20 @@ +# Learning Path Overview + +The recommended order to learn OpenAMP Foundry. + +``` +1. Read AGENTS.md and CLAUDE.md (30 min) +2. Run `make demo` and explore outputs (30 min) +3. Read LIMITATIONS_OVERVIEW.md (15 min) +4. Read QUICKSTART.md and run through it (15 min) +5. Read CONTRIBUTOR_CURRICULUM.md and pick a task (15 min) +6. Read ARCHITECTURE.md (30 min) +7. Read EVIDENCE_CERTIFICATE.md (15 min) +8. Read BENCHMARK_GOVERNANCE.md (15 min) +9. Read PROOF_LADDER.md (10 min) +10. Choose a learning path: + - Reviewer: CURRICULUM_REVIEWER.md + - Benchmark reviewer: CURRICULUM_BENCHMARK_REVIEWER.md + - Release operator: CURRICULUM_RELEASE_OPERATOR.md + - Agent: CURRICULUM_AGENT.md +``` diff --git a/tests/test_curricula_batch.py b/tests/test_curricula_batch.py new file mode 100644 index 00000000..13f5db43 --- /dev/null +++ b/tests/test_curricula_batch.py @@ -0,0 +1,20 @@ +"""Tests for curricula and governance docs batch.""" +from pathlib import Path + +FILES = [ + "CURRICULUM_REVIEWER.md", + "CURRICULUM_BENCHMARK_REVIEWER.md", + "CURRICULUM_RELEASE_OPERATOR.md", + "CURRICULUM_AGENT.md", + "LEARNING_PATH_OVERVIEW.md", + "CURRICULUM_MAINTAINER.md", + "DOC_MAP_TRUST_LAYER.md", + "DOCS_IMPROVEMENT_SCORECARD.md", + "DOCS_ARCHIVE_INDEX_GUIDE.md", + "DOCS_DEPRECATION_NOTICE_TEMPLATE.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path("docs/evidence", f).exists(), f"Missing: {f}"