Add 10 documentation standards and policies

docs/evidence/CHECKLIST_ACCESSIBILITY.md

@@ -0,0 +1,9 @@
+# Accessibility Checklist for Docs
+
+- [ ] Headings use proper hierarchy (h1, h2, h3, not bold text)
+- [ ] Links have descriptive text (not "click here")
+- [ ] Tables have header rows
+- [ ] Code blocks have language tags
+- [ ] Color is not the only way to convey information
+- [ ] Images have alt text
+- [ ] Documents use plain language where possible

docs/evidence/CHECKLIST_CLEAR_LANGUAGE.md

@@ -0,0 +1,10 @@
+# Clear-Language Review Checklist
+
+- [ ] Avoid jargon where plain language works
+- [ ] Define acronyms on first use
+- [ ] Use active voice ("the pipeline scores candidates" not "candidates are scored")
+- [ ] Keep sentences under 25 words where possible
+- [ ] Use bullet points for lists of 3+ items
+- [ ] Use numbered steps for procedures
+- [ ] Avoid "easily," "simply," "obviously" — these hide complexity
+- [ ] Run `check_claims.py` to catch overclaiming language

docs/evidence/POLICY_MANUAL_EDIT_ARTIFACTS.md

@@ -0,0 +1,20 @@
+# Manual-Edit Policy for Artifacts
+
+Some artifacts are generated by the pipeline and should not be edited manually.
+
+## Do Not Edit
+- Schema files in `schemas/` — edit the source code that produces them
+- Generated documentation — edit the source doc, not the generated copy
+- Benchmark output files in `outputs/` — regenerate with `make bench-*`
+- Evidence certificates — re-run the ranking pipeline
+
+## May Edit
+- Configuration files in `configs/` (with review)
+- Documentation in `docs/` (with review for new docs)
+- Test files in `tests/` (with review)
+- Scripts in `scripts/` (with review)
+
+## Rules
+- If a file has a "generated" warning, do not edit it directly
+- When in doubt, check the file header for instructions
+- If you must edit a generated file, add a comment explaining why

docs/evidence/STANDARD_CODE_BLOCKS.md

@@ -0,0 +1,9 @@
+# Code Block Standard for Commands
+
+- Use `bash` language tag for shell commands
+- Use `python` language tag for Python examples
+- Use `json` for JSON examples
+- Use `text` for output that is not code
+- Every command example should be runnable from a clean checkout
+- Include the expected output format, not the exact output
+- Use `$` prefix for commands, no `$` prefix for output

docs/evidence/STANDARD_DIAGRAM_STYLE.md

@@ -0,0 +1,9 @@
+# Diagram Source Style Guide
+
+- Use Mermaid for diagrams (flowchart, sequence, component)
+- Keep diagrams in markdown code blocks with the mermaid language tag
+- Place diagrams near the relevant text, not in a separate file
+- Label all nodes clearly
+- Limit to 15 nodes per diagram
+- Use `flowchart TD` for top-down, `flowchart LR` for left-right
+- Use `-->` for directed edges, `---` for undirected

docs/evidence/STANDARD_ENVIRONMENT_ASSUMPTIONS.md

@@ -0,0 +1,15 @@
+# Environment Assumption Standard
+
+Every document should state its assumptions about the reader's environment.
+
+## Required
+- Python version (minimum: 3.11)
+- Operating system (tested on: macOS, Linux)
+- Working `git` installation
+- Working `make` installation
+
+## Optional but recommended
+- Virtual environment manager (venv)
+- RAM (minimum: 4 GB, recommended: 8 GB)
+- Disk space (minimum: 500 MB)
+- Network access (required for `pip install`, optional for local checks)

docs/evidence/STANDARD_GENERATED_FILE_WARNING.md

@@ -0,0 +1,21 @@
+# Generated-File Warning Standard
+
+Files that are generated by scripts or CI must carry a warning.
+
+## Warning Format
+
+```markdown
+> **NOTE:** This file is generated. Do not edit directly.
+> Source: [path to source script or config]
+> Regenerate with: `make [target]`
+```
+
+## Where to Apply
+- Benchmark output files (if committed)
+- Generated documentation
+- Auto-generated configs
+- CI-generated artifacts
+
+## Exceptions
+- Files that are both source and output (e.g., README.md that is also generated)
+- Files in `outputs/` which are git-ignored

docs/evidence/STANDARD_OUTPUT_EXCERPTS.md

@@ -0,0 +1,8 @@
+# Command Output Excerpt Standard
+
+- Show only the relevant portion of command output, not the full output
+- Use `...` to indicate omitted content
+- Label the excerpt with the command that produced it
+- If the output is machine-readable (JSON), show it as a code block
+- If the output is human-readable, show it as a text block
+- Annotate important parts with comments where helpful

docs/evidence/STANDARD_SCREENSHOT_POLICY.md

@@ -0,0 +1,9 @@
+# Screenshot and Image Policy
+
+- Avoid screenshots — use Mermaid diagrams instead
+- If a screenshot is necessary, use PNG format
+- Keep images under 500 KB
+- Do not include screenshots of code — use code blocks instead
+- Do not include screenshots of terminal output — use text blocks instead
+- Alt text is required for all images
+- Store images in `docs/assets/`

docs/evidence/STANDARD_TABLE_FORMATTING.md

@@ -0,0 +1,8 @@
+# Table Formatting Standard
+
+- Use pipe tables (`| col | col |`)
+- Include a separator row after the header
+- Align columns with `:---` (left), `:---:` (center), `---:` (right)
+- No empty cells — use `—` or `N/A` instead
+- Keep tables under 8 columns wide
+- Break long tables into multiple smaller tables where possible

tests/test_standards_batch.py

@@ -0,0 +1,20 @@
+"""Tests for 10 standards and policies."""
+from pathlib import Path
+
+FILES = [
+    "STANDARD_TABLE_FORMATTING.md",
+    "STANDARD_DIAGRAM_STYLE.md",
+    "STANDARD_SCREENSHOT_POLICY.md",
+    "CHECKLIST_ACCESSIBILITY.md",
+    "CHECKLIST_CLEAR_LANGUAGE.md",
+    "STANDARD_CODE_BLOCKS.md",
+    "STANDARD_OUTPUT_EXCERPTS.md",
+    "STANDARD_ENVIRONMENT_ASSUMPTIONS.md",
+    "STANDARD_GENERATED_FILE_WARNING.md",
+    "POLICY_MANUAL_EDIT_ARTIFACTS.md",
+]
+
+
+def test_all_exist():
+    for f in FILES:
+        assert Path("docs/evidence", f).exists(), f"Missing: {f}"