@skill-graph/cli 0.5.6

package/schemas/manifest.v6.schema.json

@@ -0,0 +1,811 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skillgraph.dev/schemas/manifest.v6.schema.json",
+  "title": "Skill Graph Manifest (v6, pinned)",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "generated_at",
+    "summary",
+    "skills"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "oneOf": [
+        {
+          "type": "integer",
+          "const": 4
+        },
+        {
+          "type": "string",
+          "const": "4"
+        }
+      ],
+      "description": "Major contract shape version. Integer for v4+; string '4' tolerated for back-compat with hand-rolled YAML. Bumps when shape changes break consumers."
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional multi-root workspace metadata. Emitted when `.skill-graph/config.json` declares workspace projects. Consumers filter generated `skills[].project` ownership and authored `skills[].workspace_tags` relevance against this block.",
+      "properties": {
+        "projects": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "semantic_tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "skill_roots": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "total_skills"
+      ],
+      "properties": {
+        "total_skills": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "by_type": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "by_category": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "by_scope": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "by_stability": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "by_project": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      }
+    },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "path",
+          "name",
+          "description",
+          "version",
+          "type",
+          "category",
+          "scope",
+          "owner"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "project": {
+            "type": "string",
+            "description": "Literal handle of the project this skill was loaded from. Absent for skills loaded from a shared root without a project owner."
+          },
+          "name": {
+            "type": "string"
+          },
+          "urn": {
+            "type": "string",
+            "pattern": "^urn:skill:[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-/:]*$",
+            "description": "Optional globally-unique persistent identifier from the authored frontmatter (RFC 8141). Pass-through \u2014 generator does not synthesise this."
+          },
+          "description": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "capability",
+              "workflow",
+              "router",
+              "overlay"
+            ]
+          },
+          "archetype": {
+            "type": "string",
+            "enum": [
+              "capability",
+              "workflow",
+              "router",
+              "overlay"
+            ],
+            "description": "v3.1 preferred alias for `type`. Pass-through from authored frontmatter."
+          },
+          "category": {
+            "type": "string"
+          },
+          "domain": {
+            "type": "string"
+          },
+          "scope": {
+            "type": "string",
+            "enum": [
+              "codebase",
+              "reference",
+              "portable"
+            ]
+          },
+          "owner": {
+            "type": "string"
+          },
+          "stability": {
+            "type": "string",
+            "enum": [
+              "experimental",
+              "stable",
+              "frozen",
+              "deprecated"
+            ]
+          },
+          "superseded_by": {
+            "type": "string",
+            "description": "Name of the skill that replaces this one. Populated when authored `stability: deprecated`. Consumers use this to follow deprecation chains automatically."
+          },
+          "extends": {
+            "type": "string"
+          },
+          "workspace_tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "activation": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "triggers": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "keywords": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "paths": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "examples": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "anti_examples": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "relations": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "adjacent": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "related": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "broader": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "narrower": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "boundary": {
+                "type": "array",
+                "items": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": [
+                        "skill"
+                      ],
+                      "properties": {
+                        "skill": {
+                          "type": "string"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  ]
+                }
+              },
+              "disjoint_with": {
+                "type": "array",
+                "items": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": [
+                        "skill"
+                      ],
+                      "properties": {
+                        "skill": {
+                          "type": "string"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  ]
+                }
+              },
+              "verify_with": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "depends_on": {
+                "type": "array",
+                "items": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": [
+                        "skill"
+                      ],
+                      "properties": {
+                        "skill": {
+                          "type": "string"
+                        },
+                        "min_version": {
+                          "type": "string",
+                          "description": "Semver range for the minimum required version. Accepts bare semver, caret, tilde, comparator, or AND-joined ranges.",
+                          "pattern": "^(\\^|~|>=|<=|>|<|=)?[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?( +(\\^|~|>=|<=|>|<|=)?[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?)*$"
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "grounding": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "domain_object",
+              "grounding_mode",
+              "truth_sources",
+              "failure_modes",
+              "evidence_priority"
+            ],
+            "properties": {
+              "domain_object": {
+                "type": "string"
+              },
+              "subject": {
+                "type": "string",
+                "description": "v3.1 preferred alias for `domain_object`. Pass-through."
+              },
+              "grounding_mode": {
+                "type": "string",
+                "enum": [
+                  "repo_specific",
+                  "universal",
+                  "hybrid"
+                ]
+              },
+              "claim_scope": {
+                "type": "string",
+                "enum": [
+                  "repo_specific",
+                  "universal",
+                  "hybrid"
+                ],
+                "description": "v3.1 preferred alias for `grounding_mode`. Pass-through."
+              },
+              "truth_sources": {
+                "type": "array",
+                "items": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": [
+                        "path"
+                      ],
+                      "properties": {
+                        "path": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "line_range": {
+                          "type": "object",
+                          "additionalProperties": false,
+                          "required": [
+                            "start"
+                          ],
+                          "properties": {
+                            "start": {
+                              "type": "integer",
+                              "minimum": 1
+                            },
+                            "end": {
+                              "type": "integer",
+                              "minimum": 1
+                            }
+                          }
+                        },
+                        "anchor": {
+                          "type": "string"
+                        },
+                        "note": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  ]
+                }
+              },
+              "failure_modes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "evidence_priority": {
+                "type": "string",
+                "enum": [
+                  "repo_code_first",
+                  "general_knowledge_first",
+                  "equal"
+                ]
+              }
+            }
+          },
+          "routing_bundles": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "license": {
+            "type": "string"
+          },
+          "compatibility": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "runtimes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "agent_runtimes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "v3.1 preferred alias for `runtimes`. Pass-through."
+              },
+              "node": {
+                "type": "string"
+              },
+              "node_version": {
+                "type": "string",
+                "description": "v3.1 preferred alias for `node`. Pass-through."
+              },
+              "notes": {
+                "type": "string",
+                "description": "Free-text additional compatibility notes. Pass-through from SKILL.md. No protocol length cap."
+              }
+            }
+          },
+          "allowed-tools": {
+            "type": "string"
+          },
+          "allowed_tools": {
+            "type": "string",
+            "description": "v3.1 preferred snake_case alias for `allowed-tools`. Pass-through."
+          },
+          "portability": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "readiness": {
+                "type": "string",
+                "enum": [
+                  "declared",
+                  "scripted",
+                  "verified"
+                ]
+              },
+              "targets": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": [
+                    "skill-md"
+                  ]
+                }
+              },
+              "export_targets": {
+                "type": "array",
+                "description": "v3.1 preferred alias for `targets`. Pass-through.",
+                "items": {
+                  "type": "string",
+                  "enum": [
+                    "skill-md"
+                  ]
+                }
+              }
+            }
+          },
+          "health": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "eval_artifacts": {
+                "type": "string"
+              },
+              "eval_state": {
+                "type": "string"
+              },
+              "routing_eval": {
+                "type": "string"
+              },
+              "eval_last_run": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "at",
+                  "status"
+                ],
+                "properties": {
+                  "at": {
+                    "type": "string",
+                    "format": "date-time"
+                  },
+                  "status": {
+                    "type": "string",
+                    "enum": [
+                      "pass",
+                      "fail",
+                      "mixed"
+                    ]
+                  },
+                  "runner": {
+                    "type": "string"
+                  },
+                  "model": {
+                    "type": "string"
+                  },
+                  "receipt": {
+                    "type": "string"
+                  },
+                  "receipt_hash": {
+                    "type": "string",
+                    "pattern": "^[a-f0-9]{64}$"
+                  }
+                }
+              },
+              "eval": {
+                "type": "object",
+                "additionalProperties": false,
+                "description": "v3.1 preferred nested form for the eval-health triple. Pass-through from authored frontmatter.",
+                "properties": {
+                  "artifacts": {
+                    "type": "string"
+                  },
+                  "content_state": {
+                    "type": "string"
+                  },
+                  "routing_coverage": {
+                    "type": "string"
+                  },
+                  "comprehension_state": {
+                    "type": "string",
+                    "enum": [
+                      "absent",
+                      "present"
+                    ],
+                    "description": "v3.1 preferred nested alias for top-level `comprehension_state`. Pass-through."
+                  }
+                }
+              },
+              "freshness": {
+                "type": "string",
+                "format": "date"
+              },
+              "reviewed_at": {
+                "type": "string",
+                "format": "date",
+                "description": "v3.1 preferred alias for `freshness`. Pass-through."
+              },
+              "drift_check": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "last_verified"
+                ],
+                "properties": {
+                  "last_verified": {
+                    "type": "string",
+                    "format": "date"
+                  },
+                  "verified_at": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "v3.1 preferred alias for `last_verified`. Pass-through."
+                  },
+                  "truth_source_hashes": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "type": "string",
+                      "pattern": "^[a-f0-9]{64}$"
+                    }
+                  }
+                }
+              },
+              "lifecycle": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "stale_after_days": {
+                    "type": "integer",
+                    "minimum": 1
+                  },
+                  "review_cadence": {
+                    "type": "string",
+                    "enum": [
+                      "per-commit",
+                      "weekly",
+                      "quarterly",
+                      "on-truth-source-change"
+                    ]
+                  }
+                }
+              },
+              "runtime_telemetry": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "feedback_source"
+                ],
+                "properties": {
+                  "feedback_source": {
+                    "type": "string"
+                  },
+                  "last_updated": {
+                    "type": "string",
+                    "format": "date"
+                  },
+                  "metrics": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "sample_size": {
+                        "type": "integer",
+                        "minimum": 0
+                      },
+                      "success_rate": {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 1
+                      }
+                    }
+                  }
+                }
+              },
+              "has_grounding": {
+                "type": "boolean"
+              },
+              "has_relations": {
+                "type": "boolean"
+              },
+              "drift_detected": {
+                "type": "boolean",
+                "description": "True when any normalized `grounding.truth_sources` key has a current SHA-256 hash that differs from the stored `drift_check.truth_source_hashes` value. Computed by the manifest generator when hashes are available."
+              },
+              "comprehension_state": {
+                "type": "string",
+                "enum": [
+                  "absent",
+                  "present"
+                ],
+                "description": "Does this skill carry a comprehension eval (typically `evals/comprehension.json`) and a `concept` block authored for the 7-dimension comprehension grader? `absent` (no comprehension grading), `present` (comprehension evals exist; the `concept` block is required by the allOf rule). Optional in v3 \u2014 omitted means `absent`. Independent of `routing_eval` (router-level) and `eval_state` (content-level). The nested `eval.comprehension_state` is the v3.1 preferred alias."
+              },
+              "last_audited": {
+                "type": "string",
+                "format": "date",
+                "description": "ISO date (YYYY-MM-DD) the `audit` command last ran against this skill. Written by `scripts/skill/skill-audit.js`. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "last_changed": {
+                "type": "string",
+                "format": "date",
+                "description": "ISO date (YYYY-MM-DD) the SKILL.md body or frontmatter was last edited. Written automatically by `improve` operations. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "audit_verdict": {
+                "type": "string",
+                "enum": [
+                  "PASS",
+                  "PASS_WITH_FIXES",
+                  "PARTIAL",
+                  "FAIL",
+                  "UNKNOWN"
+                ],
+                "description": "Aggregate result of the most recent `audit` run. Combines `lint_verdict`, `drift_status`, and (when run with `--graded`) the seven dimension scores. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "eval_score": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 5,
+                "description": "Latest aggregate eval grade on a 0.0\u20135.0 scale, written by `scripts/skill/evaluate-skill.js`. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "eval_failed_ids": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Eval IDs that failed in the most recent run. Empty array when clean. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "lint_verdict": {
+                "type": "string",
+                "enum": [
+                  "PASS",
+                  "FAIL",
+                  "UNKNOWN"
+                ],
+                "description": "Result of the most recent deterministic-lint pass against this skill. `PASS` means zero lint errors; `UNKNOWN` is the initial state. Pass-through from authored frontmatter (v6 Health Block)."
+              },
+              "drift_status": {
+                "type": "string",
+                "enum": [
+                  "OK",
+                  "DRIFT",
+                  "BROKEN",
+                  "STALE",
+                  "NO_BASELINE",
+                  "EXTERNAL_UNHASHED",
+                  "UNKNOWN"
+                ],
+                "description": "Current truth-source drift status. `OK` (live hashes match recorded), `DRIFT` (mismatch), `BROKEN` (truth source missing), `STALE`, `NO_BASELINE`, `EXTERNAL_UNHASHED`, `UNKNOWN`. Pass-through from authored frontmatter (v6 Health Block)."
+              }
+            }
+          },
+          "concept": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "definition",
+              "mental_model",
+              "purpose",
+              "boundary",
+              "taxonomy",
+              "analogy",
+              "misconception"
+            ],
+            "properties": {
+              "definition": {
+                "type": "string",
+                "description": "What the concept IS. Primary category + what it does + who uses it. A domain outsider should understand. Author as deeply as the concept requires \u2014 there is no protocol length cap. Graded by the comprehension grader's `definition` dimension (weight 1.0)."
+              },
+              "mental_model": {
+                "type": "string",
+                "description": "Primitives and their relationships. Name primitives and the relationships between them. Markdown permitted inside the string. Author with the depth the concept needs \u2014 there is no protocol length cap. Graded by the comprehension grader's `mental_model` dimension (weight 1.5)."
+              },
+              "purpose": {
+                "type": "string",
+                "description": "What problem the concept solves and the alternative it replaced. Concrete pain point + prior alternative. No protocol length cap \u2014 explain as fully as the concept needs. Graded by the comprehension grader's `purpose` dimension (weight 1.0)."
+              },
+              "boundary": {
+                "type": "string",
+                "description": "Things commonly confused with the concept but that are NOT it. Express each difference as a mechanism (different primitives, different purpose, different scope) - not just different names. No protocol length cap. Graded by the comprehension grader's `boundary` dimension (weight 1.5)."
+              },
+              "taxonomy": {
+                "type": "string",
+                "description": "Nearby concepts with their relationship type (subset / alternative / prerequisite / composition / specialization). Markdown list permitted inside the string. No protocol length cap. Graded by the comprehension grader's `taxonomy` dimension (weight 1.0)."
+              },
+              "analogy": {
+                "type": "string",
+                "description": "Analogy that preserves the core mechanism. Translate for a non-expert without breaking the structural relationship between primitives. No protocol length cap. Graded by the comprehension grader's `analogy` dimension (weight 0.5)."
+              },
+              "misconception": {
+                "type": "string",
+                "description": "The wrong mental model people bring and why it misleads. Authored hint to inoculate the agent against the common error trap. No protocol length cap. Not directly graded; complements `boundary`."
+              }
+            },
+            "description": "Seven-field universal-subject concept teaching block. Read by the comprehension grader (`scripts/skill/evaluate-skill.js --comprehension`) and rendered into the agent context when the skill is loaded. Required when `comprehension_state: present`. No protocol length cap \u2014 author each field as deeply as the concept requires. Distinct from `## Philosophy` in the body, which is about *why this skill file exists in this repo*; the `concept` block is about *what the subject is, universally*."
+          }
+        }
+      }
+    }
+  }
+}