UEAtelier

Imported from edwinmeng163-oss/UEAtelier (AGENTS.md). Install upstream with npx skills add edwinmeng163-oss/UEAtelier. Copyright stays with the author.

UEAtelier Agent Handoff

This is the first-read briefing for AI agents. It keeps only core identity, read-order, freshness, tool-count, file-inventory, and safety rules. Deep operational guidance lives in Docs/agents-guide/.

Project Identity

UEAtelier is an Unreal Editor MCP self-extension workbench. The main deliverable is Plugins/UnrealMcp. The plugin runs inside Unreal Editor, exposes http://127.0.0.1:8765/mcp, adds Window > UEAtelier Chat, adds Window > UEAtelier Workbench, and exposes Task Atlas from the Chat panel.

Current plugin metadata:

Plugins/UnrealMcp/UnrealMcp.uplugin
FriendlyName: UEAtelier
VersionName: 0.35.0
EngineVersion: intentionally omitted for cross-version source builds
Type: Editor plugin
Required plugin: PythonScriptPlugin

The v0.35 source line prioritizes Unreal Engine 5.7 and 5.8. UE 5.6 remains a maintenance compile canary during the transition, not a primary release gate. UEvolve.uproject is the local development host and defaults to EngineAssociation 5.7. Examples/UEvolveExample57 (UE 5.7.4) is the primary sample-content host and is also built/tested with UE 5.8; the full Examples/UEvolveExample host remains the UE 5.6 maintenance canary. Do not add a duplicate multi-gigabyte UE 5.8 content host.

Multi-engine discipline:

• All #if ENGINE_*_VERSION goes in UnrealMcpEngineCompat.h.
• Before switching the shared Examples/UEvolveExample57 host between UE 5.7 and UE 5.8, delete both the plugin and host Binaries/ and Intermediate/ directories. Partial platform/build-subdirectory cleanup is insufficient.
• Run Tools/install_git_hooks.sh once after clone.
• EAiProviderKind values are append-only; do not renumber.

Product Goal

Target:

An Unreal Editor MCP self-extension workbench that lets AI add new editor
automation capabilities under audit, dry run, backup, build, test, rollback,
RAG, and long-memory safeguards.

Core capabilities: call Unreal Editor tools from Chat or external MCP clients; inspect maps, assets, actors, Blueprint graphs, Widget trees, logs, tests, metadata, memory, skills, and knowledge cards; edit Blueprint, Widget, and Actor state through fixed schemas; scaffold, validate, dry run, apply, build, test, classify, and roll back new MCP tools; use RAG/tool recommendation before creating tools; write project memory; distill repeated work into skills.

Read Order For A New Agent

Start with AGENTS.md, README.md, Plugins/UnrealMcp/README.md, Docs/Architecture.md, and Docs/SecurityModel.md.

Then read on demand:

Documentation Freshness Rule

After every meaningful project change, update the AI-facing docs before handoff:

1. Update AGENTS.md when project structure, tool-extension workflow, safety rules, build/test commands, RAG behavior, or current project status changes.
2. Update README.md when user-facing install, usage, feature coverage, deployment, or product positioning changes.
3. Update the focused doc under Docs/ when the change belongs to a specific system such as architecture, self-extension, RAG, security, supervisor, or deployment troubleshooting.
4. If the change adds or changes tools, update ToolRegistry metadata, tests, and relevant docs in the same patch.

Treat stale docs as a product bug.

Repository Map

Important versioned paths:

README.md, AGENTS.md, UEvolve.uproject, open_uevolve.command
Docs/agents-guide/
Docs/Architecture.md, Docs/CallTool.md, Docs/KnowledgeRag.md, Docs/SecurityModel.md
Docs/SelfExtensionPipeline.md, Docs/TaskAtlas.md, Docs/Verification.md
Docs/WindowsCompatibilityLessons.md, Docs/WindowsPackaging.md
Plugins/UnrealMcp/UnrealMcp.uplugin
Plugins/UnrealMcp/README.md
Plugins/UnrealMcp/Resources/
Plugins/UnrealMcp/Source/UnrealMcp/
Schemas/
Tools/UEAtelierCli/
Tools/UnrealMcpCodexBridge/, Tools/UnrealMcpKnowledge/
Tools/UnrealMcpPyToolSamples/, Tools/UnrealMcpSkills/, Tools/UnrealMcpTests/
Tools/UnrealMcpToolRegistry/, Tools/UnrealMcpToolScaffoldStarters/
Tools/UnrealMcpToolDocs/
Tools/UnrealMcpSupervisorTemplates/
Tools/extract_tool_schemas.py, Tools/generate_tool_docs.py
Tools/install_unrealmcp_to_project.py, Tools/validate_tool_registry.py
Tools/unreal_mcp_fetch_docs.py, Tools/unreal_mcp_stdio_proxy.py
Tools/unreal_mcp_supervisor.py

