<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/plans/code-quality/targeted-cleanup-scoping/">
  <id>https://docs.spec-kitty.ai/plans/code-quality/targeted-cleanup-scoping/</id>
  <title>Targeted Cleanup Scoping — sync.py and walker.py</title>
  <updated>2026-09-30T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/plans/code-quality/targeted-cleanup-scoping/"/>
  <summary>Line-level scoping of the two highest-signal code-quality cleanup targets: the calibration/walker.py duplicated-literal cluster and the cli/commands/sync.py complexity god-module.</summary>
  <content type="html">&lt;span id=&quot;targeted-cleanup-scoping--syncpy-and-walkerpy&quot;&gt;&lt;/span&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Status (2026-09-30).&lt;/strong&gt; The &lt;code dir=&quot;auto&quot;&gt;sync.py&lt;/code&gt; half of this page is void:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/sync.py&lt;/code&gt; was removed with the sync transport (the
Convergence, #3881). The &lt;code dir=&quot;auto&quot;&gt;walker.py&lt;/code&gt; half still applies (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/calibration/walker.py&lt;/code&gt;
exists). &lt;code dir=&quot;auto&quot;&gt;merge/bookkeeping_projection.py&lt;/code&gt; is now
&lt;code dir=&quot;auto&quot;&gt;consolidation/bookkeeping_projection.py&lt;/code&gt;. Current Sonar priorities are the 4.0.0 series in
the &lt;a href=&quot;/plans/4-0-0-milestone-roadmap/&quot;&gt;4.0.0 Milestone Roadmap&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Line-level scoping of the two highest-signal cleanup targets surfaced by the
2026-08-12 SonarCloud snapshot (see &lt;a href=&quot;/plans/code-quality/&quot;&gt;Code Quality index&lt;/a&gt; for the full
picture). Effort figures are SonarCloud’s own remediation estimates; the risk and
sequencing judgement is ours.&lt;/p&gt;
&lt;p&gt;The two files tell opposite stories: &lt;code dir=&quot;auto&quot;&gt;walker.py&lt;/code&gt; is a fully safe mechanical sweep that
can land today; &lt;code dir=&quot;auto&quot;&gt;sync.py&lt;/code&gt; mixes cheap safe wins with two genuine refactors that must
ride a degod wave.&lt;/p&gt;
&lt;h2 id=&quot;srcspecify_clicalibrationwalkerpy--safe-immediate-2h&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/calibration/walker.py&lt;/code&gt; — safe, immediate (~2h)&lt;/h2&gt;
&lt;p&gt;533 LOC, &lt;strong&gt;14 smells, all &lt;code dir=&quot;auto&quot;&gt;S1192&lt;/code&gt;&lt;/strong&gt; (duplicated string literals), ~1h50m Sonar effort.
Zero structural risk: the findings are all inside the module-level &lt;code dir=&quot;auto&quot;&gt;_REQUIRED_SCOPE&lt;/code&gt;
lookup table — a static &lt;code dir=&quot;auto&quot;&gt;dict[tuple[str, str], frozenset[str]]&lt;/code&gt; mapping
&lt;code dir=&quot;auto&quot;&gt;(mission_type, action_urn)&lt;/code&gt; to the doctrine URNs the step directly requires.&lt;/p&gt;
&lt;h3 id=&quot;what-the-findings-are&quot;&gt;What the findings are&lt;/h3&gt;
&lt;p&gt;The table hand-lists doctrine URNs, and many are raw duplicated strings:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;action-URN prefixes — &lt;code dir=&quot;auto&quot;&gt;&quot;action:software-dev/...&quot;&lt;/code&gt; (L113, L134, L164)&lt;/li&gt;
&lt;li&gt;directive URNs — &lt;code dir=&quot;auto&quot;&gt;&quot;directive:DIRECTIVE_024&quot;&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;025&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;028&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;029&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;030&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;034&lt;/code&gt;
(L129, L136-140)&lt;/li&gt;
&lt;li&gt;tactic URNs — &lt;code dir=&quot;auto&quot;&gt;&quot;tactic:acceptance-test-first&quot;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;&quot;tactic:quality-gate-verification&quot;&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;&quot;tactic:stopping-conditions&quot;&lt;/code&gt; (L141, L144, L145)&lt;/li&gt;
&lt;li&gt;agent-profile URNs — &lt;code dir=&quot;auto&quot;&gt;&quot;agent_profile:r...&quot;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;&quot;agent_profile:c...&quot;&lt;/code&gt; (L300, L308)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;why-it-is-safe&quot;&gt;Why it is safe&lt;/h3&gt;
&lt;p&gt;The module &lt;strong&gt;already&lt;/strong&gt; has a partial named-constant set (&lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_003&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_010&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;TACTIC_ADR_DRAFTING_WORKFLOW&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;TACTIC_REQUIREMENTS_VALIDATION_WORKFLOW&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;TACTIC_PREMORTEM_RISK_IDENTIFICATION&lt;/code&gt;, …). The fix simply &lt;strong&gt;completes&lt;/strong&gt; that set: the
inconsistency — some URNs named, most inlined — is itself the smell.&lt;/p&gt;
&lt;h3 id=&quot;scope-of-work&quot;&gt;Scope of work&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Define the missing URN constants next to the existing ones (directives 024/025/028/
029/030/034/037, the tactic URNs, the agent-profile URNs).&lt;/li&gt;
&lt;li&gt;Replace the raw duplicated string occurrences in &lt;code dir=&quot;auto&quot;&gt;_REQUIRED_SCOPE&lt;/code&gt; with the constants.&lt;/li&gt;
&lt;li&gt;No logic change — the frozensets resolve to identical values; existing calibration
tests are the regression guard.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Risk: minimal.&lt;/strong&gt; Behavior-preserving, single-file, covered by the existing calibration
suite. Good first pickup / campsite PR. Clears all 14 smells.&lt;/p&gt;
&lt;h2 id=&quot;srcspecify_cliclicommandssyncpy--split-the-safe-wins-from-the-refactor&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/sync.py&lt;/code&gt; — split the safe wins from the refactor&lt;/h2&gt;
&lt;p&gt;6,261 LOC — a &lt;strong&gt;god-module&lt;/strong&gt; of &lt;code dir=&quot;auto&quot;&gt;spec-kitty sync&lt;/code&gt; subcommands. &lt;strong&gt;26 smells&lt;/strong&gt;, ~4h
Sonar effort. This file is the worst single source file in the project and sits in the
&lt;strong&gt;Wave 4 sync-adapter cluster&lt;/strong&gt; of the &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/docs/archive/plans/refactor/degod-unshim-roadmap.md&quot;&gt;degod roadmap&lt;/a&gt;.
Do &lt;strong&gt;not&lt;/strong&gt; treat it as one cosmetic pass — separate the mechanical wins from the two
complexity monsters.&lt;/p&gt;
&lt;h3 id=&quot;tier-1--mechanical-wins-safe-now-1h-15-findings&quot;&gt;Tier 1 — mechanical wins, safe now (~1h, 15 findings)&lt;/h3&gt;
&lt;p&gt;Behavior-preserving; drops the file 26 -&gt; 11 smells.&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Rule&lt;/th&gt;&lt;th&gt;Count&lt;/th&gt;&lt;th&gt;Lines&lt;/th&gt;&lt;th&gt;Fix&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;S7632&lt;/td&gt;&lt;td&gt;6&lt;/td&gt;&lt;td&gt;1019, 1806, 2002, 2058, 3657, 3869&lt;/td&gt;&lt;td&gt;Fix malformed issue-suppression comment syntax&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S3358&lt;/td&gt;&lt;td&gt;5&lt;/td&gt;&lt;td&gt;189, 2158, 2165, 4693, 5960&lt;/td&gt;&lt;td&gt;Extract nested ternary into a statement&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S1192&lt;/td&gt;&lt;td&gt;3&lt;/td&gt;&lt;td&gt;108, 561, 2146&lt;/td&gt;&lt;td&gt;Hoist &lt;code dir=&quot;auto&quot;&gt;&quot;bold yellow&quot;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;&quot;:memory:&quot;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;&quot;[dim]Unavailable&quot;&lt;/code&gt; to constants&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;S5713&lt;/td&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;2590&lt;/td&gt;&lt;td&gt;Remove redundant &lt;code dir=&quot;auto&quot;&gt;Exception&lt;/code&gt; subclass&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Note the 6 &lt;code dir=&quot;auto&quot;&gt;S7632&lt;/code&gt; findings are malformed suppression comments — worth fixing on sight,
and a reminder that the file already leans on suppressions (see Tier 2).&lt;/p&gt;
&lt;h3 id=&quot;tier-2--cognitive-complexity-ride-wave-4-3h-10x-s3776&quot;&gt;Tier 2 — cognitive complexity, ride Wave 4 (~3h, 10x S3776)&lt;/h3&gt;
&lt;p&gt;The real debt. Two functions dominate and &lt;strong&gt;already carry &lt;code dir=&quot;auto&quot;&gt;# noqa: C901&lt;/code&gt;&lt;/strong&gt; — explicit
complexity suppressions that the campsite/charter policy says to retire, not add to:&lt;/p&gt;


















































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Function&lt;/th&gt;&lt;th&gt;Line&lt;/th&gt;&lt;th&gt;Cognitive complexity&lt;/th&gt;&lt;th&gt;Sonar effort&lt;/th&gt;&lt;th&gt;Notes&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status()&lt;/code&gt;&lt;/td&gt;&lt;td&gt;5299&lt;/td&gt;&lt;td&gt;&lt;strong&gt;90&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;1h20m&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;# noqa: C901&lt;/code&gt;; build-and-emit table + &lt;code dir=&quot;auto&quot;&gt;--check&lt;/code&gt; coherence gate&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;doctor()&lt;/code&gt;&lt;/td&gt;&lt;td&gt;5925&lt;/td&gt;&lt;td&gt;&lt;strong&gt;73&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;1h3m&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;# noqa: C901&lt;/code&gt;; diagnostic build-and-emit + gate&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;routes()&lt;/code&gt;&lt;/td&gt;&lt;td&gt;2126&lt;/td&gt;&lt;td&gt;27&lt;/td&gt;&lt;td&gt;17m&lt;/td&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;purge()&lt;/code&gt;&lt;/td&gt;&lt;td&gt;4424&lt;/td&gt;&lt;td&gt;26&lt;/td&gt;&lt;td&gt;16m&lt;/td&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_enforce_sync_now_exit_from_dispatch()&lt;/code&gt;&lt;/td&gt;&lt;td&gt;304&lt;/td&gt;&lt;td&gt;22&lt;/td&gt;&lt;td&gt;12m&lt;/td&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status()&lt;/code&gt;-adjacent&lt;/td&gt;&lt;td&gt;3737&lt;/td&gt;&lt;td&gt;19&lt;/td&gt;&lt;td&gt;9m&lt;/td&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;(subcommand)&lt;/td&gt;&lt;td&gt;5109&lt;/td&gt;&lt;td&gt;19&lt;/td&gt;&lt;td&gt;9m&lt;/td&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;share()&lt;/code&gt;&lt;/td&gt;&lt;td&gt;2232&lt;/td&gt;&lt;td&gt;18&lt;/td&gt;&lt;td&gt;8m&lt;/td&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;(subcommand)&lt;/td&gt;&lt;td&gt;5840&lt;/td&gt;&lt;td&gt;17&lt;/td&gt;&lt;td&gt;7m&lt;/td&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;(subcommand)&lt;/td&gt;&lt;td&gt;4348&lt;/td&gt;&lt;td&gt;16&lt;/td&gt;&lt;td&gt;6m&lt;/td&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;status()&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;doctor()&lt;/code&gt; are the classic decomposition shape: a long sequence of
conditional &lt;code dir=&quot;auto&quot;&gt;table.add_row(...)&lt;/code&gt; blocks (build), a &lt;code dir=&quot;auto&quot;&gt;--check&lt;/code&gt;/coherence gate (validate),
and rendering (emit). The natural split is &lt;code dir=&quot;auto&quot;&gt;_build_*_rows()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;_run_coherence_gate()&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;_render(...)&lt;/code&gt; pure helpers, each independently testable — which also satisfies the
Sonar rule “prefer testable extractions.”&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Why this is not a cosmetic pass.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;sync.py&lt;/code&gt; is a 6.3k-line CLI surface. Extracting
helpers under it without a &lt;strong&gt;golden CLI-characterization test first&lt;/strong&gt; risks silent
behavior drift, which the degod roadmap calls out as a non-negotiable invariant
(“golden-CLI-characterization test first on every command degod”). This work belongs in
the Wave 4 sync-adapter degod slice, where that harness is built, and where the
&lt;code dir=&quot;auto&quot;&gt;# noqa: C901&lt;/code&gt; suppressions come off as the functions drop under complexity 15.&lt;/p&gt;
&lt;h2 id=&quot;effort-summary&quot;&gt;Effort summary&lt;/h2&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Target&lt;/th&gt;&lt;th&gt;Findings&lt;/th&gt;&lt;th&gt;Safe now&lt;/th&gt;&lt;th&gt;Deferred to a wave&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;walker.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;14&lt;/td&gt;&lt;td&gt;~2h (all)&lt;/td&gt;&lt;td&gt;—&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;sync.py&lt;/code&gt; Tier 1&lt;/td&gt;&lt;td&gt;15&lt;/td&gt;&lt;td&gt;~1h&lt;/td&gt;&lt;td&gt;—&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;sync.py&lt;/code&gt; Tier 2&lt;/td&gt;&lt;td&gt;10&lt;/td&gt;&lt;td&gt;—&lt;/td&gt;&lt;td&gt;~3h (Wave 4, with characterization tests)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Immediate safe cleanup: &lt;strong&gt;~3h clears 29 findings&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;walker.py&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;sync.py&lt;/code&gt; Tier 1).
The 10 &lt;code dir=&quot;auto&quot;&gt;sync.py&lt;/code&gt; complexity findings ride &lt;strong&gt;Wave 4&lt;/strong&gt;. (A prior 11th target,
&lt;code dir=&quot;auto&quot;&gt;sync_workspace()&lt;/code&gt;, was resolved by deletion — issue #424 / PR #500, “Delete dead
GitVCS/VCSProtocol.sync_workspace” — and dropped from this inventory so future
cleanup planning does not chase a non-existent function.) The 3 &lt;code dir=&quot;auto&quot;&gt;S2083&lt;/code&gt; BLOCKER
vulnerabilities in &lt;code dir=&quot;auto&quot;&gt;merge/bookkeeping_projection.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;skills/verifier.py&lt;/code&gt; are a
separate ~90-min targeted fix (not on a wave) and should land before the final 3.2.6 tag (3.2.6 shipped 2026-09-03; the S2083 BLOCKERs are now tracked as #2970).&lt;/p&gt;</content>
</entry>
