ADR: Public Documentation Quality Gate, Topic Character Budgeting, and Kernel ID Scrutiny
Context
Public-facing documentation at docs.zqk.dev serves external developers, operators, and evaluators adopting the ZQK ecosystem. When documentation is overly verbose, bloated with internal sprint retrospectives, riddled with conflicting acronym expansions (e.g. ATK defined inconsistently), or leaks internal Knowledge Kernel entity IDs (BLI-*, REQ-*, PRI-*, TST-*, CRIT-*, GOAL-*, MIL-*), adoption friction increases and public trust degrades.
To maintain pristine editorial standards, public documentation must be succinct, unambiguous, free from internal cycle implementation narratives, and rigorously vetted against canonical acronym definitions.
Decision
- Automated Documentation Scrutiny Suite (
zqk-vet -suite docs): - Integrated a dedicated documentation scrutiny suite intozqk-vetgoverned bypkg/vet/check_docs.goandconfig/gates.yaml. - Enforces character count ceilings per high-level topic (sections delineated by##):- Concept and design guides: max 4,000 characters per section.
- Architecture specifications: max 8,000 characters per section.
- Validates acronym consistency across all markdown files against canonical definitions registered in
pkg/acronyms/acronyms.go(e.g., ensuringATKdenotes "Agent Task", rejecting conflicting expansions). - Prohibits internal cycle narrative achievements (e.g. "In Cycle 98 we fixed...") and project-specific raw kernel IDs (
BLI-*,REQ-*,PRI-*,TST-*,CRIT-*,GOAL-*,MIL-*) in public guides and docs.
- Docs Portal Decoupling & Sanitization (
deploy-docs-portal.sh): -scripts/open-core/docs-portal/deploy-docs-portal.shexecutes./bin/zqk-vet -suite docsas Step [0/4] before compiling HTML pages. - Internal sprint retrospectives (*_CYCLE*.md,*BURNDOWN*.md,*DEFECT_REMEDIATION*.md,*NORMALIZATION_MAP*.md) are excluded from public portal compilation inscripts/open-core/docs-portal/generate_docs_portal.py. - Markdown documents undergo automated sanitization during portal compilation to prevent raw internal kernel IDs from reaching static HTML assets. - Knowledge Kernel Policy & Invariant:
- Codified
POL-DOC-001in the Knowledge Kernel CAS, declaring that all documentation artifacts must adhere to topic brevity limits, canonical terminology, and zero raw kernel ID leakage. - Codified Three-Fold Proof verification inpkg/community/docs_quality_gate_test.goverifying static floor invariants, operational dynamic proof, and negative adversarial boundary rejection.
Status
Accepted and codified in Knowledge Kernel for Cycle 101.