PWR-HYBRID-3/CLAUDE.md

CLAUDE.md

Guidance for Claude Code (and any AI agent) working in this repository.

Living documentation — update these files

CLAUDE.md files are living. This one and the ones in subdirectories. When you learn something new about the system that a future agent would benefit from, update the appropriate CLAUDE.md before the session ends. Context that exits a session uncaptured is lost forever — treat this as the single most important rule in this repo.

Where to write:

• Stable, authoritative knowledge (architecture, conventions, interfaces, design decisions) → the relevant CLAUDE.md. Root for cross-cutting; subdirectory for layer-specific.
• Session-level findings, in-progress investigations, paths that didn't pan out → claude_memory/YYYY-MM-DD-topic.md. See claude_memory/README.md for the pattern.

When to write:

• After a non-trivial debugging session (what broke, root cause, how you knew).
• After an architectural or structural decision (what we chose, what we rejected, why).
• After discovering a non-obvious fact (subtle constraint, undocumented tool behavior, counterintuitive data format).
• Before ending a session where you explored paths that didn't pan out — so the next agent doesn't waste effort redoing them.

Over time, session notes that stabilize get distilled up into the relevant CLAUDE.md; the rest get archived or deleted. This is a discipline, not automation — do the graduation explicitly when knowledge becomes authoritative.

What this is

The preliminary example for the HAHACS thesis — a PWR startup controller demonstrating the full pipeline from written operating procedures to verified hybrid controller. This repo composes three layers of the same story:

Layer	Location	Role	Thesis mapping
Story	thesis/ (submodule)	The PhD proposal: math, prose, claims	Motivates and defines the methodology
Discrete	fret-pipeline/	FRET requirements → LTL → ltlsynt → AIGER circuit → state machine	Implements Thrust 1 + 2
Continuous	plant-model/	10-state PKE + thermal-hydraulics PWR model (MATLAB/Octave)	Plant for Thrust 3 (reachability / barrier certs)
Verification	reachability/	Continuous-mode verification artifacts	Thrust 3 output — currently empty
Hardware	hardware/	Ovation HIL artifacts	Integration milestone — currently empty
Deliverables	presentations/	Conference papers and talks (submodules)	Dissemination

Running example: the PWR_HYBRID_3 controller. The discrete automaton it synthesizes is literally the state machine drawn in thesis/3-research-approach/approach.tex Figure 1 (Cold Shutdown → Heatup → Power Operation, with SCRAM).

How changes flow

1. Requirement change. Edit the FRET export (fret-pipeline/pwr_hybrid_3.json) → run fret-pipeline/scripts/fret_to_synth.py → re-synthesize via synthesize.sh → re-trace via trace_aiger.py. New .svg / .dot / .png land in fret-pipeline/diagrams/. Copy the figure you want to cite into docs/figures/ so the thesis can pick it up.
2. Plant change. Edit plant-model/pke_params.m or dynamics in pke_th_rhs.m → re-run main.m to verify behavior. Steady-state values feed the T_avg, P_crit thresholds in the FRET requirements — if you change them here, check the requirement predicates match.
3. Verification work. Continuous-mode verification (reachability, barrier certificates) reads the guards from fret-pipeline/specs/synthesis_config_v3.json and the dynamics from plant-model/pke_th_rhs.m. Results go in reachability/.
4. Thesis edit. cd thesis && <edit> && git commit && git push origin main, then from the umbrella root: git add thesis && git commit to bump the submodule pointer.

Where to look for what

• Reactor physics, steady-state, ODE dynamics → plant-model/
• Controller synthesis, requirements, state machines → fret-pipeline/
• Research narrative, math, claims, citations → thesis/
• Shared figures (for the thesis or talks) → docs/figures/
• How the layers compose → docs/architecture.md

Submodule rituals

• Fresh clone: git clone <url> && git submodule update --init --recursive (or git clone --recurse-submodules <url>). Without this, thesis/ and presentations/2026DICE/ are empty directories.
• Editing the thesis: cd thesis && git checkout main first — submodules default to detached HEAD. Then edit, commit, push inside the submodule, then cd .. and commit the new submodule pointer in the umbrella.
• Pulling upstream thesis changes: cd thesis && git pull origin main, then commit the new pointer in the umbrella.

Conventions

• FRET variables: control_<group> = q_<value> for modes; everything else is an environment input. See fret-pipeline/README.md for the full naming rule.
• Plant model units: internal SI (W, kg, °C); printed/plotted in °F.
• Continuous state vector: y = [n; C1..C6; T_f; T_c; T_cold]. Guards in FRET should reference the algebraic outputs (T_hot, T_avg) or direct states, not derived quantities.
• Q_sg(t) is the bounded disturbance — never treat T_cold as an input.

What's deliberately missing (so you don't go looking)

• LTL-to-Stateflow translator — there's a known pain point in the thesis workflow where AIGER circuits still need to become Stateflow. Not yet automated. Current path: generate AIGER → eyeball the state machine diagram → hand-translate to Stateflow. Roadmapped.
• Hardware bring-up (Ovation DCS) — scheduled for the integration thrust. hardware/ is a placeholder.
• Continuous-mode verification — reachability/ is empty. Choice of tool (CORA / Flow* / SpaceEx / JuliaReach) still pending.