Important local-only or generated paths:

Saved/UnrealMcp/, Saved/UnrealMcp/CapturedToolArgs/, Content/, Tools/UnrealMcpToolScaffolds/
Tools/UnrealMcpSupervisor/, Binaries/, Intermediate/, DerivedDataCache/
Plugins/*/Binaries/, Plugins/*/Intermediate/

Do not commit local runtime state, fetched docs caches, KnowledgeIndex files, API keys, generated launchers, local test content, or unreviewed scaffold drafts unless explicitly asked.

Current High-Level Feature Set

• Editor/inspection: status, engine version, settings, player input configuration, logs, maps, assets, selection, PIE, console, Python, Content Browser sync, save dirty packages, asset move, redirector fixup, dependency remap, and migration helpers.
• Actor, Blueprint, Widget, and Material tools: readback, guarded edits, creation, layout, graph/pin inspection, gameplay node/input event authoring, Blueprint SCS component/default edits, map GameMode setup, actor auto-possess, parameter inspection, and strict schema writes.
• Code tools: workspace policy status, bounded file listing, file readback with whole-file sha, bounded literal/regex/filename search, and v0.29 Wave B preview/apply/rollback write closure with byte-exact sha checks, backups, manifests, locks, drift detection, and rollback.
• Self-extension: schema/C++ patch validation, Python user-extension scaffolds, unreal.mcp_user_registry_reload, unreal.mcp_user_tool_smoke, patch editing, dry-run apply, backups, build matrix, tests, pipeline, audit, rollback, locks, error classification, supervisor install, and reviewed package export/import.
• Python user-tool composition: registered user tools receive injected call_tool / call_tool_raw helpers that route through the UFUNCTION unreal.UnrealMcpCallTool.call_tool into visible core unreal.* tools with allow / force-dry-run / deny policy; a verified vetted-toolset marker may allow real core writes only inside the live hash-checked toolset scope with fail-closed vetted_real_write audit. Task Atlas grants vetting only through an in-editor human approval flow with source-policy validation, vetted-context smoke, persisted marker, and fail-closed audit. Depth=1 and user.* targets remain forbidden.
• RAG/recommendation, memory, skills, Task Atlas, and verification: KnowledgeIndex v2 with staged/verified replacement and recoverable last-known-good backup pairs, missing|empty|stale|ready|corrupt status, source/engine counts and hashes; boundary-aware/version-aware lexical search, source-kind/engine diversity, rank-aware evals, tool/workflow recommend, project memory CRUD, skill activity/drafts/promote, task extract/list/describe/rate/pin/promote, schema v2 ordered Task Atlas stepRefs with preview composite generation from private captured args, MCP wrappers for making/listing/deleting/smoking Task Atlas generated tools, RAG promotion, and user-registry introspection, unreal.automation_list, unreal.automation_run, unreal.automation_report, unreal.pie_smoke, unreal.verify_player_controls, unreal.pie_input_probe, unreal.verify_viewport_widgets, and unreal.editor_diagnostics.

Tool Registry Status

The explicit ToolRegistry is central. Do not bypass it: Tools/UnrealMcpToolRegistry/tools.json, Plugins/UnrealMcp/Resources/ToolRegistry/tools.json, Tools/UnrealMcpToolRegistry/schema.json, and Schemas/UnrealMcpToolRegistry.schema.json.

At the time this file was written, the registry contained 190 entries across: actors, blueprint, code, editor, material, memory, scaffold, self-extension, skills, task-atlas, verification, and widget.

Recent v0.14-v0.24 project work includes Python runtime smoke, readback inspectors, Blueprint refactor and macro/interface tools, UBT target matrix, migration tools, install doctor, UMG/material parity tools, Task Atlas foundation/backfill tools, verification foundation tools, diagnostics, PIE smoke, AI provider presets, Kimi reasoning_content compatibility, enriched input schemas, generated per-tool docs under Tools/UnrealMcpToolDocs/, and the Tools/UEAtelierCli/ CLI-Anything package. v0.31 R4 chunk 9 adds CLI <-> Chat Panel sync tools (chat_inject_user_input, chat_history_tail, chat_tool_log_tail) and hardens Task Atlas eligibility against external-client registry-miss noise.

