refactor(ticket-186): extract MultiAgentOrchestrator.run stages into focused helpers (STARTER-619)

project/ticket-186/README.md

@@ -0,0 +1,53 @@
+# Ticket 186: Reduce cyclomatic complexity: MultiAgentOrchestrator.run (CC=31)
+
+- **ID**: ticket-186
+- **Owner**: unresolved:human
+- **Status**: IN_PROGRESS
+- **Workflow state**: EDIT
+- **Created**: 2026-09-20
+
+## Goal and scope
+
+SESSION_EXECUTION_AUTHORIZATION: the queue owner instructed re-running the
+STARTER-619 planfile ticket unmodified after freeing one application-workstream
+WIP slot (done: ticket-185 published via PR #370 protected merge).
+
+code2llm reports `src.koru.multi_agent.MultiAgentOrchestrator.run` at
+`src/koru/multi_agent.py:304` with cyclomatic complexity 31 (limit 15).
+Extract the run() stages (GitHub sync, queue collection, dry-run plan,
+worker reaping, backlog promotion, worker spawn) into focused helper methods
+with unchanged behavior, bringing the method under the limit 15.
+
+## Acceptance criteria
+
+- [x] AC-01: `MultiAgentOrchestrator.run` cyclomatic complexity is below 15
+      (code2llm re-run on this checkout, output outside the repo tree).
+- [x] AC-02: `tests/test_multi_agent.py` passes unmodified.
+- [x] AC-03: `ruff check` and `ruff format --check` pass on
+      `src/koru/multi_agent.py`.
+- [x] AC-04: `./project/governance-check.sh --base origin/main` passes.
+
+## Validation evidence
+
+Recorded 2026-09-20 in `.worktrees/ticket-186--multi-agent-run-complexity`
+(branch `ticket/186-multi-agent-run-complexity`, base `origin/main` = `52c5a3a2`):
+
+- AC-01: `code2llm <worktree> -f all -o /tmp/opencode/code2llm-ticket186
+  --no-chunk --exclude *.md --exclude plugins` — the report no longer lists
+  any CC hotspot in `multi_agent` (module row `CC=9`; the only remaining CC
+  finding is `_parse_layer_hotspot_suggestions CC=15` in an unrelated
+  pre-existing module). Independent AST recount: `run` CC 32 → 9; every
+  extracted helper ≤ 8 (`_sync_github_issues` 7, `_try_spawn_next_worker` 8,
+  `_reap_finished_workers` 5, `_promote_backlog_task` 5,
+  `_print_dry_run_plan` 3, `_collect_pending_tasks` 2).
+- AC-02: `PYTHONPATH=src python -m pytest tests/test_multi_agent.py -q` —
+  8 passed; plus `tests/test_cli_auto.py` — 10 passed total, unmodified.
+- AC-03: `ruff check src/koru/multi_agent.py` — All checks passed;
+  `ruff format --check` — clean (after one `ruff format` pass on the edit).
+- AC-04: `bash project/governance-check.sh --base origin/main` —
+  `GOV-PASS: passed (0 errors, 0 warnings)`.
+
+## Tracking boundary
+
+This directory contains the minimal reviewed intent. Optional participant prose
+and raw command logs are not required delivery output.

project/ticket-186/intent.json

@@ -0,0 +1,96 @@
+{
+  "schema": "new-project.intent/v3",
+  "ticket": "ticket-186",
+  "summary": "Reduce cyclomatic complexity: MultiAgentOrchestrator.run (CC=31)",
+  "workstream": "application",
+  "classification": {
+    "kind": "SERVICE",
+    "priority": "P2",
+    "origin": "health"
+  },
+  "allowedPaths": [
+    "project/ticket-186/**",
+    "TODO.md",
+    "project/TICKETS.md",
+    "src/koru/multi_agent.py",
+    "tests/test_multi_agent.py"
+  ],
+  "forbiddenPaths": [
+    "project/ticket-*/user-*.md"
+  ],
+  "stacks": [],
+  "dependsOn": [],
+  "conflictsWith": [],
+  "integrationTicket": null,
+  "delivery": {
+    "acceptedBaseSha": "52c5a3a2f8158553770ea98c0b2e9b5fb7972cd7",
+    "targetBranch": "main",
+    "outcome": "MultiAgentOrchestrator.run drops from cyclomatic complexity 31 to below the code2llm limit 15 by extracting behavior-preserving private helpers (_sync_github_issues, _collect_pending_tasks, _print_dry_run_plan, _reap_finished_workers, _promote_backlog_task, _try_spawn_next_worker). No public API, CLI, output, or scheduling semantics change; tests/test_multi_agent.py passes unmodified.",
+    "nonGoals": [
+      "Changing any observable output, exit code, worker scheduling, or timeout semantics",
+      "Regenerating project/analysis.toon.yaml or project/planfile-tickets.yaml (integration-owned artifacts)",
+      "Renaming or removing any public name"
+    ],
+    "complexity": "S",
+    "estimatedMinutes": 45,
+    "budgets": {
+      "maxImplementationFiles": 1,
+      "maxAffectedComponents": 1,
+      "maxPublicInterfaceChanges": 0,
+      "maxRuntimeDependencies": 0
+    },
+    "architecture": {
+      "status": "accepted",
+      "decision": "Decompose the monolithic run() loop into single-responsibility private methods on MultiAgentOrchestrator; the loop keeps only orchestration and accounting, each helper owns one stage and returns explicit deltas so behavior is byte-for-byte equivalent.",
+      "components": [
+        {
+          "name": "multi-agent-orchestrator",
+          "paths": [
+            "src/koru/multi_agent.py",
+            "tests/test_multi_agent.py"
+          ]
+        }
+      ],
+      "responsibilityChanges": false,
+      "interfaceChanges": [],
+      "dataChanges": [],
+      "ui": {
+        "impact": "none",
+        "states": [],
+        "evidence": []
+      },
+      "rollback": "Revert the commit; the original single run() method is restored verbatim."
+    },
+    "runtimeDependencies": [],
+    "validation": [
+      {
+        "criterion": "AC-01",
+        "commands": [
+          "code2llm <worktree> -f all -o /tmp/opencode/code2llm-ticket186 --no-chunk --exclude *.md --exclude plugins (complexity re-measured on MultiAgentOrchestrator.run)"
+        ],
+        "evidence": "Re-run code2llm reports CC < 15 for MultiAgentOrchestrator.run."
+      },
+      {
+        "criterion": "AC-02",
+        "commands": [
+          "PYTHONPATH=src .venv/bin/python -m pytest tests/test_multi_agent.py -q"
+        ],
+        "evidence": "Existing multi-agent suite passes unmodified."
+      },
+      {
+        "criterion": "AC-03",
+        "commands": [
+          "ruff check src/koru/multi_agent.py && ruff format --check src/koru/multi_agent.py"
+        ],
+        "evidence": "Lint and format pass on the refactored module."
+      },
+      {
+        "criterion": "AC-04",
+        "commands": [
+          "bash project/governance-check.sh --base origin/main"
+        ],
+        "evidence": "Governance gate passes with zero errors."
+      }
+    ]
+  }
+}