Research: Agentic Large-Scale Automated Refactoring (TS + Go Monorepo)
Saved 2026-07-18 from deep-research findings. Scope: migration of ~5M active LOC (in an estate that reads as ~70M LOC with generated/vendored/templated code) using a large agent fleet.
Core thesis
Not “1,000 agents editing at once.” 1,000 logical agents as durable workflow instances; a much smaller number of active edit lanes gated by ownership, path locks, CI capacity, and merge-queue throughput. Optimize for many small, reversible PRs — never mega-branches. And: determinism first, generation last — the 65M boilerplate LOC go through deterministic AST rewrites (GritQL/ast-grep, zero per-edit tokens); only the 5M core LOC get guided agents.
Index
Batch 1 — platform & program design (docs 00–05)
| Doc | Contents |
|---|---|
| 00-executive-summary.md | Thesis, assumptions, headline numbers |
| 01-inventory-dependency-analysis.md | Component registry, static/dynamic analysis layers, boilerplate scoring, canonical component record |
| 02-platform-architecture-orchestration.md | Reference architecture, agent roles, scheduling/concurrency, sandbox isolation, Temporal vs Argo vs K8s Jobs |
| 03-observability-triage-safety.md | OTel spine, fleet metrics, human-in-the-loop triage, SLAs, end-to-end workflow, rollback levels |
| 04-models-tooling-cost.md | Model routing strategy, platform comparison, internal services to build, monorepo tooling, cost model |
| 05-rollout-kpis-risks.md | Phased rollout timeline, KPI gates, stop metrics, top risks + mitigations |
Batch 2 — six-application control plane (docs 06–10)
| Doc | Contents |
|---|---|
| 06-six-app-blueprint.md | Six-application framework, four-phase execution, leadership recommendations |
| 07-knowledge-graph-rewrite-engines.md | Tree-sitter/SQLite/MCP knowledge graph (120× token reduction), GritQL deterministic rewrites |
| 08-orchestration-triage-guardrails.md | Temporal+LangGraph two-layer orchestration, semantic-dedup triage gateway, Code Health ≥9.5 guardrails |
| 09-monitoring-limits-comparative-metrics.md | LiteLLM gateway, rate/budget limit table, unguided-vs-guided evidence |
| 10-core-logic-case-study.md | 1Password B5 case study, manifest→template→playbook→parallel-execution pattern |
| 11-monorepo-development-assessment-plan.md | Zaruba “hodnocení” runbook: 1-day fleet assessment, 9-dim rubric, Zaruba fingerprint, 23-item conformance gate |
| 12-collab-split-and-fleet-monitor.md | Two-lead collision protocol (CODEOWNERS/claim-queue/ADR-DRI), fleet-monitor build-vs-adopt verdict |
| 13-access-fix.md | groupon2 PAT fix runbook (2 min, Robert-only) — blocks the assessment |
| 14-answer-draft-tomas.md | Czech draft reply to Tomas (4 messages) — DO NOT SEND without Robert’s approval |
Cross-batch deltas (what batch 2 adds over batch 1)
- Boilerplate ≠ agent work. Batch 1 excluded generated code from waves; batch 2 goes further — deterministic AST rewrites (GritQL) handle the 65M LOC at zero marginal token cost. Removes ~93% of estate from LLM spend.
- Knowledge graph as MCP service — concrete stack (Tree-sitter + SQLite + cross-service linking via OpenAPI/protobuf/queue parsing); ~3.4k vs ~412k tokens/session for blast-radius queries.
- Semantic question dedup — embeddings cluster agent questions; matched cluster auto-applies prior human decision. Batch 1 had routing+SLAs only.
- Code Health as pre-commit gate (≥9.5) — economic rationale: degraded code costs up to +50% tokens (+120% output tokens for Java).
- Concrete gateway limits — LiteLLM TPM/RPM tiers, iteration caps, Redis circuit breaker, Temporal 2MB payload / ~500-iteration history bounds.
- Planner/executor split validated — high-capability model writes plan.md playbook; cheap executors implement. Matches this project’s operating mode.
Operating mode for this project (conversation contract)
- Fable = planner, orchestrator, auditor, reviewer.
- Execution = cheapest model that clears ~90% confidence for the task: Haiku → Sonnet → Opus escalation.
- Max parallelism on independent work; ultracode workflows for substantive tasks.