Current project status: v0.35.0 is the current public release (2026-07-14), shipped as Batch 1 of the dual-variant v0.35 plan; variant structure and optional official-MCP integration remain a later batch. Trilingual notes at Docs/Release-2026-07b.md. UE 5.7 and UE 5.8 are the primary support targets; both clean-build the current source, and both pass the new RAG 17/17, Gate D 1/1, EngineCompat 2/2, and project version migration 1/1 suites. Both primary engines also pass the v0.34 safety baselines: VetMadeTool 11/11, VettedToolset 5/5, CallTool 9/9, and TaskAtlas 38/38. The RAG P0/P1 batch isolates Gate D from the production index, prevents zero-card refresh from replacing last-known-good state, writes/validates Index v2 hash/freshness metadata, makes ActivityLog indexing opt-in, separates promoted markdown from official-doc toggles, preserves UE 5.7/5.8 metadata/headings, fixes ui-inside-build and version-token ranking, reserves source/engine diversity under the card cap, adds rank-aware eval assertions, and confines RAG roots, recursive scans, manifest textPath reads, fixed index leaves, eval files, and source-fingerprint metadata probes without following symlinks or reparse points. R1 adds interruption recovery, deterministic CJK/Latin tokenization, known-engine-only numeric filtering, isolated allowEmptyIndex, Chat refresh backoff, skipped-HTML cleanup, and Windows CI hardening. Unchanged warm index reads use cards/manifest size and timestamp metadata to bypass pair recovery, hashing, and JSONL parsing; cold or changed pairs still run full recovery and verification. The root host now targets 5.7; project_version_migration accepts primary 5.7/5.8 and maintenance 5.6. Registry count stays 190 and validation is 190/190. Detailed development notes are in Docs/Development-0.35.md.

Previous public release status: v0.34.0 (2026-07-02) ships the Make-Tool-Set vetting foundation plus the Codex bridge workspace-write network fix. Task Atlas generated composites (user.atlas_*) can be approved in-editor with "Approve real writes" and then execute their dangerous call_tool steps for real without per-run confirmation, while wire/MCP clients cannot grant that authority. Approval is fail-closed through source-policy validation (closed imports, no dynamic access/reflection, no direct Unreal usage, no file IO), manifest allowlist subset checks, live main.py SHA-256 binding, a real vetted-context test run, TOCTOU hash re-check, atomic marker write, registry reload, and audited toolset_vetted persistence; revocation is fail-safe and every vetted real write emits sanitized vetted_real_write audit. The four structural hard denies remain non-overridable: hidden tools, user-to-user calls, call-tool depth, and workflow_run. Made-tools UI and unreal.user_registry_introspect now report vetted marker/hash/approver status, and the bridge sets workspace-write network_access=true so in-editor AI can reach http://127.0.0.1:8765/mcp. Version 0.33 was an internal UE5.8 validation track and is not a public release. Tool count stays 190 (visible tools/list count stays 178); UE 5.6 + 5.7 dual-engine builds pass; VetMadeTool 11/11, VettedToolset 5/5, CallTool 9/9, TaskAtlas 38/38, and registry validation 190/190 pass; full-host automation converges to the two known baseline failures. Trilingual notes at Docs/Release-2026-07.md.

Earlier project status: v0.32.2 (2026-06-11) is an MCP protocol conformance patch on v0.32.1. codex-cli 0.132 moved its MCP client to the official rmcp 0.15 Rust SDK, whose strict untagged-result parsing mis-read our tools/list response — it carried a non-spec top-level structuredContent {toolsListVersion} — as a CallToolResult, failing MCP client startup with "MCP startup failed: Unexpected response type" and hiding every unreal.* tool from codex sessions. The patch strips that field (the chat panel reads the version counter in-process; no wire consumer existed) and pins the wire with two guardrail layers: pure UnrealMcp::Protocol response builders (UnrealMcpProtocolBuilders.h) backed by five exact-key UnrealMcp.Protocol.* Automation tests (initialize / ping / tools-list with an explicit structuredContent-absent regression pin / tool-call / JSON-RPC envelopes), plus an official @modelcontextprotocol/sdk conformance smoke (Tools/UnrealMcpCodexBridge/test-sdk-conformance.ts, devDependency-only) wired into the Stage 2 release SOP as a required gate. The bridge README gains a tested-client matrix (codex-cli 0.130.0 probe line; 0.132.0 / rmcp 0.15 current verified line) with a Codex-Desktop auto-update caveat. The stale UnrealMcp.UserToolListVersion wire test flipped to assert omission. Tool count stays 190 (visible tools/list count stays 178); UE 5.6 + 5.7 dual-engine builds pass and full automation converges to the two known failures (RunRecoversStale, PieSmoke.MapValidation). Trilingual notes at Docs/Release-2026-06c.md.

