chore(engine): rename ENGINE_V2_TRACE to IRONCLAW_RECORD_TRACE by ilblackdragon · Pull Request #2114 · nearai/ironclaw

ilblackdragon · 2026-04-07T16:16:20Z

Summary

Renames the engine trace-recording env var from ENGINE_V2_TRACE to IRONCLAW_RECORD_TRACE to align with the project-wide IRONCLAW_* naming convention
Updates is_trace_enabled() and the module doc in crates/ironclaw_engine/src/executor/trace.rs
Updates the three doc references (docs/self-improvement.md, docs/engine-v2-architecture.md, docs/plans/2026-03-20-engine-v2-architecture.md)

Test plan

cargo check -p ironclaw_engine passes (verified locally)
IRONCLAW_RECORD_TRACE=1 cargo run writes engine_trace_*.json
Old ENGINE_V2_TRACE=1 no longer enables tracing

🤖 Generated with Claude Code

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>

gemini-code-assist

Code Review

This pull request renames the ENGINE_V2_TRACE environment variable to IRONCLAW_RECORD_TRACE within the engine's trace executor and updates all relevant documentation. The review feedback suggests using the parse_option_env<bool> helper function to reduce boilerplate and recommends maintaining backward compatibility for the legacy variable name during the transition period.

gemini-code-assist · 2026-04-07T16:19:06Z

+    std::env::var("IRONCLAW_RECORD_TRACE")
        .map(|v| v == "1" || v == "true")
        .unwrap_or(false)


To maintain consistency and minimize boilerplate across the repository, use the specialized parse_option_env<T> helper function for resolving environment variables. This approach should also be used to implement the fallback logic for the legacy ENGINE_V2_TRACE variable to ensure backward compatibility during the transition period.

Suggested change

std::env::var("IRONCLAW_RECORD_TRACE")

.map(|v| v == "1" || v == "true")

.unwrap_or(false)

parse_option_env::<bool>("IRONCLAW_RECORD_TRACE")

.or_else(|| parse_option_env::<bool>("ENGINE_V2_TRACE"))

.unwrap_or(false)

References

Use specialized helper functions like parse_option_env when resolving environment variables into Option fields to minimize boilerplate and maintain consistency across configuration files.

Copilot

Pull request overview

Renames the engine trace-recording environment variable from ENGINE_V2_TRACE to IRONCLAW_RECORD_TRACE and updates related documentation to match, aiming to align with IRONCLAW_* naming.

Changes:

