docs(01): create phase plan for GNN Verifier Foundation

Phase 01: gnn-verifier-foundation
- 3 plans in 3 waves (sequential)
- Plan 01: Setup PyG + Graph Builder
- Plan 02: Temporal Encoder + GAT Verifier Model
- Plan 03: Unit Tests + Integration Verification
- Ready for execution

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: vmehtacode

.planning/ROADMAP.md

@@ -12,6 +12,13 @@
 
 **Requirements:** GNN-01, GNN-02
 
+**Plans:** 3 plans
+
+Plans:
+- [ ] 01-01-PLAN.md — Setup PyG + Graph Builder (SSEN metadata to PyG Data)
+- [ ] 01-02-PLAN.md — Temporal Encoder + GAT Verifier Model
+- [ ] 01-03-PLAN.md — Unit Tests + Integration Verification
+
 **Success Criteria:**
 1. Graph construction pipeline transforms SSEN metadata into PyTorch Geometric Data batches with nodes (households, feeders, substations) and edges (physical topology)
 2. GNN model (GAT/GraphSAGE + temporal layer) processes graph-structured input and outputs per-node anomaly scores
@@ -75,7 +82,7 @@
 
 | Phase | Name | Status | Requirements | Coverage |
 |-------|------|--------|--------------|----------|
-| 1 | GNN Verifier Foundation | Not started | GNN-01, GNN-02 | 2/10 |
+| 1 | GNN Verifier Foundation | Planned | GNN-01, GNN-02 | 2/10 |
 | 2 | Hybrid Verifier Integration | Not started | GNN-03, ENS-01, ENS-02 | 3/10 |
 | 3 | Graph-Aware Proposer | Not started | SELF-01, SELF-02 | 2/10 |
 | 4 | Evaluation Framework | Not started | EVAL-01, EVAL-02, EVAL-03 | 3/10 |

.planning/phases/01-gnn-verifier-foundation/01-01-PLAN.md

