@skill-graph/cli 0.5.6

package/docs/glossary.md

@@ -0,0 +1,190 @@
+# Skill Graph Glossary
+
+> Canonical definitions for every domain term used by Skill Metadata Protocol and Skill Graph. Field-reference doc links to these entries instead of redefining terms inline.
+
+## Relation predicates
+
+### `adjacent` *(deprecated alias of `related`)*
+
+The v3.0 name for the symmetric associative relation. Still valid in v3.x; lint emits a soft warning pointing at `related`. Removal target: v4 (ADR 0001).
+
+### `related`
+
+*v3.1 preferred name; W3C mapping: `skos:related`*
+
+Symmetric co-read relation. Use for skills that teach the same surface from different angles — reading one prompts a reader to want the other. Relation is symmetric in intent but the schema does not enforce reciprocity; lint-level reciprocity checking is a future feature. Max 5 entries recommended per skill to avoid hub-and-spoke clutter.
+
+### `boundary`
+
+Routing-layer anti-ownership edge. Use for skills this skill explicitly does NOT own, where the router should hand a near-miss prompt to a different skill. This relation is directional and Skill-Graph-specific; it is intentionally weaker than formal OWL disjointness. Item shape: bare string OR `{skill, reason}`. Reasons are strongly recommended because routing handoffs need an explicit boundary rule.
+
+### `disjoint_with`
+
+*v3.1 addition; W3C mapping: `owl:disjointWith`*
+
+Formal class-disjointness assertion. Use only when the two skill concepts are genuinely disjoint in the ontology sense. This is rare in day-to-day routing; most wrong-skill prevention belongs in `boundary`. `disjoint_with` is symmetric in meaning even though the schema does not enforce reciprocal authoring.
+
+### `broader`
+
+*v3.1 addition; W3C mapping: `skos:broader`*
+
+Cross-skill generalisation. Use when this skill is a *specialisation* of another skill that is NOT its overlay parent (if it were, use `extends` instead). Closes the gap where `category` cannot express skill-to-skill generalisation across taxonomy branches.
+
+Example: `react-best-practices` has `broader: [frontend]`.
+
+### `narrower`
+
+*v3.1 addition; W3C mapping: `skos:narrower`*
+
+Cross-skill specialisation. The inverse of `broader` — this skill is more general than the targets. Tooling can infer `narrower` from other skills' `broader` edges, so explicit authoring is optional.
+
+### `verify_with`
+
+*W3C mapping: `prov:wasInformedBy`*
+
+Skills that should be co-loaded for verification or that provide cross-checks. This is a provenance-style relation (PROV-O), not a classification relation — it captures "A's claims are informed by B's claims", not "A is-a B" or "A is-related-to B". Keep to 1-3 high-signal verifiers.
+
+### `depends_on`
+
+*W3C mapping: `dcterms:requires`*
+
+Pragmatic prerequisite — this skill requires the target conceptually or operationally. Item shape: bare string OR `{skill, min_version}`. Use `min_version` when the depended-on skill's contract has versioned and this skill's claims depend on a specific version.
+
+### `extends`
+
+*W3C mapping: `prov:wasDerivedFrom`*
+
+Overlay specialisation. Single-parent only (ADR 0001). Required when `type: overlay`. The overlay existentially depends on the parent: if the parent were deleted, the overlay loses its meaning (OntoClean +D; ADR 0003).
+
+## Archetypes
+
+### `capability`
+
+*OntoClean: +R (rigid), +I (identity), +U (unity), -D (dependence)*
+
+A standalone functional skill — what the agent *can do*. Has its own identity criteria and scope. Does not existentially depend on another skill.
+
+Required body sections: `## Coverage`, `## Philosophy`, `## Verification`, `## Do NOT Use When`.
+
+### `workflow`
+
+*OntoClean: +R, +I, +U, -D*
+
+A step-by-step procedural skill. Adds `## Workflow` to the required body sections.
+
+Required body sections: `## Coverage`, `## Philosophy`, `## Workflow`, `## Verification`, `## Do NOT Use When`.
+
+### `router`
+
+*OntoClean: ~R (semi-rigid), -I, ~U, +D*
+
+A skill that dispatches to other skills. Its essence is defined by what it dispatches to, so its identity shifts when the dispatch set shifts.
+
+Required body sections: `## Coverage`, `## Routing Rules`, `## Do NOT Use When`.
+
+### `overlay`
+
+*OntoClean: -R (anti-rigid), -I, -U, +D*
+
+A skill that specialises another skill. The overlay's essence is "specialisation of X" — it vanishes if X is deleted. Identity is inherited from the parent, not redefined.
+
+Required body sections: `## Coverage`, `## Overlay Rules`, `## Extends`, `## Do NOT Use When`. Also requires the `extends` field at the top level.
+
+The key OntoClean constraint: an anti-rigid property cannot subsume a rigid one. In practice: an overlay *specialises* its parent, it does not *replace* the parent's identity. If an overlay's body rewrites the parent's `## Coverage`, it is not an overlay — it is a separate capability. Change the `type` accordingly.
+
+## Grounding modes
+
+### `repo_specific`
+
+Skill claims are grounded in a specific codebase. `scope: codebase` requires this mode or `hybrid`. `grounding.truth_sources` lists concrete file paths.
+
+### `universal`
+
+Skill claims are grounded in a language, framework, or specification that exists independently of any one codebase. `grounding.truth_sources` lists external specs or canonical docs.
+
+### `hybrid`
+
+Skill claims blend `repo_specific` and `universal` grounding. Use when a framework's general rules interact with repo-specific patterns.
+
+## Evidence priority
+
+### `repo_code_first`
+
+When repo code and general knowledge disagree, trust the repo code. Default for `scope: codebase` skills.
+
+### `general_knowledge_first`
+
+When repo code and general knowledge disagree, trust the general knowledge. Rare; use for skills where the repo is known to be behind the standard.
+
+### `equal`
+
+No presumption. The skill's `## Verification` section tells the reader how to resolve conflicts.
+
+## Portability readiness
+
+### `declared`
+
+Portability is asserted in metadata only. The author claims the skill is portable; no export tooling has been run.
+
+### `scripted`
+
+Export tooling exists for at least one target. `scripts/export-skill.js` can transform this skill.
+
+### `verified`
+
+Export tooling exists AND the exported output has been checked against the target runtime. A receipt artifact (test run, import check) proves the exported skill works.
+
+## Eval-health triple
+
+### `eval_artifacts`
+
+Does an eval file exist on disk? Values: `none` (no work started), `planned` (intended, not yet authored), `present` (file exists and is referenced).
+
+### `eval_state`
+
+Have the evals been run and passed? Values: `unverified` (no passing run recorded), `passing` (recent green run), `monitored` (continuously verified by a live toolchain).
+
+### `routing_eval`
+
+Is routing explicitly evaluated? Values: `absent`, `present`. `present` requires the harness at `scripts/skill-graph-routing-eval.js` to return PASS for the skill.
+
+## Identity terms
+
+### `urn`
+
+*v3.1 addition, optional; target-required in v4. W3C mapping: `@id`.*
+
+Globally-unique persistent identifier in the `urn:skill:<repo>:<skill-name>` form (RFC 8141). Unlocks FAIR Findability across repos. Consumers treat the URN as stable identity; `name` is display-layer.
+
+## Contract-version terms
+
+### `schema_version`
+
+Integer or string-of-integer identifying the Skill Metadata Protocol version. Currently `3`. Bumps on breaking changes to field semantics, shape, or required-ness. Additive additions (new optional fields, new enum values, new lint warnings) do not bump the version.
+
+### `stability`
+
+Lifecycle state of the skill: `experimental`, `stable`, `frozen`, `deprecated`. `deprecated` requires `superseded_by`.
+
+### `superseded_by`
+
+Name of the skill that replaces this one. Mandatory when `stability: deprecated`. W3C mapping: `prov:wasRevisionOf` (inverted).
+
+## FAIR mapping
+
+Each term below names the FAIR dimension(s) the Skill Graph field covers (Wilkinson et al. 2016):
+
+- **Findable:** `name`, `urn`, `description`, `keywords`, `triggers`, `examples`, `category`, `domain`, `routing_bundles`
+- **Accessible:** `paths`, `allowed-tools`, `compatibility`, `portability`
+- **Interoperable:** `schema_version`, the JSON-LD `@context`, SPDX in `license`, all typed predicates
+- **Reusable:** `license`, `compatibility`, `portability.targets`, `grounding.truth_sources`, `freshness`, `drift_check`, `lifecycle`, `grounding.evidence_priority`
+
+## References
+
+- SKOS Reference — https://www.w3.org/TR/skos-reference/
+- PROV-O — https://www.w3.org/TR/prov-o/
+- Dublin Core Metadata Terms — https://www.dublincore.org/specifications/dublin-core/dcmi-terms/
+- OntoClean (Guarino & Welty 2002) — Communications of the ACM 45(2):61-65
+- FAIR Principles (Wilkinson et al. 2016) — Scientific Data 3:160018. DOI:10.1038/sdata.2016.18
+- RFC 8141 (URN Syntax) — https://datatracker.ietf.org/doc/html/rfc8141
+- SPDX License List — https://spdx.org/licenses/

