diff --git a/docs/evidence/GUIDE_ARCHIVE_DEPRECATION.md b/docs/evidence/GUIDE_ARCHIVE_DEPRECATION.md new file mode 100644 index 00000000..1fc21a49 --- /dev/null +++ b/docs/evidence/GUIDE_ARCHIVE_DEPRECATION.md @@ -0,0 +1,20 @@ +# Archive and Deprecation Guide + +How to archive and deprecate documents or features. + +## Deprecation Process +1. Add a deprecation notice to the document or feature. +2. Update references to point to the replacement. +3. Announce the deprecation in the decision log. +4. After one review cycle, archive the document. + +## Archive Process +1. Move the document to `docs/archive/` with a date prefix. +2. Update PROJECT_INDEX.md to mark it as archived. +3. Remove or redirect cross-references. +4. Add the archive entry to the archive index. + +## What NOT to Archive +- Decision logs +- Evidence documents with historical benchmark results +- Documents referenced by external publications diff --git a/docs/evidence/GUIDE_PUBLIC_READINESS.md b/docs/evidence/GUIDE_PUBLIC_READINESS.md new file mode 100644 index 00000000..b183505f --- /dev/null +++ b/docs/evidence/GUIDE_PUBLIC_READINESS.md @@ -0,0 +1,19 @@ +# Public Readiness Guide + +How to determine if the project is ready for public sharing. + +## Checks +- [ ] Release readiness checks pass +- [ ] Claim wording is safe (`check_claims.py`) +- [ ] LIMITATIONS_OVERVIEW.md is accurate +- [ ] PUBLICATION_PACK.md checklist is complete +- [ ] README.md is up to date +- [ ] CITATION.cff is up to date + +## Levels of Public Readiness +| Level | Meaning | Share With | +|-------|---------|-----------| +| Internal | Project team only | Team members | +| Review-only | Ready for expert review | External reviewers | +| Public-safe | Ready for public | Anyone | +| Release | Ready for publication | General public | diff --git a/docs/evidence/GUIDE_PUBLIC_SUMMARY_WRITING.md b/docs/evidence/GUIDE_PUBLIC_SUMMARY_WRITING.md new file mode 100644 index 00000000..2dd7a536 --- /dev/null +++ b/docs/evidence/GUIDE_PUBLIC_SUMMARY_WRITING.md @@ -0,0 +1,22 @@ +# Public Summary Writing Guide + +How to write summaries for public audiences. + +## Structure +1. **What was done** — one sentence +2. **Key finding** — one sentence +3. **Limitations** — what the result does NOT prove +4. **Next steps** — what comes next + +## Rules +- Use plain language, avoid jargon +- State limitations as prominently as findings +- Never claim biological proof without wet-lab data +- Use the project's allowed claim language +- Run `check_claims.py` before publishing + +## Example +> "We computationally nominated 24 antimicrobial peptide candidates +> using an open, reproducible pipeline. These are predictions only — +> no antimicrobial activity has been demonstrated. Wet-lab validation +> is required before any biological claim can be made." diff --git a/docs/evidence/GUIDE_REDACTION_POLICY.md b/docs/evidence/GUIDE_REDACTION_POLICY.md new file mode 100644 index 00000000..104f0abb --- /dev/null +++ b/docs/evidence/GUIDE_REDACTION_POLICY.md @@ -0,0 +1,21 @@ +# Redaction Policy Guide + +When and how to redact content 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 expert review + +## Rules +- Redacted content should be replaced with `[REDACTED]`. +- Note that redaction occurred and why. +- Redaction must not hide negative results or safety issues. +- Original unredacted versions must be preserved in a restricted location. + +## What NOT to Redact +- Benchmark results (even negative ones) +- Known limitations +- Safety warnings +- Methodology descriptions diff --git a/docs/evidence/GUIDE_RELEASE_BLOCKER_TAXONOMY.md b/docs/evidence/GUIDE_RELEASE_BLOCKER_TAXONOMY.md new file mode 100644 index 00000000..8ff2880b --- /dev/null +++ b/docs/evidence/GUIDE_RELEASE_BLOCKER_TAXONOMY.md @@ -0,0 +1,18 @@ +# Release Blocker Taxonomy + +Types of issues that can block a release. + +| Blocker Type | Description | Resolution | +|-------------|-------------|-----------| +| Safety | Overclaiming language, safety policy error | Fix before release | +| Quality | Failing tests, broken links, benchmark regression | Fix before release | +| Completeness | Missing artifact or documentation | Complete before release | +| Process | Review not completed, decision not logged | Complete before release | +| Dependency | External dependency is broken or unavailable | Wait or work around | + +## Decision Rules +- Any Safety blocker → do not release +- Any Quality blocker → do not release +- Completeness blockers → evaluate impact; minor gaps can be deferred +- Process blockers → complete before release +- Dependency blockers → evaluate urgency; may block or delay diff --git a/docs/evidence/GUIDE_RELEASE_NOTES_WRITING.md b/docs/evidence/GUIDE_RELEASE_NOTES_WRITING.md new file mode 100644 index 00000000..8e4a64e7 --- /dev/null +++ b/docs/evidence/GUIDE_RELEASE_NOTES_WRITING.md @@ -0,0 +1,32 @@ +# Release Notes Writing Guide + +How to write release notes. + +## Structure +``` +## v0.5.N — Title + +Summary of the release in 1-2 sentences. + +### Added +- New feature or document + +### Changed +- Existing feature or document update + +### Fixed +- Bug fix + +### Deprecated +- Feature or document no longer recommended + +### Removed +- Feature or document removed +``` + +## Rules +- Use the change note format (file path + description). +- Group changes by type (Added, Changed, Fixed). +- Include a summary sentence at the top. +- Link to relevant issues or PRs. +- Avoid overclaiming language. diff --git a/docs/evidence/GUIDE_RELEASE_READINESS_OVERVIEW.md b/docs/evidence/GUIDE_RELEASE_READINESS_OVERVIEW.md new file mode 100644 index 00000000..27a35e8e --- /dev/null +++ b/docs/evidence/GUIDE_RELEASE_READINESS_OVERVIEW.md @@ -0,0 +1,18 @@ +# Release Readiness Overview + +Checklist and process for determining release readiness. + +## Pre-Release Checks +- [ ] All tests pass (`python3 -m pytest -q`) +- [ ] 0 broken doc links (`python scripts/check_doc_links.py`) +- [ ] 0 overclaiming phrases (`python scripts/safety/check_claims.py`) +- [ ] Full reproducibility report succeeds (`make full-reproducibility-report`) +- [ ] METRICS_CURRENT.md is up to date +- [ ] Documentation readiness checklist is complete + +## Decision +| Result | Action | +|--------|--------| +| All checks pass | Proceed to release candidate | +| Minor issues | Fix before release | +| Major issues | Block release, fix first | diff --git a/docs/evidence/GUIDE_RELEASE_STATUS_VOCAB.md b/docs/evidence/GUIDE_RELEASE_STATUS_VOCAB.md new file mode 100644 index 00000000..8bea6295 --- /dev/null +++ b/docs/evidence/GUIDE_RELEASE_STATUS_VOCAB.md @@ -0,0 +1,13 @@ +# Release Status Vocabulary + +Standard terms for release statuses. + +| Status | Meaning | Can be cited? | +|--------|---------|:-------------:| +| Draft | Work in progress | No | +| Internal | Project team reviewed | With caveats | +| Review-only | Shared with reviewers | In review context | +| Public-safe | Safe for public sharing | Yes, with limitations | +| Restricted | Sensitive content | No | +| Archived | Superseded | As historical reference | +| Deprecated | No longer maintained | Do not cite | diff --git a/docs/evidence/GUIDE_REVIEWER_CONFLICT.md b/docs/evidence/GUIDE_REVIEWER_CONFLICT.md new file mode 100644 index 00000000..d1655e8e --- /dev/null +++ b/docs/evidence/GUIDE_REVIEWER_CONFLICT.md @@ -0,0 +1,14 @@ +# Reviewer Conflict-of-Interest Note + +Reviewers should declare any conflict of interest before reviewing. + +## Examples of Conflicts +- You authored the PR being reviewed +- You have a personal relationship with the author +- You have a financial interest in the outcome +- You are competing with the project in the same space + +## Process +1. Declare the conflict in the PR comments. +2. If the conflict is significant, recuse yourself and request a different reviewer. +3. If the conflict is minor, document it and proceed with review. diff --git a/docs/evidence/GUIDE_REVIEW_ESCALATION.md b/docs/evidence/GUIDE_REVIEW_ESCALATION.md new file mode 100644 index 00000000..e60dcde6 --- /dev/null +++ b/docs/evidence/GUIDE_REVIEW_ESCALATION.md @@ -0,0 +1,17 @@ +# Review Escalation Guide + +When a review is stuck or contested. + +## Escalation Levels +| Level | Who | When | +|-------|-----|------| +| 1 | PR author and reviewer | Initial disagreement | +| 2 | Additional reviewer | 2 reviewers disagree | +| 3 | Maintainer | Review blocked for > 48h | +| 4 | Project lead | Policy or safety disagreement | + +## Process +1. Document the disagreement in PR comments. +2. Attempt resolution at the current level. +3. Escalate only after good-faith attempts fail. +4. Higher-level decisions are final. diff --git a/tests/test_release_review_batch.py b/tests/test_release_review_batch.py new file mode 100644 index 00000000..ecb6ae4f --- /dev/null +++ b/tests/test_release_review_batch.py @@ -0,0 +1,20 @@ +"""Tests for release and review guides batch.""" +from pathlib import Path + +FILES = [ + "GUIDE_REVIEWER_CONFLICT.md", + "GUIDE_REVIEW_ESCALATION.md", + "GUIDE_RELEASE_READINESS_OVERVIEW.md", + "GUIDE_PUBLIC_READINESS.md", + "GUIDE_RELEASE_STATUS_VOCAB.md", + "GUIDE_REDACTION_POLICY.md", + "GUIDE_PUBLIC_SUMMARY_WRITING.md", + "GUIDE_RELEASE_NOTES_WRITING.md", + "GUIDE_RELEASE_BLOCKER_TAXONOMY.md", + "GUIDE_ARCHIVE_DEPRECATION.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path("docs/evidence", f).exists(), f"Missing: {f}"