tts-voice-creator-clone-and-design-2/architecture/sonar-refactorer.md

sonar-refactorer: the second multica agent (cognitive complexity)

sonar-fixer handles mechanical findings. Cognitive-complexity findings (python:S3776, javascript:S3776, about 350 locations) are refactors: they can change behaviour if done carelessly, so they get their own agent, their own autopilot and a stronger model.

Agent settings (multica: Agents -> New agent)

• Name: sonar-refactorer
• Description (255 chars max): Refactors one over-complex function at a time to cut SonarQube cognitive complexity, with tests first and behaviour unchanged. Local commits only. Stops and comments when tests cannot cover the change.
• Runtime: the same DGX-Spark Claude runtime. Model: Opus 5.5 (claude-opus-5-5). Thinking: follow CLI config.
• Concurrency: 1. It edits the same repo as sonar-fixer, so the two must never run at the same time (see "Lanes").

Autopilot (multica: Autopilot -> New autopilot)

• Name Sonar complexity to sonar-refactorer, assignee sonar-refactorer, output mode Create issue, project Voice Creator Clone & Design 2, trigger Webhook (no event filters).
• Save its webhook URL (it contains a secret) only in ~/.config/multica-webhook-refactor (chmod 600), never in the repo or in chat.
• Runbook: the instructions below.

Lanes

Only one agent may edit the tree at a time. The batch driver runs the sonar-fixer lane first; the refactor lane is started only when no sonar issue is open and the tracked tree is clean. Each lane's issues carry a label: agent-fix (fixer) or agent-refactor (refactorer).

Running the lane

npm run sonar:triage -- --all --lane refactor            # dry-run: lists the next 3 functions
npm run sonar:triage -- --all --lane refactor --apply    # files 3 issues, fires the refactor webhook

--lane refactor selects only python:S3776 and javascript:S3776, groups one issue per function, labels them sonar and agent-refactor, defaults the cap to 3 and posts to the URL in ~/.config/multica-webhook-refactor (or MULTICA_WEBHOOK_REFACTOR_URL). Start it only when no sonar issue is open and the tracked tree is clean.

Issue shape for this lane

One GitHub issue per function (one Sonar location), not per rule: a complexity refactor is reviewed and reverted per function. Title [sonar] <rule>: complexity N -> 15 in <file>:<function>. Cap: 3 issues per batch.

sonar-refactorer instructions (runbook)

Goal: reduce the cognitive complexity of the ONE function named in the webhook payload (body, github_issue_url) to 15 or below WITHOUT changing behaviour.

Context: private repo TTS Voice Creator. Read CLAUDE.md and PROJECT_MAP.md first. Python tests use unittest with an isolated HOME/CONFIG_DIR (see isolatedPyEnv in scripts/qa.mjs); JS checks use node scripts/check-frontend.mjs; browser (Playwright) specs run against the live app and cannot see worktree edits, so say which checks you did not run. Python: /usr/bin/python3 has no fastapi; use /home/sparky/miniforge3/bin/python3 (or npm run qa -- --only pyunit, which picks the right interpreter) and never report a failure that comes from a missing module as a test failure. Specs and tests mock the API and import from tests/_guard.js.

Steps:

1. Find the function by name (line numbers in Sonar are often stale). Read it and all its callers (grep the whole repo; JS files share globals).
2. Characterise first: if the function is pure or testable, write tests that pin down its current behaviour (normal, edge and error inputs) BEFORE changing it, and run them green on the old code. For a Python function use unittest; for pure JS logic use a small node --test file under tests/. If you cannot test it meaningfully (DOM, network, heavy side effects), do NOT refactor it: comment why on both issues, leave the GitHub issue open and stop.
3. Refactor with guard clauses and extracted helper functions with clear names. Keep public names, signatures, return values, exceptions, logging and side-effect order identical. No drive-by cleanups, no renames of public symbols, no new dependencies.
4. Run the new and existing tests of the touched module, node scripts/check-frontend.mjs (JS) or python3 -m py_compile (Python), and npm run qa -- --fast.
5. ONE local commit refactor(sonar): <function> cognitive complexity N -> M (<rule>), with the tests in the same commit. Never push. Never touch secrets.
6. Report as a comment on the multica issue AND on the GitHub issue (gh issue comment <number> --body-file -): commit SHA, function, complexity before and after, tests added, checks run and NOT run. Paths and line numbers only, no code. Add the label fixed-local, close the GitHub issue (gh issue close <number> --reason completed) and move the multica issue to Done.
7. If you need a design decision, the tests would not pin the behaviour, or the complexity cannot be brought down safely: comment on both issues, leave the GitHub issue open, leave the multica issue in In Review (or Blocked if you need an answer), and make no commit.