Earlier project status: v0.32.1 (2026-06-10) is a platform-coverage patch on v0.32.0. The Codex CLI subprocess provider now works on Windows: direct codex.exe spawn with no shell intermediary, MSVC CRT-quoted argv (UE auto-quotes the URL so the builder excludes the binary path), .exe-only binary validation rejecting npm .cmd/.bat shims and WindowsApps store paths, a 30000-TCHAR full-command-line guard, and the three ChatPanel Windows UI gates removed; the POSIX path is byte-identical (stash-contrast verified). The release also ships a dev-host automation baseline cleanup (committed tool.json manifest for user.editor_python_runtime_info, GateD sourceRoot fixture isolation, ExecCommandActualBashExec relative-path root-cause fix, stale count expectations refreshed, CountSeparation made baseline-relative). Tool count stays 190; UE 5.6 + 5.7 dual-engine builds pass and full automation on both dev and example hosts converges to the two known failures (RunRecoversStale, PieSmoke.MapValidation). Trilingual notes at Docs/Release-2026-06b.md.

Earlier project status: v0.32.0 (2026-06-02) was the stable release after a 9-chunk rework of Task Atlas Make Tool Set + CLI ↔ editor chat sync. The rework added 9 new MCP tools (6 task_atlas_* wrappers in chunk 5 + chat_inject_user_input/chat_history_tail/chat_tool_log_tail in chunk 9), introduced the UnrealMcp::TaskAtlasService backend namespace, switched STaskAtlasWindow handlers to thin invokers (net -483 LOC) with Test Now / Debug buttons and blocked-task disable + tooltip, added the toolsListVersion ETag on tools/list for external polling, and hardened the protocol against external-client stale-task_list poisoning (Fix B in UnrealMcpProtocol.cpp + Fix C in UnrealMcpTaskAtlasService.cpp). Tool count 181 → 190; 63/63 automation pass (49 baseline + 14 ChatSync); UE 5.6 + 5.7 dual-engine build pass; trilingual release notes at Docs/Release-2026-06.md; mac + win zip on GitHub release v0.32.0. Eligibility-based product split: preview_ready writes PyTools + explicit Test Now (no auto-smoke); partial / skeleton_pre_capture write markdown only at Saved/UnrealMcp/TaskAtlasDrafts/; blocked UI disables Make Tool Set with tooltip showing first blocked step + reason. R6 end-to-end GUI demo verified CLI ↔ editor chat sync: CLI-injected prompts appear in editor Chat Panel, AI's real responses + tool log show in editor, and chat_history_tail / chat_tool_log_tail return data byte-identical to what editor displays.

