Class SkillLineage

openspace/skill_engine/types.py:70–159

Tracks the evolutionary lineage of a skill. ``parent_skill_ids`` may contain multiple parents for DERIVED. FIXED always has exactly one parent (the previous version). IMPORTED / CAPTURED have no parents. ─── generation ───────────────────────────────────────────────── Distance

@dataclass
class SkillLineage:
    """Tracks the evolutionary lineage of a skill.

    ``parent_skill_ids`` may contain multiple parents for DERIVED.
    FIXED always has exactly one parent (the previous version).
    IMPORTED / CAPTURED have no parents.

    ─── generation ─────────────────────────────────────────────────

    Distance from root in the version DAG. Set by the evolution logic
    when creating a new skill record:

      - IMPORTED / CAPTURED → ``generation = 0``  (root node)
      - FIXED               → ``parent.generation + 1``
      - DERIVED             → ``max(p.generation for p in parents) + 1``

    ─── change_summary ─────────────────────────────────────────────

    LLM-generated free-text description of what changed vs. the parent.
    Produced by the evolution LLM when creating FIXED or DERIVED skills.
    Examples:
      - FIXED:   "Fixed curl parameter format in step 3"
      - DERIVED: "Composed weather + geocoding guides into an
                  end-to-end location-aware forecast workflow"
      - IMPORTED / CAPTURED: typically empty or a brief import note.

    ─── content_diff / content_snapshot ────────────────────────────

    ``content_snapshot`` stores the **full directory snapshot** at this
    version as a ``Dict[str, str]`` mapping relative file paths to their
    text content.

    ``content_diff`` stores a combined unified diff (``git diff``
    format) covering **all** files in the skill directory.
    Policy by parent count:

      - **0 parents** (IMPORTED / CAPTURED):
        add-all diff — every line prefixed with ``+``
        (like ``git diff /dev/null`` for each file).
      - **1 parent** (FIXED, or single-parent DERIVED):
        normal unified diff between the parent's directory content
        and this version's directory content, covering all files.
      - **N parents** (multi-parent DERIVED):
        ``""`` (empty string). A multi-parent composition is a
        creative act, not a patch — per-parent diffs are large and
        unhelpful.  The composition intent is captured in
        ``change_summary`` instead.  Individual parent content can
        be retrieved via ``parent_skill_ids`` → each parent's
        ``content_snapshot``.
    """

    origin: SkillOrigin
    generation: int = 0                                    # Distance from root (see docstring)
    parent_skill_ids: List[str] = field(default_factory=list)  # [] for IMPORTED / CAPTURED
    source_task_id: Optional[str] = None                   # Task that triggered evolution / capture
    change_summary: str = ""                               # LLM-generated description of changes
    content_diff: str = ""                                 # Combined unified diff of all files (empty for multi-parent DERIVED)
    content_snapshot: Dict[str, str] = field(default_factory=dict)  # {relative_path: content} full directory snapshot