From f066ff323e525f46a5c53e1dfeb331b2b7b4bc16 Mon Sep 17 00:00:00 2001 From: OpenCode Date: Wed, 8 Jul 2026 10:01:17 +0700 Subject: [PATCH] Add 10 docs (6 migration guides, 4 concept cards) Closes #617, Closes #618, Closes #619, Closes #620, Closes #621, Closes #622, Closes #623, Closes #624, Closes #625, Closes #626 --- .../evidence/CONCEPT_CARD_CALIBRATION_GATE.md | 23 ++++++++++++++++ docs/evidence/CONCEPT_CARD_OFFLINE_MODE.md | 21 +++++++++++++++ docs/evidence/CONCEPT_CARD_REDACTION.md | 21 +++++++++++++++ docs/evidence/CONCEPT_CARD_REVIEW_PACKET.md | 22 ++++++++++++++++ .../evidence/MIGRATION_GUIDE_ARTIFACT_DOCS.md | 8 ++++++ .../MIGRATION_GUIDE_BENCHMARK_DOCS.md | 9 +++++++ .../MIGRATION_GUIDE_DEPRECATED_DOCS.md | 9 +++++++ .../MIGRATION_GUIDE_README_TO_DOCS.md | 9 +++++++ docs/evidence/MIGRATION_GUIDE_SCHEMA_DOCS.md | 8 ++++++ .../evidence/MIGRATION_GUIDE_TUTORIAL_DOCS.md | 9 +++++++ tests/test_batch_10_v2.py | 26 +++++++++++++++++++ 11 files changed, 165 insertions(+) create mode 100644 docs/evidence/CONCEPT_CARD_CALIBRATION_GATE.md create mode 100644 docs/evidence/CONCEPT_CARD_OFFLINE_MODE.md create mode 100644 docs/evidence/CONCEPT_CARD_REDACTION.md create mode 100644 docs/evidence/CONCEPT_CARD_REVIEW_PACKET.md create mode 100644 docs/evidence/MIGRATION_GUIDE_ARTIFACT_DOCS.md create mode 100644 docs/evidence/MIGRATION_GUIDE_BENCHMARK_DOCS.md create mode 100644 docs/evidence/MIGRATION_GUIDE_DEPRECATED_DOCS.md create mode 100644 docs/evidence/MIGRATION_GUIDE_README_TO_DOCS.md create mode 100644 docs/evidence/MIGRATION_GUIDE_SCHEMA_DOCS.md create mode 100644 docs/evidence/MIGRATION_GUIDE_TUTORIAL_DOCS.md create mode 100644 tests/test_batch_10_v2.py diff --git a/docs/evidence/CONCEPT_CARD_CALIBRATION_GATE.md b/docs/evidence/CONCEPT_CARD_CALIBRATION_GATE.md new file mode 100644 index 00000000..b4bc843c --- /dev/null +++ b/docs/evidence/CONCEPT_CARD_CALIBRATION_GATE.md @@ -0,0 +1,23 @@ +# Calibration Gate — Concept Card + +The calibration gate is a safety mechanism that prevents weight updates +unless pre-registered conditions are met. + +## How It Works + +1. Lab results feed into `calibration-intake`. +2. The intake report is evaluated against `configs/recalibration_policy.yaml`. +3. The gate emits a binary verdict: `may_recalibrate` or not. +4. If blocked, no weight updates are allowed — regardless of what the data shows. + +## Key Rules + +- Exit code 0 = gate allows recalibration. +- Exit code 3 = gate rejects recalibration. +- The gate cannot be bypassed. +- Human review is required before any weight update, even if the gate passes. + +## Related + +- `docs/evidence/CALIBRATION_POLICY.md` — full policy +- `configs/recalibration_policy.yaml` — gate configuration diff --git a/docs/evidence/CONCEPT_CARD_OFFLINE_MODE.md b/docs/evidence/CONCEPT_CARD_OFFLINE_MODE.md new file mode 100644 index 00000000..41f44c15 --- /dev/null +++ b/docs/evidence/CONCEPT_CARD_OFFLINE_MODE.md @@ -0,0 +1,21 @@ +# Offline Mode — Concept Card + +Offline mode means running checks and validations without network access. + +## Which Tools Support Offline Mode + +| Tool | Offline? | Notes | +|------|:--------:|-------| +| `check_doc_links.py` | Yes | No network calls | +| `check_claims.py` | Yes | Local pattern matching | +| `check_pyproject.py` | Yes | Local file checks | +| `validate_negative_archive.py` | Yes | Local CSV validation | +| `validate_panel_csv.py` | Yes | Local CSV validation | +| `check_wave1_pass_fail.py` | Yes | Local JSON validation | +| `detect_unused_scripts.py` | Yes | Local file scanning | + +## Rules + +- All local checks must work without network access. +- Any tool requiring network access must document this requirement. +- CI runs with network access; local development should not require it. diff --git a/docs/evidence/CONCEPT_CARD_REDACTION.md b/docs/evidence/CONCEPT_CARD_REDACTION.md new file mode 100644 index 00000000..f918f384 --- /dev/null +++ b/docs/evidence/CONCEPT_CARD_REDACTION.md @@ -0,0 +1,21 @@ +# Redaction — Concept Card + +Redaction removes sensitive information from documents before public sharing. + +## What May Need Redaction + +- Full peptide sequences for dual-use candidates +- Specific assay protocols from partner CROs +- Personally identifiable information +- Unpublished candidate lists before review + +## Rules + +- Redacted content should be replaced with `[REDACTED]` or a summary. +- The fact that redaction occurred should be noted. +- Redaction must not hide negative results or safety issues. +- The original unredacted version must be preserved in a restricted location. + +## Related + +- `docs/trust/DATA_GOVERNANCE.md` — data handling policies diff --git a/docs/evidence/CONCEPT_CARD_REVIEW_PACKET.md b/docs/evidence/CONCEPT_CARD_REVIEW_PACKET.md new file mode 100644 index 00000000..845ba802 --- /dev/null +++ b/docs/evidence/CONCEPT_CARD_REVIEW_PACKET.md @@ -0,0 +1,22 @@ +# Review Packet — Concept Card + +A review packet is the set of documents a reviewer needs to evaluate a claim. + +## Required Contents + +- Candidate list with scores (CSV or JSONL) +- Evidence certificates for selected candidates +- LIMITATIONS_OVERVIEW.md for honest caveats +- METRICS_CURRENT.md for benchmark context +- The specific claim or question being reviewed + +## Optional Contents + +- Simulation scores (if `--simulation-mode info` was used) +- Expert review template (`.github/ISSUE_TEMPLATE/expert_review.yml`) + +## Rules + +- Review packets must not overclaim. +- Review packets must state what evidence is computational vs biological. +- Reviewers must be told this is a dry-lab nomination only. diff --git a/docs/evidence/MIGRATION_GUIDE_ARTIFACT_DOCS.md b/docs/evidence/MIGRATION_GUIDE_ARTIFACT_DOCS.md new file mode 100644 index 00000000..d7ce4926 --- /dev/null +++ b/docs/evidence/MIGRATION_GUIDE_ARTIFACT_DOCS.md @@ -0,0 +1,8 @@ +# Migration Guide: Artifact Docs + +When a new artifact is added to the pipeline: + +1. Add an entry in `docs/evidence/ARTIFACT_MAP.md`. +2. If the artifact has a schema, add it to `schemas/`. +3. Add a concept card if the artifact type is new. +4. Update the reproducibility report script if needed. diff --git a/docs/evidence/MIGRATION_GUIDE_BENCHMARK_DOCS.md b/docs/evidence/MIGRATION_GUIDE_BENCHMARK_DOCS.md new file mode 100644 index 00000000..eb0d78cd --- /dev/null +++ b/docs/evidence/MIGRATION_GUIDE_BENCHMARK_DOCS.md @@ -0,0 +1,9 @@ +# Migration Guide: Benchmark Docs + +When a benchmark changes or a new benchmark is added: + +1. Update `docs/evidence/BENCHMARKING.md` with the new benchmark entry. +2. Update `docs/evidence/METRICS_CURRENT.md` with new results. +3. Add a Makefile target for the benchmark if needed. +4. Run the benchmark to verify it works. +5. Update the phony list in the Makefile if needed. diff --git a/docs/evidence/MIGRATION_GUIDE_DEPRECATED_DOCS.md b/docs/evidence/MIGRATION_GUIDE_DEPRECATED_DOCS.md new file mode 100644 index 00000000..7468cd7d --- /dev/null +++ b/docs/evidence/MIGRATION_GUIDE_DEPRECATED_DOCS.md @@ -0,0 +1,9 @@ +# Migration Guide: Deprecated Docs + +When a document is deprecated: + +1. Add a deprecation notice at the top of the document. +2. Update PROJECT_INDEX.md to mark the document as deprecated. +3. Update cross-references to point to the replacement. +4. After one review cycle, archive the document. +5. After two review cycles, delete the document (per retirement policy). diff --git a/docs/evidence/MIGRATION_GUIDE_README_TO_DOCS.md b/docs/evidence/MIGRATION_GUIDE_README_TO_DOCS.md new file mode 100644 index 00000000..c9e066d6 --- /dev/null +++ b/docs/evidence/MIGRATION_GUIDE_README_TO_DOCS.md @@ -0,0 +1,9 @@ +# Migration Guide: README to Docs + +When moving content from README.md to docs/: + +1. Create the new doc in the appropriate subdirectory. +2. Link to the new doc from README.md. +3. Update any cross-references that pointed to the old location. +4. Run `python scripts/check_doc_links.py` to verify links. +5. Do not delete README.md — keep it as a navigation hub. diff --git a/docs/evidence/MIGRATION_GUIDE_SCHEMA_DOCS.md b/docs/evidence/MIGRATION_GUIDE_SCHEMA_DOCS.md new file mode 100644 index 00000000..f55a0e86 --- /dev/null +++ b/docs/evidence/MIGRATION_GUIDE_SCHEMA_DOCS.md @@ -0,0 +1,8 @@ +# Migration Guide: Schema Docs + +When a schema changes or a new schema is added: + +1. Update `schemas/` with the new or changed schema file. +2. Update `docs/engineering/SCHEMA_REGISTRY.md`. +3. Update any docs that reference the old schema path. +4. Run validation tests to confirm the schema is valid. diff --git a/docs/evidence/MIGRATION_GUIDE_TUTORIAL_DOCS.md b/docs/evidence/MIGRATION_GUIDE_TUTORIAL_DOCS.md new file mode 100644 index 00000000..814709cf --- /dev/null +++ b/docs/evidence/MIGRATION_GUIDE_TUTORIAL_DOCS.md @@ -0,0 +1,9 @@ +# Migration Guide: Tutorial Docs + +When updating tutorials or adding new ones: + +1. Verify all commands in the tutorial still work. +2. Update any CLI examples that changed. +3. Verify the tutorial output matches current pipeline behavior. +4. Run `make demo` to confirm the demo still works. +5. Update the tutorial's estimated completion time if it changed. diff --git a/tests/test_batch_10_v2.py b/tests/test_batch_10_v2.py new file mode 100644 index 00000000..826b4e20 --- /dev/null +++ b/tests/test_batch_10_v2.py @@ -0,0 +1,26 @@ +"""Tests for batch of 10 docs.""" +from pathlib import Path + +FILES = [ + "MIGRATION_GUIDE_README_TO_DOCS.md", + "MIGRATION_GUIDE_SCHEMA_DOCS.md", + "MIGRATION_GUIDE_BENCHMARK_DOCS.md", + "MIGRATION_GUIDE_ARTIFACT_DOCS.md", + "MIGRATION_GUIDE_TUTORIAL_DOCS.md", + "MIGRATION_GUIDE_DEPRECATED_DOCS.md", + "CONCEPT_CARD_CALIBRATION_GATE.md", + "CONCEPT_CARD_REVIEW_PACKET.md", + "CONCEPT_CARD_REDACTION.md", + "CONCEPT_CARD_OFFLINE_MODE.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path(f"docs/evidence/{f}").exists(), f"Missing: {f}" + + +def test_each_has_content(): + for f in FILES: + text = Path(f"docs/evidence/{f}").read_text() + assert len(text) > 50, f"{f} too short"