Merge branch 'main' into skill-script-utf8-output

Author: VectorPeak

.agents/skills/adk-architecture/SKILL.md

@@ -11,7 +11,7 @@ description: ADK architectural knowledge — graph orchestration, resumption, ex
 - [Runner](references/interfaces/runner.md) — The public interface for executing workflows and agents. Documents entrance methods `run` and `run_async`.
 - [Agent](references/interfaces/agent.md) — Blueprint defining identity, instructions, and tools. Documents that `run` is the preferred entrance method.
 - [BaseAgent](references/interfaces/base-agent.md) — Base class for all agents. Defines the contract for subclassing with `_run_impl` as the primary override point.
-- [Event](references/interfaces/event.md) — Core data structure for state reconstruction and communication. Represents a conversation turn or action.
+- [Event](references/interfaces/event.md) — Core data structure for state reconstruction and communication. Represents a conversation turn, action, and state lifecycle immutability.
 
 ## Key Principles (references/principles/)
 - [API Principles](references/principles/api-principles.md) — stability, backward compatibility, and self-containment. Use when making design choices that affect the public API surface.

.agents/skills/adk-architecture/references/architecture/observability.md

@@ -30,7 +30,7 @@ execution flow).
 implicit "current span" context. In a concurrent asyncio.Task
 runtime, implicit context can be unreliable across concurrent
 nodes. All tracing operations (attributes, logs, child spans)
-should go through `ctx._span`.
+should go through `ctx._span`. When attaching or detaching OTel context explicitly (e.g., using `context.attach()` and `context.detach()`), **always pair them inside a `try...finally` block** to prevent context leaks across requests.
 
 **Span lifecycle:**
 

.agents/skills/adk-architecture/references/interfaces/event.md

@@ -23,3 +23,8 @@ The `Event` class represents a single event in the conversation history or workf
 - `get_function_calls()`: Returns function calls in the event.
 - `get_function_responses()`: Returns function responses in the event.
 - `is_final_response()`: Returns whether the event is the final response of an agent.
+
+## State Lifecycle & Immutability
+- **Event Immutability**: Event history is immutable. Never assume that events are mutated or cleared after they are saved to a session.
+- **Signal & Action Persistence**: When checking if a signal or action is "pending" versus "resolved", do not rely on events being modified in place.
+- **Compaction Side-Effects**: Be aware that storing stateful flags on events (such as requested actions or transient status) can have permanent unintended effects on background compaction when those events age but remain in history.

.agents/skills/adk-style/references/imports.md

