@skill-graph/cli 0.5.7 → 0.5.8

package/examples/evals/visual-design-foundations.json

@@ -1,7 +1,12 @@
 {
   "skill_name": "visual-design-foundations",
   "subject": "Visual craft decisions for color, typography, spacing, density, hierarchy, elevation, and motion feel",
-  "adjacent_concepts": ["semiotics", "design-system-architecture", "layout-composition", "a11y"],
+  "adjacent_concepts": [
+    "semiotics",
+    "design-system-architecture",
+    "layout-composition",
+    "a11y"
+  ],
   "grounding_note": "Truth sources cite the whole SKILL.md file to keep the initial eval surface stable while the new skill settles.",
   "evals": [
     {
@@ -13,7 +18,9 @@
       "truth_mode": "process_correctness",
       "skill_type": "concept",
       "criticality": "high",
-      "truth_sources": ["skills/visual-design-foundations/SKILL.md"]
+      "truth_sources": [
+        "skills/design/visual-design-foundations/SKILL.md"
+      ]
     },
     {
       "id": 2,
@@ -24,7 +31,9 @@
       "truth_mode": "code_verification",
       "skill_type": "concept",
       "criticality": "normal",
-      "truth_sources": ["skills/visual-design-foundations/SKILL.md"]
+      "truth_sources": [
+        "skills/design/visual-design-foundations/SKILL.md"
+      ]
     },
     {
       "id": 3,
@@ -35,7 +44,9 @@
       "truth_mode": "code_verification",
       "skill_type": "concept",
       "criticality": "normal",
-      "truth_sources": ["skills/visual-design-foundations/SKILL.md"]
+      "truth_sources": [
+        "skills/design/visual-design-foundations/SKILL.md"
+      ]
     },
     {
       "id": 4,
@@ -46,7 +57,9 @@
       "truth_mode": "conceptual_correctness_plus_repo_application",
       "skill_type": "concept",
       "criticality": "normal",
-      "truth_sources": ["skills/visual-design-foundations/SKILL.md"]
+      "truth_sources": [
+        "skills/design/visual-design-foundations/SKILL.md"
+      ]
     }
   ]
 }

package/examples/evals/webhook-integration.json

@@ -1,7 +1,12 @@
 {
   "skill_name": "webhook-integration",
   "subject": "Inbound third-party webhook handler design for signature verification, idempotency, provider retry contracts, raw payload persistence, quarantine, secret rotation, and PII capture timing",
-  "adjacent_concepts": ["event-contract-design", "testing-strategy", "debugging", "owasp-security"],
+  "adjacent_concepts": [
+    "event-contract-design",
+    "testing-strategy",
+    "debugging",
+    "owasp-security"
+  ],
   "grounding_note": "Truth sources cite the whole SKILL.md file to keep the initial eval surface stable while routing boundaries are tightened.",
   "evals": [
     {
@@ -13,7 +18,9 @@
       "truth_mode": "process_correctness",
       "skill_type": "workflow",
       "criticality": "high",
-      "truth_sources": ["skills/webhook-integration/SKILL.md"]
+      "truth_sources": [
+        "skills/engineering/webhook-integration/SKILL.md"
+      ]
     },
     {
       "id": 2,
@@ -24,7 +31,9 @@
       "truth_mode": "conceptual_correctness_plus_repo_application",
       "skill_type": "workflow",
       "criticality": "high",
-      "truth_sources": ["skills/webhook-integration/SKILL.md"]
+      "truth_sources": [
+        "skills/engineering/webhook-integration/SKILL.md"
+      ]
     },
     {
       "id": 3,
@@ -35,7 +44,9 @@
       "truth_mode": "code_verification",
       "skill_type": "concept",
       "criticality": "normal",
-      "truth_sources": ["skills/webhook-integration/SKILL.md"]
+      "truth_sources": [
+        "skills/engineering/webhook-integration/SKILL.md"
+      ]
     },
     {
       "id": 4,
@@ -46,7 +57,9 @@
       "truth_mode": "code_verification",
       "skill_type": "concept",
       "criticality": "normal",
-      "truth_sources": ["skills/webhook-integration/SKILL.md"]
+      "truth_sources": [
+        "skills/engineering/webhook-integration/SKILL.md"
+      ]
     }
   ]
 }

package/examples/fixture-skills/README.md

