stage3: unify to cleanup; MIR return-defer; docs+smokes updated; LLVM(harness): finalize_phis ownership, ret.py simplified, uses-predeclare; cleanup return override green; method-postfix cleanup return WIP (PHI head)

docs/papers/phi_trace_observability.md

@@ -0,0 +1,20 @@
+# PHI Observability and Trace Checking (Draft)
+
+Motivation
+- SSA construction bugs are subtle. We want a first‑class, machine‑checkable record of PHI decisions.
+
+Approach
+- Emit structured JSONL events across PHI lifecycle: `finalize_begin`, `finalize_dst`, `finalize_target`, `wire_choose`, `add_incoming`, `finalize_summary`.
+- Provide a checker that validates coverage and invariants (e.g., each dst has at least one add_incoming; chosen preds ⊆ CFG preds).
+
+Code References
+- Trace writer: `src/llvm_py/llvm_builder.py`, `src/llvm_py/phi_wiring/wiring.py`
+- Checker: `tools/phi_trace_check.py`
+
+Usage
+- `NYASH_LLVM_TRACE_PHI=1 NYASH_LLVM_TRACE_OUT=tmp/phi.jsonl bash tools/test/smoke/bridge/try_result_mode.sh`
+- `python3 tools/phi_trace_check.py --summary tmp/phi.jsonl`
+
+Next
+- Expand checks (dominance, grouping at head), integrate into CI as optional gate.
+