skill-versioning Specification

Purpose

TBD - created by archiving change skill-learning-runtime. Update Purpose after archive.

Requirements

Requirement: Structural divergence triggers a new version

The system SHALL compare a newly synthesized flow's tool-name step sequence against the currently-stored version of the matching skill, and SHALL create a new version (rather than overwriting the stored one) whenever the tool-name sequence differs by insertion, deletion, or reordering of a step.

Scenario: Extra step triggers a new version

WHEN a newly executed flow for a matching skill contains an additional tap step not present in the currently-stored version's sequence
THEN the system stores a new version of the skill rather than overwriting the existing stored version

Scenario: Reordered steps trigger a new version

WHEN a newly executed flow for a matching skill executes the same tool names as the stored version but in a different order
THEN the system stores a new version of the skill

Scenario: Argument-value-only differences do not trigger a version bump

WHEN a newly executed flow has the identical tool-name sequence as the stored version and differs only in argument values already covered by parameter abstraction
THEN the system does not create a new version, and instead updates the existing version's parameters per the skill-authoring capability

Requirement: Version history is retained, never silently overwritten

The system SHALL retain every version of a skill it creates, each carrying an incrementing version number and a reference to the version it diverged from, and SHALL NOT delete or overwrite a prior version's stored record when a new version is created.

Scenario: New version references its parent

WHEN a new version of a skill is created due to structural divergence
THEN the new version's record stores a reference to the prior version's id and an incremented version number

Scenario: Prior version remains fetchable

WHEN a new version of a skill has been created
THEN the prior version's record remains retrievable by its own id, unmodified

Requirement: Default retrieval surfaces the newest version

The system SHALL treat the highest-numbered version of a skill as the default result returned by a lookup-by-name/goal-family query, while still allowing an explicit lookup of any specific prior version by its id.

Scenario: Lookup by name returns newest version

WHEN a caller looks up a skill by its name or goal-family without specifying a version
THEN the system returns the highest-numbered stored version of that skill

Scenario: Explicit id lookup returns the requested version

WHEN a caller requests a skill by a specific prior version's id
THEN the system returns that exact version's record, not the newest version

2.8 KiB Raw Blame History