package/docs/head-noun-glossary.md

@@ -0,0 +1,63 @@
+# Head-Noun Glossary
+
+> Type: Reference
+> Purpose: Canonical head nouns for skill names, derived from current live usage.
+> Last updated: 2026-05-17 (Wave 6 closure: `patterns` 6→7 from ref-patterns; Wave 6 batch 3 had bumped `design` 10→12 — the count fix resolved a pre-existing off-by-one — and `patterns` 5→6)
+
+## What this is
+
+A skill name is a **noun-anchored compound**, not a verb. The **head noun** is the rightmost segment of the kebab-case name and tells the reader what kind of thing the skill is.
+
+- `component-architecture` — head = `architecture`, modifier = `component`
+- `client-server-boundary` — head = `boundary`, modifiers = `client`, `server`
+- `epistemic-grounding` — head = `grounding`, modifier = `epistemic`
+
+This file enumerates head nouns currently in use across the 102 skills in `skill-graph/skills/`, plus head nouns reserved for upcoming gap-fill skills. Adding a new head noun to a skill name should require justifying it here.
+
+## Why head nouns matter
+
+Verb-prefix names (`polish-`, `audit-`, `critique-`, `improve-`) don't compose with the protocol's taxonomy axes. They look like commands, not concepts. Noun-anchored names compose: `category × head-noun` is a clean two-dimensional lookup that the router can reason about.
+
+The skills that violate this convention live in `name-exceptions.yaml` with citations for why they're industry term-of-art.
+
+## Active head nouns (derived from live skill names)
+
+| Head noun | Live count | Example skills |
+|---|---|---|
+| `modeling` | 7 | conceptual-modeling, data-modeling, entity-relationship-modeling, knowledge-modeling, ontology-modeling, state-machine-modeling, observability-modeling |
+| `design` | 12 | api-design, agent-eval-design, color-system-design, event-contract-design, taxonomy-design, theme-system-design, test-doubles-design, integration-test-design, e2e-test-design, server-components-design, server-actions-design, route-handler-design |
+| `testing` | 5 | contract-testing, mutation-testing, property-based-testing, snapshot-testing, performance-testing |
+| `architecture` | 7 | component-architecture, dependency-architecture, design-system-architecture, form-ux-architecture, frontend-architecture, streaming-architecture, agent-engineering (umbrella) |
+| `strategy` | 6 | testing-strategy, seo-strategy, tool-call-strategy, test-coverage-strategy, indexing-strategy, sharding-strategy |
+| `development` | 4 | spec-driven-development, ai-native-development, eval-driven-development, test-driven-development |
+| `engineering` | 3 | agent-engineering, performance-engineering, prompt-craft (suffix-style) |
+| `analysis` | 3 | diff-analysis, research-synthesis, task-analysis |
+| `patterns` | 7 | interaction-patterns, vercel-composition-patterns, replication-patterns, hooks-patterns, suspense-patterns, middleware-patterns, ref-patterns |
+| `fundamentals` | 3 | acid-fundamentals, data-modeling-fundamentals, security-fundamentals |
+| `mapping` | 2 | bounded-context-mapping, journey-mapping |
+| `recognition` | 2 | intent-recognition, pattern-recognition |
+| `composition` | 2 | design-module-composition, layout-composition |
+| `boundary` | 2 | client-server-boundary, error-boundary |
+
+## Single-instance head nouns (kept for completeness)
+
+`audit`, `cognition`, `craft`, `defense` (live in `prompt-injection-defense`), `evolution` (live in `schema-evolution`), `extraction`, `feedback`, `flow` (live in `tool-call-flow`), `foundations`, `governance`, `hierarchy`, `humanizer`, `infrastructure`, `isolation` (live in `transaction-isolation`), `management` (live in `state-management`), `migration`, `models` (live in `mental-models`), `monitor`, `optimization` (live in `query-optimization`), `palette`, `pooling` (live in `connection-pooling`), `queue`, `relations`, `review`, `router`, `routing`, `scaffold`, `scheduling`, `semantics`, `semiotics`, `solving`, `storming`, `summarization`, `synthesis`, `system`, `thinking`, `tracking`, `tradeoffs` (live in `cap-theorem-tradeoffs`), `ui` (live in `generative-ui`), `updates`, `ux`, `window`.
+
+## Reserved head nouns (gap-fill skills, not yet authored)
+
+All Wave 1–5 reservations are now live in source. New gap-fill waves will populate this section.
+
+_(empty — all reservations promoted to Active or Single-instance lists)_
+
+## Rules
+
+1. **Use an existing head noun when one fits.** Don't invent new ones for nominal variation.
+2. **One head noun per skill name.** The compound is `<modifier(s)>-<head>`. Modifiers can be multi-segment (`client-server-`), the head is always the last segment.
+3. **No verb prefixes.** Banned in the head position and as standalone names: `audit-X`, `polish-X`, `critique-X`, `improve-X`, `fix-X`. Exception: when the verb has a noun reading that is the industry term-of-art (e.g. `code-review`, `design-review`, `event-storming`). These must be enumerated in `docs/name-exceptions.yaml` with a citation.
+4. **Adding a new head noun.** Update this glossary in the same commit as the skill, with the live example and a one-line rationale. Drift between glossary and live names is a lint warning candidate.
+
+## See also
+
+- `docs/name-exceptions.yaml` — Established industry term-of-art skills that violate the head-noun rule.
+- `SKILL_METADATA_PROTOCOL.md` § `name` — the schema pattern (`^[a-z0-9][a-z0-9-/:]*$`) is the shape; this glossary is the policy.
+- `scripts/lint/check-category-enum.js` — companion lint check for the category axis.

