ADR-026 · Operations permission model — Claude-judged auto vs FES-gated (restringe ADR-008)¶

Fecha: 2026-04-29 Source: /srv/projects/cis/cis-plan/DECISIONS.md (do not edit here — re-split desde la fuente)

Contexto

ADR-008 (2026-04-09) estableció que toda operación privilegiada (sudo, ejecución MCP, modificar DB, firmar documento, aprobar pago) pasa por Firma Electrónica Simple vía firmasydocumentos.cl con OTP/SMS/TOTP. La motivación legal (Ley 19.799) es sólida — todo acto privilegiado queda con evidencia legal.

En la práctica operativa el alcance amplio de ADR-008 se choca con el patrón "Claudia secretaria 24/7" (Bloque A del plan v2). Si cada systemctl restart caddy requiere una FES con OTP, el flow se rompe: el usuario abre WhatsApp para "reiniciá caddy", y termina haciendo 30s de OTP en lugar de la operación misma. La fricción se acumula y el ecosistema se vuelve hostil al uso casual.

El plan v2 (decisión 6, Bloque A.2) introduce un modelo de juicio Claude donde la propia Claudia clasifica si una operación es auto (ejecuta + log) o fes (genera URL approval). El ADR-008 sigue válido — la FES sigue siendo legalmente vinculante para los actos críticos. Lo que cambia es el alcance: ADR-026 restringe la lista de operaciones que requieren FES, y declara explícitamente cuáles van por modo auto.

Alternativas consideradas

(a) ADR-008 alcance amplio (status quo)
Pro: máxima trazabilidad legal.
Contra: fricción operacional. Estimación: 10-30 FES/día de uso normal. UX hostil. Deshabilita el patrón "Claudia ejecuta lo trivial sin pedir".
(b) Modelo dual auto vs FES con tabla taxonómica ← propuesta
Pro: las operaciones realmente críticas (vault_set en proyectos sensibles, drop DB, DNS apex, systemd disable T0) siguen con FES legal. Las cotidianas (restart no-T0, caddy reload, DNS no-apex, draft inbox, spawn agente) van auto con audit log. Estimación: <1 FES/semana en operación normal.
Contra: la línea auto/FES debe estar muy clara. Si una op nueva no está clasificada, default debe ser FES (fail-safe).
(c) Sin FES, todo es audit log
Pro: cero fricción.
Contra: pierde la cobertura legal de Ley 19.799. Insuficiente para vault prod, banca, drop DB.

Decisión

Modelo dual con tabla canónica (OPERATIONS_TAXONOMY.md deliverable A.2):

Modo auto (Claudia ejecuta, audit log obligatorio, notificación opcional)¶

Categoría	Operaciones
systemd	`service_action(<svc no-T0>, restart)`, `service_action(<svc no-T0>, start)`
caddy	`caddy reload`, `caddy validate`, write site nuevo (no override)
dns	create record (no apex), update record (no apex)
agentes	`spawn_agent(prompt, scope)`, `read_channel(filters)`, `append_channel(msg)`
inbox	`draft_reply(thread_id, text)`, query mensajes
vault	`vault_list(project)`, `vault_get(project, key)` (read-only)
DB	SELECT en cualquier DB cis_*
archivos	edit en `/srv/projects/` no productivos, mover archivos no críticos
registro	`register_new_site(slug, port?, brand?)`, `register_new_service(slug, type, port?)` con convención clara
tests	run pytest, run pre-commit

Modo FES (Claudia genera URL `infra.innovacionsantiago.cl/approvals/<id>`, OTP, audit en `chat_tool_audits.fes_receipt_id`)¶

Categoría	Operaciones
vault sensible	`vault_set` en proyectos `vps-cis`, `cis-auth`, `innovacionsantiago`, `circulodesantiago`, `cis-platform/PAGOS_INTERNAL_HMAC_KEY`, cualquier `_PASSWORD` / `_KEY` / `*_TOKEN` en proyectos prod
DNS crítico	DNS edit/delete en zone apex (`innovacionsantiago.cl`, `circulodesantiago.cl`, `indieweb.cl`, `cochid.cl` cuando exista)
systemd T0	`service_action <svc T0>` con `disable` o `mask` (cis-core, cis-auth, cis-platform, cis-mailer, cis-style/Caddy, Authentik)
DB destructiva	`psql DROP TABLE`, `DROP DATABASE`, `DELETE` sin WHERE, `TRUNCATE`
certificados	rotación cert TLS, cert digital SII, transferencia dominios
banca	cualquier op en namespace `cis-pagos` que toque keys de Flow.cl o cuenta bancaria
identidad	crear superadmin, cambiar Authentik flow `cis-primary-auth` o `admin-password-emergency`, drop user privilegiado

