224d81e7fe
Closes #137 (and partially #138, #139): platform/ now contains 56 folders
(verified: ls -d platform/*/ | wc -l). Pass 104 set the anchor at 53;
Pass 105 added platform/spire/, platform/nats-jetstream/, and
platform/sealed-secrets/ as G2 wrapper charts for the bootstrap kit
(commit 8c0f766). This brings the count anchor up to date.
Files updated:
- CLAUDE.md L46: '53 folders total' → '56 folders total'
- docs/TECHNOLOGY-FORECAST-2027-2030.md L11: 'all 53 platform components'
→ 'all 56 platform components'
- docs/TECHNOLOGY-FORECAST-2027-2030.md §Mandatory: header (26) → (29);
added rows for spire, nats-jetstream, sealed-secrets with 2026/2027/2030
scores + Catalyst-specific notes
- docs/BUSINESS-STRATEGY.md: 26 'bare-53' references → 56 (executive
summary, principles, comparison tables, expert network, GTM)
- docs/AUDIT-PROCEDURE.md grep #9: anchor expectation 53 → 56; banned-list
pattern shifted from '52 components' → '53 components' (the now-stale
count). Deep-read rotation note updated 53 → 56.
- docs/PROVISIONING-PLAN.md: Group K execution-status row reflects the
refresh; §5 'what doesn't change' clarified that anchor moved 53 → 56.
Verified post-update: grep -rE '\b53 components\b|\b53 platform components\b|\b53 curated\b|\b53-component\b' docs/ README.md CLAUDE.md → empty (excluding VALIDATION-LOG history).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
143 lines
7.9 KiB
Markdown
143 lines
7.9 KiB
Markdown
# Documentation Audit Procedure
|
|
|
|
**Status:** Authoritative. **Updated:** 2026-04-28.
|
|
|
|
This document is the procedure for performing a documentation-integrity validation pass on the canonical Catalyst docs and component READMEs. It is **on-demand only** — there is no scheduled audit loop.
|
|
|
|
For invocation via Claude Code, see the `audit-catalyst-docs` skill.
|
|
|
|
---
|
|
|
|
## When to run
|
|
|
|
- After any architectural change that touches multiple docs (component additions/removals, terminology shifts, structural model changes).
|
|
- Before tagging a public release of the canonical docs.
|
|
- Before adding a new Sovereign-curated catalog (`catalog-sovereign` Gitea Org) — to confirm the upstream canon is consistent.
|
|
- On request, ad-hoc, when a contributor questions whether a doc claim is current.
|
|
|
|
**Never run as a scheduled background loop.** Past loops over-anchored on incorrect models (see `VALIDATION-LOG.md` Pass 103); text-shape consistency is not the same as architectural soundness.
|
|
|
|
---
|
|
|
|
## What the audit verifies
|
|
|
|
The audit cross-checks the canonical docs and component READMEs against five categories of anchors:
|
|
|
|
1. **Banned-term hygiene** — 11 terms in `GLOSSARY.md` §"Banned terms" must not appear (in non-exempt contexts) anywhere in the canon.
|
|
2. **Naming canonicality** — `env_type` 3-char form, DNS pattern split (control-plane vs Application), API group split (`catalyst.openova.io` vs `compose.openova.io`), JetStream subject prefix.
|
|
3. **Structural invariants** — `App = Gitea Repo` (the unified rule from Pass 103), branches `develop`/`staging`/`main` map to envs, 5 Gitea Orgs convention (`catalog`, `catalog-sovereign`, per-Catalyst-Organization, `system`).
|
|
4. **Component-count consistency** — number of `platform/<x>/` folders matches the count anchored across `CLAUDE.md`, `TECHNOLOGY-FORECAST-2027-2030.md` L11, `BUSINESS-STRATEGY.md`, and the implicit table sums in TF.
|
|
5. **Defense-in-depth architectural anchors** — load-bearing decisions (OpenBao independent-Raft per region, SeaweedFS as unified S3 encapsulation, Catalyst-as-platform / OpenOva-as-company, Valkey-NOT-control-plane, no-bidirectional-Gitea-mirror) must each appear consistently across at least 4 representational levels.
|
|
|
|
---
|
|
|
|
## The 13 acceptance greps
|
|
|
|
Run from the repo root (`/home/openova/repos/openova`). All should produce zero output unless an exemption explanation is included.
|
|
|
|
```bash
|
|
# 1. Banned terms (excluding contextual exemptions noted in GLOSSARY)
|
|
for term in 'tenant' 'Workspace' 'Lifecycle Manager' 'bootstrap wizard' 'Backstage' \
|
|
'Synapse' 'Fuse' 'Module' 'Template' 'Operator' 'Client' 'Instance'; do
|
|
grep -rni "\\b$term\\b" docs/ platform/*/README.md products/*/README.md core/README.md README.md CLAUDE.md \
|
|
| grep -v 'GLOSSARY.md' | grep -v 'VALIDATION-LOG.md'
|
|
done
|
|
|
|
# 2. env_type long-form (must be 0)
|
|
grep -rnE 'acme-staging|acme-production|acme-development' docs/ platform/*/README.md products/*/README.md README.md CLAUDE.md \
|
|
| grep -v VALIDATION-LOG
|
|
|
|
# 3. JetStream subject prefix (must show only NAMING §11.2 occurrence)
|
|
grep -rnE 'ws\.\{?(env|org)' docs/ARCHITECTURE.md docs/NAMING-CONVENTION.md docs/GLOSSARY.md docs/SECURITY.md docs/PLATFORM-TECH-STACK.md
|
|
|
|
# 4. API group split (count must be ≥7 across Catalyst CRDs + Crossplane XRDs)
|
|
grep -rnE 'compose\.openova\.io/v1alpha1|catalyst\.openova\.io/v1alpha1' \
|
|
docs/ARCHITECTURE.md docs/NAMING-CONVENTION.md docs/SECURITY.md docs/BLUEPRINT-AUTHORING.md \
|
|
core/README.md platform/crossplane/README.md | wc -l
|
|
|
|
# 5. Subsection ordering monotonicity
|
|
grep -nE '^### 7\.[0-9]' docs/PLATFORM-TECH-STACK.md
|
|
grep -nE '^### 2\.[0-9]|^### 11\.[0-9]' docs/NAMING-CONVENTION.md
|
|
grep -nE '^### 5\.[0-9]' docs/SECURITY.md
|
|
grep -nE '^### 9\.[0-9]' docs/SRE.md
|
|
# Manual check: numbers must be strictly increasing.
|
|
|
|
# 6. Old App-as-folder model (must be 0 outside VALIDATION-LOG)
|
|
grep -rnE 'Environment Gitea repo|/{org}/{org}-{env_type}|<org>/<org>-<env_type|per-Environment Gitea repos' \
|
|
docs/*.md README.md CLAUDE.md | grep -v VALIDATION-LOG
|
|
|
|
# 7. Branches-map-to-envs anchor present in 4+ docs
|
|
grep -lE 'develop`/`staging`/`main|develop/staging/main|branches.*map.*env' \
|
|
docs/GLOSSARY.md docs/NAMING-CONVENTION.md docs/ARCHITECTURE.md docs/PERSONAS-AND-JOURNEYS.md
|
|
|
|
# 8. 5 Gitea Orgs convention (must be in GLOSSARY + ARCHITECTURE + PTS + BLUEPRINT-AUTHORING)
|
|
grep -lE 'catalog-sovereign|`system` Gitea Org|five conventional Gitea Orgs|5 conventional Gitea Orgs' \
|
|
docs/GLOSSARY.md docs/ARCHITECTURE.md docs/PLATFORM-TECH-STACK.md docs/BLUEPRINT-AUTHORING.md
|
|
|
|
# 9. Component count = 56 across all anchors (must produce no "53 components" except VALIDATION-LOG)
|
|
grep -rnE '\b53 components\b|\b53 curated\b|\b53-component\b|\ball 53\b|\b53 platform\b|\b53 folders\b' \
|
|
docs/*.md README.md CLAUDE.md | grep -v VALIDATION-LOG
|
|
ls -d platform/*/ | wc -l # must equal 56
|
|
|
|
# 10. SeaweedFS encapsulation (no MinIO except intentional TF L37 explanation)
|
|
grep -rinE '\bminio\b' docs/*.md README.md CLAUDE.md core/README.md products/*/README.md platform/*/README.md \
|
|
| grep -v VALIDATION-LOG | grep -v 'platform/seaweedfs/' | grep -v 'TECHNOLOGY-FORECAST'
|
|
|
|
# 11. OpenBao independent-Raft (must appear in 5+ representational levels)
|
|
grep -lE 'INDEPENDENT, NOT STRETCHED|independent Raft cluster|no stretched cluster|Independent OpenBao Raft' \
|
|
docs/SECURITY.md docs/ARCHITECTURE.md docs/GLOSSARY.md docs/PLATFORM-TECH-STACK.md docs/BUSINESS-STRATEGY.md
|
|
|
|
# 12. Catalyst-as-platform anchor (must appear in GLOSSARY + README + BUSINESS-STRATEGY)
|
|
grep -lE 'Company vs.*Platform|Catalyst is the open|OpenOva.*the company|Catalyst.*the platform itself' \
|
|
docs/GLOSSARY.md README.md docs/BUSINESS-STRATEGY.md
|
|
|
|
# 13. DNS pattern split (NAMING + multiple consumers)
|
|
grep -nE '\{component\}\.\{location-code\}\.\{sovereign-domain\}|\{app\}\.\{environment\}\.\{sovereign-domain\}' \
|
|
docs/NAMING-CONVENTION.md
|
|
grep -lE '<location-code>\.<sovereign-domain>|<env>\.<sovereign-domain>' \
|
|
docs/SOVEREIGN-PROVISIONING.md docs/BLUEPRINT-AUTHORING.md docs/SRE.md \
|
|
platform/llm-gateway/README.md platform/valkey/README.md
|
|
```
|
|
|
|
---
|
|
|
|
## Deep-read rotation
|
|
|
|
After greps, deep-read **one canonical doc + one component README** per pass. Rotate through the canon and the 56 platform components + 7 products (catalyst, cortex, axon, fingate, fabric, relay, specter) over time. The next-most-stale entry should be the target.
|
|
|
|
The deep-read confirms the doc's known anchors are present and consistent with the rest of the canon. For each:
|
|
|
|
1. Read the doc end-to-end.
|
|
2. Check known fix-trajectory anchors (see `VALIDATION-LOG.md` for what was previously fixed in that file).
|
|
3. Cross-check at least 2 other docs the deep-read target references, looking for bidirectional consistency.
|
|
4. Verify the **5 invariants** (Section above) hold.
|
|
|
|
---
|
|
|
|
## Output
|
|
|
|
Append a numbered Pass entry to `docs/VALIDATION-LOG.md` describing:
|
|
|
|
- Date, pass number, target doc + target component
|
|
- Acceptance grep results (clean / drift)
|
|
- Deep-read findings
|
|
- Any architectural anchors verified or flagged
|
|
- If drift: what was fixed and the new anchor
|
|
|
|
If clean: short entry confirming clean. If drift: longer entry documenting the fix and a Lesson if the drift represents a recurring pattern.
|
|
|
|
Commit message format: `docs(pass-N): <target-doc> <ordinal>-cycle + <component> <ordinal>-cycle <clean|fixed>`. Commit as `hatiyildiz` per the repo's git-identity convention.
|
|
|
|
---
|
|
|
|
## What this audit does NOT do
|
|
|
|
- **Architectural review.** Text-shape consistency does not validate that the architecture is right. Architectural review is a separate, complementary discipline. See Pass 103 and Lesson #21.
|
|
- **Code review.** Most code is design-stage per `IMPLEMENTATION-STATUS.md`. Code review is a separate concern.
|
|
- **Compliance review.** Mappings to PSD2/DORA/NIS2/SOX live in `bp-specter`'s Compliance Agent's runtime evaluation, not in doc audit.
|
|
- **Security review.** Security review is `/security-review` skill's domain.
|
|
|
|
---
|
|
|
|
*Part of [OpenOva](https://openova.io)*
|