refactor(memory): rename synthesis Skill dataclass to DistilledProcedure (#2684)

Two different frozen dataclasses were both named `Skill` and both
reachable from `gaia.agents.base`: the synthesis pipeline's four-field
LLM-output schema and the on-disk agentskills.io file contract landing
in `src/gaia/skills/` (#2669). The split is a deliberate security
boundary — the model may only derive
`name`/`when_to_use`/`body`/`tools_required`, never `license`,
`version`, or a security tier — so both classes stay; the synthesis one
becomes `DistilledProcedure`, matching its own docstring and the
`procedures` corpus it feeds. Anyone importing both no longer needs an
alias, and nobody can pass the wrong one.

Also adds the test `to_skill_md`'s docstring has been asserting all
along: the rendered document is now round-tripped through the real
`gaia.skills.format` parser + validator instead of a hand-rolled YAML
check. Verified against #2669's branch — **it validates, no drift**
(`tools_required` is a first-class `metadata.gaia` field there). The
test skips until #2669 merges.

Part of #2671.

## Test plan

- [ ] `python -m pytest tests/unit/test_skill_synthesis.py
tests/unit/test_memory_mixin.py tests/unit/test_chat_dynamic_tools.py
-q` — 310+ pass, the round-trip test skips while `gaia.skills` is
unmerged
- [ ] After #2669 merges, rebase and confirm
`test_renders_a_document_the_format_validator_accepts` runs and passes
rather than skipping
- [ ] `python -m pytest tests/unit/ -q` — no new failures vs.
`origin/main` (verified: identical failure set, all pre-existing
environment issues)
- [ ] `python util/lint.py --all` clean
- [ ] `grep -rn '\bSkill\b' src/gaia/agents/base/` returns only prose
section headers, no class references

Author: kovtcharov

docs/plans/skill-synthesis.mdx

@@ -103,9 +103,9 @@ new model, no new store engine.
      of ≥ MIN_OCCURRENCES
                                  │
                                  ▼
-  3. DISTILL  distill_cluster(cluster, llm) → Skill | None     PROPOSED
+  3. DISTILL  distill_cluster(cluster, llm) → DistilledProcedure|None PROPOSED
      one low-temp LLM call per cluster (DISTILL_SYSTEM_PROMPT);
-     Skill.parse() validates; literal "SKIP" → None
+     DistilledProcedure.parse() validates; literal "SKIP" → None
                                  │
                                  ▼
   4. STORE    reconcile_and_store(candidate, store)            PROPOSED
@@ -242,20 +242,20 @@ The pipeline *emits* a `SKILL.md`; it does **not** define the format. The format
 **references** that schema and never redefines a field.
 
 The subtlety — and the single most important correctness point — is the split
-between **what the LLM emits** and **what `Skill.parse()` injects**. The guiding
+between **what the LLM emits** and **what `DistilledProcedure.parse()` injects**. The guiding
 rule: **the LLM emits only the fields it *derives* from the learned procedure;
 fixed constants are injected, never emitted.** So `DISTILL_SYSTEM_PROMPT` asks the
 model for an **intermediate** frontmatter of four learned fields, and a
-deterministic `Skill.parse()` maps them to the canonical #691 document and adds the
+deterministic `DistilledProcedure.parse()` maps them to the canonical #691 document and adds the
 two constants:
 
 | Field | Origin | → Canonical `SKILL.md` (#691) | Why |
 |---|---|---|---|
 | `name` | **LLM (derived)** | `name` | Identity, derived from the cluster. Matches the rule at [`skill-format.mdx:150`](https://github.com/amd/gaia/blob/main/docs/plans/skill-format.mdx). |
 | `when_to_use` | **LLM (derived)** | `description` | **`when_to_use` is the LLM-emitted field on purpose** — it forces the model to *conclude the trigger boundaries* of the skill; `description` is too vague a label to constrain it. Its embedding is what `recall_skill(goal)` matches against. Maps to the required `description` ([`skill-format.mdx:151`](https://github.com/amd/gaia/blob/main/docs/plans/skill-format.mdx)). |
 | `tools_required` (top-level) | **LLM (derived)** | `metadata.gaia.tools_required` | The tool set the procedure actually used. #691 **locks** `tools_required` as the cross-spec recipe contract and nests it under `metadata.gaia` ([`skill-format.mdx:143`](https://github.com/amd/gaia/blob/main/docs/plans/skill-format.mdx), `:158`). |
-| `markdown_body` | **LLM (derived)** | body | The LLM writes the **full procedure — numbered steps *and* a `## Edge cases` section — inline**. `Skill.parse()` does not synthesize a separate edge-case section; the distilled body already carries it. |
-| `license: MIT`, `version: 1.0.0` | **`Skill.parse()` (fixed)** | `license`, `version` | **Fixed constants, not learned content — the LLM does *not* emit them.** `license` is always the repository license ([`skill-format.mdx:152`](https://github.com/amd/gaia/blob/main/docs/plans/skill-format.mdx)); a freshly synthesised skill is always `version: 1.0.0` (SemVer — [`skill-format.mdx:153`](https://github.com/amd/gaia/blob/main/docs/plans/skill-format.mdx)). Injecting them keeps the prompt's output surface purely dynamic and removes any chance the model emits a wrong version. |
+| `markdown_body` | **LLM (derived)** | body | The LLM writes the **full procedure — numbered steps *and* a `## Edge cases` section — inline**. `DistilledProcedure.parse()` does not synthesize a separate edge-case section; the distilled body already carries it. |
+| `license: MIT`, `version: 1.0.0` | **`DistilledProcedure.parse()` (fixed)** | `license`, `version` | **Fixed constants, not learned content — the LLM does *not* emit them.** `license` is always the repository license ([`skill-format.mdx:152`](https://github.com/amd/gaia/blob/main/docs/plans/skill-format.mdx)); a freshly synthesised skill is always `version: 1.0.0` (SemVer — [`skill-format.mdx:153`](https://github.com/amd/gaia/blob/main/docs/plans/skill-format.mdx)). Injecting them keeps the prompt's output surface purely dynamic and removes any chance the model emits a wrong version. |
 
 A synthesised recipe therefore emits a **bounded field set** — `name`,
 `description`, `license`, `version`, `metadata.gaia.tools_required`, and the body.
@@ -269,10 +269,10 @@ most-restrictive `experimental` at load time.
 This is the **one deliberate refinement** of the maintainer's pseudocode: his
 `DISTILL_SYSTEM_PROMPT` listed `version: 1.0.0` *inside* the LLM's required output
 ([#887 technical-spec comment](https://github.com/amd/gaia/issues/887#issuecomment-4321407541));
-this spec moves `version` (and `license`) to `Skill.parse()` injection because both
+this spec moves `version` (and `license`) to `DistilledProcedure.parse()` injection because both
 are fixed, not derived. The pipeline otherwise keeps the maintainer's prompt as
 written, and **(a)** treats the four learned fields as the intermediate shape,
-**(b)** specifies `Skill.parse()` as the translator to the locked schema, and
+**(b)** specifies `DistilledProcedure.parse()` as the translator to the locked schema, and
 **(c)** guarantees the emitted file validates under #691 — an explicit acceptance
 criterion (see [Acceptance criteria traceability](#acceptance-criteria-traceability)).
 
@@ -448,7 +448,7 @@ current code; these are the corrections an implementer must internalize.
 
 | Original framing | Reality on `main` | Consequence |
 |---|---|---|
-| `DISTILL_SYSTEM_PROMPT` emits `when_to_use` + top-level `tools_required` as the on-disk shape | #691 locks `description` + `metadata.gaia.tools_required` ([`skill-format.mdx:151`](https://github.com/amd/gaia/blob/main/docs/plans/skill-format.mdx), `:158`) | The prompt fields are the **intermediate** shape; `Skill.parse()` maps them. See [The format contract](#the-format-contract). |
+| `DISTILL_SYSTEM_PROMPT` emits `when_to_use` + top-level `tools_required` as the on-disk shape | #691 locks `description` + `metadata.gaia.tools_required` ([`skill-format.mdx:151`](https://github.com/amd/gaia/blob/main/docs/plans/skill-format.mdx), `:158`) | The prompt fields are the **intermediate** shape; `DistilledProcedure.parse()` maps them. See [The format contract](#the-format-contract). |
 | Scope C: *"New **tool**: `recall_skill`"* | The memory registry is exactly five tools ([`memory.py:1984`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/memory.py)+) and the planner calls recall programmatically | `recall_skill` is an **internal method**, not a sixth `@tool`. See [Decided design](#decided-design). |
 | Hook is `on_consolidation_pass` → `_consolidate_old_sessions / _reconcile_contradictions / _prune_stale` | Those names don't exist; the real pass is `_run_memory_post_init` → `reconcile_memory` + `consolidate_old_sessions` ([`memory.py:1206`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/memory.py)) | Bind `_synthesize_skills` to the **real** maintenance method. |
 | Tunables in `~/.gaia/config.toml [memory.skill_synthesis]` | Memory is configured via `~/.gaia/memory_settings.json` ([`memory.py:57`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/memory.py)) + `GAIA_MEMORY_DISABLED`; there is **no** `config.toml` `[memory]` section | Surface the thresholds on the **existing** memory-settings surface, not a new TOML section — see [Open questions](#open-questions). |
@@ -460,7 +460,7 @@ current code; these are the corrections an implementer must internalize.
 - **The intermediate frontmatter is not the on-disk schema.** A reader of the
   maintainer's `DISTILL_SYSTEM_PROMPT` must not write `when_to_use` /
   top-level `tools_required` to disk. The on-disk file is the #691 schema
-  (`description`, `metadata.gaia.tools_required`); `Skill.parse()` is the only
+  (`description`, `metadata.gaia.tools_required`); `DistilledProcedure.parse()` is the only
   bridge.
 - **`recall_skill` is not an LLM tool.** Do not register a sixth memory `@tool`;
   it would change the five-tool registry the rest of the system assumes.
@@ -510,7 +510,7 @@ mirroring the v1→v2 `ADD COLUMN` pattern
 ### Phase 1 — Detect → cluster → distill → reconcile/store (PROPOSED)
 
 `skill_synthesis.py` with `extract_sequences` / `cluster_by_goal` /
-`distill_cluster` / `Skill.parse` / `reconcile_and_store`, hooked into the
+`distill_cluster` / `DistilledProcedure.parse` / `reconcile_and_store`, hooked into the
 maintenance pass as `_synthesize_skills` after `consolidate_old_sessions`
 ([`memory.py:1233`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/memory.py)).
 Reuses the nomic-768 embedder ([`memory.py:148`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/memory.py)).
@@ -569,9 +569,9 @@ The recipe reuses `triage-support-ticket`
 so its `tools_required` resolve to real registry tools.
 
 <AccordionGroup>
-<Accordion title="A. The synthesised SKILL.md (Skill.parse output — the on-disk #691 document)">
+<Accordion title="A. The synthesised SKILL.md (DistilledProcedure.parse output — the on-disk #691 document)">
 
-What `Skill.parse()` writes after distillation — a valid #691 document. `name`,
+What `DistilledProcedure.parse()` writes after distillation — a valid #691 document. `name`,
 `description`, `license`, `version`, and `metadata.gaia.tools_required` are all the
 locked schema. Each `tools_required` name is a real registry tool (`query_documents`
 from `RAGToolsMixin`, `read_file` from `FileIOToolsMixin`, `remember` from the
@@ -606,12 +606,12 @@ metadata:
 ```
 
 </Accordion>
-<Accordion title="B. The intermediate DISTILL_SYSTEM_PROMPT output (before Skill.parse)">
+<Accordion title="B. The intermediate DISTILL_SYSTEM_PROMPT output (before DistilledProcedure.parse)">
 
 What the LLM emits — **only the four learned fields**: top-level `name`,
 `when_to_use`, `tools_required`, and a body that already contains the
 `## Edge cases` section. No `version`, no `license` — those are fixed constants.
-`Skill.parse()` maps `when_to_use → description`, `tools_required →
+`DistilledProcedure.parse()` maps `when_to_use → description`, `tools_required →
 metadata.gaia.tools_required`, and **injects the fixed `license: MIT` and
 `version: 1.0.0`** to produce example A.
 
@@ -672,7 +672,7 @@ tool-loader's `CORE ∪ SKILL ∪ SEMANTIC` union ahead of semantic results.
 # PROPOSED — at turn start, before tool selection (internal method, not an @tool)
 matches = self.recall_skill(user_goal, top_k=2)
 # matches → [
-#   Skill(
+#   DistilledProcedure(
 #     name="triage-support-ticket",
 #     when_to_use="Triage an inbound support ticket end to end. ...",
 #     body="# Triage a Support Ticket\n1. ...\n## Edge cases\n- ...",
@@ -746,7 +746,7 @@ The memory layer it builds on is real and merged; the synthesis pipeline is
 | Prompt composition | `_compose_system_prompt`, `_select_tools_for_turn` | `agent.py:591`, `:786` | **Exists** — injection seam |
 | Memory REST + dashboard | `/api/memory/*`, `X-Gaia-UI` guard, three-tab dashboard | `ui/routers/memory.py:26`, `:29`; `MemoryDashboard.tsx:267` | **Exists** — exposes procedural data |
 | `category='skill'` (a fact, not a procedure) | `VALID_CATEGORIES` includes `"skill"` | `memory_store.py:97` | **Exists** — *different concept* |
-| **`skill_synthesis.py` / `procedures` table / `extract_sequences` / `cluster_by_goal` / `distill_cluster` / `Skill.parse` / `SkillProvenance` / `reconcile_and_store` / `recall_skill` / `_synthesize_skills` / `put_skill` / `search_skills` / `supersede_skill` / `iter_sessions`** | — | **NOT FOUND** (verified absent on `main`) | **Greenfield — PROPOSED** |
+| **`skill_synthesis.py` / `procedures` table / `extract_sequences` / `cluster_by_goal` / `distill_cluster` / `DistilledProcedure.parse` / `SkillProvenance` / `reconcile_and_store` / `recall_skill` / `_synthesize_skills` / `put_skill` / `search_skills` / `supersede_skill` / `iter_sessions`** | — | **NOT FOUND** (verified absent on `main`) | **Greenfield — PROPOSED** |
 
 ---
 
@@ -779,7 +779,7 @@ guarantees a consumer. Deferrals are explicit, with the track that owns them.
 | **Scope E** — Dashboard "Procedures" tab + provenance + promote | [Phase 2 deferral](#phased-build) | **Tab build DEFERRED to #606's dashboard track**; #887 stores provenance + exposes the data. |
 | **AC** — after 3 successful similar sequences, auto-create a `SKILL.md` discoverable via `recall_skill()` | [KPIs](#kpis), [Phase 1](#phased-build) + [Phase 2](#phased-build) | The headline KPI. |
 | **AC** — recall measurably reduces tool-step count on the 4th attempt | [KPIs](#kpis), [Phase 2](#phased-build) | Measured vs the tool-loader baseline. |
-| **AC** — synthesised skills are valid agentskills.io documents (Hermes parser) | [The format contract](#the-format-contract), [Examples A–B](#examples) | `Skill.parse()` round-trip; 100% validity KPI. |
+| **AC** — synthesised skills are valid agentskills.io documents (Hermes parser) | [The format contract](#the-format-contract), [Examples A–B](#examples) | `DistilledProcedure.parse()` round-trip; 100% validity KPI. |
 | **AC** — Dashboard shows count / last-used / provenance | [Phase 2 deferral](#phased-build) | **Data exposed by #887**; *rendering* is #606's tab. |
 | **AC** — disabling a skill prevents recall | [Off-states](#off-states-as-safe-floors), [Phase 2](#phased-build) | The recall path honours `enabled = 0` (this **is** #887); the toggle UI is #606's tab. |
 | **Out of scope** — marketplace / tiers / OpenClaw shim | [Dependencies](#dependencies) | → #647 / #692. |

docs/plans/tool-loader.mdx

@@ -431,7 +431,7 @@ stored procedure declares the exact `tools_required` for that recipe.
 
 #### How Part 3 shipped (implementation reference)
 
-**The loader stays memory-agnostic.** `recall_skill` and `Skill` are *not*
+**The loader stays memory-agnostic.** `recall_skill` and `DistilledProcedure` are *not*
 imported into `tool_loader.py` (that would be an upward dependency). Instead
 `ChatAgent` — the composition layer — flattens the recalled procedures'
 `tools_required` into a `List[str]` and passes it to `select()` via a new
@@ -442,7 +442,7 @@ never learns what a skill is.
 cost).** `recall_skill` already runs once per turn in
 `MemoryMixin._refresh_recalled_skills` (before tool selection, via the
 `process_query` → `super()` ordering). Part 3 refactors that method to cache the
-matched `Skill` objects in `self._recalled_skills` alongside the rendered
+matched `DistilledProcedure` objects in `self._recalled_skills` alongside the rendered
 prompt; `_recalled_skill_tools()` reads that cache. So the SKILL signal adds
 **no** second embed/FAISS call — TTFT is the whole point of the loader.
 

src/gaia/agents/base/memory.py

@@ -483,9 +483,10 @@ def init_memory(
         # the composed system prompt.  Empty string = no recall = the system
         # prompt stays byte-identical to a build without procedural memory.
         self._recalled_skill_prompt = ""
-        # The matched Skill objects from the same per-turn recall (#1451): the
-        # tool loader reads their tools_required via _recalled_skill_tools as the
-        # SKILL signal.  Empty list = no recall = no SKILL signal this turn.
+        # The matched DistilledProcedure objects from the same per-turn recall
+        # (#1451): the tool loader reads their tools_required via
+        # _recalled_skill_tools as the SKILL signal.  Empty list = no recall =
+        # no SKILL signal this turn.
         self._recalled_skills = []
 
         # Step 2: Validate Lemonade embedding service connectivity.

src/gaia/agents/base/procedural_memory.py

@@ -20,7 +20,7 @@
 import numpy as np
 
 from gaia.agents.base.skill_synthesis import (
-    Skill,
+    DistilledProcedure,
     SynthesisConfig,
     cluster_by_goal,
     distill_cluster,
@@ -180,7 +180,7 @@ def _proc_faiss_search(self, query_vec: np.ndarray, top_k: int) -> List[tuple]:
 
     def recall_skill(
         self, goal: str, top_k: int = 2, similarity_tau: Optional[float] = None
-    ) -> List[Skill]:
+    ) -> List[DistilledProcedure]:
         """Recall stored procedures whose trigger matches ``goal`` (vector search).
 
         The RECALL half of the procedural loop and the consumer the tool-loader
@@ -215,8 +215,9 @@ def recall_skill(
                 so a recalling turn reads the settings file only once.
 
         Returns:
-            Matched ``Skill`` objects (full bodies; injection truncates, the row
-            keeps the full body), best match first; ``[]`` on any off-state.
+            Matched ``DistilledProcedure`` objects (full bodies; injection
+            truncates, the row keeps the full body), best match first; ``[]``
+            on any off-state.
         """
         from gaia.agents.base.memory import (
             _load_memory_settings,  # deferred (cycle break)
@@ -250,7 +251,7 @@ def recall_skill(
             if similarity_tau is not None
             else load_synthesis_config(_load_memory_settings()).similarity_tau
         )
-        skills: List[Skill] = []
+        skills: List[DistilledProcedure] = []
         recalled_ids: List[str] = []
         for procedure_id, score in matches:
             if score < tau:
@@ -267,7 +268,7 @@ def recall_skill(
                 continue
             row = rows[0]
             skills.append(
-                Skill(
+                DistilledProcedure(
                     name=row["name"],
                     when_to_use=row["when_to_use"],
                     body=row["markdown_body"],
@@ -291,7 +292,7 @@ def recall_skill(
 
     def _recall_skills_for_turn(
         self, goal: str
-    ) -> Tuple[List[Skill], Optional[SynthesisConfig]]:
+    ) -> Tuple[List[DistilledProcedure], Optional[SynthesisConfig]]:
         """Recall the procedures matching ``goal`` once, with the resolved config.
 
         The single per-turn recall pass shared by both consumers:
@@ -332,7 +333,7 @@ def _recall_skills_for_turn(
         return skills, config
 
     def _build_recalled_skills_prompt(
-        self, skills: List[Skill], config: Optional[SynthesisConfig]
+        self, skills: List[DistilledProcedure], config: Optional[SynthesisConfig]
     ) -> str:
         """Render the recalled-procedure system-prompt section from ``skills``.
 
@@ -400,8 +401,9 @@ def _refresh_recalled_skills(self, goal: str) -> None:
         """Recompute the per-turn recalled-skill state for ``goal``.
 
         Recalls the matching procedures **once** and caches both consumers'
-        inputs: ``self._recalled_skills`` (the matched ``Skill`` objects, read by
-        the tool loader through ``_recalled_skill_tools`` — #1451) and the
+        inputs: ``self._recalled_skills`` (the matched ``DistilledProcedure``
+        objects, read by the tool loader through ``_recalled_skill_tools`` —
+        #1451) and the
         rendered ``self._recalled_skill_prompt`` (the system-prompt block, read by
         ``get_recalled_skills_system_prompt`` — #887).  The single recall keeps
         the loader's SKILL signal free (no second ``recall_skill``).