Default cuando ambiguo: FES. Si una operación nueva no está clasificada, Claudia ejecuta como FES (fail-safe) y propone clasificación al final del hilo (humano valida + actualiza OPERATIONS_TAXONOMY.md).

Audit log universal: cada operación (auto o FES) escribe row en cis_claudia.chat_tool_audits con:

CREATE TABLE chat_tool_audits (
    id UUID PRIMARY KEY,
    message_id UUID FK,
    tool TEXT NOT NULL,
    params JSONB NOT NULL,
    permission_mode TEXT NOT NULL CHECK (permission_mode IN ('auto', 'fes')),
    fes_receipt_id UUID NULL,  -- FK firmasydocumentos receipt si fes
    result JSONB,
    duration_ms INT,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

Template del approval URL:

Order: <action_summary>
Why: <claudia_reasoning>
Impact: <services_affected, scope, reversibility>
Rollback: <command_or_steps>
Requested at: <timestamp>
Authorize via FES: <button to firmasydocumentos.cl/sign?action_id=...>

El user abre, Authentik valida, FES con OTP/SMS/TOTP, receipt firmado, Claudia ejecuta + log + reporta resultado al thread.

Estimación operacional: <1 FES/semana en operación normal. Si supera 2/semana, revisar la clasificación — algo está mis-categorizado. Métrica trackeada en cis-monitoreo: ratio auto_count / fes_count por ventana semanal.

Restricción de ADR-008: ADR-008 sigue válido para los actos definidos como FES en este ADR. No rige para los actos de modo auto. La cobertura legal Ley 19.799 sigue intacta para los actos donde se necesita (sudo crítico, banca, vault prod, drop DB, DNS apex). El audit log universal cubre los actos auto con evidencia operacional sin peso legal de FES — suficiente para reconstruir y atribuir.

Consecuencias

Positivo: el patrón "Claudia ejecuta lo trivial sin pedir" se vuelve operable. Fricción cae a <1 FES/semana. Cobertura legal sigue para los actos críticos. Audit log universal permite reconstrucción cross-tool.
Negativo: la tabla taxonómica debe mantenerse al día. Una op nueva mal clasificada como auto cuando debería ser fes rompe el modelo de seguridad. Mitigación: default FES + review humano.
Riesgo: si Claudia se equivoca al clasificar (ej. ejecuta una op que afecta T0 como auto), el audit log permite detectarlo post-hoc pero el daño puede ser hecho. Mitigación: la lista canónica de T0 (cis-core, cis-auth, cis-platform, cis-mailer, cis-style, Authentik) es hardcoded en core/py-common/permissions.py, no inferida.
Migración: en cuanto ADR-026 se acepte, cis-claudia v2 (Bloque A.1) implementa el modelo. Operaciones manuales actuales (vía core-server MCP con approval simple) siguen funcionando hasta que A.2 esté live.
Compatibilidad: ADR-008 no se reverte; se restringe en alcance. Receipts FES emitidos por firmasydocumentos siguen siendo válidos legalmente. La diferencia es que ahora muchos actos no los necesitan.
Auditoría externa: si un tercero (auditor, SII, juzgado) pregunta "qué pasó con la cuenta X", el log universal chat_tool_audits da reconstrucción completa. Para los actos críticos, el fes_receipt_id da el receipt legal.
Dependencia de Bloque A: requires cis-claudia v2 con HTTP MCP (ADR-015), infra.innovacionsantiago.cl/approvals/ UI (Bloque A.3), firmasydocumentos.cl con sign endpoint (T1 roadmap). Mientras esos estén en construcción, las ops siguen vía core-server MCP con aprobación simple — fallback documentado.

ADR-026 · Operations permission model — Claude-judged auto vs FES-gated (restringe ADR-008)¶

Modo auto (Claudia ejecuta, audit log obligatorio, notificación opcional)¶

Modo FES (Claudia genera URL infra.innovacionsantiago.cl/approvals/<id>, OTP, audit en chat_tool_audits.fes_receipt_id)¶

Modo FES (Claudia genera URL `infra.innovacionsantiago.cl/approvals/<id>`, OTP, audit en `chat_tool_audits.fes_receipt_id`)¶