Earlier project status: v0.31 Stage 2 was complete through Wave E docs: ActivityLog records now carry eventId plus public capture metadata; tool arguments are redacted for secret fields, home/project paths, per-tool skip rules, and size caps before optional storage in private Saved/UnrealMcp/CapturedToolArgs; Task Atlas task JSON uses schema v2 ordered non-deduped stepRefs with replayEligibility; and Make Tool Set generates honest preview or skeleton composite Python user tools with sanitized captured defaults, per-step policyDecision, isError, and force-dry-run effectiveArgsDiff while avoiding any promise of real replay; v0.30 R2 Wave C makes Task Atlas Make Tool Set generate skeleton composite Python user tools directly under the user registry from visible core unreal.* critical-path steps, writing closed tool.json schemas, pythonHandlerSha256, smokeArgs, then running user-registry reload and smoke while preserving the then-current core registry count; v0.30 R2 Wave B adds Python user-tool call_tool / call_tool_raw builtins over unreal.UnrealMcpCallTool.call_tool, enabling fail-closed composition of visible core unreal.* tools; v0.29 Wave B implements the code category with seven visible core code tools: four read-only tools unreal.code_workspace_status, unreal.code_list_files, unreal.code_read_file, and unreal.code_search, plus write-closure tools unreal.code_preview_change, unreal.code_apply_change, and unreal.code_rollback_change; v0.28 adds eight visible core gameplay authoring tools: unreal.bp_add_input_axis_event_node, unreal.bp_add_input_action_event_node, unreal.bp_add_component, unreal.bp_set_component_property, unreal.bp_set_class_default, unreal.bp_add_gameplay_node, unreal.editor_set_map_game_mode, and unreal.actor_set_auto_possess, plus runtime verification tools unreal.pie_input_probe and unreal.verify_viewport_widgets; v0.27.1 adds core player input configuration, now including arbitrary legacy axis/action names, and existence-only player control verification; v0.27 walls core apply/pipeline off from the AI, makes AI self-extension the Python user-tool track only, keeps core promotion manual/developer-only and deferred, adds a workflow_run hidden-tool guard, and merges the three project skills into mcp-self-extension; v0.26 completes Reform C with centralized server-message provider system prompt assembly, six baked safety rules, the AssistantRun approval gate, Python user-extension default scaffolds, lifecycle-aware reload/smoke controls, and the 11-code audit taxonomy; v0.25 rewrites Codex CLI exec; v0.24 adds AI provider presets, Kimi reasoning_content compatibility, enriched input schemas, generated per-tool docs under Tools/UnrealMcpToolDocs/, and progressive-disclosure agent docs; v0.23 adds cli-anything-ueatelier; v0.22 adds unreal.pie_smoke; v0.21 adds unreal.editor_diagnostics; v0.20 hardens async automation runs and watchdog stale recovery; v0.19 completes the original Task Atlas Make Tool scaffold path, To RAG ingestion, and label backfill; v0.19.1 disables Unity build for the UnrealMcp module after a UE 5.6 collision. unreal.configure_fps_settings remains scaffold-only pending functional verification.

Reform C v0.26 resolves the v0.25 self-extension incident by centralizing server-message provider prompts in UnrealMcpAssistantSystemPromptBuilder, baking in the six lifecycle/dry-run/ approval safety rules, enforcing the approval gate at the AssistantRun provider seam, and making project-local Python user extensions the default path. v0.27 finishes the wall-off: AI self-extension is Python user tools only, while core C++ apply/pipeline and promotion are hidden, manual, developer-only, and deferred.

Visible tool counts can differ because hidden entries and aliases are filtered. Trust /tool unreal.mcp_workbench_status {} and /tool unreal.mcp_tool_audit {}. Validate registry changes with:

python3 Tools/validate_tool_registry.py

C++ Architecture File Inventory

UnrealMcpModule.cpp is intentionally thin. Do not add tool logic there.

Lifecycle/protocol: UnrealMcpModule.cpp, UnrealMcpProtocol.cpp,
  UnrealMcpProtocolBuilders.h
Tool metadata: UnrealMcpToolDefinitions.cpp, UnrealMcpToolDescriptor.h,
  UnrealMcpToolRegistrar.cpp/.h, UnrealMcpToolRegistry.cpp/.h,
  UnrealMcpToolHandlerRegistry.cpp/.h, UnrealMcpToolDispatcher.cpp
Execution: UnrealMcpToolExecutionGuard.cpp/.h, UnrealMcp*OutcomeVerifier.cpp,
  UnrealMcpSession.h, UnrealMcpActivityLog.h, UnrealMcpCallToolPolicy.cpp/.h,
  UnrealMcpVettedToolset.cpp/.h,
  UnrealMcpCallToolLibrary.cpp/.h, UnrealMcpPythonToolBridge.cpp,
  UnrealMcpHashUtils.cpp/.h, UnrealMcpCaptureRedaction.cpp/.h,
  UnrealMcpCapturedArgsStore.cpp/.h
Task/verification: UnrealMcpTaskAtlasTools.cpp/.h,
  UnrealMcpTaskAtlasService.cpp/.h, UnrealMcpTaskLabelBackfillTool.cpp/.h,
  UnrealMcpAutomationTools.cpp/.h, UnrealMcpPieSmokeTools.cpp/.h,
  UnrealMcpDiagnosticsTools.cpp/.h
