Implement point-in-zone classifier tool (E03 step 4)

[IanMayo]

Summary

Implement the point-in-zone classifier tool — step 4 of the E03 buffer zone analysis chain. This tool classifies reference points by testing each coordinate against concentric detection zone polygons using a ray-casting point-in-polygon algorithm, then updates per-point metadata with zone assignment and color.

Key Changes

Specification & Documentation

• Feature specification at specs/081-point-in-zone-classifier/spec.md with 3 user stories and 14 functional requirements
• Tool specification at shared/tools/reference/classification/point-in-zone-classifier.1.0.md covering algorithm, inputs, outputs, and annotations
• Golden example pairs (basic classification + all-outside scenarios) with input/output JSON files
• Supporting documentation: research decisions, data model, tool contract, quickstart, and implementation plan

Python Implementation

• services/calc/debrief_calc/tools/reference/classification.py — core tool implementation with:
  • _point_in_polygon(): Ray-casting algorithm for point-in-polygon testing
  • point_in_zone_classifier(): Main classifier function registered via @tool decorator with ContextType.MULTI
  • Innermost-first zone priority (most specific zone wins)
  • Metadata preservation and extension with zone and color fields
  • pointColors array generation for per-point rendering
• Tool registration in services/calc/debrief_calc/tools/reference/__init__.py and services/calc/debrief_calc/tools/__init__.py

TypeScript Implementation

• apps/vscode/src/tools/reference/classification/pointInZoneClassifier.ts — identical algorithm in TypeScript with:
  • Ray-casting point-in-polygon implementation
  • Zone classification with innermost-first priority
  • Metadata preservation and color assignment
• Barrel export at apps/vscode/src/tools/reference/classification/index.ts
• Tool registration in apps/web-shell/src/services/toolService.ts

Comprehensive Test Suite

• services/calc/tests/tools/reference/test_classification.py — 22 tests covering:
  • TestClassifyBasic (7 tests): Zone assignment, point colors array, innermost-first priority
  • TestMetadataPreservation (4 tests): Field preservation, reclassification, immutability
  • TestDeterminism (2 tests): Reproducibility and geometry preservation
  • TestEdgeCases (7 tests): Missing features, invalid geometry, metadata mismatches, empty inputs
  • TestGoldenExamples (2 tests): Validation against golden I/O files

Implementation Details

• Algorithm: Ray-casting (even-odd rule) for O(n) point-in-polygon testing per point
• Zone Priority: Tests zones innermost-first; first match wins (prevents outer zones from overriding inner)
• Metadata Handling: Deep copies input metadata, preserves all existing fields, adds/updates zone and color
• Color Mapping: Extracts from zone metadata style.fill_color (preferred) or style.color; defaults to #666666 for points outside all zones
• Dependencies: Stdlib only (no external geometry libraries) — Constitution Article I (offline) and Article IX (minimal dependencies) compliant
• Performance: Classifies 10,000 points against 3 zones in < 1 second

All 22 tests passing. Zero external dependencies. Ready for integration with generate-reference-points (#78) and buffer-zone-generator (#80).

https://claude.ai/code/session_01EWe9YQXUrUdynXavqEZUmG

[github-actions]

🚀 Preview Deployments

Web Shell (Standalone App)

📱 Open Web Shell

Use this for Playwright testing and demos - runs outside Storybook.

Storybook (Component Library)

📚 Open Storybook

Browse all components, stories, and documentation.

---

All Links

Environment	Web Shell	Storybook
This PR	Open App	Open Storybook
Main branch	Open App	Open Storybook

Updated on commit adb50fa