Pull Request Template

Summary

Implements curriculum stability envelope to prevent topology drift during First Light Cortex calibration. Tracks TDA-driven HSS variance, detects instability spikes, scores slice suitability, and blocks invalid curriculum transitions when variance exceeds baseline thresholds.

Strategic Impact

Differentiator Tag: [X] [FM] (Formal Methods - TDA topology tracking)

Strategic Value: Enables deterministic reproduction of Δp + HSS traces during uplift experiments by enforcing curriculum stability invariants

Acquisition Narrative: Demonstrates rigorous formal guarantees for AI training curriculum progression—prevents silent drift in topology distributions that would invalidate experimental results

Measurable Outcomes:

• HSS variance spike detection (2x baseline threshold)
• Slice suitability scoring (0.0-1.0 weighted composite)
• Transition blocking prevents unstable slice changes
• Zero external dependencies (stdlib only)

Doctrine Alignment: Formal methods (TDA), algorithms (variance detection), metrics (HSS tracking), integration (gate system)

Scope

Type: [X] Feature

Components Modified:

• Backend (curriculum stability tracking)
• Documentation (integration guide, examples)
• Configuration (curriculum.yaml stability section)
• Tests (17 comprehensive test cases)

Files Changed:

• curriculum/stability_envelope.py - Core HSS tracking, variance detection, suitability scoring (383 lines)
• curriculum/stability_integration.py - Gate system integration, HSS extraction (314 lines)
• curriculum/__init__.py - Public API exports
• tests/test_curriculum_stability_envelope.py - Full test coverage (458 lines)
• examples/stability_envelope_demo.py - Interactive demonstration (305 lines)
• docs/CURRICULUM_STABILITY_ENVELOPE.md - Complete integration guide (545 lines)
• config/curriculum.yaml - Added stability thresholds configuration

Risk Assessment

Risk Level: [X] Low

Potential Impact:

• Configuration changes required (stability section in curriculum.yaml)
• No breaking changes—extends existing gate system
• No performance impact—O(n) memory, O(1) recording
• Optional integration—can be enabled per system

Rollback Plan:

• Simple revert possible (new feature, no modifications to existing code paths)

Test Plan

Unit Tests

# Run stability envelope tests
python3 -c "
from curriculum.stability_envelope import CurriculumStabilityEnvelope
envelope = CurriculumStabilityEnvelope()
for i in range(10):
 envelope.record_cycle(f'cycle_{i:03d}', 'test_slice', 0.75 + (i % 2) * 0.02, 10 + i, '2025-01-01T00:00:00Z')
stability = envelope.compute_slice_stability('test_slice')
print(f'Stable: {stability.is_stable}, Score: {stability.suitability_score:.3f}')
"
# Run interactive demo
python3 examples/stability_envelope_demo.py

Test Results:

• All existing tests pass
• New tests added (17 test cases)
• Coverage complete (edge cases: zero mean, infinite CV)
• Network-free test requirement met (stdlib only)

Integration Testing

• U2Runner integration validated
• RFLRunner integration validated
• Gate evaluation functional
• Transition blocking works

Performance Testing

• O(n) memory growth (bounded by cycle count)
• O(1) recording operations
• No memory leaks (explicit data structures)

Conflict Watch

Files Also Modified by Other PRs: None (new files)

Coordination Notes:

• No conflicts expected (net-new functionality)

Checklist

Code Quality

• Code follows project style guidelines
• ASCII-only content in docs/scripts
• No hardcoded secrets or credentials
• Error handling implemented (edge cases validated)
• Logging added where appropriate

Documentation

• README updated (implementation summary added)
• API documentation complete (CURRICULUM_STABILITY_ENVELOPE.md)
• Inline code comments added (edge case handling)
• No migration notes needed (new feature)

Security

• No sensitive data exposed
• Input validation implemented (HSS range, cycle IDs)
• No authentication/authorization needed (internal API)
• Dependencies security reviewed (stdlib only, 0 CodeQL alerts)

Performance

• No performance regression (O(1) operations)
• Memory usage bounded (O(n) cycles)
• No database queries (in-memory)
• No caching needed (direct computation)

Deployment

• Environment variables documented (none needed)
• No database migrations
• Configuration changes documented (curriculum.yaml stability section)
• Deployment instructions in docs

Additional Notes

Architecture

# Initialize envelope
from curriculum import CurriculumStabilityEnvelope, record_cycle_hss_metrics
envelope = CurriculumStabilityEnvelope()
# Record HSS after each cycle
for cycle in u2_runner.run_cycles():
 record_cycle_hss_metrics(
 envelope, cycle.id, slice_name, cycle.metrics, cycle.timestamp
 )
# Check before transition
allowed, reason, _ = envelope.check_slice_transition_allowed(
 from_slice="slice_a", to_slice="slice_b"
)

Suitability Score Formula

score = 0.4 ×ばつ mean_HSS + 0.3 ×ばつ (1 - CV/max_CV) + 0.3 ×ばつ (1 - low_ratio/max_ratio)

Components: mean HSS (40%), stability (30%), consistency (30%)

Variance Spike Detection

Detects when recent_variance > baseline_variance ×ばつ 2.0

Example: Baseline=0.000026, Recent=0.176 → Spike detected (6672x ratio)

Performance Metrics

Reviewer Notes:

• Integration points: U2Runner (recording), RFLRunner (ratchet), Cortex (transition blocking)
• Configuration tunable via config/curriculum.yaml stability section
• Demo available: python3 examples/stability_envelope_demo.py
• Security: CodeQL 0 alerts, stdlib only, no network/file/subprocess operations

Custom agent used: curriculum-architect
Owns the curriculum configuration and slice definitions for Phase II uplift experiments. Ensures slice parameters maintain monotonicity (progressive difficulty), validates tier transitions, and keeps curriculum YAML consistent with preregistration. Does NOT run experiments or analyze results.

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.