Knowledge: UnrealMcpKnowledgeBridge.h, UnrealMcpKnowledgeTools.cpp,
  UnrealMcpWorkflowTools.cpp
Category handlers: UnrealMcpEditorTools.cpp,
  UnrealMcpEditorEngineVersionTool.cpp, UnrealMcpActorTools.cpp,
  UnrealMcpCodeTools.cpp/.h,
  UnrealMcpBlueprintTools.cpp, UnrealMcpBlueprintGraphLibrary.cpp/.h,
  UnrealMcpBlueprintComponentLibrary.cpp/.h, UnrealMcpWidgetTools.cpp,
  UnrealMcpScaffoldTools.cpp, UnrealMcpSelfExtension*.cpp,
  UnrealMcpMemoryTools.cpp, UnrealMcpSkillTools.cpp
UI/assistant/tests: UnrealMcpChatPanel.cpp/.h,
  UnrealMcpWorkbenchPanel.cpp/.h, STaskAtlasWindow.cpp/.h,
  UnrealMcpEditorTabs.cpp, UnrealMcpAssistantRun.cpp/.h, Private/Tests/*.cpp
  including Private/Tests/UnrealMcpCallToolLibraryTests.cpp and
  Private/Tests/UnrealMcpTaskAtlasCompositeTests.cpp and
  Private/Tests/UnrealMcpCaptureRedactionTests.cpp and
  Private/Tests/UnrealMcpCapturedArgsStoreTests.cpp

Prefer cautious single-category edits. The largest files remain ChatPanel, ActorTools, KnowledgeTools, ScaffoldTools, BlueprintTools, WidgetTools, ToolDefinitions, AssistantRun, and several SelfExtension helpers.

Tool-count Discipline

The registry tool count must stay synced across the canonical registry, plugin mirror, the "the registry contained N entries" line in this AGENTS.md, the N registered MCP tools line in README.md (EN + Chinese + Japanese), and the tool lists in Plugins/UnrealMcp/README.md.

python3 -c 'import json; print(len(json.load(open("Tools/UnrealMcpToolRegistry/tools.json"))["tools"]))'
grep -nE "registry contained|registered MCP tools" AGENTS.md README.md Docs/agents-guide/*.md

Before any commit that adds or removes a tool, bump all tool-count references in the same commit.

Safety Rules For Future AI

Always: run git status --short before editing; respect existing uncommitted changes; prefer rg/rg --files; use apply_patch for manual edits; keep generated local data out of Git; use fixed schemas; ensure write tools have policy, preflight, and postcheck metadata; dry run, backup, manifest, build, test, and rollback source mutations; use unreal.preview_change_plan or document the plan for high-risk tasks; write/read project memory for long work; run unreal.knowledge_eval_run if RAG/tool recommendation changes; run python3 Tools/validate_tool_registry.py if ToolRegistry changes; update AGENTS.md, README.md, and focused docs after meaningful changes.

Avoid: putting new tools directly into UnrealMcpModule.cpp; committing Saved/, generated KnowledgeIndex, local fetched docs, API keys, local supervisor launchers, or unreviewed scaffolds; assuming Content/ is clean distributable plugin state; installing over both engine-level and project-level plugin copies; assuming newly built C++ tools are visible until Editor restarts; treating ChatHistory as canonical product docs.

Coding discipline (Karpathy guidelines)

Full text + attribution now lives in the merged Tools/UnrealMcpSkills/mcp-self-extension/SKILL.md playbook (MIT, from Andrej Karpathy's observations on LLM coding pitfalls). These are the behavioral counter to the v0.26 incident class (a 291-line embedded-Python handler = "Simplicity First" violation; hand-merging into core = "Surgical Changes" violation):

1. Think Before Coding — state assumptions; surface tradeoffs and multiple interpretations; push back when a simpler path exists; stop and ask when confused.
2. Simplicity First — minimum code that solves the problem; no speculative features/abstractions/flexibility; if 200 lines could be 50, rewrite.
3. Surgical Changes — touch only what the task requires; don't "improve" adjacent code/comments/formatting; mention unrelated dead code, don't delete it; only remove orphans your own change created. Every changed line traces to the request.
4. Goal-Driven Execution — turn tasks into verifiable success criteria (tests-first, dual-engine build + automation green) and loop until verified.

Current Local Caveat

Re-check current state with git status --short, git branch --show-current, and python3 Tools/validate_tool_registry.py. If the worktree is dirty, inspect diffs before editing.