ui/_docs/03_implementation/batch_14_cycle3_report.md

Batch 14 — AZ-511 (classColors carve-out)

Date: 2026-05-13 Cycle: 3 — autodev Step 10 (Implement), batch 2 of 3 (fixes-first order: AZ-510 ✓ → AZ-511 → AZ-512) Tickets: AZ-511 (Epic AZ-509) Verdict: PASS

---

Task Results

Task	Status	Files Modified	Tests	AC Coverage	Issues
AZ-511_classcolors_carve_out	Done	12 files (1 mv, 1 new barrel, 4 consumer imports, 1 06_annotations barrel cleanup, 1 script, 2 tests, 4 doc updates)	31 files / 231 passed / 13 skipped (full fast suite); static profile PASS; bun run build PASS with zero circular-import warnings	6/6 ACs covered	None

AC Test Coverage: 6/6 covered

• AC-1 → ls src/class-colors/ (classColors.ts, index.ts); find src/features/annotations -name classColors.ts empty
• AC-2 → rg "from.*classColors" src (no path-form imports remain)
• AC-3 → tests/architecture_imports.test.ts "AC-4: FAILS when a deep import bypasses the class-colors barrel" (replaces the prior exemption-WORKS fixture per Risk 4 mitigation)
• AC-4 → bun run build log (built in 3.83s, no circular warnings)
• AC-5 → bunx vitest run (231 passed)
• AC-6 → rg "F3-pending\|physical location pending refactor\|EXCEPT classColors" _docs scripts src returns nothing

Code Review Verdict: PASS

• Report: _docs/03_implementation/reviews/batch_14_review.md
• 0 findings (Critical / High / Medium / Low)
• Resolved baseline finding F3 (physical / logical owner split for classColors.ts); F4's "carried-forward exemption" note also retired

Auto-Fix Attempts: 0

Stuck Agents: 0

---

Implementation Notes

Changed Files

Production code:

• src/class-colors/classColors.ts — moved from src/features/annotations/classColors.ts (byte-for-byte; no API change).
• src/class-colors/index.ts — new barrel re-exporting getClassColor, getPhotoModeSuffix, getClassNameFallback, FALLBACK_CLASS_NAMES.
• src/components/DetectionClasses.tsx — from '../features/annotations/classColors' → from '../class-colors'.
• src/features/annotations/CanvasEditor.tsx — from './classColors' → from '../../class-colors'.
• src/features/annotations/AnnotationsSidebar.tsx — same.
• src/features/annotations/AnnotationsPage.tsx — same.
• src/features/annotations/index.ts — removed the 7-line "classColors symbols are NOT re-exported here" carry-over comment block.

Scripts + tests:

• scripts/check-arch-imports.mjs — ARCH_IMPORTS_EXEMPT_RE set to null (was the F3 deep-import regex); scanner now skips the exemption branch when null. Added class-colors to COMPONENT_DIRS so deep imports past the new barrel are caught symmetric to every other component.
• tests/architecture_imports.test.ts — replaced the "still PASSES when only the classColors F3-pending exemption is used" fixture with "FAILS when a deep import bypasses the class-colors barrel (AZ-511 regression guard)" — stronger replacement per spec Risk 4 mitigation.
• tests/detection_classes.test.tsx — import { FALLBACK_CLASS_NAMES } from '../src/features/annotations/classColors' → from '../src/class-colors'; carry-over comment block removed.
• scripts/run-tests.sh — updated the description block of static_check_no_cross_component_deep_imports to reflect zero exemptions and the new barrel.

Documentation:

• _docs/02_document/module-layout.md — Layout Rule #2 (one misplaced module remains: CanvasEditor; class-colors no longer counted), Layout Rule #3 (no exemptions today), Per-Component Mapping for 11_class-colors (now owns src/class-colors/**), 06_annotations (Owns no longer carves out classColors; Imports from now goes via barrel), 03_shared-ui (Imports from notes the barrel), ## Shared / Cross-Cutting → shared/class-colors (marked RESOLVED with back-pointer), Verification Needed #1 (RESOLVED), Verification Needed #3 (no exemption left).
• _docs/02_document/components/11_class-colors/description.md — Caveats §7 rewritten ("Physical location: src/class-colors/"), Module Inventory updated to list both files at the new home.
• _docs/02_document/architecture_compliance_baseline.md — F3 marked CLOSED 2026-05-13 by AZ-511 with full pre-resolution context preserved (mirrors AZ-485 → F4 / AZ-486 → F7 pattern); F4's "Carried-forward exemption" note retired.
• _docs/02_document/04_verification_log.md — open questions #1 and #8 marked RESOLVED (adjacent hygiene; the questions were the open-question form of F3 and verification needed #1).

Resolved Finding

• F3 (_docs/02_document/architecture_compliance_baseline.md): Physical / logical owner split for classColors.ts — closed by AZ-511. The 5-coupled-places carry-over surface logged in _docs/LESSONS.md 2026-05-12 is fully retired.

Test Run

• Static profile: PASS (STC-ARCH-01 with no exemptions, STC-ARCH-02 unchanged, all other gates green)
• Fast profile: 31 files / 231 passed / 13 skipped (no test count change vs. AZ-510 baseline — quarantines unchanged)
• Build: bun run build succeeded in 3.83s; 198 modules transformed; no circular-import warnings involving class-colors / annotations / DetectionClasses

Next Batch

Batch 15 (cycle 3 / batch 3 of 3) — AZ-512 admin edit detection class. Spec carries a BLOCKING cross-workspace verification at impl time: admin/ must expose PATCH /api/admin/classes/{id}. Will pause at that gate.