docs(ai): introduce state machine flow and Mermaid rendering rules

Implement a mandatory State Machine model (PLAN and IMPLEMENTATION states)
in root instructions to prevent the AI from generating code prematurely.
The rules require mechanical reloading of skill files during execution
to combat context-window memory loss.

Also update Mermaid diagram instructions to explicitly ban <br> tags for
newlines and prohibit raw angle brackets (<, >) in nodes, enforcing
real newlines and HTML entities (&lt;, &gt;) to fix rendering issues.

.ai/ai-root-instructions.md

@@ -15,7 +15,26 @@ Your response MUST always begin with:
 
 Then continue with your actual response on the next line.
 
-This allows the user to verify you have read this file every time.
+## 🚦 STATE MACHINE RULES (THINK BEFORE ACT)
+
+To prevent premature execution and ensure you follow instructions mechanically, you are operating as a State Machine.
+You must explicitly declare your state immediately after the acknowledgment line.
+
+**Valid States:**
+- `STATE: PLAN` (Default state for analysis and planning)
+- `STATE: IMPLEMENTATION` (Only when user explicitly tells you "Approve", "Implement this", or "Go ahead")
+
+**Rules for `<STATE: PLAN>`:**
+- **FIRST ACTION REQUIRED:** You MUST ensure `instructions/behavior/core-principles.instructions.md` is loaded into your context before analyzing.
+- **FORBIDDEN:** You CANNOT use `replace_string_in_file`, `create_file`, or run terminal commands that modify state (e.g., `git add`, writing to files). Read-only tools ONLY.
+- **ALLOWED:** You may use `read_file`, `file_search`, `grep_search`, `run_in_terminal` (for read-only commands like `ls`, `cat`), and propose plans.
+- If the user asks for a feature, you MUST propose the implementation strategy first, output a prompt asking for approval, AND STOP.
+- Do NOT output concrete implementation code blocks in your proposals. Propose the strategy in bullet points only.
+
+**Rules for `<STATE: IMPLEMENTATION>`:**
+- **CRITICAL PRE-EXECUTION ACTION:** Before executing ANY file edits, you MUST mechanically use the `read_file` tool to *reload* all relevant specific skill files (e.g., `skills/clean-code.instructions.md`, `skills/helm.instructions.md`) for the task. Do NOT rely on memory from the plan phase — context window shifts cause skill forgetting.
+- **ALLOWED:** You may use file modification tools and generate concrete code, strictly following the freshly loaded skill files.
+- This state resets back to `PLAN` after the approved task is completed.
 
 ---
 

.ai/instructions/skills/mermaid.instructions.md

@@ -17,7 +17,7 @@ Use `-- "text" -->` syntax, **not** `-->|text|` syntax.
 
 ## Line Breaks (Multiline Text)
 
-Do not use `\n` for line breaks inside Mermaid nodes or labels. It does not always render correctly.
+Do not use `\n`, `<br>`, or `<br/>` for line breaks inside Mermaid nodes or labels. They do not always render correctly.
 Instead, use actual line breaks (real newlines) inside quoted text.
 
 ```
@@ -25,6 +25,20 @@ Instead, use actual line breaks (real newlines) inside quoted text.
 Second line"]
 
 ❌ B["First line\nSecond line"]
+❌ C["First line<br/>Second line"]
+```
+
+---
+
+## Angle Brackets and Special Characters
+
+Do not use raw `<` or `>` characters in Mermaid nodes or labels (e.g. `<customer>-idp-deployment`), as they are often parsed as HTML tags and break rendering.
+Instead, use HTML entities `&lt;` and `&gt;`.
+
+```
+✅ A["&lt;customer&gt;-idp-deployment"]
+
+❌ B["<customer>-idp-deployment"]
 ```
 
 ---