@@ -0,0 +1,265 @@
+---
+phase: 01-gnn-verifier-foundation
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - pyproject.toml
+  - src/fyp/gnn/__init__.py
+  - src/fyp/gnn/graph_builder.py
+autonomous: true
+
+must_haves:
+  truths:
+    - "PyTorch Geometric is installed and importable"
+    - "SSEN feeder metadata can be transformed into PyG Data objects"
+    - "Graph has three node types: substations, feeders, households"
+    - "Edges are bidirectional representing physical connectivity"
+  artifacts:
+    - path: "src/fyp/gnn/__init__.py"
+      provides: "GNN module initialization"
+      exports: ["GridGraphBuilder"]
+    - path: "src/fyp/gnn/graph_builder.py"
+      provides: "SSEN metadata to PyG Data transformation"
+      min_lines: 100
+      contains: "class GridGraphBuilder"
+  key_links:
+    - from: "src/fyp/gnn/graph_builder.py"
+      to: "torch_geometric.data.Data"
+      via: "import and instantiation"
+      pattern: "from torch_geometric.data import Data"
+    - from: "src/fyp/gnn/graph_builder.py"
+      to: "src/fyp/ingestion/ssen_ingestor.py"
+      via: "compatible data format"
+      pattern: "feeder_id|secondary_substation|primary_substation"
+---
+
+<objective>
+Set up PyTorch Geometric dependency and implement the graph construction pipeline that transforms SSEN feeder/substation metadata into PyG Data objects.
+
+Purpose: Establishes the foundation for GNN-based anomaly detection by representing the UK distribution network as a graph structure that captures physical topology.
+
+Output: Working graph builder that produces properly formatted PyG Data with three-level node hierarchy.
+</objective>
+
+<execution_context>
+@/Users/vatsalmehta/.claude/get-shit-done/workflows/execute-plan.md
+@/Users/vatsalmehta/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/01-gnn-verifier-foundation/01-CONTEXT.md
+@.planning/phases/01-gnn-verifier-foundation/01-RESEARCH.md
+
+# Existing code to understand SSEN data format
+@src/fyp/ingestion/ssen_ingestor.py
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add PyTorch Geometric dependency</name>
+  <files>pyproject.toml</files>
+  <action>
+Add torch-geometric ^2.7.0 to the project dependencies in pyproject.toml under [tool.poetry.dependencies].
+
+Place it in the "Machine learning and statistics" section after torch.
+
+Run `poetry add torch-geometric` to install and update the lock file.
+
+Do NOT install torch-scatter or torch-sparse yet - these are optional performance optimizations.
+  </action>
+  <verify>
+```bash
+poetry run python -c "import torch_geometric; print(f'PyG version: {torch_geometric.__version__}')"
+```
+Should print PyG version 2.7.x without errors.
+  </verify>
+  <done>torch-geometric is in pyproject.toml and importable in the project environment</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Create GNN module structure</name>
+  <files>src/fyp/gnn/__init__.py</files>
+  <action>
+Create the new `src/fyp/gnn/` directory and its `__init__.py`.
+
+The __init__.py should:
+1. Import and export GridGraphBuilder from graph_builder (will be created next)
+2. Define __all__ with public exports
+3. Include module docstring explaining GNN verifier purpose
+
+Module docstring should mention:
+- Graph-based anomaly detection for UK distribution networks
+- Uses SSEN topology (substations -> feeders -> households)
+- PyTorch Geometric-based implementation
+  </action>
+  <verify>
+```bash
+ls -la src/fyp/gnn/
+```
+Directory exists with __init__.py file.
+  </verify>
+  <done>src/fyp/gnn/ module exists with proper __init__.py</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Implement GridGraphBuilder</name>
+  <files>src/fyp/gnn/graph_builder.py</files>
+  <action>
+Implement GridGraphBuilder class that transforms SSEN metadata into PyG Data objects.
+
+**Class structure:**
+```python
+class GridGraphBuilder:
+    """Build PyG graphs from SSEN distribution network topology."""
+
+    def __init__(self, exclude_incomplete: bool = True):
+        """Initialize builder.
+
+        Args:
+            exclude_incomplete: If True, skip nodes with missing metadata (recommended)
+        """
+
+    def build_from_metadata(
+        self,
+        metadata_df: pd.DataFrame,
+        node_features: dict[str, torch.Tensor] | None = None,
+    ) -> Data:
+        """Build graph from SSEN metadata DataFrame.
+
+        Expects columns: lv_feeder_id, secondary_substation_id, primary_substation_id
+        Optional: total_mpan_count, postcode, etc.
+
+        Returns:
+            PyG Data with:
+            - x: node features [num_nodes, num_features]
+            - edge_index: COO format [2, num_edges]
+            - node_type: 0=substation, 1=feeder, 2=household
+            - node_ids: original IDs for each node
+        """
+
+    def build_from_parquet(self, parquet_path: Path | str) -> Data:
+        """Convenience method to load from SSEN metadata parquet."""
+```
+
+**Implementation details:**
+
+1. **Node extraction:**
+   - Extract unique primary_substation_id -> type 0
+   - Extract unique secondary_substation_id -> type 1 (these are "feeders" in the hierarchy)
+   - Extract unique lv_feeder_id -> type 2 (these connect to households)
+   - Create node_to_idx mapping
+
+2. **Edge construction (COO format):**
+   - primary_substation <-> secondary_substation (bidirectional)
+   - secondary_substation <-> lv_feeder (bidirectional)
+   - Use torch.tensor(...).t().contiguous() pattern from research
+
+3. **Node features (if not provided):**
+   - Default: one-hot node type encoding [3 dims]
+   - Add log(total_mpan_count + 1) if available [1 dim]
+   - Total default: 4-dimensional features
+
+4. **Data object:**
+   - Always set num_nodes explicitly (handles isolated nodes)
+   - Store node_ids as string list for reverse lookup
+   - Store node_type as torch.long tensor
+
+5. **Error handling:**
+   - Log warning for missing columns
+   - Skip rows with NaN in required ID columns
+   - Track and log number of nodes/edges created
+
+**Key patterns to follow (from research):**
+```python
+# COO format construction
+edge_index = torch.tensor(edges, dtype=torch.long).t().contiguous()
+
+# Always explicit num_nodes
+data = Data(x=x, edge_index=edge_index, num_nodes=x.size(0))
+```
+
+**Anti-patterns to avoid:**
+- Do NOT use adjacency matrix format
+- Do NOT forget .contiguous() after transpose
+- Do NOT let PyG infer num_nodes from edge_index (breaks isolated nodes)
+  </action>
+  <verify>
+```bash
+poetry run python -c "
+from fyp.gnn import GridGraphBuilder
+import pandas as pd
+
+# Test with minimal mock data
+df = pd.DataFrame({
+    'primary_substation_id': ['PS1', 'PS1', 'PS1'],
+    'secondary_substation_id': ['SS1', 'SS1', 'SS2'],
+    'lv_feeder_id': ['LV1', 'LV2', 'LV3'],
+    'total_mpan_count': [50, 30, 20],
+})
+
+builder = GridGraphBuilder()
+data = builder.build_from_metadata(df)
+print(f'Nodes: {data.num_nodes}')
+print(f'Edges: {data.edge_index.size(1)}')
+print(f'Node types: {data.node_type.unique().tolist()}')
+print(f'Features shape: {data.x.shape}')
+assert data.num_nodes == 6  # 1 PS + 2 SS + 3 LV
+assert 0 in data.node_type.tolist()  # has substations
+assert 2 in data.node_type.tolist()  # has feeders
+print('SUCCESS')
+"
+  </verify>
+  <done>GridGraphBuilder correctly transforms SSEN metadata into PyG Data with proper node hierarchy and bidirectional edges</done>
+</task>
+
+</tasks>
+
+<verification>
+After all tasks complete:
+
+1. **Dependency verification:**
+```bash
+poetry run python -c "import torch_geometric; from torch_geometric.data import Data; print('OK')"
+```
+
+2. **Module import verification:**
+```bash
+poetry run python -c "from fyp.gnn import GridGraphBuilder; print('OK')"
+```
+
+3. **Graph structure verification with real SSEN data (if available):**
+```bash
+poetry run python -c "
+from fyp.gnn import GridGraphBuilder
+from pathlib import Path
+
+parquet_path = Path('data/processed/ssen_metadata.parquet')
+if parquet_path.exists():
+    builder = GridGraphBuilder()
+    data = builder.build_from_parquet(parquet_path)
+    print(f'Real SSEN graph: {data.num_nodes} nodes, {data.edge_index.size(1)} edges')
+else:
+    print('SSEN metadata not available, skipping real data test')
+"
+```
+</verification>
+
+<success_criteria>
+- [ ] torch-geometric ^2.7.0 in pyproject.toml and importable
+- [ ] src/fyp/gnn/ module exists with proper structure
+- [ ] GridGraphBuilder transforms SSEN metadata to PyG Data
+- [ ] Graph has correct three-level hierarchy (substation -> feeder -> household)
+- [ ] Edges are bidirectional (edge count = 2 * physical connections)
+- [ ] Node features include type encoding and optional metadata
+- [ ] num_nodes explicitly set (handles isolated nodes)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-gnn-verifier-foundation/01-01-SUMMARY.md`
+</output>