@@ -0,0 +1,47 @@
+# Hermetic Test Fixtures (v6)
+
+> **Purpose:** minimal v6-conformant skills used as hermetic fixtures for the
+> `@skill-graph/cli` package tests. The published package can validate
+> against these without needing a sibling `skills/` clone.
+>
+> **Status:** v6 (current contract). Update when the schema bumps.
+
+## Fixtures
+
+| Fixture | Type | Scope | Tests | Status |
+|---|---|---|---|---|
+| [`minimal-capability`](minimal-capability/SKILL.md) | capability | portable | Bare-minimum v6 frontmatter; happy-path lint pass | **shipped** |
+| [`with-grounding`](with-grounding/SKILL.md) | capability | codebase | Conditional requiredness — `grounding.*` sub-fields + non-empty `keywords` | **shipped** |
+| [`with-relations`](with-relations/SKILL.md) | capability | portable | All four `relations.*` edges (related / boundary / verify_with / depends_on) using `{skill, reason}` object shape | **shipped** |
+| [`comprehension-full`](comprehension-full/SKILL.md) | capability | portable | Flat Understanding fields + nested v5 `concept` block (anyOf back-compat) | **shipped** |
+
+All four fixtures cross-reference each other in `with-relations`, forming
+a closed reference set: lint resolves every relation target from this
+directory alone, with no dependency on the sibling `../skills/skills/`
+canonical library. The four fixtures together exercise every conditional
+required rule in the v6 schema (`scope: codebase → grounding`,
+`comprehension_state: present → concept`) plus the lint rule that
+`scope: codebase` demands non-empty `keywords`. See [SH-6132](https://linear.app/sales-hub/issue/SH-6132) EPIC for context.
+
+## Usage
+
+```bash
+# Lint a single fixture against the v6 schema:
+node bin/skill-graph.js lint examples/fixture-skills/minimal-capability
+
+# Lint every fixture in one pass:
+node scripts/skill-lint.js --path examples/fixture-skills
+```
+
+## Invariants
+
+- Every shipped fixture validates against `schemas/skill.v6.schema.json` with zero errors.
+- Every fixture has `schema_version: 6`.
+- No fixture depends on a non-fixture skill (relations between fixtures only).
+- Cross-fixture `relations.*` targets MUST exist in this directory.
+
+## Maintenance
+
+- When the schema bumps, every fixture's `schema_version` advances in the same commit as the schema change.
+- When a new conditional rule lands (e.g. a new `allOf` block), add or extend the fixture that exercises it.
+- Treat these as the canonical regression suite for any change to lint, audit, manifest generation, or routing.

package/examples/fixture-skills/comprehension-full/SKILL.md

@@ -0,0 +1,79 @@
+---
+schema_version: 6
+name: comprehension-full
+description: "Use as the v6-conformant fixture exercising the full Understanding surface — flat top-level fields (mental_model, purpose, boundary, analogy, misconception) AND the nested v5 concept block for anyOf back-compat. Activate this skill when verifying that lint accepts both presentation forms when comprehension_state is present. Do NOT use as a production skill (use a real capability skill from the canonical library)."
+version: 1.0.0
+type: capability
+category: engineering
+scope: portable
+owner: skill-graph-fixture-suite
+freshness: "2026-05-19"
+comprehension_state: present
+mental_model: "Understanding fields are the comprehension grader's reading surface. The grader expects five primitives — mental_model, purpose, boundary, analogy, misconception — each with its own grading dimension and weight. v6 promotes them to flat top-level fields; v5 nested them inside a concept block. Both shapes must round-trip cleanly through lint, manifest generation, and the grader."
+purpose: "Comprehension grading checks whether an agent given the SKILL.md can answer realistic scenarios. The Understanding fields anchor that grading by declaring what the skill claims to teach. Before v6, these primitives lived as bold-label body sections that parsers had to scrape; v5 lifted them into the nested concept block; v6 promotes them to flat top-level fields so consumers no longer need to walk a sub-object to read them."
+boundary: "Comprehension grading is NOT routing-eval (which tests whether the router picks the right skill) and NOT lint (which tests schema conformance). The flat top-level boundary field (concept-layer) is also distinct from relations.boundary (routing-layer handoff): one declares what the skill is NOT conceptually; the other declares which sibling skill should handle a misrouted query."
+analogy: "Like the difference between a book's table of contents and its index. Both let a reader find content, but they answer different questions. Flat Understanding fields are the index — direct, addressable, no nesting. The legacy concept block was the table of contents — hierarchical, requiring traversal."
+misconception: "Believing that comprehension_state: present means the skill ships a passing comprehension eval. It does not. comprehension_state: present means the skill carries the Understanding fields the grader reads against; eval_state: passing is a separate, independent claim that the eval has been run and succeeded."
+concept:
+  definition: "The legacy nested v5 concept block. Seven required sub-fields covering definition, mental_model, purpose, boundary, taxonomy, analogy, and misconception. Retained in v6 for back-compat so v5 skills not yet migrated still satisfy the comprehension_state: present requirement."
+  mental_model: "v5 grouped the seven primitives under one frontmatter key (concept) for namespacing. v6 unbundled them to flat top-level fields. The grader reads from the flat fields first when both are present; the nested block remains valid as a fallback."
+  purpose: "Allow v5 skills to satisfy the comprehension_state: present requirement during the multi-cycle v5→v6 migration without forcing a flag-day rewrite of every author skill."
+  boundary: "Not a replacement for the flat fields in v6 — when both are present in a v6 skill, the flat fields win. Do not author new v6 skills that only set the nested block; treat the nested block as a back-compat surface, not the canonical home."
+  taxonomy: "Subset of the v6 Understanding surface — every nested concept.* sub-field has a flat top-level equivalent (or, for definition, is absorbed by description; for taxonomy, by category + relations.broader)."
+  analogy: "Like the v3.1 alias pattern (e.g., grounding.subject for grounding.domain_object). Both shapes validate; both round-trip; the preferred form takes precedence when both are present."
+  misconception: "Believing the v6 schema removed the nested concept block. It did not — the schema retains it under an anyOf rule so v5 skills continue to validate without modification. v6 deprecates the nested form for new skills but does not eliminate it."
+drift_check:
+  last_verified: "2026-05-19"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: Apache-2.0
+---
+
+# Comprehension-Full Fixture
+
+This fixture exercises the full Understanding surface in two presentation
+forms simultaneously: the v6 flat top-level fields (`mental_model`,
+`purpose`, `boundary`, `analogy`, `misconception`) AND the nested v5
+`concept` block. The lint and the comprehension grader must both accept
+either shape, and when both are present the flat fields must win.
+
+## Coverage
+
+The five flat Understanding fields (v6 canonical) and the seven nested
+`concept` sub-fields (v5 back-compat) co-existing in one skill, plus
+`comprehension_state: present` to trigger the conditional requirement.
+No grounding (scope: portable), no relations, no Health Block.
+
+## Philosophy
+
+The v5 → v6 migration cannot happen as a flag-day — there are too many
+adopter skills to rewrite atomically. v6 keeps the nested `concept` block
+under an `anyOf` rule so v5 skills validate without changes, while the
+new flat top-level fields become the canonical authoring surface for
+new skills. This fixture is the smallest configuration that proves both
+shapes round-trip through lint together, anchoring the regression test
+that detects any future change that would force a flag-day rewrite.
+
+## Verification
+
+```bash
+node scripts/skill-lint.js --path examples/fixture-skills/comprehension-full
+# expected: 0 errors
+node scripts/skill-lint.js --path examples/fixture-skills
+# expected: 0 errors across all four fixtures
+```
+
+Lint must accept the dual-shape skill: `comprehension_state: present`
+satisfied by the nested `concept` block (per the v6 anyOf back-compat
+rule) AND the flat top-level fields present alongside it. If the grader
+reads from both, the flat values must take precedence — that contract is
+documented in the v5-to-v6 migration note in `skill-metadata-protocol`.
+
+## Do NOT Use When
+
+- You need to test the bare-minimum frontmatter — use `minimal-capability`.
+- You need to test codebase grounding — use `with-grounding`.
+- You need to test typed relations — use `with-relations`.
+- You need to test v6-only flat Understanding fields without the nested back-compat block — author a separate fixture or use a real v6-only canonical skill.

package/examples/fixture-skills/minimal-capability/SKILL.md

@@ -0,0 +1,51 @@
+---
+schema_version: 6
+name: minimal-capability
+description: "Use as the smallest v6-conformant capability fixture for skill-graph package tests. Activate this skill when verifying that lint, manifest generation, and routing accept the bare-minimum required v6 frontmatter. Do NOT use as a production skill (use a real capability skill from the canonical library)."
+version: 1.0.0
+type: capability
+category: engineering
+scope: portable
+owner: skill-graph-fixture-suite
+freshness: "2026-05-19"
+drift_check:
+  last_verified: "2026-05-19"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: Apache-2.0
+---
+
+# Minimal Capability Fixture
+
+This fixture exercises the bare-minimum required v6 frontmatter. It contains
+only the required fields, the recommended stability + license fields, and the
+four capability-archetype body sections.
+
+## Coverage
+
+The 13 required v6 frontmatter fields, plus `stability` and `license`. No
+optional fields, no relations, no grounding, no Understanding fields, no
+Health Block.
+
+## Philosophy
+
+The simplest possible v6 skill should still pass lint. If this fixture ever
+starts failing lint without a deliberate schema change, the lint check has
+regressed or grown a new required field that this fixture should adopt
+together with the canonical library.
+
+## Verification
+
+```bash
+node scripts/skill-lint.js --path examples/fixture-skills/minimal-capability
+# expected: 0 errors
+```
+
+## Do NOT Use When
+
+- You need to exercise codebase grounding — see the `with-grounding` planned fixture in [`../README.md`](../README.md).
+- You need to exercise typed relations — see the `with-relations` planned fixture in [`../README.md`](../README.md).
+- You need to exercise flat Understanding fields or the Health Block — see the `comprehension-full` planned fixture in [`../README.md`](../README.md).
+- You need a real production-grade authoring example — use a canonical skill from `skills/`.

package/examples/fixture-skills/with-grounding/SKILL.md

@@ -0,0 +1,78 @@
+---
+schema_version: 6
+name: with-grounding
+description: "Use as the minimal v6-conformant codebase-grounded fixture for skill-graph package tests. Activate this skill when verifying that lint enforces grounding requireds (domain_object, grounding_mode, truth_sources, failure_modes, evidence_priority) and non-empty keywords for scope: codebase. Do NOT use as a production skill (use a real grounded skill from the canonical library)."
+version: 1.0.0
+type: capability
+category: engineering
+scope: codebase
+owner: skill-graph-fixture-suite
+freshness: "2026-05-19"
+keywords:
+  - grounding
+  - fixture
+  - truth-sources
+  - hermetic-test
+grounding:
+  domain_object: "v6 grounding contract"
+  grounding_mode: repo_specific
+  truth_sources:
+    - path: "examples/fixture-skills/README.md"
+      anchor: "Invariants"
+      note: "The hermetic-fixture invariants document what every fixture in this directory must satisfy."
+  failure_modes:
+    - "If the v6 schema renames or removes a grounding sub-field, this fixture must move in lockstep with the schema bump."
+    - "If the fixture-skills README anchor 'Invariants' is renamed, the anchor reference above breaks and lint fails."
+  evidence_priority: repo_code_first
+drift_check:
+  last_verified: "2026-05-19"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: Apache-2.0
+---
+
+# With-Grounding Fixture
+
+This fixture exercises the v6 conditional rule `scope: codebase → grounding
+required`, plus the lint rule that `scope: codebase` skills must declare
+non-empty `keywords`. Together those two rules form the smallest
+routing-discoverable, drift-trackable v6 skill.
+
+## Coverage
+
+The five required `grounding` sub-fields (`domain_object`, `grounding_mode`,
+`truth_sources`, `failure_modes`, `evidence_priority`), an object-shaped
+truth_source entry with `path` + `anchor` + `note`, and the non-empty
+`keywords` array that scope: codebase demands. No relations, no Health Block,
+no Understanding fields.
+
+## Philosophy
+
+The grounding block is the contract that distinguishes a knowledge skill from
+a hallucinated one. A `scope: codebase` skill is making claims about specific
+local files; those claims rot when the files move. The grounding block records
+*which* files anchor the claim, *how* to detect drift (anchor or line_range
+hashing), and *what* failure modes appear when drift occurs. This fixture is
+the smallest configuration that exercises every grounding required field
+without depending on a sibling skills clone.
+
+## Verification
+
+```bash
+node scripts/skill-lint.js --path examples/fixture-skills/with-grounding
+# expected: 0 errors
+```
+
+Lint must accept this fixture even when the published `@skill-graph/cli`
+package is installed standalone (no sibling `../skills/skills/` clone). The
+truth_source path resolves under the package's own `examples/fixture-skills/`
+tree, not under the canonical skill library.
+
+## Do NOT Use When
+
+- You need to test the bare-minimum frontmatter — use `minimal-capability`.
+- You need to test typed relations — use `with-relations`.
+- You need to test flat Understanding fields or the nested concept block — use `comprehension-full`.
+- You need a production codebase-grounded skill — use a real grounded skill from `skills/` (e.g. `nextauth-patterns`, `query-tier-safety`).

package/examples/fixture-skills/with-relations/SKILL.md

@@ -0,0 +1,87 @@
+---
+schema_version: 6
+name: with-relations
+description: "Use as the v6-conformant fixture exercising all four typed relation predicates (related, boundary, verify_with, depends_on) using the {skill, reason} object shape. Activate this skill when verifying that lint resolves cross-fixture relation targets without a sibling skills clone. Do NOT use as a production skill (use a real capability skill from the canonical library)."
+version: 1.0.0
+type: capability
+category: engineering
+scope: portable
+owner: skill-graph-fixture-suite
+freshness: "2026-05-19"
+relations:
+  related:
+    - skill: minimal-capability
+      reason: "Same fixture-suite kind (capability/portable) — minimal-capability is the bare-minimum baseline this fixture extends with relation edges."
+  boundary:
+    - skill: with-grounding
+      reason: "Use with-grounding instead when the test target is grounding-block requireds or scope: codebase keyword enforcement — this fixture is portable and groundless by design."
+  verify_with:
+    - skill: comprehension-full
+      reason: "When this fixture's relation edges are exercised in a routing-eval pass, comprehension-full provides the flat Understanding fields the grader reads against."
+  depends_on:
+    - skill: minimal-capability
+      reason: "Composition signal: this fixture assumes the lint passes for the minimal-capability baseline; if minimal-capability regresses, this fixture is meaningless until the baseline is repaired."
+drift_check:
+  last_verified: "2026-05-19"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: Apache-2.0
+---
+
+# With-Relations Fixture
+
+This fixture exercises every typed relation predicate in the v6 contract using
+the canonical `{skill, reason}` object shape. Together with the sibling
+fixtures (`minimal-capability`, `with-grounding`, `comprehension-full`) it
+forms a closed cross-reference cluster — lint resolves every relation target
+from the fixtures directory alone, with no dependency on the sibling
+`../skills/skills/` canonical library.
+
+## Coverage
+
+The four relation kinds with distinct semantics:
+
+| Predicate | Meaning | Target here |
+|---|---|---|
+| `related` | Adjacency for browse / routing expansion | `minimal-capability` |
+| `boundary` | Routing-layer handoff ("use that one instead because...") | `with-grounding` |
+| `verify_with` | Cross-check: when applied, verify with another | `comprehension-full` |
+| `depends_on` | Composition: this assumes the other is in scope | `minimal-capability` |
+
+Each entry carries a non-empty `reason` string — lint warns on relations that
+omit the reason field because routing decisions become unauditable without it.
+
+## Philosophy
+
+Relations are the edges of the Skill Graph. The four predicates are
+intentionally orthogonal: `related` is symmetric and weakly directional,
+`boundary` is asymmetric and routing-routed, `verify_with` is symmetric and
+quality-routed, `depends_on` is asymmetric and load-order-routed. Conflating
+them would force the router to guess intent. This fixture is the smallest
+configuration that demonstrates the distinction across every predicate at
+once, hermetically, without leaking any canonical-skill name into the test
+surface.
+
+## Verification
+
+```bash
+node scripts/skill-lint.js --path examples/fixture-skills/with-relations
+# expected: 0 errors
+node scripts/skill-lint.js --path examples/fixture-skills
+# expected: 0 errors across all four fixtures with relations resolved
+```
+
+Lint must resolve every relation target from the union of configured roots
+plus the explicit `--path` set. In a hermetic package-test environment
+(no sibling skills clone), the four fixtures in this directory form a closed
+cross-reference set: every `relations.*` target above names another fixture
+that lives in the same directory.
+
+## Do NOT Use When
+
+- You need to test the bare-minimum frontmatter — use `minimal-capability`.
+- You need to test codebase grounding — use `with-grounding`.
+- You need to test flat Understanding fields or the nested concept block — use `comprehension-full`.
+- You need to test relation-target resolution against the canonical library — use any real skill from `skills/` (e.g. `naming-conventions` → `semantics`).