feat(nextgen): roadmap follow-up validation and hardening

[alexandervazquez98]

Pre-flight Checks

• I have searched existing open issues and this is not a duplicate
• I understand implementation PRs should be approved/sliced before review if the diff grows

Problem Description

The first read-only next-gen MCP milestone is now implemented and pushed, but Raven still needs follow-up work before the next-gen incident workflow is production-ready end to end.

Current state:

• raven nextgen-mcp exposes read-only next-gen tools.
• Raven incident skill and agent setup docs exist.
• Unit tests cover the local client/server contract with fake HTTP servers.
• No live/staging next-gen validation, refresh-token flow, raw-size enforcement, or mutating next-gen actions exist yet.

Proposed Roadmap

Milestone 2 — end-to-end validation and hardening

• Test raven nextgen-mcp against a real or staging next-gen API with an AI_DIAGNOSTIC-style token.
• Capture sanitized example payloads for representative event, CI search, CI events, and metrics responses.
• Verify endpoint assumptions:
  • GET /api/events?status=<status>
  • GET /api/events/{event_id}
  • GET /api/nodes/search?q=<query>
  • GET /api/events/related/{ci_id}
  • GET /api/nodes/{node_id}/metrics
• Add integration-style tests or fixtures based on sanitized real payload shapes.
• Decide whether transport-level MCP schema rejection needs an integration test instead of only direct handler tests.
• Confirm path-prefix deployments work, e.g. https://host/proxy/api/....

Milestone 3 — Raven persistence safety

• Define and enforce a max persisted raw size for Raven events.
• Add a redaction/sanitization helper for candidate payloads before raven_record_event / raven event ingest.
• Add tests for omitting secrets and oversized raw payloads.
• Document the exact persisted fields for next-gen events.
• Consider a CLI/tool flow that reviews a candidate before writing it to Raven.

Milestone 4 — auth resilience

• Decide whether to support NEXTGEN_REFRESH_TOKEN.
• If supported, add one safe retry on 401 with refresh-token handling.
• Ensure refresh tokens are never logged, returned in MCP output, or committed in project config.
• Add timeout and retry tests for auth failures and refresh failures.

Milestone 5 — controlled mutating next-gen tools

Only after read-only behavior is validated:

• Design explicit, non-read-only MCP tools for:
  • nextgen_run_diagnostic
  • nextgen_ack_event
  • nextgen_comment_event
  • nextgen_close_event
• Encode next-gen guardrails:
  • cooldowns respected
  • critical events require human escalation
  • AI cannot force-close events
  • close notes include Causa raíz: and Nota: where required
• Require explicit operator approval before destructive/remote-mutating actions.
• Add audit-result envelopes and tests.

Milestone 6 — setup automation

• Add raven setup <agent> after the docs contract stabilizes.
• Keep setup project-local by default.
• Do not silently edit global profiles such as ~/.gemini, ~/.codex, or Ollama server env.
• Add validation for generated .gemini/settings.json, .codex/config.toml, Ollama Modelfile, and wrapper scripts.

Recommended Test Plan

Short-term:

go test -count=1 ./...
go vet ./...
git diff --check
python3 -m json.tool .gemini/settings.json >/dev/null
python3 - <<'PY'
import tomllib
with open('.codex/config.toml','rb') as f:
    tomllib.load(f)
PY
bash -n scripts/raven-ollama

Live/staging validation:

NEXTGEN_BASE_URL=https://<staging-nextgen> \
NEXTGEN_ACCESS_TOKEN=<redacted-ai-diagnostic-token> \
raven nextgen-mcp

Then exercise via an MCP client:

• nextgen_list_events(status="ACTIVE")
• nextgen_get_event(event_id="...")
• nextgen_search_cis(query="...")
• nextgen_get_ci_events(ci_id="...")
• nextgen_get_ci_metrics(node_id="...")
• nextgen_build_raven_event_candidate(event_id="...", canonical_ci_id="...")

Acceptance Criteria

• Read-only next-gen MCP behavior is validated against sanitized real/staging payloads.
• Raven persistence cannot store obvious secrets from next-gen raw payloads by default.
• Oversized raw/event evidence handling is documented and tested.
• Auth refresh is either explicitly implemented or explicitly deferred with rationale.
• Mutating tools, if implemented, are non-read-only, operator-approved, and guardrailed.
• Setup automation does not commit or write secrets/global profile state unexpectedly.

References

• docs/design/nextgen-mcp-contract.md
• docs/design/raven-incident-workflow.md
• docs/agent-setup.md
• docs/ai-usage.md
• internal/nextgen/
• internal/nextgenmcp/

[alexandervazquez98]

Nota para el diseño del bridge Ollama/next-gen:

next-gen es el lugar natural para ejecutar el agente local, porque el sistema ya tiene soporte nativo para una IA local/chat operacional. Para Ollama no conviene asumir que la UI oficial ejecuta tools/MCP: Ollama soporta tool calling por API, pero el loop lo debe implementar el cliente.

Propuesta a evaluar en próximos pasos:

• Implementar el bridge/tool-loop del lado de next-gen o como wrapper local asociado a next-gen.
• Mantener Raven como memoria/CMDB/timeline y persistencia operacional.
• Mantener next-gen como sistema upstream/event source.
• Para consultas locales, el bridge puede ser simple y basado en shell/bash al inicio:
  • ejecutar Raven CLI/MCP para resolver CI y leer timeline;
  • ejecutar raven nextgen-mcp o llamadas read-only equivalentes para eventos/CI/metrics;
  • inyectar resultados al chat local de IA;
  • no permitir mutaciones next-gen todavía.
• Raven writes siguen requiriendo aprobación explícita del operador.
• next-gen mutating actions (ack, comment, close, run_diagnostic) siguen diferidas/guardrailed.

Esto permite aprovechar el chat IA local existente en next-gen sin entregar tokens ni capacidad de mutación directamente al modelo/UI de Ollama.