Skip to content

OBJ-WPDOCTOR-001: WPDoctor — agente ADK SRE para WordPress

Objective ID: OBJ-WPDOCTOR-001 Status: active (lanzamiento GO dado por Carlos 2026-09-08: plan + kanban + waves) Drafted by: wetopi-lead (plan) — Owned by: platform Ejecución: wetopi-worker · Gates: operator (GATE-0, GATE-M0, GATE-M1)

Outcome

Un SRE autónomo especializado en WordPress/WooCommerce que opera infraestructura de terceros vía SSH, provider-agnostic, multi-host y multi-site, con memoria por tenant, policy engine independiente del LLM, auditoría completa y aprendizaje por incidente (LEARN). La autonomía es gradual (READONLY / COPILOT / AUTOPILOT): el producto NO entrega root sin restricciones a un LLM.

Primera entrega: M0 (contratos) + M1 (SSH + discovery + inventario + demo wpdoctor discover), con E2E contra fixture SSH dockerizada (sin hosts de cliente ni mutación remota).

Context

  • Fuerzas: estates WordPress gestionados por la flota requieren triaje SRE repetitivo (estado de servicios, versiones, logs, WordPress/Woo); la plataforma ya tiene el contrato documental (ADR-0016: diseños nuevos nacen como ADR proposed) y el plan de waves está aprobado.
  • Autoridad arquitectónica: ADR-0001 del repo agent-adk-wpdoctor (status proposed, commiteada en T0.1) codifica MEMORIA-TECNICA + ARCHITECTURE-PACK sin inventar decisiones nuevas.
  • El runtime elegido es google-adk==2.8.0 — decisión registrada como ADR-0017 (proposed) en este Knowledge Plane; la frontera framework-agnóstica garantiza que es reemplazable.
  • Repo wetopi-platform/agent-adk-wpdoctor: privado, main con README+.gitignore (GATE-0 cerrado 2026-09-08).

Decisiones (resumen — detalle en el ADR del repo + ADR-0017)

  1. Runtime = google-adk 2.8.0, pin en pyproject; SOLO src/wpdoctor/agents/ y el bootstrap importan google.adk (pack §5, ADR-0017).
  2. Topología: wpdoctor-manager público + especialistas internos (linux, web, php, database, wordpress, woocommerce, performance, security, lifecycle, backup, reviewer).
  3. SSH = transporte, no lógica de negocio: el conector solo conecta, autentica, verifica host key, ejecuta con timeout, redacta y audita.
  4. Discovery determinista antes que LLM (/etc/os-release, command -v, systemctl, nginx -V, php -v, mysql --version, redis-cli, wp --info, wp-config.php).
  5. Herramientas estrechas por defecto; execute_any_shell_command solo como tooling excepcional, nunca vía principal (pack §10).
  6. Policy engine independiente del LLM (ALLOW / DENY / REQUIRE_APPROVAL); el LLM no puede override un DENY.
  7. E2E M1 contra fixture SSH dockerizada (sshd + binarios fake + árbol WordPress fake); VPS real desechable = backlog posterior.

Hitos (waves)

Hito Contenido Cierre
GATE-0 Repo GitHub privado creado (main + README) lead (2026-09-08)
M0 Contratos: scaffold + docs inmutables + ADR-0001 proposed; dominio pydantic; config+logging+CLI+runtime skeleton; conector SSH (asyncssh, known_hosts, redaction, audit); policy engine + audit JSONL; manager ADK + specialists registry + Docker dev image GATE-M0 (operator)
M1 Inventario persistente (tenant→hosts→sites→capabilities); discovery host+capacidades; discovery WordPress multi-site + redacción de credenciales; operación discover (manifest READONLY) + CLI e2e + fixture compose; audit events + trazas en discovery GATE-M1 (operator + lead)
Knowledge (paralelo) OBJ-WPDOCTOR-001 + ADR-0017 + id-registry + nav mkdocs (esta card, K1) PR (merge = Carlos)

Acceptance criteria (DONE)

  • AC1 — M0: uv run pytest verde en el repo, imagen wpdoctor:dev buildable, sin mutación remota; checklist pack §7-M0 completa (GATE-M0).
  • AC2 — M1: wpdoctor discover ejecuta el flujo §16 completo (connect→discover→capabilities→wordpress→persist→structured print) contra fixture SSH en CI; inventario persistente y reconstructible; cero secretos en inventario/logs (GATE-M1).
  • AC3 — Knowledge plane: OBJ-WPDOCTOR-001 + ADR-0017 merged en wetopi-knowledge vía PR (frontmatter completo, registrado en records/id-registry.md, entradas en nav mkdocs.yml, mkdocs build --strict OK).
  • AC4 — Frontera respetada: SOLO src/wpdoctor/agents/ y el bootstrap importan google.adk (verificable con grep en CI/review).

Verification contract

AC Evidencia Fuente de verdad
AC1 uv run pytest verde + docker build OK en GATE-M0 CI del repo + gate
AC2 Demo wpdoctor discover en CI (fixture sshd compose) CI del repo + gate
AC3 PR merged en wetopi-knowledge; build --strict OK GitHub PR state
AC4 Grep google.adk fuera de agents/+bootstrap = 0 resultados repo

Constraints

  • TDD obligatorio: tests primero; uv run pytest verde antes de cerrar hito.
  • PROHIBIDO: tocar el clúster k8s, hosts reales de clientes, meter secretos reales en código/git/memoria; nunca mergear la propia PR.
  • Los docs del repo (MEMORIA-*, ARCHITECTURE-PACK, ADR-0001) son inmutables.
  • Cada operación/tool declara riesgo y requisitos; cada comando SSH remoto genera audit metadata.
  • No usar fences mermaid en fichas de este repo (docs-runtime sin plugin).

Out of scope (backlog posterior)

M2 (ops read-only SRE), M3 (policy + ejecución controlada), M4 (lifecycle WordPress), M5 (Hindsight), M6 (dogfooding Wetopi), M7 (eval corpus ≥25). VPS real desechable para demo fuera de CI. SaaS/control-plane (no, pack §14).

Review boundaries

  • PRs del repo revisados por el lead; gates por el operator.
  • Merge de esta ficha (K1) = Carlos (no auto-merge).