skill-flow 1.0.1 → 1.0.3

package/docs/refrences/naming-dedupe-warning-rules.md

@@ -1,482 +0,0 @@
-# Naming, Dedupe, and Warning Rules
-
-This document explains the naming rules used by `skill-flow`, especially for workflow groups and skills, and clarifies the current dedupe and warning behavior.
-
-## Overview
-
-The project intentionally separates:
-
-- stable internal identifiers
-- user-facing display names
-- final projected names on target agents
-
-These are related, but they are not the same field.
-
-## Core Terms
-
-### Group
-
-A group is one registered Git source. In code, this is the source/workflow group stored in `manifest.json` and `lock.json`.
-
-Relevant fields:
-
-- `source.locator`: the user-provided source locator
-- `source.displayName`: the readable group name
-- `source.id`: the stable internal identifier
-
-### Skill
-
-A skill is one discovered `SKILL.md` leaf inside a group.
-
-Relevant fields:
-
-- `leaf.id`: the stable internal identifier
-- `leaf.name`: normalized value from `SKILL.md` frontmatter `name`
-- `leaf.linkName`: the readable skill name and default projection name
-- `leaf.title`: display title derived from the first markdown heading or the raw name
-
-### Projected Name
-
-When a skill is deployed to an agent target, the actual directory/link name may differ from `leaf.linkName` if there is a collision. The final deployed name is the projected name.
-
-Current rule:
-
-- no collision: use `leaf.linkName`
-- collision: prefer `groupName-skillName`
-- if that still collides, fall back to `groupId-skillName`
-
-## Group Naming Rules
-
-### `source.locator`
-
-This is the original source reference the user added, for example:
-
-- `garrytan/gstack`
-- `https://github.com/garrytan/gstack`
-- `https://github.com/garrytan/gstack.git`
-- `git@github.com:garrytan/gstack.git`
-- `/local/path/to/repo`
-
-### `source.displayName`
-
-This is the readable group name.
-
-Rules:
-
-- GitHub source: use the repo name
-- `.git` URL: use the basename without `.git`
-- local path: use the final path segment
-
-Examples:
-
-- `garrytan/gstack` -> `gstack`
-- `https://github.com/garrytan/gstack.git` -> `gstack`
-- `/Users/me/my-skills` -> `my-skills`
-
-### `source.id`
-
-This is the stable internal group identifier.
-
-Rules:
-
-- GitHub source: `slugify("${owner}-${repo}")`
-- non-GitHub source: `slugify(displayName)`
-
-Examples:
-
-- `garrytan/gstack` -> `garrytan-gstack`
-- `https://github.com/garrytan/gstack.git` -> `garrytan-gstack`
-- `git@github.com:garrytan/gstack.git` -> `garrytan-gstack`
-- `/Users/me/my-skills` -> `my-skills`
-
-Why this exists:
-
-- `displayName` is for readability
-- `source.id` is for stability and uniqueness
-
-This is why two GitHub repos with the same repo name but different owners do not collide:
-
-- `alice/gstack` -> `alice-gstack`
-- `garrytan/gstack` -> `garrytan-gstack`
-
-## Group Display Rules
-
-In `config`, group labels are displayed as:
-
-- `group_name(@user_name)`
-
-Example:
-
-- `gstack(@garrytan)`
-
-This is display-only. It does not change `source.id`, `displayName`, bindings, or lock data.
-
-The same group label is now also used in user-facing list and doctor output where the source is known.
-
-## Skill Naming Rules
-
-### Discovery
-
-The scanner finds every `SKILL.md` under the source checkout, excluding:
-
-- `.git`
-- `node_modules`
-
-Each discovered `SKILL.md` becomes a skill candidate.
-
-### `leaf.id`
-
-This is the stable skill identifier.
-
-Rule:
-
-- `leaf.id = "${sourceId}:${relativePath}"`
-
-Examples:
-
-- `garrytan-gstack:browse`
-- `garrytan-gstack:catalog/review`
-- `garrytan-gstack:.` for a root-level skill
-
-This ID is based on source identity plus path identity, not on frontmatter `name`.
-
-### `leaf.name`
-
-This comes from frontmatter `name`, normalized with `slugify`.
-
-Example:
-
-```yaml
----
-name: browse
-description: ...
----
-```
-
-becomes:
-
-- `leaf.name = "browse"`
-
-This field is the skill's declared canonical name, but it is not the main config display label.
-
-### `leaf.linkName`
-
-This is the human-facing skill name used in `config`, and the default projected name for deployment.
-
-Rules:
-
-- if the skill is inside a subdirectory, use that directory name
-- if the skill is at the repo root, use the group's `displayName`
-
-Examples:
-
-Repository:
-
-```text
-repo/
-  browse/SKILL.md
-  review/SKILL.md
-```
-
-Results:
-
-- `browse` -> `leaf.linkName = "browse"`
-- `review` -> `leaf.linkName = "review"`
-
-Repository:
-
-```text
-repo/
-  SKILL.md
-```
-
-If the group display name is `gstack`, then:
-
-- root skill -> `leaf.linkName = "gstack"`
-
-Important:
-
-- skill labels do not inherit the GitHub owner in normal display
-- the owner is shown at the group level, not the skill level
-
-### `leaf.title`
-
-This is derived from:
-
-- the first `# ` heading in the markdown body, or
-- the raw frontmatter `name`, or
-- `"Untitled skill"`
-
-This is descriptive metadata, not the deployment name.
-
-## Dedupe Logic
-
-There are two different dedupe layers in the project.
-
-### 1. Source dedupe
-
-This prevents the same source from being added twice.
-
-The add flow checks whether a source with the same `source.id` already exists.
-
-For GitHub, these forms all normalize to the same source identity:
-
-- `https://github.com/garrytan/gstack`
-- `https://github.com/garrytan/gstack.git`
-- `git@github.com:garrytan/gstack.git`
-- `garrytan/gstack`
-
-All four produce:
-
-- `source.displayName = "gstack"`
-- `source.id = "garrytan-gstack"`
-
-So they are treated as the same group and cannot be added twice.
-
-This dedupe is identity-based.
-
-It does not depend on:
-
-- how the user typed the locator
-- whether the source used https, ssh, or `owner/repo`
-
-### 2. Skill content dedupe inside one source
-
-After scanning a source, the inventory builder dedupes skills inside that source.
-
-The dedupe key is:
-
-- `parsed.name + "\n" + parsed.description`
-
-This means two skills in the same source are considered duplicates if both:
-
-- their frontmatter `name` is the same
-- their frontmatter `description` is the same
-
-When duplicates are found:
-
-- the first discovered candidate is kept
-- later duplicates are moved to `invalidLeafs`
-- an invalid reason is recorded explaining which earlier path won
-
-Current discovery order:
-
-- files and directories are walked in sorted order
-- visible directories are scanned before hidden directories
-
-So "first discovered" is deterministic.
-
-Important limitations of the current dedupe behavior:
-
-- dedupe happens only within one source scan
-- it does not merge or eliminate duplicates across different groups
-- cross-group duplication is handled later at projection time, not inventory time
-
-### 3. Cross-group name collision handling during deployment
-
-This is not inventory dedupe. It is deployment conflict resolution.
-
-When multiple selected skills for the same target have the same `leaf.linkName`:
-
-- if there is no collision, projected name = `leaf.linkName`
-- if there is a collision, projected name prefers `${groupName}-${leaf.linkName}`
-- if that projected name still collides, projected name falls back to `${sourceId}-${leaf.linkName}`
-
-Example:
-
-- group `gstack(@garrytan)` has `browse`
-- group `toolkit(@alice)` has `browse`
-
-If both are selected for the same target:
-
-- `browse` becomes `gstack-browse`
-- `browse` becomes `toolkit-browse`
-
-This keeps both deployable without overwriting each other.
-
-Fallback example:
-
-- `gstack(@alice)` has `browse`
-- `gstack(@garrytan)` has `browse`
-
-Preferred projected names would both be `gstack-browse`, so the system falls back to:
-
-- `alice-gstack-browse`
-- `garrytan-gstack-browse`
-
-## Warning Logic
-
-Warnings in the current system come from multiple places.
-
-### 1. Metadata warnings on valid skills
-
-A skill can still be valid while carrying metadata warnings.
-
-Current metadata warning rules include:
-
-- `name` is not 1-64 characters
-- `name` contains invalid characters
-- `name` does not match the parent directory name
-- `description` is empty
-- `description` is longer than 1024 characters
-
-These warnings do not block the skill from being included if the required structure is still valid.
-
-Examples:
-
-- frontmatter exists
-- `name` exists
-- `description` exists
-- but `name` does not match the directory
-
-That skill is still accepted, but it carries a warning.
-
-### 2. Invalid leaf records
-
-Some issues are hard failures for a specific skill candidate.
-
-Examples:
-
-- `SKILL.md` does not start with YAML frontmatter
-- frontmatter is missing `name`
-- frontmatter is missing `description`
-- the skill was dropped as a duplicate within the same source
-
-These are recorded as `invalidLeafs`.
-
-Invalid leafs are not added to the active leaf inventory.
-
-When a source is added or updated:
-
-- valid leafs are kept
-- invalid leafs are reported as warnings in the operation result
-
-So from the user's perspective, "skipped" items often surface as warnings, even though internally they are tracked as invalid leafs.
-
-### 3. Projection warnings
-
-During config/deployment preview, additional warnings can appear.
-
-Examples:
-
-- another selected skill in a different group has identical content
-- selected leaf no longer exists in source inventory
-- a target path is blocked by foreign content
-
-These warnings are deployment-related, not metadata-related.
-
-They describe what will happen when the current selection is projected.
-
-### 4. UI display behavior
-
-In `config`:
-
-- a skill row is tinted warning/yellow if it has metadata warnings
-- a skill row is also tinted warning/yellow if it has projection warnings
-
-This means the same yellow state can be caused by different warning categories:
-
-- metadata shape problem
-- projection conflict
-- duplicate-selection side effect
-
-## Valid vs Warning vs Invalid
-
-The easiest way to reason about the current system is:
-
-- valid: accepted into inventory and deployable in principle
-- warning: accepted, but something about it is questionable or conflicting
-- invalid: not accepted into inventory as an active skill
-
-Examples:
-
-- `name` mismatches parent directory -> valid + warning
-- missing `description` -> invalid
-- duplicate content inside one source -> invalid
-- same skill name in two groups -> valid, but may need renamed projection on a target
-
-## Practical Examples
-
-### Example 1: same GitHub repo added with different locator formats
-
-Commands:
-
-```bash
-skill-flow add https://github.com/garrytan/gstack
-skill-flow add git@github.com:garrytan/gstack.git
-```
-
-Result:
-
-- second add is rejected as already existing
-- because both normalize to `source.id = garrytan-gstack`
-
-### Example 2: root-level skill GitHub repo
-
-Repo:
-
-```text
-gstack/
-  SKILL.md
-```
-
-Result:
-
-- group display in config: `gstack(@garrytan)`
-- root skill display in config: `gstack`
-
-Not:
-
-- `garrytan-gstack`
-
-### Example 3: duplicate skill content inside one repo
-
-Repo:
-
-```text
-repo/
-  browse/SKILL.md
-  browse-copy/SKILL.md
-```
-
-If both files declare the same frontmatter `name` and `description`:
-
-- first one discovered is kept
-- second one is marked invalid
-- the source add/update returns a warning for the skipped duplicate
-
-### Example 4: same link name across different groups
-
-Groups:
-
-- `gstack(@garrytan)` with skill `browse`
-- `toolkit(@alice)` with skill `browse`
-
-Config display:
-
-- both still show as `browse`
-
-Projection to the same target:
-
-- `gstack-browse`
-- `toolkit-browse`
-
-This is conflict resolution, not inventory dedupe.
-
-## Current Design Intent
-
-The naming model is intentionally split this way:
-
-- group identity should be globally stable
-- group display should be human-readable
-- skill display should follow repo structure
-- deployment naming should stay clean by default
-- only collisions should force prefixes
-
-In short:
-
-- group uniqueness uses `source.id`
-- group display uses `displayName` plus owner context in UI
-- skill display uses `leaf.linkName`
-- target conflict resolution prefers `${displayName}-${linkName}`
-- if that still collides, target conflict resolution falls back to `${sourceId}-${linkName}`