package/docs/integrations/github-actions.md

@@ -0,0 +1,155 @@
+# GitHub Actions Integration
+
+Add Skill Graph lint to your own repository's CI pipeline.
+
+> **Package shape.** The GitHub repository is `jacob-balslev/skill-graph`. The npm package is `@skill-graph/cli`, and it exposes the `skill-graph` binary. The CLI is a thin dispatcher over the same zero-dependency scripts used in this repo, so local development, CI, and installed usage share one code path.
+
+## Installation (npm package)
+
+After the package is published, install it as a dev dependency and run the binary through `npx`:
+
+```bash
+npm install --save-dev @skill-graph/cli
+```
+
+```yaml
+# .github/workflows/skill-graph-lint.yml
+name: Skill Graph Lint
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'skills/**'
+  pull_request:
+    paths:
+      - 'skills/**'
+
+jobs:
+  lint:
+    name: Lint skills
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install Skill Graph
+        run: npm install --save-dev @skill-graph/cli
+      - name: Run skill lint
+        run: npx skill-graph lint
+      - name: Verify SKILL.md export
+        run: npx skill-graph export-verify
+```
+
+For local release testing before npm publish, run `npm link` from a clone of this repo, then use `skill-graph lint`, `skill-graph manifest`, `skill-graph route`, and `skill-graph drift` from the consumer repository.
+
+## Installation (clone and vendor)
+
+For air-gapped environments or repos with strict supply-chain policy, copy the self-contained scripts into your repository and commit them alongside your skills. The scripts use only Node built-ins once vendored.
+
+### 1. Vendor the scripts
+
+From the Skill Graph repo, copy these paths into your own repository under a path you control (example uses `tools/skill-graph/`):
+
+```
+scripts/skill-lint.js           → tools/skill-graph/skill-lint.js
+scripts/lib/                    → tools/skill-graph/lib/
+scripts/lint/                   → tools/skill-graph/lint/
+scripts/check-protocol-consistency.js  (optional) → tools/skill-graph/check-protocol-consistency.js
+scripts/generate-manifest.js    (optional) → tools/skill-graph/generate-manifest.js
+scripts/export-skill.js         (optional) → tools/skill-graph/export-skill.js
+schemas/skill.schema.json       → tools/skill-graph/schemas/skill.schema.json
+schemas/manifest.schema.json    → tools/skill-graph/schemas/manifest.schema.json
+```
+
+The lint script resolves its schema location relative to its own file path, so keep the `schemas/` directory alongside the scripts in whichever target layout you pick.
+
+### 2. Commit and reference from CI
+
+```yaml
+# .github/workflows/skill-graph-lint.yml
+name: Skill Graph Lint
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'skills/**'
+      - 'tools/skill-graph/**'
+  pull_request:
+    paths:
+      - 'skills/**'
+      - 'tools/skill-graph/**'
+
+jobs:
+  lint:
+    name: Lint skills
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Run skill lint
+        run: node tools/skill-graph/skill-lint.js
+```
+
+This triggers on any PR or push to `main` that touches a file under `skills/` or the vendored scripts. It exits 1 (failing the job) when any skill file has a schema or structural error.
+
+**Trade-off.** No external dependency. You own the script and update it manually by re-copying from the Skill Graph repo when you want a newer version. This is the right path for air-gapped environments and repos with strict supply-chain policies.
+
+### 3. Pointing at a non-default skills directory
+
+If your skills live somewhere other than `skills/`, either declare the roots in `.skill-graph/config.json` or pass the root directory explicitly. The linter treats a directory containing many `<skill>/SKILL.md` folders as a skill root:
+
+```yaml
+- name: Run skill lint
+  run: node tools/skill-graph/skill-lint.js src/skills
+```
+
+Update the `paths:` filter to match:
+
+```yaml
+paths:
+  - 'src/skills/**'
+```
+
+### 4. Skipping generator parity when you intentionally diverge
+
+When `examples/skills.manifest.sample.json` is absent, generator parity is skipped automatically. Use `--skip-generator-parity` only when the sample manifest exists but your CI job intentionally does not want to compare it with freshly generated output:
+
+```yaml
+- name: Run skill lint
+  run: node tools/skill-graph/skill-lint.js --skip-generator-parity
+```
+
+## What the lint checks
+
+The same checks run whether you install the npm package or vendor the script:
+
+1. Schema validation against `skill.schema.json`
+2. Parent-directory-matches-name (SKILL.md compatibility)
+3. Relation target existence (linked skills must exist in the repo)
+4. Eval artifact coherence (`eval_artifacts: present` requires at least one eval file)
+5. Archetype-aware section validation (required H2 sections per archetype)
+6. Routing quality (keywords required for `scope: codebase` skills)
+7. SKILL.md export compatibility (when `export-verify` is run)
+
+See [`SKILL_AUDIT_CHECKLIST.md`](https://github.com/jacob-balslev/skill-audit-loop/blob/main/SKILL_AUDIT_CHECKLIST.md) for the full list of what each check catches.
+
+## Example: PR blocked by a malformed skill
+
+Given a skill file with a missing required `description` field:
+
+```
+ERR  skills/my-skill/SKILL.md:3:1
+  |
+3 | name: my-skill
+  | ^
+  |
+  = description: required field is missing
+    Add a one-line routing contract: `description: "What this skill does and when to use it."`
+```
+
+The job exits 1 and GitHub blocks the merge until the field is added.