refactor: restructure packages into domain-specific modules

microfinity:
- microfinity.core.constants -> microfinity.spec.constants
- microfinity.core.base -> microfinity.parts.base
- microfinity.core.helpers -> microfinity.cq.helpers
- microfinity.core.export -> microfinity.cq.export
- microfinity.core.spec -> microfinity.spec.loader

meshcutter:
- meshcutter.core.* -> meshcutter.{pipeline,cutter,detection,mesh}.*
- meshcutter.core.constants -> meshcutter.constants
- meshcutter.core.replace_base -> meshcutter.pipeline.replace_base
- meshcutter.core.detection -> meshcutter.detection.footprint
- meshcutter.core.boolean -> meshcutter.mesh.boolean

Also:
- Delete legacy microfinity/scripts/ CLI entry points
- Move tests into package directories
- Consolidate shared CadQuery utilities in microfinity.cq

Author: Your Name

CLAUDE.md

@@ -9,6 +9,65 @@ This file provides context for Claude when working on this project.
 1. **microfinity/** - CadQuery-based generator for boxes, baseplates, and spacers
 2. **meshcutter/** - Mesh-based tool to convert 1U Gridfinity boxes to micro-divided feet
 
+## Package Structure
+
+### microfinity/
+```
+microfinity/
+├── __init__.py           # Package exports and version
+├── py.typed              # PEP 561 marker
+├── cli/                  # CLI commands
+│   ├── main.py           # Unified CLI entry point
+│   └── debug.py          # Debug subcommands
+├── spec/                 # Gridfinity specifications
+│   ├── loader.py         # YAML spec loading
+│   └── constants.py      # Derived constants
+├── cq/                   # CadQuery utilities (shared)
+│   ├── compat.py         # ZLEN_FIX version detection
+│   ├── extrude.py        # extrude_profile()
+│   ├── helpers.py        # Geometry helpers
+│   └── export.py         # STEP/STL/SVG export
+├── parts/                # Gridfinity objects
+│   ├── base.py           # GridfinityObject base class
+│   ├── box.py            # GridfinityBox
+│   ├── baseplate.py      # GridfinityBaseplate
+│   ├── baseplate_layout.py
+│   └── drawer.py         # GridfinityDrawerSpacer
+├── calibration/          # Calibration prints
+│   └── test_prints.py
+└── tests/                # Package tests
+```
+
+### meshcutter/
+```
+meshcutter/
+├── __init__.py           # Package exports
+├── py.typed              # PEP 561 marker
+├── constants.py          # Re-exports + meshcutter-specific
+├── cli/                  # CLI commands
+│   └── meshcut.py
+├── pipeline/             # Main conversion pipelines
+│   └── replace_base.py
+├── cutter/               # Cutter geometry generation
+│   ├── base.py           # generate_cutter()
+│   ├── cq.py             # CadQuery cutter generation
+│   ├── foot.py           # Micro-foot generation
+│   └── grid.py           # Grid/offset calculations
+├── detection/            # Mesh analysis
+│   ├── footprint.py      # Bottom frame detection
+│   └── validation.py     # Geometry validation
+├── mesh/                 # Mesh operations
+│   ├── convert.py        # Trimesh/Manifold conversions
+│   ├── boolean.py        # Boolean operations
+│   ├── geometry.py       # 2D geometry helpers
+│   ├── grid.py           # Grid mask generation
+│   └── profile.py        # Profile constants
+├── io/                   # File I/O
+│   ├── loader.py
+│   └── exporter.py
+└── tests/                # Package tests
+```
+
 ## Key Architecture Decisions
 
 ### Meshcutter: Replace-Base Approach
@@ -21,11 +80,10 @@ The meshcutter uses a **replace-base pipeline** (not boolean subtraction) to con
 
 This produces geometry **identical** to natively-generated micro boxes (<1mm³ difference).
 
-**Important**: The legacy boolean subtraction approach has been deprecated and removed.
-
 ### Gridfinity Constants
 
-All Gridfinity constants should come from `meshcutter/core/constants.py`, which re-exports from `microfinity.core.constants`.
+All Gridfinity constants should come from `microfinity.spec.constants`, which loads from YAML specs.
+Meshcutter re-exports these via `meshcutter.constants`.
 
 Key values:
 - `GRU = 42.0` - 1U pitch (mm)
@@ -34,52 +92,41 @@ Key values:
 - `GR_BASE_CLR = 0.25` - Clearance above foot
 - `Z_SPLIT_HEIGHT = 5.0` - Where we cut between top and base
 
-## Important Files
+### Shared CadQuery Utilities
 
-### Core Modules
-- `meshcutter/core/replace_base.py` - Main replace-base pipeline
-- `meshcutter/core/constants.py` - Centralized constants
-- `meshcutter/core/mesh_utils.py` - Mesh conversion utilities
-- `meshcutter/core/cq_utils.py` - CadQuery utilities
-- `meshcutter/core/grid_utils.py` - Grid/offset calculations
+All CadQuery utilities live in `microfinity.cq/`:
+- `ZLEN_FIX` detection - single source of truth
+- `extrude_profile()` - shared by both packages
+- Export utilities (STEP/STL/SVG)
 
-### CLI
-- `meshcutter/cli/meshcut.py` - Command-line interface
+Meshcutter imports from `microfinity.cq` instead of duplicating.
+
+## Testing
 
-### Tests
-- `tests/test_meshcutter/test_golden.py` - Golden comparison tests
-- `tests/test_meshcutter/golden_utils.py` - Test utilities
+### Running Tests
+```bash
+# All tests
+pytest -v
 
-## Refactoring Tracking
+# Microfinity tests only
+pytest microfinity/tests/ -v
 
-**IMPORTANT**: When completing refactoring tasks, update `REFACTOR_TODO.md` to mark items as complete.
+# Meshcutter tests only
+pytest meshcutter/tests/ -v
 
-The refactoring TODO file tracks:
-- DRY elimination (utility modules)
-- Module updates
-- Test creation
-- CI setup
+# Shared/integration tests
+pytest tests/ -v
 
-## Testing
+# Skip slow golden tests
+pytest -v -m "not golden"
+```
 
 ### Golden Tests
 Golden tests compare meshcutter output against microfinity-generated references:
 - Reference meshes are generated on-demand (not stored)
 - Acceptance threshold: <1mm³ total geometric difference
 - Test configurations: 1x1x1, 2x3x2, 1x1x3, 3x3x1
 
-### Running Tests
-```bash
-# All meshcutter tests
-pytest tests/test_meshcutter/ -v
-
-# Just golden tests
-pytest tests/test_meshcutter/test_golden.py -v
-
-# Quick unit tests (skip slow golden tests)
-pytest tests/test_meshcutter/ -v -m "not golden"
-```
-
 ## Code Style
 
 - **Line length**: 120 characters (configured in pyproject.toml)
@@ -90,16 +137,16 @@ pytest tests/test_meshcutter/ -v -m "not golden"
 ## Common Tasks
 
 ### Adding a New Micro-Division Size
-1. Update `meshcutter/core/grid_utils.py` if offset calculations change
-2. Add test configuration to `tests/test_meshcutter/test_golden.py`
+1. Update `meshcutter/cutter/grid.py` if offset calculations change
+2. Add test configuration to `meshcutter/tests/test_golden.py`
 3. Update `docs/TODO_FUTURE_DIVISIONS.md`
 
 ### Updating Constants
-1. Check if constant exists in `microfinity.core.constants`
-2. If yes, re-export in `meshcutter/core/constants.py`
+1. Check if constant exists in `microfinity.spec.constants`
+2. If yes, re-export in `meshcutter/constants.py`
 3. If no, add to meshcutter-specific section
 
 ### Debugging Mesh Issues
-1. Use `mesh_utils.get_mesh_diagnostics()` for mesh info
+1. Use `meshcutter.mesh.convert.get_mesh_diagnostics()` for mesh info
 2. Export intermediate meshes with `mesh.export('/tmp/debug.stl')`
 3. View in external tool (MeshLab, Blender)

lefthook.yml

@@ -8,6 +8,10 @@ pre-commit:
     lint-fix:
       glob: "*.py"
       run: black {staged_files} && git add {staged_files}
+    flake8:
+      glob: "*.py"
+      fail_text: "Lint warnings found (non-blocking)"
+      run: flake8 {staged_files} --max-line-length=120 --extend-ignore=E203,W503,F401,F403,F405,E402,F821,W293,W605,F841 || true
 
 commit-msg:
   commands:

meshcutter/__init__.py

@@ -1,19 +1,18 @@
 #! /usr/bin/env python3
-#
-# meshcutter - Gridfinity mesh profile cutter
-#
-# Cut gridfinity micro-division profiles into existing STL/3MF models
-# using mesh boolean operations.
-#
-# Part of the microfinity package - shares version with microfinity.
-#
+"""
+meshcutter - Gridfinity mesh profile cutter.
+
+Cut gridfinity micro-division profiles into existing STL/3MF models
+using mesh boolean operations.
+
+Part of the microfinity package - shares version with microfinity.
+"""
 
 from microfinity import __version__
 
-from meshcutter.core.detection import detect_bottom_frame, extract_footprint
-from meshcutter.core.grid import generate_grid_mask, compute_grid_positions
-from meshcutter.core.cutter import generate_cutter
-from meshcutter.core.boolean import boolean_difference, repair_mesh
+from meshcutter.detection import detect_bottom_frame, extract_footprint
+from meshcutter.mesh import generate_grid_mask, compute_grid_positions, boolean_difference, repair_mesh
+from meshcutter.cutter import generate_cutter
 from meshcutter.io.loader import load_mesh
 from meshcutter.io.exporter import export_stl
 

meshcutter/cli/meshcut.py

@@ -18,17 +18,17 @@
 from pathlib import Path
 
 from meshcutter import __version__
-from meshcutter.core.constants import (
+from meshcutter.constants import (
     GR_BASE_HEIGHT,
     COPLANAR_EPSILON,
     MIN_COMPONENT_FACES,
     MIN_SLIVER_SIZE,
     MIN_SLIVER_VOLUME,
     GRU,
 )
-from meshcutter.core.detection import detect_aligned_frame
-from meshcutter.core.foot_cutter import generate_microgrid_cutter, convert_to_micro_feet
-from meshcutter.core.boolean import (
+from meshcutter.detection.footprint import detect_aligned_frame
+from meshcutter.cutter.foot import generate_microgrid_cutter, convert_to_micro_feet
+from meshcutter.mesh.boolean import (
     boolean_difference,
     validate_boolean_inputs,
     check_manifold3d_available,
@@ -508,7 +508,7 @@ def run_meshcut(args: argparse.Namespace) -> None:
             print(f"  Footprint: {width:.1f} x {height:.1f} mm")
 
             # Infer cell count
-            from meshcutter.core.foot_cutter import detect_cell_centers
+            from meshcutter.cutter.foot import detect_cell_centers
 
             centers = detect_cell_centers(footprint, GRU)
             cells_x = int(round((width + 0.5) / GRU))
@@ -573,7 +573,7 @@ def run_meshcut(args: argparse.Namespace) -> None:
 
         # Validate cutter geometry (detect internal faces / stacked sheets)
         if not args.no_validate:
-            from meshcutter.core.validation import validate_cutter_geometry, CutterValidationError
+            from meshcutter.detection.validation import validate_cutter_geometry, CutterValidationError
 
             if args.verbose:
                 print("Validating cutter geometry...", end=" ", flush=True)

meshcutter/core/constants.py meshcutter/constants.pymeshcutter/core/constants.py renamed to meshcutter/constants.py

@@ -1,14 +1,15 @@
 #! /usr/bin/env python3
-#
-# meshcutter.core.constants - Centralized Gridfinity constants
-#
-# Re-exports constants from microfinity.core.constants for consistency,
-# plus meshcutter-specific constants for the replace-base pipeline.
+"""
+meshcutter.constants - Centralized Gridfinity constants.
+
+Re-exports constants from microfinity.spec.constants for consistency,
+plus meshcutter-specific constants for the replace-base pipeline.
+"""
 
 from __future__ import annotations
 
 # Re-export Gridfinity constants from microfinity
-from microfinity.core.constants import (
+from microfinity.spec.constants import (
     GRU,  # 42.0 - 1U pitch (mm)
     GR_TOL,  # 0.5 - Clearance between feet (mm)
     GR_RAD,  # 4.0 - Nominal exterior fillet radius (mm)
@@ -25,20 +26,18 @@
 # -----------------------------------------------------------------------------
 
 # Z_SPLIT_HEIGHT is the plane where we cut between top (kept) and base (replaced)
-# z_split = z_min + GR_BASE_HEIGHT + GR_BASE_CLR = z_min + 5.0mm
 Z_SPLIT_HEIGHT: float = GR_BASE_HEIGHT + GR_BASE_CLR  # 4.75 + 0.25 = 5.0mm
 
 # SLEEVE_HEIGHT - how far the new base extends ABOVE z_split for overlap
-# This is critical: overlap ensures robust union (no coplanar faces)
 SLEEVE_HEIGHT: float = 0.5  # mm
 
 # COPLANAR_EPSILON - offset to avoid coplanar geometry issues in booleans
 COPLANAR_EPSILON: float = 0.02  # mm
 
 # Mesh cleanup thresholds
 MIN_COMPONENT_FACES: int = 100  # Minimum faces to keep a component
-MIN_SLIVER_SIZE: float = 0.001  # 1 µm - any dimension smaller is suspicious
-MIN_SLIVER_VOLUME: float = 1e-12  # mm³ - volumes below this are effectively zero
+MIN_SLIVER_SIZE: float = 0.001  # 1 micron
+MIN_SLIVER_VOLUME: float = 1e-12  # mm^3
 
 # Golden test acceptance threshold
-MAX_VOLUME_DIFF_MM3: float = 1.0  # Maximum acceptable difference in mm³
+MAX_VOLUME_DIFF_MM3: float = 1.0  # mm^3

meshcutter/core/__init__.py

@@ -0,0 +1,16 @@
+#! /usr/bin/env python3
+"""
+meshcutter.cutter - Cutter geometry generation.
+
+Provides functions for generating micro-foot cutters using CadQuery.
+"""
+
+from meshcutter.cutter.base import generate_cutter
+from meshcutter.cutter.grid import micro_foot_offsets_single_cell, micro_foot_offsets_grid, detect_cell_centers
+
+__all__ = [
+    "generate_cutter",
+    "micro_foot_offsets_single_cell",
+    "micro_foot_offsets_grid",
+    "detect_cell_centers",
+]

meshcutter/cutter/__init__.py

@@ -1,6 +1,6 @@
 #! /usr/bin/env python3
 #
-# meshcutter.core.cutter - 2D to 3D extrusion for cutter mesh generation
+# meshcutter.cutter - 2D to 3D extrusion for cutter mesh generation
 #
 
 from __future__ import annotations
@@ -12,8 +12,8 @@
 from shapely.geometry import Polygon, MultiPolygon
 from shapely.ops import unary_union
 
-from meshcutter.core.detection import BottomFrame
-from meshcutter.core.profile import CutterProfile, get_profile, PROFILE_RECTANGULAR
+from meshcutter.detection.footprint import BottomFrame
+from meshcutter.mesh.profile import CutterProfile, get_profile, PROFILE_RECTANGULAR
 
 
 # Penetration below the bottom plane to avoid coplanar boolean degeneracy.