notion-governance-runtime

# Notion Governance Runtime ## Objetivo Forzar que Claude trate Notion como el espacio de trabajo de David y no como un log interno del sistema, alineando cualquier cambio o diagnóstico contra la gobernanza viva del repo GitHub `Umbral-Bot/notion-governance` (no hay clone local en la VPS; ver R5 de `docs/runbooks/cross-thread-vps-concurrency.md`). ## Superficies de referencia - Gobernanza viva: repo GitHub `Umbral-Bot/notion-governance` (sin clone local en VPS) - Runtime/deploy reference: `/home/rick/umbral-agent-stack` - Clean working copy: `/home/rick/umbral-agent-stack-main-clean` ## Cuándo usar esta skill Úsala cuando la tarea toque: 1. `smart_reply` 2. `notion.*` 3. `granola.*` 4. comentarios hacia David en Control Room 5. páginas de tarea o artefactos en Notion 6. surfaces `raw`, `project`, `task`, `deliverable`, bridge, dashboard 7. conflictos entre V1 y V2 ## Reglas operativas 1. **Notion es user-facing.** Todo lo que vea David debe ser útil, corto y comprensible. 2. **Silencio > acuse vacío.** No dejar “Recibido”, “Procesando”, ni confirmaciones sin valor. 3. **No telemetría interna.** No mostrar `comment_id`, `trace_id`, modelo, task técnico, IDs internos, etc. 4. **Español claro.** Todo output visible para David debe quedar en español natural. 5. **Superficie canónica primero.** Si la gobernanza V2 define una superficie canónica, no reintroducir la surface legacy por comodidad. 6. **Control Room no es basurero.** No usarlo para dumps, self-talk o reportes internos que deberían vivir en objetos canónicos. 7. **Si encuentras conflicto V1/V2, explícitalo.** No lo tapes con wording neutro sin explicarlo en el diagnóstico. ## Flujo recomendado ### 1. Leer la gobernanza antes de proponer No asumas el contrato. Revisa el repo de gobernanza y extrae: - surfaces activas - surfaces legacy - campos obligatorios - reglas de promoción/capitalización - expectativas de interacción con David ### 2. Comparar contra el runtime real Revisa: - código que escribe comentarios - código que crea páginas o tasks - pipeline Granola - task pages y comentarios actuales - cualquier metadata que se esté filtrando a Notion ### 3. Clasificar cada cosa Para cada interacción Notion importante, decide si es: - valor real para David - coordinación útil - telemetría interna mal expuesta - ruido - legacy V1 incompatible con V2 ### 4. Proponer cambios mínimos primero Antes de rediseñar todo, prioriza: - quitar ruido visible - quitar telemetría visible - mover la información al objeto correcto - alinear fields obligatorios - dejar claro qué bloquea la migración completa a V2 ## Qué debe quedarse fuera del output a David - trailers tipo `(comment_id=...)` - modelos seleccionados - trace IDs - “Task técnico” - “Procesando…” si no aporta una acción real verificable - auto-narración del agente ## Qué sí debe sobrevivir - resultados reales - bloqueos concretos - preguntas de ambigüedad que realmente requieran decisión humana - links al artefacto canónico correcto - cambios de estado útiles ## Antipatrones - usar Notion como consola del sistema - mantener V1 por inercia cuando V2 ya es la referencia - confundir trazabilidad técnica con comunicación útil para David - dejar la UX de Notion gobernada por conveniencia del runtime en vez de por utilidad real ## Guardrails de capitalización Granola Cualquier cierre de una página raw de `Transcripciones Granola` hacia objetos canónicos (proyecto, oportunidad, tarea, bridge item, sesión curada) debe respetar los guardrails normativos documentados en: - `openclaw/workspace-templates/skills/granola-pipeline/SKILL.md` - `docs/54-granola-capitalize-raw-slice.md` Resumen operativo para Claude (usarlo antes de marcar una raw como capitalizada): 1. **Trazabilidad de ingest = read+append.** No reemplazar el campo `Trazabilidad` por completo. Preservar siempre, si existen, `granola_document_id`, `source_updated_at`, `source_url`, `ingest_path`, `content_hash`, `char_count`, `segment_count`, `truncation_detected`, `ingested_at` y `reconciled_at`. Solo anexar `capitalization_mode`, `canonical_target_type`, `canonical_target_name`, `canonical_target_url` y `processed_at`. Prohibido emitir frases tipo "Residuo legacy descartado" sobre trazabilidad de ingest — eso rompe la reconciliación descrita en `docs/78-granola-transcript-finality-reconciliation.md`. 2. **Reuniones comerciales = project-first, no tarea suelta.** Si hay cliente/partner + oportunidad implicita, la salida canonica es la pagina del proyecto. Orden: cliente -> proyecto/oportunidad (o `bridge item` si falta DB/permiso) -> propuesta/presupuesto como seccion o subpagina del proyecto -> tarea operativa (seguimiento) vinculada -> trazabilidad cruzada. No usar "📦 Entregables" (DB eliminada) ni "Bandeja de revision - Rick" para propuestas comerciales Granola. Si falta algun paso, la raw queda como **capitalización parcial** o **revisión requerida**, nunca como `Estado=Procesada` + `Accion agente=Capitalizado`. 3. **Datos fonéticos ambiguos.** No convertir transcripción fonética ambigua (correos, nombres, dominios) en dato firme. Dejarlo como "mencionado fonéticamente; confirmar" hasta que David lo valide. 4. **Caso Comgrap Dynamo** funciona como test de regresión: si la capitalización de una reunión con cliente nombrado y oportunidad técnica clara se cierra como tarea suelta, la capitalización está mal. ## Trazabilidad de regularizaciones manuales Notion Cuando una operación crítica sobre Notion se hace por fuera del Worker (curl directo, script ad-hoc, panel manual de David, otro agente corrigiendo a mano, etc.), Notion queda coherente pero el stack no recibe evento central en `ops_log.jsonl`. Esto rompe la auditabilidad cross-agente. Regla normativa: > Toda regularización manual Notion con API/curl/script directo debe > emitir un `notion.operation_trace` con `operation_id`. No cerrar > como trazado si solo hay comentarios Notion. Para cumplirla sin llamar a Notion: - `infra.ops_logger.OpsLogger.notion_operation(...)` — método programático (trunca `details`, sanitiza `target_page_ids`, genera `operation_id` si no se provee, nunca rompe la operación del caller). - `scripts/notion_trace_operation.py` — CLI con `--dry-run`. Contrato de seguridad: no persistir transcript crudo, prompts completos ni contenido largo de páginas Notion. `details` se trunca a 500 caracteres. `target_page_ids` es una lista corta (≤25). Caso de regresión documentado: **Comgrap Dynamo** fue regularizado con `curl` directo desde la VPS sin dejar breadcrumb central; el resultado es correcto en Notion pero deja brecha de auditoría sistémica. Usar ese caso como ejemplo al explicar el mecanismo. Referencias: - `docs/78-granola-transcript-finality-reconciliation.md` §10 - `docs/50-granola-notion-pipeline.md` §9.9 - `openclaw/workspace-templates/skills/granola-pipeline/SKILL.md` (G6)