From 3a524aa6b7ade491a814cbe633d4c664bf3b0df2 Mon Sep 17 00:00:00 2001 From: OpenCode Date: Wed, 8 Jul 2026 12:36:36 +0700 Subject: [PATCH] Add 10 doc maps and learning resources Closes #577, Closes #579, Closes #582, Closes #583, Closes #584, Closes #585, Closes #586, Closes #587, Closes #588, Closes #590 --- docs/evidence/DOC_MAP_BENCHMARK.md | 9 +++++++++ docs/evidence/DOC_MAP_COMMAND.md | 8 ++++++++ docs/evidence/DOC_MAP_FILE_OWNERSHIP.md | 13 +++++++++++++ docs/evidence/DOC_MAP_ISSUE_TAXONOMY.md | 9 +++++++++ docs/evidence/DOC_MAP_RELEASE.md | 9 +++++++++ docs/evidence/DOC_MAP_REVIEW.md | 9 +++++++++ docs/evidence/DOC_MAP_ROADMAP.md | 8 ++++++++ docs/evidence/DOC_MAP_SOURCE_OF_TRUTH.md | 13 +++++++++++++ docs/evidence/GLOSSARY_LEARNING_SEQUENCE.md | 12 ++++++++++++ docs/evidence/READER_SELF_ASSESSMENT.md | 21 +++++++++++++++++++++ tests/test_doc_maps.py | 20 ++++++++++++++++++++ 11 files changed, 131 insertions(+) create mode 100644 docs/evidence/DOC_MAP_BENCHMARK.md create mode 100644 docs/evidence/DOC_MAP_COMMAND.md create mode 100644 docs/evidence/DOC_MAP_FILE_OWNERSHIP.md create mode 100644 docs/evidence/DOC_MAP_ISSUE_TAXONOMY.md create mode 100644 docs/evidence/DOC_MAP_RELEASE.md create mode 100644 docs/evidence/DOC_MAP_REVIEW.md create mode 100644 docs/evidence/DOC_MAP_ROADMAP.md create mode 100644 docs/evidence/DOC_MAP_SOURCE_OF_TRUTH.md create mode 100644 docs/evidence/GLOSSARY_LEARNING_SEQUENCE.md create mode 100644 docs/evidence/READER_SELF_ASSESSMENT.md create mode 100644 tests/test_doc_maps.py diff --git a/docs/evidence/DOC_MAP_BENCHMARK.md b/docs/evidence/DOC_MAP_BENCHMARK.md new file mode 100644 index 00000000..4ffe1b8f --- /dev/null +++ b/docs/evidence/DOC_MAP_BENCHMARK.md @@ -0,0 +1,9 @@ +# Documentation Map: Benchmark Docs + +| Document | Purpose | Location | +|----------|---------|----------| +| BENCHMARKING.md | Benchmark plan and targets | docs/evidence/BENCHMARKING.md | +| METRICS_CURRENT.md | Current benchmark results | docs/evidence/METRICS_CURRENT.md | +| BENCHMARK_GOVERNANCE.md | Benchmark policies | docs/evidence/BENCHMARK_GOVERNANCE.md | +| SIMULATION_BENCHMARK.md | Simulation module evaluation | docs/evidence/SIMULATION_BENCHMARK.md | +| Concept card: benchmark caveat | Benchmark limitations | docs/evidence/CONCEPT_CARD_BENCHMARK_CAVEAT.md | diff --git a/docs/evidence/DOC_MAP_COMMAND.md b/docs/evidence/DOC_MAP_COMMAND.md new file mode 100644 index 00000000..0af34a1f --- /dev/null +++ b/docs/evidence/DOC_MAP_COMMAND.md @@ -0,0 +1,8 @@ +# Documentation Map: Command Docs + +| Document | Purpose | Location | +|----------|---------|----------| +| COMMAND_SURFACE.md | CLI command reference | docs/getting-started/COMMAND_SURFACE.md | +| QUICKSTART.md | Quickstart guide | docs/getting-started/QUICKSTART.md | +| CLADUE.md | Agent guidance | CLAUDE.md | +| Exit code registry | Exit code meanings | configs/exit_code_registry.json | diff --git a/docs/evidence/DOC_MAP_FILE_OWNERSHIP.md b/docs/evidence/DOC_MAP_FILE_OWNERSHIP.md new file mode 100644 index 00000000..8f824692 --- /dev/null +++ b/docs/evidence/DOC_MAP_FILE_OWNERSHIP.md @@ -0,0 +1,13 @@ +# Documentation Map: File Ownership + +| Path | Owner | Review Required | +|------|-------|:---------------:| +| src/openamp_foundry/ | Maintainer | Yes | +| tests/ | Maintainer | Yes | +| docs/ | Maintainer | For new docs | +| configs/ | Maintainer | Yes | +| schemas/ | Maintainer | Yes | +| scripts/ | Maintainer | For new scripts | +| Makefile | Maintainer | Yes | +| README.md | Project lead | Yes | +| AGENTS.md | Project lead | Yes | diff --git a/docs/evidence/DOC_MAP_ISSUE_TAXONOMY.md b/docs/evidence/DOC_MAP_ISSUE_TAXONOMY.md new file mode 100644 index 00000000..7a2a4728 --- /dev/null +++ b/docs/evidence/DOC_MAP_ISSUE_TAXONOMY.md @@ -0,0 +1,9 @@ +# Documentation Map: Issue Taxonomy + +| Label Category | Labels | Purpose | +|---------------|--------|---------| +| Type | bug, enhancement, docs, test | What kind of change | +| Area | safety, benchmark, calibration | Which part of the project | +| Priority | P0, P1, P2, P3 | Urgency | +| Status | good-first-issue, help-wanted | Contributor targeting | +| Process | urgent, needs-design, blocked | Workflow state | diff --git a/docs/evidence/DOC_MAP_RELEASE.md b/docs/evidence/DOC_MAP_RELEASE.md new file mode 100644 index 00000000..4145b433 --- /dev/null +++ b/docs/evidence/DOC_MAP_RELEASE.md @@ -0,0 +1,9 @@ +# Documentation Map: Release Docs + +| Document | Purpose | Location | +|----------|---------|----------| +| PUBLICATION_PACK.md | Release checklist | docs/review/PUBLICATION_PACK.md | +| RELEASE_DRY_RUN_GUIDE.md | Dry-run reading guide | docs/review/RELEASE_DRY_RUN_GUIDE.md | +| RELEASE_DRY_RUN_WALKTHROUGH.md | Dry-run walkthrough | docs/review/RELEASE_DRY_RUN_WALKTHROUGH.md | +| RELEASE_CHECKLIST.md | Release process | docs/trust/RELEASE_CHECKLIST.md | +| METRICS_CURRENT.md | Current metrics | docs/evidence/METRICS_CURRENT.md | diff --git a/docs/evidence/DOC_MAP_REVIEW.md b/docs/evidence/DOC_MAP_REVIEW.md new file mode 100644 index 00000000..d180795d --- /dev/null +++ b/docs/evidence/DOC_MAP_REVIEW.md @@ -0,0 +1,9 @@ +# Documentation Map: Review Docs + +| Document | Purpose | Location | +|----------|---------|----------| +| EXPERT_REVIEW_PACK.md | Review packet contents | docs/review/EXPERT_REVIEW_PACK.md | +| LAB_PARTNER_ONBOARDING.md | CRO onboarding | docs/review/LAB_PARTNER_ONBOARDING.md | +| RELEASE_DRY_RUN_GUIDE.md | Dry-run interpretation | docs/review/RELEASE_DRY_RUN_GUIDE.md | +| PUBLICATION_PACK.md | Publication preparation | docs/review/PUBLICATION_PACK.md | +| WET_LAB_HANDOFF.md | Wet-lab procedures | docs/review/WET_LAB_HANDOFF.md | diff --git a/docs/evidence/DOC_MAP_ROADMAP.md b/docs/evidence/DOC_MAP_ROADMAP.md new file mode 100644 index 00000000..2ced5d8b --- /dev/null +++ b/docs/evidence/DOC_MAP_ROADMAP.md @@ -0,0 +1,8 @@ +# Documentation Map: Roadmap Docs + +| Document | Purpose | Location | +|----------|---------|----------| +| ROADMAP.md | Shipped milestones and next horizons | docs/research/ROADMAP.md | +| 50_LOOP_PLAN.md | 50-loop execution plan | docs/50_LOOP_PLAN.md | +| NEXT_100_PR_MAP.md | Sequenced infrastructure backlog | docs/research/NEXT_100_PR_MAP.md | +| WAVE2_PLAN.md | Wave 2 planning | docs/research/WAVE2_PLAN.md | diff --git a/docs/evidence/DOC_MAP_SOURCE_OF_TRUTH.md b/docs/evidence/DOC_MAP_SOURCE_OF_TRUTH.md new file mode 100644 index 00000000..fdfcdd91 --- /dev/null +++ b/docs/evidence/DOC_MAP_SOURCE_OF_TRUTH.md @@ -0,0 +1,13 @@ +# Documentation Map: Source of Truth + +Defines which document is authoritative for each topic. + +| Topic | Source of Truth | Backup/Reference | +|-------|----------------|-----------------| +| Pipeline metrics | `docs/evidence/METRICS_CURRENT.md` | Benchmark outputs | +| Evidence schema | `schemas/candidate.schema.json` | `docs/evidence/EVIDENCE_CERTIFICATE.md` | +| Lab result schema | `schemas/lab_result.schema.json` | `docs/review/WET_LAB_HANDOFF.md` | +| Benchmark governance | `docs/evidence/BENCHMARK_GOVERNANCE.md` | `docs/evidence/BENCHMARKING.md` | +| Calibration policy | `configs/recalibration_policy.yaml` | `docs/evidence/CALIBRATION_POLICY.md` | +| Safety policy | `SAFETY.md` | `RESPONSIBLE_USE.md` | +| Agent contract | `AGENTS.md` | `AGENT_TASKS.json` | diff --git a/docs/evidence/GLOSSARY_LEARNING_SEQUENCE.md b/docs/evidence/GLOSSARY_LEARNING_SEQUENCE.md new file mode 100644 index 00000000..a9a69c77 --- /dev/null +++ b/docs/evidence/GLOSSARY_LEARNING_SEQUENCE.md @@ -0,0 +1,12 @@ +# Glossary Learning Sequence + +Recommended order to learn project terminology. + +1. **Evidence** — what constitutes proof at different levels (PROOF_LADDER.md) +2. **Artifact** — any generated file that carries evidence (ARTIFACT_MAP.md) +3. **Schema** — machine-readable definition of an artifact's structure +4. **Manifest** — record of inputs, configs, and outputs for a run +5. **Gate** — a safety mechanism that blocks or allows an action +6. **Abstention** — when a module declines to make a prediction due to uncertainty +7. **Baseline** — a simple heuristic that any new method must beat +8. **Calibration** — adjusting model outputs based on real data diff --git a/docs/evidence/READER_SELF_ASSESSMENT.md b/docs/evidence/READER_SELF_ASSESSMENT.md new file mode 100644 index 00000000..84ab300b --- /dev/null +++ b/docs/evidence/READER_SELF_ASSESSMENT.md @@ -0,0 +1,21 @@ +# Reader Self-Assessment Checklist + +Use this checklist to assess your understanding of the project documentation. + +## Level 1: Can run the pipeline +- [ ] I can run `make demo` and understand the output +- [ ] I can find evidence certificates in `outputs/evidence/` +- [ ] I know what `charge_bias` means +- [ ] I understand that scores are computational, not biological proof + +## Level 2: Can contribute +- [ ] I know how to find the right document from PROJECT_INDEX.md +- [ ] I can run docs checks locally +- [ ] I understand the contribution workflow from CONTRIBUTING.md +- [ ] I know how to create a PR referencing an issue + +## Level 3: Can review +- [ ] I can assess a PR for overclaiming language +- [ ] I understand the benchmark limitations +- [ ] I know where to find the current metrics +- [ ] I understand the simulation module status diff --git a/tests/test_doc_maps.py b/tests/test_doc_maps.py new file mode 100644 index 00000000..1a37f98b --- /dev/null +++ b/tests/test_doc_maps.py @@ -0,0 +1,20 @@ +"""Tests for 10 doc maps batch.""" +from pathlib import Path + +FILES = [ + "DOC_MAP_BENCHMARK.md", + "DOC_MAP_REVIEW.md", + "DOC_MAP_RELEASE.md", + "DOC_MAP_COMMAND.md", + "DOC_MAP_ISSUE_TAXONOMY.md", + "DOC_MAP_ROADMAP.md", + "DOC_MAP_FILE_OWNERSHIP.md", + "DOC_MAP_SOURCE_OF_TRUTH.md", + "GLOSSARY_LEARNING_SEQUENCE.md", + "READER_SELF_ASSESSMENT.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path("docs/evidence", f).exists(), f"Missing: {f}"