@@ -27,3 +27,4 @@ if TYPE_CHECKING:
 ```
 
 This works because `from __future__ import annotations` makes all annotations strings (deferred evaluation), so the import is never needed at runtime.
+

.agents/skills/adk-style/references/typing.md

@@ -48,3 +48,7 @@ Use `isinstance()` for runtime type discrimination when handling polymorphic inp
 - Always include an `else` branch that raises `TypeError` or handles the unknown case.
 - Prefer `isinstance(x, SomeType)` over `type(x) is SomeType` — it handles subclasses correctly.
 - For checking multiple types: `isinstance(x, (TypeA, TypeB))`.
+
+## No Asserts in Production Code
+
+**Never use `assert` statements in production code.** They can be optimized away when Python runs with `-O` flags and provide poor error messages. Use specific exceptions like `ValueError`, `TypeError`, or `RuntimeError` instead.

.agents/skills/adk-verify-snippets/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: adk-verify-snippets
+description: >
+  Extracts and verifies the runnability and code coverage of all Python code blocks inside a Markdown file.
+  Generates a detailed compilation and execution report.
+metadata:
+  author: Antigravity
+  version: 1.4.0
+---
+
+# Verify Markdown Snippets Skill
+
+This skill extracts all ` ```python ` blocks from a Markdown file, executes each
+one in a process-isolated environment using the bundled `run.py` harness, and
+generates a structured report covering load status, run status, and line
+coverage.
+
+> [!CAUTION] **STRICT READ-ONLY CONSTRAINT — READ THIS BEFORE DOING ANYTHING
+> ELSE**
+>
+> This skill is **read-only**. The agent **MUST NOT**: - **Modify** any file in
+> the repository (source, test, config, docs, or skill files — including this
+> SKILL.md). - **Delete** any file in the repository. - **Create** any new file
+> in the repository.
+>
+> The **only two write operations permitted** are: 1. Writing temporary `.py`
+> snippet files to a **system temp directory outside the repository**. 2.
+> Writing the final `<filename>_REPORT.md` into the **same directory as the
+> source Markdown file**.
+>
+> If in doubt, do not write. Any other mutation is a violation of this skill's
+> contract.
+
+--------------------------------------------------------------------------------
+
+## 🔧 Prerequisites
+
+1.  **ADK Python environment**: Run from the repository root with the `uv`
+    virtual environment active.
+2.  **`coverage` package** *(optional)*: Enables per-snippet coverage reporting.
+    Without it, coverage columns show `—`.
+
+    ```bash
+    uv pip install coverage
+    ```
+
+3.  **Gemini API key**: Required only for snippets that instantiate an `Agent`,
+    `App`, or `Workflow` (which make live Gemini API calls). Set one of:
+
+    ```bash
+    export GEMINI_API_KEY="your-key-here"
+    # or
+    export GOOGLE_API_KEY="your-key-here"
+    ```
+
+    If both are set, `GEMINI_API_KEY` takes precedence.
+
+--------------------------------------------------------------------------------
+
+## 🛠️ Usage
+
+```bash
+uv run --no-sync python .agents/skills/adk-verify-snippets/scripts/verify_md.py <path_to_markdown_file.md>
+```
+
+The script prints progress for each snippet, then writes a report to
+**`<filename>_REPORT.md`** in the same directory as the source file and prints
+the full path on completion.
+
+**Report contents:** :- **Executive Summary table** — one row per snippet:
+preceding heading, Load phase status, Run phase status, coverage %, and error
+detail.
+
+-   **Detailed section** — for each snippet: the extracted code block, full
+    execution logs (stdout + stderr/traceback), and the coverage report.
+
+--------------------------------------------------------------------------------
+
+## 📝 How Snippets Are Classified
+
+Each ` ```python ` block falls into one of these categories:
+
+### 1. Runnability Test (has a module-level ADK component)
+
+If the snippet assigns a `Workflow`, `Agent`, or `App` to a **module-level
+variable**, the runner executes it against the Gemini API.
+
+-   The variable name does not matter — the runner finds it automatically via
+    `vars(module)`.
+-   For multi-agent snippets, the runner identifies the root agent by excluding
+    any agent that appears in another agent's `sub_agents` list.
+-   To use a custom test prompt instead of the default `"Test input topic"`,
+    define a module-level `test_input` string in the snippet.
+
+If no module-level ADK component is found, the run phase is skipped and the
+report shows `➖ NO ADK COMPONENT`.
+
+### 2. Loadability-Only (no ADK component)
+
+The runner verifies the snippet compiles and imports without error. No API call
+is made.
+
+### 3. Skipped (annotated with ignore)
+
+Place `<!-- verify-snippets: ignore -->` immediately before the opening
+` ```python ` fence to exclude a block entirely. Use this for pseudo-code,
+illustrative examples, or snippets that require external setup.
+
+````markdown
+<!-- verify-snippets: ignore -->
+```python
+# pseudo-code — not runnable as-is
+my_agent = Agent(model="gemini-ultra-hypothetical", ...)
+```
+````
+
+The report shows these as `⏭️ SKIPPED`.
+
+--------------------------------------------------------------------------------
+
+## ⚠️ Known Limitations
+
+-   **No shared state between snippets**: Each snippet runs in a fresh
+    subprocess with no imports or variables carried over from previous snippets.
+    A snippet that depends on code from an earlier block will fail with
+    `NameError` or `ImportError`. Make each snippet self-contained, or annotate
+    it with `<!-- verify-snippets: ignore -->`.
+-   **120-second timeout**: Each snippet is killed after 120 seconds. Annotate
+    long-running or blocking snippets with `<!-- verify-snippets: ignore -->`.
+-   **Ignore annotation placement**: The `<!-- verify-snippets: ignore -->`
+    annotation applies to the next ` ```python ` fence encountered. Blank lines
+    between the annotation and the fence are tolerated, but any non-blank line
+    (prose or a heading) cancels the annotation.
+-   **Bare ` ``` ` closes the block**: The parser closes a Python block on the
+    first bare ` ``` ` line (no language tag). A bare ` ``` ` appearing as
+    content inside a snippet (e.g. to demonstrate Markdown syntax) will
+    prematurely close the block. Annotate such snippets with
+    `<!-- verify-snippets: ignore -->`.
+
+--------------------------------------------------------------------------------
+
+## ⚠️ Behavioral Constraints (For AI Agents)
+
+-   **Read-only**: See the caution block at the top. The constraint is absolute.
+-   **Report only, do not fix**: The agent MUST NOT rewrite the source Markdown,
+    modify code blocks, or generate patches. Present the summary table to the
+    user and stop.
+-   **Present the summary table verbatim**: After the script completes, read the
+    generated `_REPORT.md` and copy the Executive Summary table to the user
+    **exactly as written** — same six columns, same order, no renaming or
+    dropping: `Snippet | Preceding Heading | Load Phase | Run Phase | Coverage |
+    Details`