COCOA v1 epic: static polyglot system graph + cross-service blast radius

[rahlk]

Goal

Build COCOA (Code Context Agent) as CLDK's plug-and-play agent product: one unified, precise, static system graph of a polyglot k8s-native codebase, with cross-service blast radius grounded through the database as the hero capability. Fresh repo; stack pattern (fastmcp + typer + cldk + MCP-client tests) ported from upstream codellm-devkit/cocoa-mcp. Competitive frame: graphify — match its frictionless UX and distribution mechanics, beat it on fidelity: every edge derived from real static analysis (DERIVED-STATIC) or explicitly INFERRED — never guessed. Graphify indexes files; COCOA understands systems.

Status — v1 engine COMPLETE (2026-07-08)

14 tasks + final whole-branch review merged (#16–#29, #34). 79 tests green. Real Online Boutique evidence: cross-service RPC edges derived, blast radius {'emailservice': 9, 'recommendationservice': 1} on hipstershop.Money.units, token headline ~25,772× vs naive read. E2E launch gate stays strict pending the Go analyzer prerequisite.

Scope (v1)

• System graph — nodes: Service, K8sWorkload, Function, RPCEndpoint, ProtoMessage/ProtoField, Datastore, Table, KeyPattern. Edges: intra-service CALLS (codeanalyzer-* backends via canonical analysis.json), cross-service RPC_CALLS/HANDLES/HOSTS (proto + stub call sites + k8s/helm/kustomize/compose wiring, statically rendered), data access READS/WRITES (Redis client calls + SQL/ORM).
• Provenance: DERIVED-STATIC / INFERRED (fallback only, always labeled) + DECLARED-UNUSED annotation. Skipped services recorded, never silent. Single-source topology rollup (cocoa.system.topology) keeps report/map/MCP surfaces agreeing.
• Artifacts: .cocoa/system-graph.json, system-map.html, SYSTEM_REPORT.md.
• Surfaces: MCP tools (build_graph, blast_radius, service_graph, data_access, query_subgraph — bounded outputs, honest totals); cocoa map|blast|serve|demo CLI; skillset plugin modeled on the obra/superpowers paradigm (plan 2); one-command installer + Docker all-in-one runtime (plan 2).
• Hero demo + golden fixture: Online Boutique v0.10.5 (cocoa demo).

Build stages → child issues

''- [x] Stage 1 — Runtime image: #39 image · #40 CI (real smoke: container mapped a fixture; unit CI live and green)''

• Stage 2 — Engine foundations + polyglot driver: Task 1: Repo scaffold + graph models #2 Task 2: Proto parser #3 Task 3: Wiring — k8s/helm/kustomize/compose #4 Task 4: Service & config detection #5 Task 5: Normalized facts + language adapters #6 Task 6: Analysis driver #7
• Stage 3 — RPC stitcher: Task 7: RPC stitcher #8
• Stage 4 — Data-access extractors: Task 8: Data-access extractors (Redis + SQL/ORM) #9
• Stage 5 — Query engine, artifacts, CLI, MCP: Task 9: Graph assembly + persistence #10 Task 10: Blast radius engine #11 Task 11: Report + HTML map artifacts #12 Task 12: CLI — cocoa map / blast #13 Task 13: MCP server + five system tools #14
  '- [ ] Stage 6 — Skillset + commands + installer: P2 Task 1: Plugin manifests + asset-validation harness #35 manifests · P2 Task 2: Skills — using-cocoa + grounding-claims #36 P2 Task 3: Skills — mapping-a-system + blast-radius #37 skills · P2 Task 4: Slash commands + plugin MCP config #38 commands/MCP'
• Stage 7 — Online Boutique demo: Task 14: Online Boutique flagship demo #15 (shipped with real e2e evidence; full-tooling gate blocked only on codeanalyzer-go#5)
• Final whole-branch review: Final review: cross-surface RPC topology consistency (self-loops + HOSTS provenance) #30 (fix wave merged)
  '- [ ] Stage 8 — Distribution pass: P2 Task 7: Distribution docs #41 docs/comparison/demo-tape'

'## Follow-ups from review (non-blocking)

• Follow-up: packaging hardening backlog (plan-2 review triage) #50 packaging hardening backlog (plan-2 triage)'

• Follow-up: defensive config parsing and skip observability #31 defensive config parsing + skip observability

• Follow-up: MCP/CLI input hygiene and UX polish #32 MCP/CLI input hygiene + UX polish

• Follow-up: precision/completeness backlog from per-task reviews #33 precision/completeness backlog

Prerequisites (cross-repo)

• Merge and release feat/initial-implementation codeanalyzer-go#5 — merge & release feat/initial-implementation (gates the strict e2e)
• Build level-1 Roslyn analyzer (symbol table + call graph) codeanalyzer-dotnet#1 — level-1 Roslyn analyzer (critical path: cartservice→Redis)
• Validate plain-JavaScript analysis on Node gRPC services codeanalyzer-typescript#52 — validate plain-JS Node gRPC services
• Wire Go frontend (CLDK.go) once codeanalyzer-go ships python-sdk#234 — CLDK.go wiring (post-release)
• Wire C# frontend (CLDK.csharp) once codeanalyzer-dotnet ships python-sdk#235 — CLDK.csharp wiring (post-release)
• cldk 1.4.0 wheel is missing the bundled codeanalyzer jar python-sdk#236 — cldk 1.4.0 wheel missing bundled jar (found by our demo run)
• Rename pip package to cocoa-mcp (free the name for the product repo) cocoa-mcp#3 — free the cocoa pip name

Success criteria

1. cocoa demo runs unattended on a clean machine (Docker path gates plan-2 launch; host-native path works today).
2. Money-field blast radius on Online Boutique complete and correct across ≥4 languages, with call sites; zero unlabeled guesses. (Pending Go + dotnet prereqs for full breadth; derived edges today carry honest provenance.)
3. A blast-radius query costs ≤5k tokens; headline ratio ≥50× vs. naive. (Measured: ~25,772×.)
4. A useful graph on a polyglot repo without k8s manifests. (Static-only mode tested.)
5. The skillset installs and answers correctly on Claude Code, Codex, and Cursor. (Plan 2.)