docs: define actionable planned feature delivery tracks

Author: kygeospatial

README.md

@@ -124,6 +124,10 @@ Planned features include:
 - distributed dataset comparison
 - visualization tooling
 
+Execution plan and acceptance criteria are tracked in:
+
+- `docs/planned-features.md`
+
 ---
 
 ## Contributing

docs/planned-features.md

@@ -0,0 +1,121 @@
+# Planned Features Delivery Plan
+
+This plan turns roadmap bullets into implementable tracks with clear ownership and acceptance criteria.
+
+## Track 1: Advanced Spatial Diff Algorithms
+
+### Scope
+- Add geometry-aware comparison modes in `faultline_diff`.
+- Support configurable tolerance and deterministic classification output.
+- Preserve stable artifact schema for downstream sync and audit consumers.
+
+### Crates
+- `faultline_rust_scaffold/crates/faultline-diff`
+- `faultline_rust_scaffold/crates/faultline-geometry`
+- `faultline_rust_scaffold/crates/faultline-core`
+
+### Milestones
+1. Add algorithm strategy enum and config object in diff models.
+2. Implement baseline geometry-aware comparator using existing geometry primitives.
+3. Add golden fixtures and deterministic output tests.
+4. Expose CLI flags for strategy selection and tolerance.
+
+### Acceptance Criteria
+- Same input fixtures produce byte-stable diff artifacts.
+- Geometry changes are classified separately from attribute-only changes.
+- Test coverage includes insert/update/remove plus geometry delta scenarios.
+
+## Track 2: Topology Change Detection
+
+### Scope
+- Introduce topology validation and topology-specific change event classification.
+- Emit explicit rule violations for invalid geometries.
+
+### Crates
+- `faultline_rust_scaffold/crates/faultline-geometry`
+- `faultline_rust_scaffold/crates/faultline-diff`
+
+### Milestones
+1. Define topology rule set and violation model.
+2. Add rule evaluators for closed ring and self-intersection checks.
+3. Integrate violations into diff artifact output.
+4. Add fixtures for valid and invalid topology transitions.
+
+### Acceptance Criteria
+- Topology violations are represented with deterministic rule IDs.
+- Diff outputs include topology-specific classification events when applicable.
+
+## Track 3: Cloud Optimization Validation Rules
+
+### Scope
+- Add validation contracts and checks for cloud-native geospatial artifact expectations.
+- Start with format-agnostic rules and add format-specific adapters incrementally.
+
+### Crates
+- `faultline_rust_scaffold/crates/faultline-core`
+- `faultline_rust_scaffold/crates/faultline-compute`
+- `faultline_rust_scaffold/apps/faultline-cli`
+
+### Milestones
+1. Define validation result schema and severity model.
+2. Add initial rule engine and rule registry.
+3. Add CLI `validate` command behavior backed by rule execution.
+4. Add report output in JSON for automation pipelines.
+
+### Acceptance Criteria
+- Validation run returns machine-readable JSON with rule IDs and severities.
+- CLI exit codes support CI use cases (pass/warn/fail policy).
+
+## Track 4: Distributed Dataset Comparison
+
+### Scope
+- Add remote/local snapshot comparison contract and transport-agnostic interfaces.
+- Keep transport implementation separate from comparison core.
+
+### Crates
+- `faultline_rust_scaffold/crates/faultline-sync`
+- `faultline_rust_scaffold/crates/faultline-diff`
+- `faultline_rust_scaffold/crates/faultline-index`
+
+### Milestones
+1. Define remote snapshot descriptor and fetch contract.
+2. Add distributed comparison session interface.
+3. Implement local simulation harness for peer-vs-peer diff tests.
+4. Add conflict and divergence reporting artifacts.
+
+### Acceptance Criteria
+- Remote descriptor contract supports deterministic compare requests.
+- Divergence reports include enough detail for remediation.
+
+## Track 5: Visualization Tooling
+
+### Scope
+- Add a minimal visualization layer for diff and topology outputs.
+- Keep renderer decoupled from core engine outputs.
+
+### Components
+- `faultline_rust_scaffold/apps/faultline-web`
+- Optional CLI report rendering in `apps/faultline-cli`
+
+### Milestones
+1. Define visualization data contract from diff artifacts.
+2. Implement first map overlay prototype for before/after geometry and change classes.
+3. Add topology violation layer.
+4. Add exportable report assets.
+
+### Acceptance Criteria
+- Visualization reads canonical artifact JSON without transformation hacks.
+- Change classes and topology violations are visually distinct.
+
+## Recommended Execution Order
+1. Advanced Spatial Diff Algorithms
+2. Topology Change Detection
+3. Cloud Optimization Validation Rules
+4. Distributed Dataset Comparison
+5. Visualization Tooling
+
+## Suggested Immediate Sprint (next 1-2 weeks)
+- Implement Track 1 Milestones 1 and 2.
+- Implement Track 2 Milestone 1.
+- Add fixture set expansion for deterministic diff and topology assertions.
+- Ship CLI flags for diff strategy and tolerance behind stable defaults.