Updated is_trace_enabled() and module docs in crates/ironclaw_engine/src/executor/trace.rs to read IRONCLAW_RECORD_TRACE.
Replaced ENGINE_V2_TRACE with IRONCLAW_RECORD_TRACE across three documentation files.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docs/self-improvement.md	Updates the debug command example to use the new env var name.
docs/plans/2026-03-20-engine-v2-architecture.md	Updates architectural plan reference to the new env var name.
docs/engine-v2-architecture.md	Updates architecture doc reference to the new env var name.
crates/ironclaw_engine/src/executor/trace.rs	Changes the env var checked for enabling engine trace recording and updates module docs.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-07T16:19:41Z

 /// Check if trace recording is enabled.
 pub fn is_trace_enabled() -> bool {
-    std::env::var("ENGINE_V2_TRACE")
+    std::env::var("IRONCLAW_RECORD_TRACE")
        .map(|v| v == "1" || v == "true")
        .unwrap_or(false)


IRONCLAW_RECORD_TRACE is already used elsewhere (e.g., src/llm/recording.rs) to enable LLM trace capture for E2E replay fixtures. Reusing the same env var here will unexpectedly enable/disable two different trace systems with different output formats/paths. Consider using a more specific env var for engine traces (e.g., IRONCLAW_ENGINE_TRACE / IRONCLAW_ENGINE_RECORD_TRACE), or intentionally unify the formats and output config so a single flag makes sense.

Copilot · 2026-04-07T16:19:41Z

 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: `IRONCLAW_RECORD_TRACE=1` writes full JSON traces to `engine_trace_*.json`.


This doc now points users to IRONCLAW_RECORD_TRACE, but that env var is already documented/used to enable LLM trace recording for replay testing. If engine tracing keeps using the same variable, please clarify the dual behavior here; otherwise update this to the engine-specific env var name chosen for engine traces.

Suggested change

For trace debugging: `IRONCLAW_RECORD_TRACE=1` writes full JSON traces to `engine_trace_*.json`.

For trace debugging, use the existing shared trace flag: `IRONCLAW_RECORD_TRACE=1`. This env var is also used for LLM trace recording/replay testing; when Engine v2 routing is enabled, it additionally writes full engine JSON traces to `engine_trace_*.json`.

Copilot · 2026-04-07T16:19:41Z


 ### 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.
+`IRONCLAW_RECORD_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.


Same concern as other docs: IRONCLAW_RECORD_TRACE is already used for LLM trace recording. Either clarify that it enables multiple trace outputs, or switch this reference to the engine-specific env var used by the executor trace recorder.

Suggested change

`IRONCLAW_RECORD_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.

`IRONCLAW_RECORD_TRACE=1` enables trace recording across the system, including the full engine/thread JSON traces described here. Automatic trace analysis detects 8 issue categories. Reflection pipeline produces Summary/Lesson/Issue/Spec/Playbook docs. All run inside ThreadManager after thread completion.

Copilot · 2026-04-07T16:19:42Z

@@ -207,7 +207,7 @@ The mission is capped at 5 threads per day (`max_threads_per_day: 5`).
 Enable trace logging to see the self-improvement loop in action:


This command now uses IRONCLAW_RECORD_TRACE, which is also used to enable LLM trace recording. If engine tracing gets a separate env var to avoid the collision, update this example accordingly (or clarify that this enables multiple trace outputs).

Suggested change

Enable trace logging to see the self-improvement loop in action:

Enable trace logging to see the self-improvement loop in action. Note that

`IRONCLAW_RECORD_TRACE=1` currently enables multiple trace outputs, including

LLM trace recording:

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>

claude · 2026-04-08T04:51:37Z

Code review

Found 3 issues:

[MEDIUM:75] Documentation references to ENGINE_V2_TRACE may not be fully updated

The PR updates docs to reference IRONCLAW_RECORD_TRACE in several files, but you should verify no stale ENGINE_V2_TRACE references remain in .env.example, example commands in test fixtures, or other generated client documentation. Users setting the old flag will silently get no tracing.

https://github.com/anthropics/ironclaw/blob/fdb093fb4270f1f57df7acffdf414c091bee6498/.env.example (check for ENGINE_V2_TRACE references)

[MEDIUM:75] Loss of error handling visibility in trace recording

The removed write_trace() function returned Option<PathBuf> and logged failures (e.g., "Failed to write trace: {e}"). The consolidated RecordingLlm approach is architecturally cleaner, but if trace recording fails silently in the host crate, the engine layer has no way to detect it. The trace is non-critical (debug feature), but the removal of explicit error logging is a minor observability regression.

https://github.com/anthropics/ironclaw/blob/fdb093fb4270f1f57df7acffdf414c091bee6498/crates/ironclaw_engine/src/executor/trace.rs#L108-L143

[LOW:65] IRONCLAW_TRACE_OUTPUT env var referenced in docs but not in config

The updated docs mention IRONCLAW_TRACE_OUTPUT as configurable (engine-v2-architecture.md line 121), but this env var is not documented in src/config/llm.rs or .env.example. Either add the config entry or remove the documentation reference.

https://github.com/anthropics/ironclaw/blob/fdb093fb4270f1f57df7acffdf414c091bee6498/docs/engine-v2-architecture.md#L121

chore(engine): rename ENGINE_V2_TRACE to IRONCLAW_RECORD_TRACE

2b67d0b

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>

Copilot AI review requested due to automatic review settings April 7, 2026 16:16

github-actions Bot added scope: docs Documentation size: XS < 10 changed lines (excluding docs) risk: low Changes to docs, tests, or low-risk modules contributor: core 20+ merged PRs labels Apr 7, 2026

Copilot started reviewing on behalf of ilblackdragon April 7, 2026 16:17 View session

gemini-code-assist Bot reviewed Apr 7, 2026

View reviewed changes

Copilot AI reviewed Apr 7, 2026

View reviewed changes

github-actions Bot added size: M 50-199 changed lines and removed size: XS < 10 changed lines (excluding docs) labels Apr 7, 2026

ilblackdragon merged commit fdb093f into staging Apr 8, 2026
14 checks passed

ilblackdragon deleted the rename-engine-trace-env branch April 8, 2026 03:31

github-actions Bot mentioned this pull request Apr 8, 2026

chore: promote staging to staging-promote/288fe49a-24110798843 (2026-04-08 04:48 UTC) #2136

Merged

ironclaw-ci Bot mentioned this pull request Apr 10, 2026

chore: release #2075

Merged

ironclaw-ci Bot mentioned this pull request Apr 18, 2026

chore: release #2606

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(engine): rename ENGINE_V2_TRACE to IRONCLAW_RECORD_TRACE#2114

chore(engine): rename ENGINE_V2_TRACE to IRONCLAW_RECORD_TRACE#2114
ilblackdragon merged 2 commits intostagingfrom
rename-engine-trace-env

ilblackdragon commented Apr 7, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Apr 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Uh oh!

claude Bot commented Apr 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	For trace debugging: `IRONCLAW_RECORD_TRACE=1` writes full JSON traces to `engine_trace_*.json`.
	For trace debugging, use the existing shared trace flag: `IRONCLAW_RECORD_TRACE=1`. This env var is also used for LLM trace recording/replay testing; when Engine v2 routing is enabled, it additionally writes full engine JSON traces to `engine_trace_*.json`.

	`IRONCLAW_RECORD_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.
	`IRONCLAW_RECORD_TRACE=1` enables trace recording across the system, including the full engine/thread JSON traces described here. Automatic trace analysis detects 8 issue categories. Reflection pipeline produces Summary/Lesson/Issue/Spec/Playbook docs. All run inside ThreadManager after thread completion.

		@@ -207,7 +207,7 @@ The mission is capped at 5 threads per day (`max_threads_per_day: 5`).
		Enable trace logging to see the self-improvement loop in action:

-Enable trace logging to see the self-improvement loop in action:
+Enable trace logging to see the self-improvement loop in action. Note that
+`IRONCLAW_RECORD_TRACE=1` currently enables multiple trace outputs, including
+LLM trace recording:

Conversation

ilblackdragon commented Apr 7, 2026

Summary

Test plan

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

claude Bot commented Apr 8, 2026

Code review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants