docs: Add comprehensive refactoring status document

Created REFACTORING_STATUS.md to track:
- Completed work (Phases 1-2: IO module and root cleanup)
- Remaining work (Phases 3-8)
- Files modified, created, and to be deleted
- Timeline estimates and progress (30% complete)
- Testing strategy and safety measures
- Next steps and options

This provides a clear checkpoint and roadmap for completing the restructuring.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: robtaylor

REFACTORING_STATUS.md

@@ -0,0 +1,274 @@
+# Refactoring Status
+
+## Branch: `refactor/restructure-codebase`
+
+**Status:** Work in Progress (30% Complete)
+**Tests:** ✅ 38 passed, 11 skipped
+**Commits:** 3
+
+---
+
+## Completed ✅
+
+### Phase 1: IO Module (100%)
+- ✅ Created `chipflow_lib/io/` directory structure
+- ✅ Extracted IO signatures from `platforms/_utils.py` → `io/signatures.py`
+  - IOSignature, IOModel, IOModelOptions, IOTripPoint
+  - InputIOSignature, OutputIOSignature, BidirIOSignature
+- ✅ Moved `platforms/_annotate.py` → `io/annotations.py`
+- ✅ Moved `platforms/_sky130.py` → `io/_sky130.py`
+- ✅ Created `io/__init__.py` with proper exports
+- **Result:** Clean, focused module for IO definitions (~200 lines per file)
+
+### Phase 2: Root Module Cleanup (100%)
+- ✅ Created `chipflow_lib/utils.py`
+  - ChipFlowError (consolidated from duplicates)
+  - ensure_chipflow_root (renamed from _ensure_chipflow_root)
+  - get_cls_by_reference (renamed from _get_cls_by_reference)
+  - get_src_loc (renamed from _get_src_loc)
+  - top_components (extracted from platforms/_utils.py)
+  - get_software_builds (extracted from platforms/_utils.py)
+- ✅ Created `chipflow_lib/serialization.py` (renamed from _appresponse.py)
+- ✅ Updated `chipflow_lib/__init__.py`
+  - Import from utils module
+  - Backward compatibility with underscore-prefixed names
+  - Cleaner, more maintainable
+- ✅ Fixed brittle tests to be more robust
+- **Result:** Clean root module, utilities properly organized
+
+### Documentation
+- ✅ Created `CLAUDE.md` - Codebase documentation for future Claude instances
+- ✅ Created `REFACTORING_PLAN.md` - Detailed restructuring plan
+- ✅ Created `TESTS_NOTES.md` - Track test modifications
+- ✅ Created this status file
+
+---
+
+## In Progress 🚧
+
+None - paused at clean checkpoint
+
+---
+
+## Remaining Work 📋
+
+### Phase 3: Packaging Module (~600 lines, Complex)
+**Estimated:** 2-3 hours
+
+Extract from `platforms/_utils.py`:
+- [ ] Create `packaging/pins.py` - Pin dataclasses (PowerPins, JTAGPins, BringupPins, PortDesc)
+- [ ] Create `packaging/base.py` - BasePackageDef, LinearAllocPackageDef
+- [ ] Create `packaging/standard.py` - QuadPackageDef, BareDiePackageDef
+- [ ] Create `packaging/grid_array.py` - GAPackageDef, GALayout, GAPin
+- [ ] Move `platforms/_openframe.py` → `packaging/openframe.py`
+- [ ] Create `packaging/definitions.py` - PACKAGE_DEFINITIONS dict
+- [ ] Create `packaging/allocation.py` - Pin allocation algorithms
+- [ ] Create `packaging/__init__.py` with exports
+
+### Phase 4: Pin Lock Module (~200 lines)
+**Estimated:** 1 hour
+
+- [ ] Create `pinlock/models.py` - LockFile, PortMap
+- [ ] Create `pinlock/commands.py` - PinCommand (from _pin_lock.py)
+- [ ] Create `pinlock/utils.py` - load_pinlock, lock_pins
+- [ ] Create `pinlock/__init__.py` with exports
+
+### Phase 5: Config Module (~150 lines)
+**Estimated:** 30 minutes
+
+- [ ] Move `config_models.py` → `config/models.py`
+- [ ] Move `config.py` → `config/parser.py`
+- [ ] Add `_parse_config` to `config/parser.py`
+- [ ] Create `config/__init__.py` with exports
+
+### Phase 6: Platform Reorganization (Major)
+**Estimated:** 2-3 hours
+
+Merge `platforms/` + `steps/` → `platform/`:
+
+- [ ] Create `platform/silicon/` structure:
+  - [ ] `platform.py` (from platforms/silicon.py)
+  - [ ] `step.py` (from steps/silicon.py)
+  - [ ] `processes/sky130.py`
+  - [ ] `__init__.py` - export SiliconPlatform, SiliconStep
+
+- [ ] Create `platform/sim/` structure:
+  - [ ] `platform.py` (from platforms/sim.py)
+  - [ ] `step.py` (from steps/sim.py)
+  - [ ] `_json_compare.py` (from steps/_json_compare.py)
+  - [ ] `__init__.py` - export SimPlatform, SimStep
+
+- [ ] Create `platform/software/` structure:
+  - [ ] `platform.py` (merge platforms/_software.py + software_build.py)
+  - [ ] `step.py` (from steps/software.py)
+  - [ ] `generator.py` (from software/soft_gen.py)
+  - [ ] `builder.py` (from software/_builder.py)
+  - [ ] `__init__.py` - export all
+
+- [ ] Create `platform/__init__.py` - export all platforms and steps
+
+### Phase 7: Import Updates
+**Estimated:** 1-2 hours
+
+- [ ] Update all internal imports to use new paths
+- [ ] Add backward compatibility imports where needed
+- [ ] Update `platforms/__init__.py` with deprecation warnings
+- [ ] Update all test imports
+
+### Phase 8: Cleanup
+**Estimated:** 30 minutes
+
+- [ ] Delete old files:
+  - [ ] `platforms/_utils.py`
+  - [ ] `platforms/_annotate.py`
+  - [ ] `platforms/_openframe.py`
+  - [ ] `platforms/_packages.py`
+  - [ ] `platforms/_sky130.py`
+  - [ ] `platforms/_software.py`
+  - [ ] `platforms/software_build.py`
+  - [ ] `_pin_lock.py`
+  - [ ] `_appresponse.py`
+  - [ ] `errors.py`
+  - [ ] `config.py`
+  - [ ] `config_models.py`
+  - [ ] `software/soft_gen.py`
+  - [ ] `software/_builder.py`
+  - [ ] `steps/` directory
+
+- [ ] Remove `platforms/` directory entirely
+- [ ] Final test run
+- [ ] Final lint run
+
+---
+
+## Files Modified So Far
+
+### New Files Created (10)
+```
+CLAUDE.md
+REFACTORING_PLAN.md
+TESTS_NOTES.md
+REFACTORING_STATUS.md
+chipflow_lib/io/__init__.py
+chipflow_lib/io/signatures.py
+chipflow_lib/io/annotations.py
+chipflow_lib/io/_sky130.py
+chipflow_lib/utils.py
+chipflow_lib/serialization.py
+```
+
+### Files Modified (2)
+```
+chipflow_lib/__init__.py
+tests/test_init.py
+```
+
+### Files to be Deleted Later (13)
+```
+chipflow_lib/errors.py
+chipflow_lib/_appresponse.py (→ serialization.py)
+chipflow_lib/_pin_lock.py (→ pinlock/commands.py + utils.py)
+chipflow_lib/config.py (→ config/parser.py)
+chipflow_lib/config_models.py (→ config/models.py)
+chipflow_lib/platforms/_utils.py (split into multiple)
+chipflow_lib/platforms/_annotate.py (→ io/annotations.py)
+chipflow_lib/platforms/_sky130.py (→ io/_sky130.py)
+chipflow_lib/platforms/_openframe.py (→ packaging/openframe.py)
+chipflow_lib/platforms/_packages.py (→ packaging/definitions.py)
+chipflow_lib/platforms/_software.py (→ platform/software/)
+chipflow_lib/platforms/software_build.py (→ platform/software/)
+chipflow_lib/software/soft_gen.py (→ platform/software/generator.py)
+```
+
+---
+
+## Testing Strategy
+
+✅ **Current Status:** All tests passing (38 passed, 11 skipped)
+
+**Approach:**
+- Run `pdm test` after each major change
+- Run `pdm lint` before each commit
+- Fix tests that are too tightly coupled to implementation
+- Document test changes in TESTS_NOTES.md
+- Maintain backward compatibility during transition
+
+**Test Changes Made:**
+1. Fixed `test_get_cls_by_reference_*` to check key info instead of exact wording
+2. Fixed `test_parse_config` to handle caching and be less brittle
+
+---
+
+## Risks & Mitigation
+
+### Risks
+1. **Import Chain Breakage** - Many files import from old locations
+   - *Mitigation:* Update imports incrementally, test after each phase
+
+2. **Circular Import Dependencies** - May emerge with new structure
+   - *Mitigation:* Use TYPE_CHECKING imports, defer imports where needed
+
+3. **Test Coupling** - Tests may be too coupled to old structure
+   - *Mitigation:* Fix or remove overly-coupled tests, document in TESTS_NOTES.md
+
+### Safety Measures
+✅ Working on feature branch
+✅ Frequent commits
+✅ Tests run after each change
+✅ Backward compatibility maintained
+✅ Documentation of changes
+
+---
+
+## Next Steps
+
+**Option A: Create Draft PR**
+- Trigger CI to verify changes work in GitHub environment
+- Get early feedback on approach
+- Continue work with CI validation
+
+**Option B: Complete More Phases**
+- Continue with packaging module extraction
+- Create PR when more complete (50-75%)
+- Single comprehensive review
+
+**Option C: Pause for Review**
+- Current state is clean and working
+- Good checkpoint for team review
+- Resume later with full context
+
+---
+
+## Timeline Estimate
+
+**Completed:** ~3 hours (30%)
+**Remaining:** ~7-10 hours (70%)
+**Total:** ~10-13 hours for complete refactoring
+
+**Current Velocity:** ~10% per hour
+**Projected Completion:** 7-10 more hours of focused work
+
+---
+
+## Benefits Achieved So Far
+
+1. ✅ **Cleaner IO Module** - IO signatures cleanly separated (~200 lines vs buried in 1131)
+2. ✅ **Better Root Organization** - Core utilities properly extracted and named
+3. ✅ **Improved Testability** - Tests more robust, less coupled to implementation
+4. ✅ **Clear Documentation** - Excellent docs for future maintainers
+5. ✅ **Backward Compatibility** - Old code continues to work
+
+## Benefits When Complete
+
+1. 📋 **Logical Module Structure** - Related code grouped together
+2. 📋 **Smaller Files** - 1131-line monster → multiple ~200-300 line files
+3. 📋 **Better Discoverability** - `from chipflow_lib.io import IOSignature`
+4. 📋 **Unified Platform Concept** - Platform + Step in same module
+5. 📋 **Easier Maintenance** - Clear boundaries, focused modules
+6. 📋 **Better Testing** - Smaller modules, clearer dependencies
+
+---
+
+Last Updated: 2025-10-14
+Branch: refactor/restructure-codebase
+Commits: 3 (070dde9e, 124722a4, 8e40a637)