chore(engine): rename ENGINE_V2_TRACE to IRONCLAW_RECORD_TRACE (#2114)

* chore(engine): rename ENGINE_V2_TRACE to IRONCLAW_RECORD_TRACE

Aligns the trace-recording env var with the project-wide IRONCLAW_*
naming convention so it's discoverable alongside other ironclaw flags.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* unify engine v2 trace recording with v1 RecordingLlm

Address PR review feedback. Instead of having two separate trace
systems both named IRONCLAW_RECORD_TRACE (the v1 RecordingLlm in
src/llm/recording.rs and the engine v2 executor/trace.rs JSON dumper),
collapse them to one.

Engine v2's LlmBackend is wired to the host's full LLM provider chain,
which already includes RecordingLlm when IRONCLAW_RECORD_TRACE=1.
That means engine v2 LLM interactions are already captured by the
unified trace_*.json fixture file -- no engine-side env var, no second
JSON output, no risk of one flag enabling two divergent recorders.

Removed:
- is_trace_enabled() and write_trace() from executor/trace.rs
- the engine_trace_*.json write site in runtime/manager.rs

Kept (still useful, runs unconditionally for the self-improvement
mission):
- build_trace() / analyze_trace() / log_trace_summary()

Docs updated to point to RecordingLlm as the single trace mechanism.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ilblackdragon

crates/ironclaw_engine/src/executor/trace.rs

@@ -1,12 +1,15 @@
-//! Execution trace recording and analysis.
+//! Execution trace analysis.
 //!
-//! Records full execution traces to JSON files for debugging. Optionally
-//! runs a post-execution analysis to detect common issues.
+//! Builds an in-memory `ExecutionTrace` from a completed `Thread` and runs a
+//! retrospective analyzer that flags common failure patterns. Used by the
+//! self-improvement mission and surfaced in debug logs.
 //!
-//! Enable with `ENGINE_V2_TRACE=1` env var. Traces are written to
-//! `engine_trace_{timestamp}.json` in the current directory.
-
-use std::path::PathBuf;
+//! **There is no separate engine trace file.** Live trace recording for the
+//! whole system is handled by `RecordingLlm` in the host crate
+//! (`src/llm/recording.rs`), gated by `IRONCLAW_RECORD_TRACE`. Because the
+//! engine's `LlmBackend` is wired to the same provider chain, engine LLM
+//! interactions are captured by that single recorder — no engine-side env var
+//! and no second JSON file.
 
 use chrono::Utc;
 use serde::Serialize;
@@ -15,13 +18,6 @@ use tracing::debug;
 use crate::types::event::ThreadEvent;
 use crate::types::thread::{Thread, ThreadId, ThreadState};
 
-/// Check if trace recording is enabled.
-pub fn is_trace_enabled() -> bool {
-    std::env::var("ENGINE_V2_TRACE")
-        .map(|v| v == "1" || v == "true")
-        .unwrap_or(false)
-}
-
 /// A complete execution trace for a single thread.
 #[derive(Debug, Serialize)]
 pub struct ExecutionTrace {
@@ -108,29 +104,6 @@ pub fn build_trace(thread: &Thread) -> ExecutionTrace {
     }
 }
 
-/// Write a trace to a JSON file.
-pub fn write_trace(trace: &ExecutionTrace) -> Option<PathBuf> {
-    let filename = format!("engine_trace_{}.json", Utc::now().format("%Y%m%dT%H%M%S"));
-    let path = PathBuf::from(&filename);
-
-    match serde_json::to_string_pretty(trace) {
-        Ok(json) => match std::fs::write(&path, json) {
-            Ok(()) => {
-                debug!(path = %path.display(), "Execution trace written");
-                Some(path)
-            }
-            Err(e) => {
-                debug!("Failed to write trace: {e}");
-                None
-            }
-        },
-        Err(e) => {
-            debug!("Failed to serialize trace: {e}");
-            None
-        }
-    }
-}
-
 /// Print a summary of the trace to the log.
 pub fn log_trace_summary(trace: &ExecutionTrace) {
     debug!(

crates/ironclaw_engine/src/runtime/manager.rs

@@ -290,11 +290,9 @@ impl ThreadManager {
                 tracing::debug!(thread_id = %thread_id, "failed to transition to Done: {e}");
             }
 
-            // Write trace file if enabled
-            if crate::executor::trace::is_trace_enabled() {
-                crate::executor::trace::log_trace_summary(&trace);
-                crate::executor::trace::write_trace(&trace);
-            }
+            // Trace recording is handled centrally by `RecordingLlm` in the
+            // host crate (gated by `IRONCLAW_RECORD_TRACE`). The engine no
+            // longer writes its own JSON trace file.
 
             if let Err(e) = store_for_task.append_events(&exec.thread.events).await {
                 tracing::debug!(

docs/engine-v2-architecture.md

@@ -118,7 +118,7 @@ The bridge connects the engine to existing IronClaw infrastructure:
 
 Set `ENGINE_V2=true` environment variable. The router in `src/bridge/router.rs` intercepts messages and routes them through the engine instead of the v1 agent loop.
 
-For trace debugging: `ENGINE_V2_TRACE=1` writes full JSON traces to `engine_trace_*.json`.
+For trace debugging set `IRONCLAW_RECORD_TRACE=1`. Engine v2 reuses the host crate's `RecordingLlm` (see `src/llm/recording.rs`) — the engine's `LlmBackend` is wired to the same provider chain, so LLM interactions are captured in the standard `trace_*.json` fixture file (configurable via `IRONCLAW_TRACE_OUTPUT`). There is no separate engine trace file.
 
 ## Memory System
 

docs/plans/2026-03-20-engine-v2-architecture.md

@@ -346,7 +346,7 @@ Engine broadcasts `ThreadEvent`s via `tokio::broadcast`. Router subscribes and f
 `EngineState` persists across messages (OnceLock singleton). ConversationManager builds the visible conversation transcript for continuity. The orchestrator persists its mutable working transcript and intermediate execution state in `persisted_state` / internal thread transcript rather than mixing tool traces into the user-visible transcript.
 
 ### 6.5 Trace recording + retrospective — DONE
-`ENGINE_V2_TRACE=1` writes full JSON traces. Automatic trace analysis detects 8 issue categories. Reflection pipeline produces Summary/Lesson/Issue/Spec/Playbook docs. All run inside ThreadManager after thread completion.
+Live trace recording is handled by the host crate's `RecordingLlm` (`IRONCLAW_RECORD_TRACE=1`) — engine v2 piggybacks on it via the shared LLM provider chain, so there is no separate engine trace file. Inside ThreadManager, retrospective trace analysis runs unconditionally after each thread completes: the analyzer detects 8 issue categories and the reflection pipeline produces Summary/Lesson/Issue/Spec/Playbook docs.
 
 ### 6.6 Bugs found and fixed via traces
 - Tool name hyphens vs underscores (web-search vs web_search)

docs/self-improvement.md

@@ -204,10 +204,14 @@ The mission is capped at 5 threads per day (`max_threads_per_day: 5`).
 
 ## Debugging Self-Improvement
 
-Enable trace logging to see the self-improvement loop in action:
+Enable trace logging to see the self-improvement loop in action.
+`IRONCLAW_RECORD_TRACE=1` is the unified flag — it enables `RecordingLlm`,
+which captures every LLM interaction into a shared `trace_*.json` fixture
+file. Engine v2 reuses the same provider chain, so its LLM calls are recorded
+through the same mechanism (no separate engine trace file):
 
 ```bash
-ENGINE_V2=true ENGINE_V2_TRACE=1 RUST_LOG=ironclaw_engine=debug cargo run
+ENGINE_V2=true IRONCLAW_RECORD_TRACE=1 RUST_LOG=ironclaw_engine=debug cargo run
 ```
 
 Look for: