docs(03-01): complete graph-aware proposer plan

- SUMMARY.md with 3 task commits, 24 tests, 2 files
- STATE.md updated with position, decisions, metrics
- ROADMAP.md updated with phase 03 progress (1/2 plans)
- REQUIREMENTS.md: SELF-01, SELF-02 marked complete

Author: vmehtacode

.planning/REQUIREMENTS.md

@@ -15,8 +15,8 @@ Requirements for this milestone. Each maps to roadmap phases.
 
 ### Self-Play Enhancement
 
-- [ ] **SELF-01**: Implement graph-aware Proposer generating topology-respecting scenarios
-- [ ] **SELF-02**: Scenarios cascade through neighbors (COLD_SNAP, OUTAGE propagation)
+- [x] **SELF-01**: Implement graph-aware Proposer generating topology-respecting scenarios
+- [x] **SELF-02**: Scenarios cascade through neighbors (COLD_SNAP, OUTAGE propagation)
 
 ### Three-Layer Ensemble
 

.planning/ROADMAP.md

@@ -64,7 +64,7 @@ Plans:
 **Plans:** 2 plans in 2 waves
 
 Plans:
-- [ ] 03-01-PLAN.md — Graph-aware proposer tests + implementation (TDD)
+- [x] 03-01-PLAN.md — Graph-aware proposer tests + implementation (TDD)
 - [ ] 03-02-PLAN.md — SelfPlayTrainer integration + integration tests
 
 **Success Criteria:**

.planning/STATE.md

@@ -2,14 +2,14 @@
 gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: — GNN-Based Anomaly Detection with Self-Play Validation
-status: verifying
+status: executing
 stopped_at: Completed 04-04-PLAN.md
-last_updated: "2026-03-28T12:17:35.187Z"
+last_updated: "2026-03-28T14:04:04.276Z"
 last_activity: 2026-03-28
 progress:
   total_phases: 4
   completed_phases: 3
-  total_plans: 13
+  total_plans: 15
   completed_plans: 13
   percent: 100
 ---
@@ -21,18 +21,18 @@ progress:
 See: .planning/PROJECT.md (updated 2026-01-26)
 
 **Core value:** Detect anomalies in energy distribution networks without labeled data, using physics constraints and self-play learned patterns on graph-structured grid data
-**Current focus:** Phase 04 — evaluation-framework
+**Current focus:** Phase 03 — graph-aware-proposer
 
 ## Current Position
 
-Phase: 04 (evaluation-framework) — EXECUTING
-Plan: 1 of 4
+Phase: 03 (graph-aware-proposer) — EXECUTING
+Plan: 2 of 2
 
-- **Phase:** 2 of 4 (Hybrid Verifier Integration) - EXECUTING
-- **Plan:** 3 of 3 (Config & Physics Layer) - COMPLETE
-- **Status:** Phase complete — ready for verification
+- **Phase:** 03 of 4 (Graph-Aware Proposer)
+- **Plan:** 2 of 2
+- **Status:** Executing Phase 03
 - **Last activity:** 2026-03-28
-- **Progress:** [██████████] 100%
+- **Progress:** [██████████████] 93%
 
 ## Performance Metrics
 
@@ -49,6 +49,7 @@ Plan: 1 of 4
 | Phase 04 P02 | 4min | 2 tasks | 3 files |
 | Phase 04 P03 | 6min | 2 tasks | 2 files |
 | Phase 04 P04 | 3min | 2 tasks | 3 files |
+| Phase 03 P01 | 5min | 3 tasks | 2 files |
 
 ## Key Decisions
 
@@ -77,6 +78,10 @@ Plan: 1 of 4
 | Auto-detect voltage vs power in PhysicsConstraintLayer | 2x absolute_max_kw heuristic avoids scoring voltages as capacity | 02-01 |
 | Nested Pydantic config with Field(ge/le) | Automatic validation rejects invalid physics thresholds | 02-01 |
 | Tolerance band scoring for physics constraints | Three-zone graduated response (safe=0, warning=linear, violation=1) | 02-01 |
+| 1-3 seed nodes per scenario | Cascade expands from few seeds; realistic propagation | 03-01 |
+| LV feeder preference for cascading types | COLD_SNAP/OUTAGE/EV_SPIKE affect end-consumer nodes first | 03-01 |
+| 30% cap on affected nodes | Prevents unrealistic whole-graph anomalies | 03-01 |
+| Per-node blending formula | baseline + mag * (transform - baseline) for smooth interpolation | 03-01 |
 
 ## Blockers
 
@@ -139,13 +144,14 @@ Plan: 1 of 4
 - 2026-01-27: Completed 01-05 Training Pipeline (2 tasks, 5 min) - Gap closure
 - 2026-01-27: Completed 01-06 Training/Evaluation Scripts (3 tasks, 11 min) - Gap closure, PHASE 1 COMPLETE
 - 2026-03-26: Completed 02-01 Config & Physics Layer (2 tasks, 5 min) - Phase 2 begins
+- 2026-03-28: Completed 03-01 Graph-Aware Proposer (3 tasks, 5 min) - Phase 3 begins
 
 ## Session Continuity
 
-**Last session:** 2026-03-28T12:17:35.184Z
-**Stopped at:** Completed 04-04-PLAN.md
+**Last session:** 2026-03-28T14:10:34Z
+**Stopped at:** Completed 03-01-PLAN.md
 **Resume file:** None
-**Next action:** Execute Plan 02-02 (CascadeLogicLayer, GNN integration, HybridVerifierAgent)
+**Next action:** Execute Plan 03-02 (SelfPlayTrainer graph integration)
 
 ---
