Add 10 docs: runbooks, charter, migration guides

docs/evidence/DOCS_GOVERNANCE_CHARTER.md

@@ -0,0 +1,41 @@
+# Documentation Governance Charter
+
+## Purpose
+
+This charter defines how documentation is governed in the OpenAMP Foundry project.
+
+## Principles
+
+1. **Truthfulness first** — documentation must not overclaim.
+2. **Single source of truth** — `docs/evidence/METRICS_CURRENT.md` is authoritative for metrics.
+3. **Freshness** — documents should be reviewed on a regular cadence.
+4. **Accessibility** — documents should be findable from PROJECT_INDEX.md.
+5. **Accountability** — every document has an owner (maintainer or designated reviewer).
+
+## Document Types
+
+| Type | Description | Review Cadence |
+|------|-------------|----------------|
+| Policy | Rules and governance | Every 6 months |
+| Guide | How-to instructions | Every 3 months |
+| Reference | Factual documentation | Every 6 months |
+| Concept card | Short explanations | Annually |
+| Runbook | Step-by-step procedures | Every 3 months |
+
+## Change Process
+
+- **Minor changes** (typos, formatting): Direct commit to main or PR with `minor` label.
+- **Major changes** (new policy, restructuring): Standard PR with full review.
+- **Urgent fixes** (safety, accuracy): Immediate fix + 24h review.
+
+## Roles
+
+See `docs/evidence/DOCS_ROLE_DEFINITIONS.md` for role descriptions.
+
+## Related Documents
+
+- `docs/evidence/DOCS_MINOR_EDIT_POLICY.md`
+- `docs/evidence/DOCS_REVIEW_CADENCE_POLICY.md`
+- `docs/evidence/DOCS_RETIREMENT_POLICY.md`
+- `docs/evidence/DOCS_ESCALATION_POLICY.md`
+- `docs/evidence/DOCS_EXCEPTION_POLICY.md`

docs/evidence/MIGRATION_GUIDE_BACKLOG_DOCS.md

@@ -0,0 +1,8 @@
+# Migration Guide: Backlog Docs
+
+When moving items from backlog to active or completed:
+
+1. Update `docs/research/NEXT_100_PR_MAP.md` if the item was there.
+2. Update `docs/research/ROADMAP.md` with the new status.
+3. If the work was completed, ensure all related docs are updated.
+4. Close the corresponding GitHub issue with a link to the PR.

docs/evidence/MIGRATION_GUIDE_COMMAND_DOCS.md

@@ -0,0 +1,8 @@
+# Migration Guide: Command Docs
+
+When CLI commands change, update:
+
+1. `docs/getting-started/COMMAND_SURFACE.md` for command workflows.
+2. `docs/evidence/EXIT_CODE_REGISTRY.md` if exit codes changed.
+3. Any runbooks that reference the old command.
+4. QUICKSTART.md if the change affects demo commands.

docs/evidence/MIGRATION_GUIDE_GLOSSARY_DOCS.md

@@ -0,0 +1,8 @@
+# Migration Guide: Glossary Docs
+
+When terms change or new terms are added:
+
+1. Update the glossary entries in the relevant docs.
+2. Check PROJECT_INDEX.md for cross-references to the old term.
+3. Run `python scripts/check_doc_links.py` to catch broken references.
+4. If a term was removed, add it to the deprecation notice.

docs/evidence/MIGRATION_GUIDE_RELEASE_DOCS.md

@@ -0,0 +1,9 @@
+# Migration Guide: Release Docs
+
+When preparing a release, ensure these docs are updated:
+
+1. `docs/evidence/METRICS_CURRENT.md` — update benchmark numbers.
+2. `docs/research/ROADMAP.md` — update completed items.
+3. `docs/evidence/SIMULATION_BENCHMARK.md` — update gate verdict.
+4. `docs/review/PUBLICATION_PACK.md` — complete checklist.
+5. `README.md` — update version references.

docs/getting-started/RUNBOOK_FAILING_DOCS_CHECKS.md

@@ -0,0 +1,9 @@
+# Contributor Runbook: Failing Docs Checks
+
+If a docs check fails in CI:
+
+1. Read the error message — it tells you which check failed and why.
+2. Run the check locally: `python scripts/check_doc_links.py` or `python scripts/safety/check_claims.py`.
+3. Fix the issue (broken link, overclaiming language, etc.).
+4. Re-run the check locally to confirm.
+5. Push the fix — CI will re-run automatically.

docs/getting-started/RUNBOOK_FINISHING_DOCS_PR.md

@@ -0,0 +1,9 @@
+# Contributor Runbook: Finishing a Docs PR
+
+Before marking a docs PR as ready:
+
+1. Run `python scripts/check_doc_links.py` — 0 broken links.
+2. Run `python scripts/safety/check_claims.py` — no overclaiming.
+3. Run `python3 -m pytest -q` — all tests pass.
+4. Verify any new docs are linked from PROJECT_INDEX.md.
+5. Request review from a maintainer.

docs/getting-started/RUNBOOK_OPENING_FOLLOW_UPS.md

@@ -0,0 +1,8 @@
+# Contributor Runbook: Opening Follow-Up Issues
+
+If your PR uncovers a separate issue that needs attention:
+
+1. Open a new issue describing the problem.
+2. Link the new issue to your PR in a comment.
+3. In your PR description, note that follow-up work is tracked in the new issue.
+4. Do not scope-creep your current PR — focus on the original task.

docs/getting-started/RUNBOOK_RUNNING_DOCS_CHECKS.md

@@ -0,0 +1,10 @@
+# Contributor Runbook: Running Docs Checks
+
+Before submitting a PR, always run:
+
+```bash
+python scripts/check_doc_links.py   # check for broken links
+python scripts/safety/check_claims.py  # check for overclaiming language
+```
+
+Fix any issues before requesting review.

docs/getting-started/RUNBOOK_UPDATING_INDEXES.md

@@ -0,0 +1,5 @@
+# Contributor Runbook: Updating Indexes
+
+After adding a new document, update PROJECT_INDEX.md.
+After removing a document, remove its entry from PROJECT_INDEX.md.
+After renaming a document, update its entry in PROJECT_INDEX.md.

tests/test_batch_10.py

@@ -0,0 +1,28 @@
+"""Tests for batch of 10 docs."""
+from pathlib import Path
+
+FILES = [
+    "RUNBOOK_UPDATING_INDEXES.md",
+    "RUNBOOK_RUNNING_DOCS_CHECKS.md",
+    "RUNBOOK_FAILING_DOCS_CHECKS.md",
+    "RUNBOOK_OPENING_FOLLOW_UPS.md",
+    "RUNBOOK_FINISHING_DOCS_PR.md",
+    "DOCS_GOVERNANCE_CHARTER.md",
+    "MIGRATION_GUIDE_COMMAND_DOCS.md",
+    "MIGRATION_GUIDE_RELEASE_DOCS.md",
+    "MIGRATION_GUIDE_GLOSSARY_DOCS.md",
+    "MIGRATION_GUIDE_BACKLOG_DOCS.md",
+]
+
+
+def test_all_exist():
+    for f in FILES:
+        path = Path("docs/evidence") / f if "RUNBOOK" not in f else Path("docs/getting-started") / f
+        assert path.exists(), f"Missing: {f}"
+
+
+def test_each_has_content():
+    for f in FILES:
+        path = Path("docs/evidence") / f if "RUNBOOK" not in f else Path("docs/getting-started") / f
+        text = path.read_text()
+        assert len(text) > 50, f"{f} too short"