diff --git a/docs/evidence/GUIDE_GLOSSARY_LINTER.md b/docs/evidence/GUIDE_GLOSSARY_LINTER.md new file mode 100644 index 00000000..59cfe2b9 --- /dev/null +++ b/docs/evidence/GUIDE_GLOSSARY_LINTER.md @@ -0,0 +1,20 @@ +# Glossary Term Linter + +Checks that glossary terms are used consistently across documentation. + +## How It Works +The linter scans markdown files for project-specific terms and checks +that they match the canonical form defined in the glossary. + +## Terms to Check +| Canonical | Also Seen | Correction | +|-----------|-----------|------------| +| evidence certificate | cert, evidence file | Use "evidence certificate" | +| ensemble score | combined score, total score | Use "ensemble score" | +| simulation mode | sim mode, virtual mode | Use "simulation mode" | +| calibration gate | recalibration gate | Use "calibration gate" | +| pass/fail criteria | acceptance criteria | Use "pass/fail criteria" | + +## Usage +Manual review is currently required. Future automation could use grep +or a custom linter script. diff --git a/docs/evidence/GUIDE_PACKAGE_METADATA_CHECKER.md b/docs/evidence/GUIDE_PACKAGE_METADATA_CHECKER.md new file mode 100644 index 00000000..16172dab --- /dev/null +++ b/docs/evidence/GUIDE_PACKAGE_METADATA_CHECKER.md @@ -0,0 +1,24 @@ +# Package Metadata Completeness Checker + +Verifies that pyproject.toml has all required metadata fields. + +## Required Fields +- `name` +- `version` +- `description` +- `requires-python` +- `license` +- `dependencies` + +## Optional but Recommended +- `readme` +- `authors` +- `classifiers` +- `keywords` +- `urls` + +## Usage +```bash +python scripts/check_pyproject.py +``` +The script checks for missing fields and reports them. diff --git a/docs/evidence/GUIDE_SENSITIVE_FIELD_SCANNER.md b/docs/evidence/GUIDE_SENSITIVE_FIELD_SCANNER.md new file mode 100644 index 00000000..deacc02f --- /dev/null +++ b/docs/evidence/GUIDE_SENSITIVE_FIELD_SCANNER.md @@ -0,0 +1,23 @@ +# Sensitive-Field Scanner for Generated Artifacts + +Scans generated artifacts for potentially sensitive content. + +## What to Scan +- Evidence certificates for PII in notes fields. +- Lab results for unexpected fields. +- Manifests for internal path information. +- Any generated file that will be shared externally. + +## Patterns to Flag +- Email addresses +- IP addresses +- Internal file paths +- API keys or tokens +- Personal names (not in citations) + +## Implementation +The scanner should be a script that reads a JSON or CSV file +and reports any lines that match sensitive patterns. + +## Status +Proposed — not yet implemented. diff --git a/docs/evidence/PROPOSAL_DEVCONTAINER.md b/docs/evidence/PROPOSAL_DEVCONTAINER.md new file mode 100644 index 00000000..be4a7577 --- /dev/null +++ b/docs/evidence/PROPOSAL_DEVCONTAINER.md @@ -0,0 +1,27 @@ +# Dev Container Proposal + +A development container (devcontainer) provides a consistent development +environment. + +## Benefits +- Pre-configured Python environment +- Consistent across macOS, Linux, Windows +- No manual dependency installation +- VS Code integration + +## Proposed Configuration +```json +{ + "name": "OpenAMP Foundry", + "image": "mcr.microsoft.com/devcontainers/python:3.14", + "postCreateCommand": "pip install -e .[dev]", + "customizations": { + "vscode": { + "extensions": ["ms-python.python", "charliermarsh.ruff"] + } + } +} +``` + +## Status +Proposed — not yet implemented. Requires `.devcontainer/devcontainer.json`. diff --git a/docs/evidence/REGISTRY_ACRONYMS.md b/docs/evidence/REGISTRY_ACRONYMS.md new file mode 100644 index 00000000..782f2ac4 --- /dev/null +++ b/docs/evidence/REGISTRY_ACRONYMS.md @@ -0,0 +1,25 @@ +# Acronym Registry + +Standard acronyms used in the project. + +| Acronym | Meaning | +|---------|---------| +| AMP | Antimicrobial Peptide | +| AUROC | Area Under the Receiver Operating Characteristic curve | +| AUPRC | Area Under the Precision-Recall Curve | +| CI | Confidence Interval | +| CLI | Command-Line Interface | +| CRO | Contract Research Organization | +| CSV | Comma-Separated Values | +| HC50 | Half-maximal Hemolytic Concentration | +| JSONL | JSON Lines | +| MIC | Minimum Inhibitory Concentration | +| RBC | Red Blood Cell | +| SHA | Secure Hash Algorithm | +| SPPS | Solid-Phase Peptide Synthesis | +| TI | Therapeutic Index | + +## Rules +- Always expand an acronym on first use in a document. +- Use the canonical form from this registry. +- Add new acronyms to this registry when introduced. diff --git a/docs/evidence/REGISTRY_DEPENDENCY_PIN_RATIONALE.md b/docs/evidence/REGISTRY_DEPENDENCY_PIN_RATIONALE.md new file mode 100644 index 00000000..25e6311c --- /dev/null +++ b/docs/evidence/REGISTRY_DEPENDENCY_PIN_RATIONALE.md @@ -0,0 +1,13 @@ +# Dependency Pin Rationale Registry + +Why specific dependency versions are pinned. + +| Dependency | Pinned Version | Reason | +|------------|:--------------:|--------| +| — | — | No dependencies are currently pinned | + +## Policy +- Pin versions only when necessary (incompatibility, security fix). +- Document the reason for each pin. +- Review pins quarterly and remove if no longer needed. +- Use range constraints (`>=`) rather than exact pins where possible. diff --git a/docs/evidence/REPORT_LICENSE_COMPATIBILITY.md b/docs/evidence/REPORT_LICENSE_COMPATIBILITY.md new file mode 100644 index 00000000..41da301e --- /dev/null +++ b/docs/evidence/REPORT_LICENSE_COMPATIBILITY.md @@ -0,0 +1,17 @@ +# License Compatibility Report + +License compatibility for project dependencies. + +| Dependency | License | Compatible with Apache 2.0? | +|------------|---------|:---------------------------:| +| pytest | MIT | ✅ | +| ruff | MIT | ✅ | +| PyYAML | MIT | ✅ | +| jsonschema | MIT | ✅ | + +## Rules +- Apache 2.0 is compatible with MIT, BSD, and Apache 2.0. +- GPL and AGPL are NOT compatible and must not be used. +- LGPL may be acceptable with review. +- All dependencies must have a documented license. +- If a dependency's license is unknown, do not use it. diff --git a/docs/evidence/REPORT_PACKAGE_INVENTORY.md b/docs/evidence/REPORT_PACKAGE_INVENTORY.md new file mode 100644 index 00000000..62891db3 --- /dev/null +++ b/docs/evidence/REPORT_PACKAGE_INVENTORY.md @@ -0,0 +1,24 @@ +# Package Inventory Report + +Current package metadata summary. + +| Field | Value | +|-------|-------| +| Name | openamp-foundry | +| Version | 0.1.0 | +| Python | >=3.11 | +| License | Apache 2.0 | +| Dependencies | See pyproject.toml | +| Optional deps | dev (pytest, ruff) | + +## How to Check +```bash +pip show openamp-foundry +``` +Or check `pyproject.toml` for the full metadata. + +## What to Verify +- Version number is updated after each release. +- Dependencies are current. +- Optional dependency groups are documented. +- Python version requirement matches CI configuration. diff --git a/docs/evidence/STANDARD_DOC_OWNERSHIP.md b/docs/evidence/STANDARD_DOC_OWNERSHIP.md new file mode 100644 index 00000000..188ff0ba --- /dev/null +++ b/docs/evidence/STANDARD_DOC_OWNERSHIP.md @@ -0,0 +1,25 @@ +# Documentation Ownership Metadata + +Every document should have ownership metadata in its header. + +## Format +```markdown +> **Owner:** @github_username or team name +> **Last reviewed:** YYYY-MM-DD +> **Status:** Draft | Internal | Public-safe +``` + +## Rules +- Every document has exactly one owner. +- The owner is responsible for keeping the document current. +- If the owner changes, update the metadata. +- Documents without an owner are owned by the project lead by default. + +## Current Ownership +| Path | Owner | +|------|-------| +| docs/evidence/ | @maintainer | +| docs/review/ | @maintainer | +| docs/getting-started/ | @maintainer | +| README.md | @project-lead | +| AGENTS.md | @project-lead | diff --git a/docs/evidence/STANDARD_SOURCE_TRUTH_TAGS.md b/docs/evidence/STANDARD_SOURCE_TRUTH_TAGS.md new file mode 100644 index 00000000..1cd6e530 --- /dev/null +++ b/docs/evidence/STANDARD_SOURCE_TRUTH_TAGS.md @@ -0,0 +1,16 @@ +# Docs Source-of-Truth Tags + +Standard tags to mark the authoritative source for a piece of information. + +## Tags +| Tag | Meaning | Example | +|-----|---------|---------| +| `` | Metrics authority | Benchmark values | +| `` | Evidence authority | Certificate schema | +| `` | Agent rules authority | Agent operating principles | + +## Rules +- Every document that contains authoritative information should be tagged. +- Tags are HTML comments in markdown files. +- Tags should reference the single source of truth document. +- If a tag is missing, add it when you find the source of truth. diff --git a/tests/test_batch_369_405.py b/tests/test_batch_369_405.py new file mode 100644 index 00000000..a83c8595 --- /dev/null +++ b/tests/test_batch_369_405.py @@ -0,0 +1,20 @@ +"""Tests for latest batch of 10 docs.""" +from pathlib import Path + +FILES = [ + "STANDARD_SOURCE_TRUTH_TAGS.md", + "STANDARD_DOC_OWNERSHIP.md", + "GUIDE_GLOSSARY_LINTER.md", + "REGISTRY_ACRONYMS.md", + "PROPOSAL_DEVCONTAINER.md", + "REGISTRY_DEPENDENCY_PIN_RATIONALE.md", + "REPORT_PACKAGE_INVENTORY.md", + "REPORT_LICENSE_COMPATIBILITY.md", + "GUIDE_PACKAGE_METADATA_CHECKER.md", + "GUIDE_SENSITIVE_FIELD_SCANNER.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path("docs/evidence", f).exists(), f"Missing: {f}"