Saltar al contenido principal

Auditoría de cobertura documental

Esta página resume la primera auditoría de documentación realizada sobre Rapid OS v3. Su propósito es mantener una relación explícita entre producto implementado y producto documentado.

Baseline auditado​

La primera versión del portal se construyó contra el estado de release de Rapid OS v3.0.0 que incluye:

  • packaging PEP 517/518;
  • CLI global rapid;
  • compatibilidad v2;
  • Project Intelligence;
  • Context Compiler;
  • Spec Registry;
  • Execution Policy y Run Registry;
  • Harness Capability Registry;
  • Evidence Engine;
  • Behavioral Evals;
  • validación y diagnósticos;
  • instaladores estables;
  • matriz de CI Python 3.10–3.13.

Cobertura por área​

Área implementadaDocumento principalEstado
Propósito y límites del productoQué es Rapid OSCubierto
Instalación y requisitosGetting StartedCubierto
Casos de usoCasos de usoCubierto
Flujo end-to-endGovernance LoopCubierto
Project IntelligenceArquitectura v3Cubierto técnicamente
Context CompilerArquitectura v3Cubierto técnicamente
Spec RegistryCLI + Arquitectura v3Cubierto
Execution Policy / RunsCLI + Governance LoopCubierto
Harness profiles y capabilitiesCapabilities y permisosCubierto
Evidence EngineGovernance Loop + CLICubierto
Behavioral EvalsGovernance Loop + CLICubierto
Estructura de archivosEstructura de archivosCubierto
Diagnósticos RAPIDxxxCLICubierto
Release v3.0.0Release v3.0.0Cubierto
Release checklistRelease checklistCubierto
Mantenimiento del portalMantener la documentaciónCubierto

Hallazgos principales​

1. La documentación existente era técnicamente rica, pero estaba orientada al repositorio​

Los documentos de arquitectura y CLI describen bien contratos internos, diagnósticos y entidades, pero un usuario nuevo necesitaba una capa anterior que respondiera:

  • qué es Rapid OS;
  • para qué sirve;
  • cuándo usarlo;
  • qué no hace;
  • cómo empezar;
  • qué archivos modifica;
  • cómo interpretar “permisos” y capabilities.

La nueva arquitectura de información cubre esa capa.

2. “Permisos” requería una definición de producto​

Rapid OS no implementa un sistema de autorización del sistema operativo. El concepto equivalente dentro del producto es el Harness Capability Registry. La documentación separa ahora:

  • capability declarada;
  • compatibilidad del harness;
  • requirement del contrato;
  • evidencia observable;
  • veredicto de evaluación.

3. La fuente documental debía ser única​

El portal Docusaurus usa directamente docs/ como fuente. No existe una segunda carpeta de contenido dentro de website/.

Esto reduce drift entre documentación visible en GitHub y documentación publicada.

4. El portal debe fallar cuando la documentación se rompe​

La configuración usa broken links como error y el workflow de CI ejecuta:

npm ci
npm run typecheck
npm run build

Un PR que rompa navegación o compilación documental debe fallar antes de merge.

Próxima cobertura recomendada​

La siguiente iteración debería profundizar en tutoriales operativos, no solo referencia:

  1. tutorial completo “primer proyecto gobernado”;
  2. recetas por modo: feature, bugfix, refactor, hardening y research;
  3. ejemplos completos de evidence.json por cada EvidenceKind;
  4. cookbook de políticas .rapid-os/policy.json;
  5. cookbook de HarnessProfile;
  6. troubleshooting por diagnóstico RAPIDxxx;
  7. integración CI/CD;
  8. despliegue oficial del portal documental.