-*Last updated: 2026-03-26*
+*Last updated: 2026-03-28*

.planning/phases/03-graph-aware-proposer/03-01-SUMMARY.md

@@ -0,0 +1,119 @@
+---
+phase: 03-graph-aware-proposer
+plan: 01
+subsystem: selfplay
+tags: [graph-aware, proposer, cascade, topology, pyg, torch-geometric, bfs]
+
+# Dependency graph
+requires:
+  - phase: 01-gnn-verifier
+    provides: GridGraphBuilder (node_type constants, COO edge format)
+  - phase: 02-hybrid-ensemble
+    provides: CascadeLogicLayer._build_adjacency pattern, cascade decay convention
+provides:
+  - Graph-aware ProposerAgent with topology-based seed selection
+  - 2-hop cascade propagation with 0.7 decay through grid neighbors
+  - ScenarioProposal.apply_to_graph_timeseries() for per-node magnitude scaling
+  - ScenarioProposal.metadata enrichment with graph_aware, seed_nodes, affected_nodes
+affects: [03-02, selfplay-trainer, graph-training-loop]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [BFS cascade propagation, per-node magnitude blending, graph_data optional parameter]
+
+key-files:
+  created:
+    - tests/test_graph_proposer.py
+  modified:
+    - src/fyp/selfplay/proposer.py
+
+key-decisions:
+  - "1-3 seed nodes per scenario (not 10-30%); cascade expands from few seeds"
+  - "LV feeder (node_type=2) preference for COLD_SNAP, OUTAGE, EV_SPIKE seed selection"
+  - "30% graph cap on affected nodes with seed preservation during subsampling"
+  - "Per-node blending formula: baseline + magnitude * (transform - baseline)"
+
+patterns-established:
+  - "graph_data optional parameter pattern for backward-compatible graph enrichment"
+  - "BFS cascade with decay_factor per hop for anomaly propagation"
+  - "apply_to_graph_timeseries per-node scaling for multi-node time series"
+
+requirements-completed: [SELF-01, SELF-02]
+
+# Metrics
+duration: 5min
+completed: 2026-03-28
+---
+
+# Phase 03 Plan 01: Graph-Aware Proposer Summary
+
+**Graph-aware ProposerAgent with topology-based seed selection, 2-hop BFS cascade propagation (0.7 decay), and per-node time-series application via apply_to_graph_timeseries**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-03-28T14:05:05Z
+- **Completed:** 2026-03-28T14:10:34Z
+- **Tasks:** 3 (TDD: RED/GREEN for each)
+- **Files modified:** 2
+
+## Accomplishments
+- ProposerAgent.propose_scenario() accepts optional graph_data parameter with full backward compatibility
+- Seed nodes selected from LV feeders (node_type=2) for COLD_SNAP/OUTAGE/EV_SPIKE, all nodes for PEAK_SHIFT/MISSING_DATA
+- Cascade propagates through 2-hop BFS with 0.7 decay per hop (seeds=1.0, hop1=0.7, hop2=0.49)
+- Affected nodes capped at 30% of graph with seed preservation during subsampling
+- apply_to_graph_timeseries() applies per-node magnitude scaling to 2-D time-series arrays
+- 24 tests covering all graph-aware behavior, backward compatibility, and per-node application
+
+## Task Commits
+
+Each task was committed atomically (TDD flow):
+
+1. **Task 1: Test scaffold for graph-aware proposer** - `dcb337a` (test)
+2. **Task 2: Implement graph-aware proposer methods** - `37cff8a` (feat)
+3. **Task 3: Implement apply_to_graph_timeseries** - `e7370d6` (feat)
+
+## Files Created/Modified
+- `tests/test_graph_proposer.py` - 24 tests across 9 test classes covering graph-aware proposer, seed selection, cascade propagation, decay, backward compat, diversity, cap, and per-node application
+- `src/fyp/selfplay/proposer.py` - Extended with graph_data parameter, _enrich_with_graph_topology, _select_seed_nodes, _build_adjacency, _propagate_through_neighbors, and apply_to_graph_timeseries
+
+## Decisions Made
+- **1-3 seed nodes per scenario:** Cascade expands from few seeds rather than affecting 10-30% directly. This produces realistic propagation patterns.
+- **LV feeder preference for cascading types:** COLD_SNAP, OUTAGE, EV_SPIKE affect end-consumer nodes first, matching physical grid behavior.
+- **30% cap with seed preservation:** When cascade exceeds cap, seeds are always kept and non-seed nodes are randomly subsampled. Ensures cascade structure is preserved.
+- **Per-node blending formula:** `baseline + magnitude * (transform - baseline)` provides smooth interpolation between untouched and fully transformed time series.
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## Known Stubs
+
+None - all methods are fully implemented with no placeholder data.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Graph-aware proposer ready for integration with SelfPlayTrainer in Plan 03-02
+- apply_to_graph_timeseries() provides the per-node application method that SelfPlayTrainer will use when graph_data is available
+- All 28 existing selfplay tests continue to pass (backward compatibility confirmed)
+
+## Self-Check: PASSED
+
+- tests/test_graph_proposer.py: FOUND
+- src/fyp/selfplay/proposer.py: FOUND
+- 03-01-SUMMARY.md: FOUND
+- Commit dcb337a: FOUND
+- Commit 37cff8a: FOUND
+- Commit e7370d6: FOUND
+
+---
+*Phase: 03-graph-aware-proposer*
+*Completed: 2026-03-28*