@skill-graph/cli 0.5.6

package/CHANGELOG.md

@@ -0,0 +1,247 @@
+# Changelog
+
+All notable changes to Skill Graph are recorded here.
+
+The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Skill Graph versions describe the contract at each checkpoint in the git history and are how consumers pin. Beginning with 0.5.0, the repository is package-ready as `@skill-graph/cli` with the `skill-graph` binary. `schema_version` in the JSON Schemas tracks contract shape (currently `6` — owned by [skill-metadata-protocol](https://github.com/jacob-balslev/skill-metadata-protocol); see [ADR 0007](https://github.com/jacob-balslev/skill-metadata-protocol/blob/main/docs/adr/0007-version-source-of-truth.md) for the cross-repo source-of-truth model); this changelog tracks the library as a whole (tooling + starters + docs).
+
+## [Unreleased]
+
+### Added
+- **`data/publication-classification.json`** — hand-edited ledger of per-skill marketplace publication classification (`publishable` / `sales-hub-bound` / `personal-infra`) plus market-state attributes (`tier`, `pop_score`, `source`, `needs_sanitization`, `demand_signal`, `rename_to`, `notes`). Seeds the `publicationQueue` in the unified `.opencode/progress/skill-audit-worklist.json` (consumed by `skill-audit-loop@0.3.0`). 218 skills classified at seed (136 publishable, 55 sales-hub-bound, 27 personal-infra). Seeded by `scripts/seed-publication-classification.js` from the now-archived 2026-05-18 priority doc; hand-edited going forward.
+- **`scripts/seed-publication-classification.js`** — one-off seeder script that parses the priority doc tables into the ledger. Re-runnable; preserves first-classification-wins semantics.
+- **`docs/marketplace-publication-queue.generated.md`** — auto-generated by `skill-audit-loop@0.3.0` from the ledger. Tier-grouped publication queue with conflict and orphan tracking. Replaces the hand-curated priority doc as the living source of marketplace publication priority.
+- **npm publish pipeline (SH-6111).** Added `.github/workflows/publish.yml` — CI publishes `@skill-graph/cli` to npm on `v*.*.*` tag push after `npm test` passes. Uses `NPM_TOKEN` secret and npm provenance attestation (`--provenance`). Manual prereqs before first publish: (1) create the `@skill-graph` npm org at https://www.npmjs.com/org/create (the npm CLI does NOT support org creation; the org must be created via the website), (2) add `NPM_TOKEN` as a GitHub repo secret. First publish is pending Jacob's `npm version patch && git push --tags`. See [README.md § Releasing](README.md#releasing-maintainers).
+- **Lint check 14 — stability promotion gate (SH-6109).** `scripts/skill-lint.js` now includes a WARN-level check that fires when a skill declares `stability: stable` without meeting five promotion criteria: (1) `eval_state` is `passing` or `monitored`, (2) `eval_score` ≥ 4.0 on the 0.0–5.0 scale, (3) `routing_eval: present`, (4) `drift_check.last_verified` within the last 90 days, (5) `grounding.truth_sources` is populated for `scope: codebase` and `scope: reference` skills (`scope: portable` is exempt). All five criteria are evaluated independently — all failures are reported, never short-circuited. WARN level only (never ERROR), so the 140 currently-experimental skills are unaffected. Implemented in `scripts/lint/check-stability-promotion.js`; 8 tests in `scripts/__tests__/test-stability-promotion.js` (6 required cases + 2 edge cases). Promotion criteria documented in `docs/skill-metadata-protocol.md § Stability Promotion Criteria`. Status: 0/140 library skills currently declare `stability: stable`.
+
+### Removed
+- **`docs/marketplace-publication-priority-2026-05-18.md`** — archived to `docs/_archived/marketplace-publication-priority-2026-05-18.md` and superseded by `docs/marketplace-publication-queue.generated.md`. The hand-curated priority doc lived for one day before being merged into the auto-generated queue (via `skill-graph/data/publication-classification.json` + `skill-audit-loop@0.3.0`). Reasoning preserved in the archived copy for audit-trail grep.
+
+### Changed
+- **Cross-repo version reconciliation (SH-6124).** README and CHANGELOG references to `schema_version: 4` updated to `schema_version: 6` (the actual current contract owned by `skill-metadata-protocol`). Repository Map updated to mention v6 in `schemas/`. The local `schemas/` directory still pins v4 and v5 alongside v6 for tooling that consumes the schemas directly; the unversioned mirror tracks v6.
+- **schema_version 6 — flat fields + Health Block.** Promotes the seven nested `concept.*` sub-fields to flat top-level fields (`mental_model`, `purpose`, `boundary`, `analogy`, `misconception`; `definition` collapses into `description`; `taxonomy` collapses into `category` + `relations.broader`) and introduces the seven-field flat Health Block (`last_audited`, `last_changed`, `audit_verdict`, `eval_score`, `eval_failed_ids`, `lint_verdict`, `drift_status`). Added `schemas/skill.v6.schema.json` + the v5→v6 migration codemod at `scripts/migrate-skill-v5-to-v6.js`. Full author-facing procedure lives in [`skill-metadata-protocol/docs/migrations/v5-to-v6.md`](https://github.com/jacob-balslev/skill-metadata-protocol/blob/main/docs/migrations/v5-to-v6.md).
+- **schema_version 5 — closed `category` enum.** Closed the `category` field to a 6-value enum (`foundations | engineering | design | quality | agent | product`) and removed 7 deprecated values. Promoted `quality` from facet to 6th category. Added `schemas/skill.v5.schema.json` and `scripts/migrate-skill-v4-to-v5.js`.
+- **schema_version 4 naming cleanup.** Renamed `browse_category` to `category`, hierarchical `category` / `category_path` to `domain`, `project_tags` to `workspace_tags`, and `routing_groups` to `routing_bundles`. Added active and pinned v4 skill/manifest schemas, migrated shipped skills, regenerated manifests/exports/marketplace artifacts, and added `scripts/migrate-skill-v3-to-v4.js`.
+- **Skill Audit Loop reframed as a re-grounding mechanism (docs only, no `schema_version` impact).** The loop was documented mechanics-first — its cadence and outputs without its purpose. `README.md` and `SKILL_AUDIT_LOOP.md` now open with the conceptual frame: a skill is a contract about a subject, and the loop is what re-grounds it against its two moving targets — the codebase it is grounded in and the subject it describes. `README.md` closing line changed "maintenance loop" to "re-grounding loop"; `SKILL_GRAPH.md` gains a three-layer relationship paragraph (protocol declares grounding, graph operates across the library, loop re-grounds each skill on a cadence). Rationale recorded in new `docs/proposals/skill-audit-loop-positioning.md`. Stated entirely in existing protocol vocabulary — no new fields, scripts, or CLI verbs.
+
+## [0.5.0] — 2026-05-13
+
+The "package-ready CLI + contract honesty" release. It keeps the existing zero-dependency scripts as the implementation surface, exposes them through one npm-ready `skill-graph` binary, closes the v3.1 alias pass-through gap, and tightens router/path behavior that made the contract look stronger than the implementation.
+
+### Added
+- **Conformance and compatibility docs.** Added `docs/CONFORMANCE.md` for L0-L4 adoption levels, `docs/SKILL-MD-FORMAT-COMPATIBILITY.md` for the base SKILL.md export contract, and `docs/ROUTING-METRICS.md` for routing metrics, confusion-matrix interpretation, and scale limits.
+- **SKILL.md export verifier.** Added `scripts/verify-skill-md-export.js`, `npm run export:verify-skill-md`, and `skill-graph export-verify` to prove exported skills keep only base SKILL.md top-level fields and string-only metadata values.
+- **Routing eval confusion matrix.** `scripts/skill-graph-routing-eval.js --confusion-matrix` now reports expected skill vs actual top-1 winner for positive examples plus negative-case summaries.
+- **Markdown link verification.** Added `scripts/check-markdown-links.js` and `npm run docs:links`; `npm run verify` now fails when repo-local Markdown links or anchors point at missing files/sections.
+- **Export/parser/drift regression coverage.** Added `scripts/__tests__/test-export-parser-drift.js` for CRLF export preservation, documented inline YAML parsing, URL truth-source drift status, and lint enforcement of schema conditionals.
+- **Installable CLI package shape.** `package.json` now publishes as `@skill-graph/cli`, exposes the `skill-graph` binary, declares public scoped-package publishing metadata, and ships the scripts, schemas, examples, docs, starter skills, and license needed by downstream users. `bin/skill-graph.js` dispatches to the existing implementation scripts (`lint`, `manifest`, `route`, `drift`, `overlap`, `routing-eval`, `export`, `audit`, `protocol-check`) instead of introducing a second command framework.
+- **Anchored grounding truth sources + eval-run receipts.** `grounding.truth_sources` now accepts structured entries with `path`, optional `line_range`, optional `anchor`, and optional `note` while preserving legacy string entries. Drift hashing now normalizes CRLF and can hash only the cited line slice. New optional `eval_last_run` records `{ at, status, runner?, model?, receipt?, receipt_hash? }` so `eval_state: passing` / `monitored` can point at evidence.
+- **Top-level `concept` block + `comprehension_state` field (additive, no `schema_version` bump).** The 7-field universal-subject teaching block — previously authored as a `## Concept Card` body section in adopter SKILL.md files with bold-label parsing — is now a structured frontmatter object. Schema additions (all in `schemas/skill.v3.schema.json`): (1) new optional top-level `comprehension_state` enum `[absent, present]`; (2) mirrored nested `eval.comprehension_state` (v3.1 alias pattern); (3) new optional top-level `concept` object with seven required string sub-fields (`definition`, `mental_model`, `purpose`, `boundary`, `taxonomy`, `analogy`, `misconception`) and per-field `minLength` floors (10 or 20 chars) that prevent empty strings without capping maximum length; (4) one new `allOf` rule that requires the `concept` block when `comprehension_state: present`. **No total word ceiling, no token budget.** Author each field as deeply as the concept requires — skill content is sized by what the subject demands, not by a length cap. Drove the migration in adopter repos away from body-section grafts and back into schema-validated metadata — closes the "Concept Card is a 6th layer outside the contract" finding from the 2026-05-12 review. Distinct from `## Philosophy` (about *why this skill file exists in this repo*): the `concept` block is about *what the subject is, universally*. Adopters with legacy body sections migrate via a per-adopter codemod that lifts each `**<Label>:**` value into the corresponding frontmatter field; the seven labels map deterministically to the seven keys (`What it is` → `definition`, `Mental model` → `mental_model`, `Why it exists` → `purpose`, `What it is NOT` → `boundary`, `Adjacent concepts` → `taxonomy`, `One-line analogy` → `analogy`, `Common misconception` → `misconception`). The codemod preserves all prose verbatim; it does not summarise, shorten, or rewrite content.
+- **v3.1 preferred field-name aliases (additive, non-breaking).** A roundtable critique of the v3 contract identified sign-drift, polysemy, and casing-inconsistency issues in 10 field names. v3.1 adds the renamed forms as optional aliases that validate alongside the legacy names. v4 will make them canonical and remove the legacy names. The added aliases: `archetype` (for `type`), `category_path` (for `category`), `reviewed_at` (for `freshness`), `allowed_tools` (for `allowed-tools`), `eval: { artifacts, content_state, routing_coverage }` (for the top-level `eval_artifacts` + `eval_state` + `routing_eval` triple), `grounding.subject` (for `grounding.domain_object`), `grounding.claim_scope` (for `grounding.grounding_mode`), `compatibility.agent_runtimes` (for `compatibility.runtimes`), `compatibility.node_version` (for `compatibility.node`), `portability.export_targets` (for `portability.targets`), `drift_check.verified_at` (for `drift_check.last_verified`). All 80 shipped skills continue to validate unchanged. `SKILL_METADATA_PROTOCOL.md` § "v3.1 — preferred field-name aliases" documents the migration; `docs/field-reference.md` carries the per-alias narrative.
+
+### Fixed
+- **Export body loss on CRLF files.** `scripts/export-skill.js` now preserves the body when the source `SKILL.md` uses Windows line endings, and the export verifier exercises the same full export path instead of only rebuilding frontmatter.
+- **Exported skill-name safety.** Export normalizes `/` and `:` in names for plain SKILL.md compatibility, and the verifier rejects exported names that still contain those path/YAML-hostile characters.
+- **Schema conditional lint parity.** `scripts/skill-lint.js` now enforces `stability: deprecated -> superseded_by` and `comprehension_state: present -> concept`, matching the JSON Schema `allOf` contract.
+- **Scoped package spelling.** Package docs and metadata now consistently use `@skill-graph/cli`, matching the project name and exposed `skill-graph` binary.
+- **Router `activation.paths` semantics.** `scripts/skill-graph-route.js` now applies gitignore-style negation lists correctly: positive globs include, later `!` globs subtract, and negation-only lists match nothing. The matcher also supports brace expansion (`*.{js,ts}`) and exports `matchPathList()` for unit coverage. This closes the gap where a negated path could accidentally behave like a positive match.
+- **v3.1 alias contract enforcement.** `scripts/lib/alias-contract.js` centralizes preferred/legacy alias parity checks. Lint now errors when both forms are present with divergent values, and the manifest generator refuses to compile divergent aliases while passing valid alias fields through into the manifest projection.
+- **Installed CLI root resolution.** `scripts/lib/roots.js` separates the package root from the caller workspace. Installed commands resolve schemas and packaged fixtures from `@skill-graph/cli`, but read and write skills, manifests, drift baselines, and workspace config relative to the consumer repository. Lint and overlap now honor `.skill-graph/config.json` skill roots and explicit non-default root directories.
+- **ADR 0006 normative bug — `owl:disjointWith` is irreflexive, not reflexive.** Line 32 originally claimed `owl:disjointWith` is "symmetric, reflexive". OWL class-disjointness is irreflexive (a class is never disjoint with itself; every class is identical to itself). Fixed in `docs/adr/0006-revise-predicate-rename.md`.
+- **Schema description hygiene.** Stripped ADR back-references (`Per ADR 0003`, `See ADR 0006`, etc.) and version-history phrasing (`v3.0 name`, `v3.1 preferred name`, `v3.1 addition`, `v2-compatible`, `v0.5.0 loosened`) from inline `description:` fields in `schemas/skill.v3.schema.json` and the unversioned mirror. Migration history belongs in `SKILL_METADATA_PROTOCOL.md` and this `CHANGELOG.md`, not in JSON-Schema descriptions that surface in IDE hovers and validation errors.
+- **`allowed-tools` separator inconsistency.** Schema description said "comma-separated whitelist"; `SKILL_METADATA_PROTOCOL.md` and every example use space-separated. Schema description corrected to "space-separated".
+- **`SKILL_METADATA_PROTOCOL.md` § Conditionally required.** The `keywords` row claimed `allOf` enforcement; the schema has no such `allOf`. The table now distinguishes schema-`allOf` rules (`extends`, `grounding`, `superseded_by`) from lint-enforced rules (`keywords`).
+- **`docs/skill-metadata-protocol.md` § Anatomy Mermaid diagram.** Field count corrected from 32 to 33.
+- **`SKILL_METADATA_PROTOCOL.md` v2→v3 migration table.** The relation-predicate-names row implied `boundary` was deprecated alongside `adjacent`. Per ADR 0006, `boundary` stays canonical; only `adjacent` is deprecated. Row rewritten.
+- **Windows-safe verification and script metadata.** `package.json` now describes the repo as a private CommonJS script project instead of advertising missing build outputs, and the verification scripts run under Node's CommonJS loader. Frontmatter parsing, archetype-section extraction, contract heading extraction, manifest path normalization, and drift-baseline recording now handle CRLF paths/files correctly on Windows.
+- **Current-library documentation drift.** README, architecture, primer, manifest-contract, concept-map, quickstart, and recommendation docs now reflect the current 36-field canonical schema, 40 shipped skills plus template sample manifest, 7-check contract gate, shipped overlap checker, and the role of `skillsmp.com` / `skills.sh` as public skill libraries used before Skill Graph relevance metadata.
+- **Positioning angle corrected.** README, primer, and marketplace positioning now frame Skill Graph as a project-relevance metadata protocol for AI SKILL.md: area, angle, taxonomy, semantic cluster, project fit, methodology, framework, grounding, and verification loop first; routing, trust, clustering, drift checks, and eval loops are downstream effects.
+- **Skill metadata hygiene.** Long routing descriptions, duplicate trigger/keyword surfaces, and stale drift baselines were cleaned up; `docs/field-reference.generated.md` and `examples/skills.manifest.sample.json` were regenerated from source tooling.
+
+### Changed
+- **SKILL.md export strictness.** `scripts/export-skill.js` now JSON-encodes structured Skill Graph extension metadata as strings under SKILL.md `metadata`, matching the base spec's string-to-string metadata contract.
+- **URL truth-source drift semantics.** `scripts/skill-graph-drift.js` now reports URL grounding references as `EXTERNAL_UNHASHED` instead of treating them as broken local files; manifest drift detection skips URL hashes unless a separate fetch-and-hash workflow records evidence.
+- **Documented inline YAML forms now parse.** The frontmatter parser now accepts inline arrays/maps and inline object sequence items used by docs and examples, such as `keywords: [a, b]` and `- { skill: x, reason: y }`.
+- **R1 — v3.1 SKOS predicate runtime migration closed (Critical).** The 4-reviewer board meeting (2026-05-04 multi-model synthesis, kept private) flagged a silent data-loss bug: ADR 0001 added `related`, `broader`, `narrower` as preferred v3.1 predicates and the schema accepted them, but the runtime hardcoded the iteration list at `['adjacent', 'boundary', 'verify_with', 'depends_on']` in `scripts/generate-manifest.js`, `scripts/skill-lint.js`, and the alias-target check in `scripts/skill-graph-route.js`. Skills following the ADR with the new SKOS names had their relations silently dropped from the compiled manifest. The fix extends the iteration list across all four runtime files to include `related`, `broader`, `narrower`, plus `disjoint_with` (now a separate orthogonal relation per ADR 0006). Back-compat for `adjacent` is preserved — both names continue to round-trip. Verified by new test `scripts/__tests__/test-v3-1-skos-runtime.js`, which round-trips the full predicate set through `buildSkillEntry()` against the new fixture at `examples/tests/v3-1-skos-fixture/SKILL.md`.
+- **R2 — ADR 0001 § Decision #2 revised by ADR 0006 — `boundary` is not `owl:disjointWith`.** The original ADR framed `boundary` as a deprecated alias for `disjoint_with` mapping to OWL `owl:disjointWith`. The board meeting flagged this as a category error: `boundary` is a routing-layer asymmetric handoff (the router uses it to redirect wrong-skill queries) and `owl:disjointWith` is a formal class-theoretic claim — they operate at different semantic layers. GPT-5.5's empirical audit confirmed the in-tree JSON-LD context already mapped `boundary` to `sg:disjointOwnership` (a custom Skill-Graph predicate), not to `owl:disjointWith` — so the implementation was correct; only the ADR text was wrong. New ADR `docs/adr/0006-revise-predicate-rename.md` documents what the implementation already does: `boundary` stays canonical for routing-layer use, `disjoint_with` becomes a separate orthogonal relation with explicit OWL class-disjointness semantics (Option B from synthesis IP-R2 § 4 — preserves capability per the project's quality doctrine). Schema descriptions, JSON-LD `@context`, lint deprecation warnings, ADR 0001 status banner, and `docs/field-reference.md § relations` all updated to match. The deprecation warning on `relations.boundary` is removed; the warning on `relations.adjacent → related` (Decision #1, sound) stays.
+- **`scripts/skill-graph-route.js` Stage 4b — `broader` parent recall boost.** Per ADR 0001 Decision #3, `relations.broader` declares cross-skill generalisation. The router now treats this as a co-load signal: when a top-match declares `broader: [parent]`, the parent is added to the selection as a generalisation companion. One hop only (no transitive ancestor walk), to mirror Stage 4's verify_with shape. The inverse `narrower` is NOT used to drive co-load — a parent match should not pull in arbitrary children.
+- **`schemas/skill.context.jsonld` v1.1.0** — `boundary` keeps its existing `sg:disjointOwnership` mapping (correct per ADR 0006); `disjoint_with` switches from alias-of-`boundary` to its own `owl:disjointWith` mapping. New `owl` namespace declaration (`http://www.w3.org/2002/07/owl#`) added. New `_adr_anchors` block points back to ADR 0001, ADR 0002, and ADR 0006 so future maintainers see the reasoning for the split mapping.
+- **`docs/field-reference.md § relations` enriched with the ADR 0006 split.** The relations key reference now describes the seven valid keys (was four), the `boundary` vs `disjoint_with` semantic distinction, and a worked example for the rare formal-OWL-class-disjointness case. The "deprecated alias" framing on `boundary` is removed. Added a new "When NOT to use" warning: do not use `disjoint_with` as an emphatic `boundary` — the OWL semantics are real and reaching for them changes how RDF consumers reason about the graph. Also fixes F22: the `routing_eval` § block now correctly states all 8 starters declare `present` and pass the harness 8-of-8.
+- **`scripts/generate-manifest.js`** — when imported as a module (rather than run via `node generate-manifest.js`), the file now exports `buildSkillEntry`, `sortKeys`, `validate`, `detectDrift`, `normalizeTruthSource`, `sha256TruthSource`, `computeSummary` for unit-test consumers. CLI behaviour is unchanged when invoked directly. Enables the new R1 round-trip test without ceremony.
+- **`scripts/skill-lint.js`** — relation-target validation now iterates the full v3.1 predicate set (`related`, `broader`, `narrower`, `adjacent`, `boundary`, `verify_with`, `depends_on`, `disjoint_with`) instead of the hardcoded v3.0 four. Dangling targets in any of the new predicates are now caught.
+- **`schemas/manifest.schema.json` + `manifest.v3.schema.json`** — extended the manifest's `relations` block to accept `related`, `broader`, `narrower`, and `disjoint_with` alongside the v3.0 four. Without this update the runtime fix in `generate-manifest.js` would emit manifests that fail their own validation (the gap was found during Path 1 lint when new skills used `related`). Both schema files updated to keep C6 parity.
+- **R8 — field-reference docs split + F22 schema description drift fixed.** The 1000-line `docs/field-reference.md` is now the apex of a three-doc structure: (1) `field-reference.md` — hand-curated prose with examples and lint notes (canonical for authoring); (2) `field-reference.generated.md` — auto-generated index from `schemas/skill.v3.schema.json` description strings (drift-free against the schema); (3) `field-rationale.md` — hand-authored "why this field exists" rationale for the ten non-obvious fields (`scope`, `eval_artifacts`, `eval_state`, `routing_eval`, `relations.depends_on`, `relations.verify_with`, `relations.broader`, `grounding.evidence_priority`, `lifecycle.review_cadence`, `portability.readiness`). The existing prose was preserved entirely (per `quality-doctrine` § "improve = enrich, never simplify"); a new "Three docs, three genres" preamble at the top of `field-reference.md` navigates between them. F22 root cause closed: 20 top-level schema fields that lacked `description` strings (which made the auto-generated index emit `"_No description in schema._"` placeholders) now have canonical descriptions in both `schemas/skill.v3.schema.json` and `schemas/skill.schema.json`, sourced from the hand-curated prose.
+- **`scripts/gen-field-reference.js` → `scripts/build-field-reference.js`** — renamed to match the canonical "build-" verb convention (synthesis IP-R8). Header banner in the generated file now points at the new name. No callers existed outside the script itself; no CI breakage.
+- **R13 — SKILL_METADATA_PROTOCOL.md and skill-metadata-protocol.md enriched by genre.** The two docs are now coordinated by distinct genres: SKILL_METADATA_PROTOCOL.md is the **normative spec** (terse, boundary-aware, no rationale — the doc a consumer prints out and tapes to the wall); skill-metadata-protocol.md is the **design rationale** (pedagogical, philosophical, ADR-referencing). Three new sections in skill-metadata-protocol.md sharpen the rationale genre: (1) "Why archetypes are rigid vs anti-rigid" — full OntoClean treatment of `capability` / `workflow` / `router` / `overlay` per ADR 0003, including the `extends` vs `relations.broader` test; (2) "Why the eval-health triple is orthogonal" — the three-axis decomposition of `eval_artifacts` / `eval_state` / `routing_eval` and why conflating them would force consumers to guess; (3) "How JSON-LD context maps fields to W3C terms" — full mapping table including the ADR 0006 split between `boundary` (sg:disjointOwnership) and `disjoint_with` (owl:disjointWith). SKILL_METADATA_PROTOCOL.md preamble now points at skill-metadata-protocol.md for the *why* and explicitly names itself as the *what*. README.md § Tier 2 entry updated to reflect the genre split. Both files grew (the normative spec 392→394, skill-metadata-protocol.md 325→405). Two of four reviewers had recommended retiring the separate normative spec; v4 explicitly rejected this under quality-doctrine § "improve = enrich, never simplify".
+
+### Added
+- **`docs/field-rationale.md`** — new hand-authored rationale doc for 10 non-obvious fields. Each section follows the same three-part structure: "Why this field exists", "Common confusion", "Worked example". Linked from `field-reference.md` and `field-reference.generated.md`.
+- **`scripts/check-contract-consistency.js` C7 — Generated field-reference parity.** New check spawns `node scripts/build-field-reference.js --check` and surfaces non-zero exit as a structured contract error. Closes the loop where a schema description edit could land without a corresponding regeneration of `docs/field-reference.generated.md`. Sits alongside C1-C6 in the per-PR consistency gate.
+- **Routing harness follow-up sprint — 9/9 starters PASS.** The library-wide harness run now returns `9 skill(s): 9 PASS, 0 FAIL, 0 SKIP`, up from `0 PASS, 9 FAIL` at the end of the harness sprint. The work split into two halves, both executed together per `docs/plans/routing-harness-followup.md`:
+  - **L4 router scoring (`scripts/skill-graph-route.js`)** — four surgical changes closing 28 of 32 original failures. (1) `tokenize()` now drops a 46-entry English stopword set from both query and keyword sides; the keyword side additionally enforces `length >= 3` to keep single-char particles like "it" out of scoring. (2) `scoreSkill()` now runs keywords in TWO dedup passes — exact first, then substring — with separate per-token sets so a substring credit on "clean" from the phrase "cleanup" no longer blocks a later exact match on "clean" from the phrase "clean this up" (the bug that broke a11y and refactor hard-negatives in the first implementation pass). (3) Stage-5 boundary exclusion is now score-aware AND iterates only over `topMatches`, never `coLoaded` — a co-loaded `verify_with` partner can no longer boundary-exclude the very skill that brought it into the selection, which was the regression source that dropped debugging / refactor / testing-strategy to 1/7 on the first authoring pass. (4) `scored.sort()` comparator extended with the documented doctrine: scope (codebase > reference > portable) then type (workflow > capability > router > overlay) before alphabetical.
+  - **L5 authoring sweep (8 SKILL.md files + `examples/skill-metadata-template.md`)** — targeted keyword enrichment, boundary extension, anti_example rewriting, and three adjacent-relation removals. Keywords: a11y gained 7 form/assistive-tech terms; debugging gained 16 failure-idiom terms including "used to work", "agent stuck", "broke the build"; documentation gained 12 prose-audience terms including "progressive disclosure" and "reading level"; lint-overlay gained 13 migration/gate terms; refactor gained 13 decomposition/rename terms; skill-router gained 15 meta-routing terms including "activate skill", "dispatch request", "routing decision"; skill-metadata-template gained 11 authoring terms; testing-strategy gained 7 coverage-planning terms. Boundaries: debugging↔testing-strategy↔refactor triangle hardened into mutual boundary (was adjacent, which the router was conflating); a11y += documentation; lint-overlay += testing-strategy; refactor += debugging; skill-router += debugging; skill-metadata-template += skill-router + graph-audit. Anti_examples: a11y dropped the visual-design coverage-gap; graph-audit rewrote two antis to use debugging and documentation vocabulary so the router absorbs them correctly; refactor rewrote the retry-logic anti to route to debugging; skill-router replaced the falsified "router activated the wrong skill" anti with "reproduce this routing mis-dispatch from production logs" (which correctly routes to debugging per the plan's P2.2 recommendation). Example rewrite: skill-router's first positive example changed from `"which skill should activate for 'my tests are failing in CI'?"` to `"activate the right skill for this agent request: 'my tests are failing in CI'"` — same meta-routing intent, but "request" adds a third skill-router-exclusive token that outscores debugging's two `tests`+`failing` tokens.
+- **`routing_eval` flipped `absent` → `present` for 7 starter SKILL.md files** (a11y, debugging, documentation, graph-audit, lint-overlay, refactor, skill-router, testing-strategy; `examples/skill-metadata-template.md` stays `absent` because it teaches the authoring-time default). Restored under the same "honesty over green checkmarks" rule that drove the original downgrade — the harness now agrees, so the assertion is earned. Lint check 12 gates future regressions on every changed SKILL.md.
+- **`skills/skill-router/SKILL.md`** — the `routing_eval: absent` downgrade block from the harness sprint is replaced with a `present`-restoration block explaining which of the four L4 fixes + L5 rewrites resolved the hard-negative.
+- **`examples/skills.manifest.sample.json`** — regenerated via `node scripts/generate-manifest.js --include-template --timestamp 1970-01-01T00:00:00Z --output examples/skills.manifest.sample.json` to reflect all SKILL.md edits and the `routing_eval` flips.
+
+### Added
+- **5 new Tier A starter skills (Path 1 / IP-R9 Phase 1).** The OSS library grows from 8 starters to 13. Each new skill follows the v3.1 contract end-to-end (≥8 examples, ≥5 anti_examples, `relations.boundary` with `{skill, reason}` entries, grounding declared where applicable, `routing_eval: absent` until the harness verifies). Per the curated picks documented in [`docs/recommended-skills.md`](docs/recommended-skills.md):
+  - **`skills/skill-scaffold/SKILL.md`** — closes the empty `scope: reference` gap. Authoring contract for new skills: copy → rename → adapt → strip teaching annotations → verify → commit. Covers archetype selection, semantic-layer discipline (`description` vs `## Coverage`), the lint-first authoring gate, and the routing-eval honesty rule.
+  - **`skills/naming-conventions/SKILL.md`** — universal portable skill. Identifier morphology (verb-noun choice, plural/singular, prefix/suffix), casing per artifact kind, the verb contract (get vs fetch vs load vs compute vs validate vs assert), names that lie detection, rename coordination workflow.
+  - **`skills/code-review/SKILL.md`** — universal workflow for reviewing PRs / diffs / proposed changes. Six-phase workflow (pre-review fact-gathering → tests-first reading → implementation reading → call-site reading → comment authoring → merge decision). Severity-grading rubric across nine review concerns. Explicit no-rubber-stamp rule for AI-generated diffs (with the 1.7-2.74× security-issue premium evidence).
+  - **`skills/prompt-craft/SKILL.md`** — universal AI-engineering skill for writing, structuring, and improving LLM prompts. Seven-layer prompt anatomy. Output-format discipline (schema + example + output cue triple-reinforcement). The X-mention reinforcement effect on negative instructions. Defence against adversarial input. Iterative-improvement loop with mandatory eval-set measurement.
+  - **`skills/owasp-security/SKILL.md`** — security baseline. Full OWASP Top 10 (2021) coverage with detection patterns and mitigation patterns per category. Threat-modelling four-question STRIDE-lite. AI-generated code premium (1.7-2.74× security-issue rate, top five CWEs). Defence-in-depth posture.
+- **`docs/adr/0006-revise-predicate-rename.md`** — new ADR. Status: Accepted. Supersedes ADR 0001 § Decision #2 only (Decisions #1, #3, #4 stand). Documents the routing-layer-vs-ontology-layer distinction with W3C OWL 2 spec citation and the empirical evidence that the JSON-LD context was already correctly mapped. Cross-references ADR 0001 with the explicit "Supersedes Decision #2 only" note.
+- **`scripts/skill-lint.js` — relation double-declaration check.** New warning when a skill declares the same target under both `adjacent` (deprecated) and `related` (preferred) — drops the deprecated entry to avoid double-counting in the compiled manifest. The check is intentionally narrow: `boundary` and `disjoint_with` are NOT treated as alias pairs (per ADR 0006 they have distinct semantics) so declaring the same target under both is legitimate and is not flagged.
+- **`scripts/__tests__/test-v3-1-skos-runtime.js`** — new test. Builds a manifest entry from the v3.1 fixture and asserts every declared predicate round-trips: `related`, `broader`, `narrower`, `boundary`, `disjoint_with`, `verify_with`, `depends_on`. Synthesises a parallel in-memory fixture to verify `adjacent` back-compat continues to work. Exits 0 on PASS, 1 on FAIL. Self-contained (only Node built-ins, only the existing parse-frontmatter and generate-manifest helpers).
+- **`examples/tests/v3-1-skos-fixture/SKILL.md`** — new fixture skill exercising the full v3.1 predicate set. Used by the test runner above; not a production skill (declares `eval_artifacts: none` and lives outside the default `skills/` walk).
+- **`scripts/skill-graph-routing-eval.js`** — new Tier 4 consumer script that makes `routing_eval: present` honest. For every skill in the manifest it runs each `activation.examples[]` entry through `scripts/skill-graph-route.js` and asserts the top-1 winner equals the skill itself (positive-class); runs each `activation.anti_examples[]` entry and asserts the winner is NOT the skill and (when non-null) is named in `relations.boundary[]` (negative-class). Emits per-skill verdicts (`PASS` / `FAIL` / `NO_CASES`) plus per-case evidence. Verdicts: `PASS` when every case resolves correctly; `FAIL` on any positive miss or any hard-negative regression; `COVERAGE_GAP` (informational) when an anti-example correctly avoids the skill but no other skill absorbs it — the anti-example did its job; the gap is a future-sprint signal. CLI: `--manifest PATH`, `--skill NAME`, `--only-asserted`, `--json`, `--quiet`. Exits 1 on any `FAIL`. Self-contained — only Node built-ins, `require()`s `scripts/skill-graph-route.js` directly so the scoring/boundary pipeline is reused verbatim.
+- **`scripts/lint/check-routing-eval.js`** + **`scripts/skill-lint.js` check 12** — new per-file lint check. Fires only when `routing_eval: present`; errors when (a) `examples` or `anti_examples` is empty (the harness has no prompts to evaluate), or (b) the harness reports any `FAIL` case for this skill. Each failing prompt surfaces as an individual lint error with a code-framed pointer at the `routing_eval:` line. Turns the `present` assertion into a verifiable claim — authors can no longer ship `present` without the harness agreeing. See `docs/field-reference.md § routing_eval` for the full enforcement contract.
+- **`docs/ARCHITECTURE.md` § Tier 4 — Routing harness** — new Mermaid diagram + rendered PNG (`docs/images/routing-harness.png`) showing the per-skill decision path the harness follows. Caption asks one question ("How does `skill-graph-routing-eval.js` decide whether a skill's `routing_eval: present` claim holds?"). Twelve nodes, explicit legend (green = pass / endpoint, red = FAIL, pink = decision gate, blue = work, purple-dashed = `COVERAGE_GAP`). The asymmetry between the positive and negative gates is the whole point — positive cases must uniquely identify the skill; negative cases must only avoid it. Source in `docs/diagrams/routing-harness.mmd`. This is the fourth diagram in Tier 4's neighborhood (pipeline, drift-states, starter-graph, routing-harness) and is the only one that explains the harness's decision path, which no existing diagram covers.
+- **`.github/workflows/skill-graph-lint.yml`** — new `routing-eval` job running after `lint`. Regenerates the sample manifest (so the harness reads the current authored state) then runs `node scripts/skill-graph-routing-eval.js --only-asserted` — exits non-zero if any skill with `routing_eval: present` fails the harness library-wide, complementing the per-skill lint check 12 for the same-PR enforcement case.
+
+### Changed
+- **`skills/skill-router/SKILL.md`** — `routing_eval: present` → `routing_eval: absent`. The harness revealed one hard-negative regression: the anti-example `"the router activated the wrong skill once — debug it"` routes back to `skill-router` instead of to `debugging`. Per the "honesty over green checkmarks" rule now documented in `docs/field-reference.md § routing_eval`, a falsified assertion is downgraded rather than defended. Re-flip back to `present` once the router's scoring or `skill-router`'s description boundary clause tightens enough that the harness agrees.
+- **`docs/field-reference.md § routing_eval`** — the "Current status (forward-looking)" block is replaced with an "Enforcement" block documenting the harness + lint check 12 and naming the current starter-library state (0/9 pass today; the harness reveals the work). The forward-looking pointers to planned `scripts/skill-router.js` and `scripts/build-coverage.js` are deleted — the harness that absorbed both responsibilities now ships.
+- **`examples/skill-metadata-template.md`** — the `routing_eval` TEMPLATE NOTE is rewritten to teach the new lint enforcement: `present` now requires populated `examples` + `anti_examples` AND a passing harness run (`node scripts/skill-graph-routing-eval.js --skill <name>`). Default remains `absent` at authoring time; adopters flip only after the harness agrees.
+- **`scripts/lib/parse-frontmatter.js`** — scalar-value parsing now strips trailing YAML inline comments (` # ...` preceded by whitespace, outside of quoted strings). Previously the parser kept the entire raw line including the comment as the string value, which polluted `examples` / `anti_examples` array entries in the generated manifest with `# author-note` tails (authors write `- "prompt" # why this routes elsewhere`). The fix brings the parser in line with standard YAML semantics and cleans the manifest; all other consumers benefit transparently.
+- **`examples/skills.manifest.sample.json`** — regenerated via `node scripts/generate-manifest.js --include-template --timestamp 1970-01-01T00:00:00Z --output examples/skills.manifest.sample.json` to reflect the cleaned parser (inline-comment tails dropped from `activation.examples` and `activation.anti_examples`) and the skill-router `routing_eval` downgrade.
+
+### Added
+- **`scripts/skill-lint.js`** — `truth_sources` entries in eval artifacts may now use `path#anchor` format (e.g. `skills/documentation/SKILL.md#doc-type-selection`) alongside the existing `path` and `path:start-end` forms. The linter extracts all markdown headings from the target file, slugifies them using the common GitHub/pandoc convention (lowercase, non-alphanumerics → hyphens, collapsed), and reports an error with the known-anchor list when an entry cites a slug that no heading produces. Anchors are drift-resistant: renaming a section forces an anchor update the linter catches, whereas editing section content around fixed line numbers silently drifts. Authors are encouraged to cite both a line range and a heading anchor for defense in depth.
+- **`examples/evals/comprehension.json`** — documentation eval artifact expanded from 10 to 12 cases and migrated to dual-citation (line range + heading anchor). Eval 6 now also cites the frontmatter `relations.boundary` block so boundary grounding spans both the Do-NOT-Use table and the declared boundary reasons. Evals 11–12 add a new `rule_conflict` dimension — adversarial cases where two skill rules collide (same-commit doc updates vs. security hotfix time pressure; structural checklist passing vs. the "faster mental model" philosophical test) with explicit `expected_reasoning`.
+- **`skills/documentation/SKILL.md` § Relations Rationale** — explicit justification for an empty `verify_with` surface: doc-drift and link-checking are owned by CI tools (`lychee`, `markdownlint`) that live outside the skill graph rather than by sibling skills. Points at where a future `doc-freshness` or `link-check` skill would live.
+- **`docs/ARCHITECTURE.md` § System Model — how the pieces fit together** — top-level orientation diagram (5 entities: `SKILL.md`, `skill-lint.js`, `skills.manifest.json`, `skill-audit.js`, `audit artifacts`). Caption asks the single question the diagram answers ("What are the moving parts of Skill Graph, and who talks to whom?"). First thing readers see before the five authority tiers. Legend named inline. Rendered companion PNG committed at `docs/images/system-model.png` and embedded with an `<img>` tag so any viewer (not only Mermaid-aware ones) sees the diagram.
+- **`docs/skill-metadata-protocol.md` § Anatomy** — rewritten to follow progressive disclosure. Replaces the previous 9-subgraph convoluted flowchart with a 4-node composition diagram (`SKILL.md` = Frontmatter + Body + optional Teaching Layer) and a navigable Markdown table listing all 32 authored fields grouped by 8 semantic purposes (Identity, Classification, Health & Drift, Eval Health, Activation & Routing, Relations, Grounding, Portability & Standards). Each field name links to its canonical definition in `docs/field-reference.md` — the diagram conveys shape, the table conveys enumeration, neither duplicates the schema. Rendered companion PNG at `docs/images/skill-anatomy.png`.
+- **`docs/library-audit-workflow.md` § Loop at a Glance** — rewritten as two focused diagrams plus a bullet list. Diagram 1: the 5-phase horizontal flow captioned "What are the phases of an audit?" showing Select → Deterministic → Graded (optional) → Aggregate → Fix → Re-verify → Next with the PASS-skip shortcut. Diagram 2: a zoomed view of Phase 2 captioned "What happens inside graded mode?" showing the 7-dimension fan-out through the grader CLI and the parse step. Artifact traceability (which phase writes to `findings.md` / `verdict.md` / `scorecard.md`) moved from tangled dotted arrows into a clean bullet list. Rendered companion PNGs at `docs/images/audit-phases.png` and `docs/images/graded-mode.png`.
+- **`docs/images/`** — new directory shipping rendered PNG copies of every Mermaid diagram in the docs. Each PNG is regenerated from the Mermaid source via `npx @mermaid-js/mermaid-cli -i <source>.mmd -o docs/images/<name>.png`. Source remains in the Markdown files so the diagrams stay diffable and editable; the PNGs exist purely so readers using viewers without Mermaid support still see the rendered image. Seven PNGs today: `system-model.png`, `skill-anatomy.png`, `audit-phases.png`, `graded-mode.png`, `manifest-pipeline.png`, `drift-states.png`, `starter-graph.png`.
+- **`docs/diagrams/`** — new directory holding the standalone `.mmd` Mermaid sources for the three newest diagrams (`manifest-pipeline.mmd`, `drift-states.mmd`, `starter-graph.mmd`). Inline Mermaid in Markdown remains the editable canonical copy; the `.mmd` files exist so `npx @mermaid-js/mermaid-cli -i <file>.mmd -o <png>` renders without having to extract blocks from the Markdown first.
+- **`docs/ARCHITECTURE.md` § Tier 3 — Pipeline** — new Mermaid diagram + rendered PNG (`docs/images/manifest-pipeline.png`) showing how `generate-manifest.js` projects authored frontmatter into `skills.manifest.json`. Caption question: "How does a SKILL.md become a manifest entry?" Seven nodes (authored SKILL.md set + optional workspace config → parse-frontmatter → rename/group → SHA-256 on truth sources → ajv validation → compiled manifest, with an exit-1 branch on validation failure). Ends the old gap where the compiler was prose-only. Proves Tier 3's topology earns its complexity.
+- **`docs/ARCHITECTURE.md` § Tier 4 — Drift sentinel state machine** — new Mermaid `stateDiagram-v2` + rendered PNG (`docs/images/drift-states.png`) showing the five states a grounded skill can sit in (`NO_BASELINE`, `OK`, `STALE`, `DRIFT`, `BROKEN`) and every transition between them. Drives the argument for the v3 `drift_check.truth_source_hashes` + `lifecycle.stale_after_days` fields — without them the sentinel has nothing to compare against and nothing to time-box. Caption question: "What state can `skill-graph-drift.js` put a skill in, and what transitions it?"
+- **`docs/ARCHITECTURE.md` § The starter graph** — new Mermaid diagram + rendered PNG (`docs/images/starter-graph.png`) showing the relations graph across all eight starter skills plus the template. First visual aid for Layer 7 (the Graph layer in the 7-layer authority model) — the layer whose silent drift produces confidently-wrong router decisions. Edge styles encode relation type (thick solid = `depends_on` / `extends`, dashed = `verify_with`, thin undirected = `adjacent`, red = `boundary`). Node style encodes archetype + scope. Caption question: "Who verifies whom, depends on whom, and boundaries whom out across the eight starters?"
+- **`examples/skill-metadata-template.md` — new TEMPLATE NOTE for `category`** — explains that `category` is OPTIONAL, complements (never replaces) `category`, and should be removed for small libraries per `docs/field-reference.md § category` ("fewer than 20 skills rarely benefits"). Closes the authoring gap where adopters copy-pasted the template's hierarchical path without thinking about whether a tree structure earned its line count.
+- **`examples/skill-metadata-template.md` — new TEMPLATE NOTE for `stability` + `superseded_by`** — explains the schema's `allOf` rule that requires `superseded_by` whenever `stability: deprecated`, with a commented-out worked example showing the two-field deprecation shape. Prior readers had to reach `schemas/skill.v3.schema.json` directly to discover the rule; the template now teaches it in-place.
+
+### Changed
+- **`docs/skill-metadata-protocol.md` § Authored vs Generated Fields** — corrected field count from 29 to 32 (doc drift fix). The previous list was missing `superseded_by` (required when `stability: deprecated`), `examples` (positive activation prompts — v0.5.0+), and `anti_examples` (negative activation prompts — v0.5.0+). All three fields exist in `schemas/skill.v3.schema.json` and have their own sections in `docs/field-reference.md`; only the summary count in Skill Metadata Protocol was stale.
+- **`docs/manifest-contract.md` § Top-level authored fields** — same drift fix propagated here. Corrected heading count from 29 to 32 and added three table rows with the correct manifest projections: `superseded_by` (top-level flow-through when present, required when `stability: deprecated`), `examples` (grouped under `activation.examples`), `anti_examples` (grouped under `activation.anti_examples`). Renumbered rows 16–32 to preserve schema order. Caught while loading the full doc set in prep for the layered consultant prompt; fix follows the same pattern already applied in Skill Metadata Protocol.
+- **`README.md`** — same fix, matched the 29 → 32 count in the "Shipping today" bullet that points at Skill Metadata Protocol.
+- **`docs/ARCHITECTURE.md` § Further reading** — now points at the new System Model / Anatomy / Loop at a Glance diagram sections so the tiered tour terminates at the visual overviews. Extended again to include the three 2026-04-19 diagrams (Pipeline, Drift state machine, Starter graph).
+- **`docs/manifest-contract.md` § Related documents + § Verification** — residual drift cleanup on top of the earlier 29 → 32 fix: "six shipped skills" → "eight starter skills plus the template (nine entries total)" (§ Related documents) and "five starters plus the template" → "eight starters plus the template" (§ Verification). The body rename-map table was already repaired; these two captions lagged by the same count mismatch.
+- **`docs/skill-metadata-protocol.md` § Schema Strictness** — dropped the dated "v1 OSS schemas are intentionally strict" framing to "The Skill Graph schemas are intentionally strict." Version-scoped framing dates itself; the strictness rule is not a v1 artefact.
+- **`docs/skill-metadata-protocol.md` § Relationship to the SKILL.md Standard** — the "Skill Graph extension" row now lists `examples`, `anti_examples`, and `superseded_by` alongside the other extension fields. The three fields exist in the v3 schema and have their own reference sections but were absent from this relationship table, creating an inconsistency inside the same document.
+- **`docs/single-skill-audit-checklist.md` § 1 Frontmatter validity** — corrected the "(schema_version 3, orthogonal triple)" parenthetical on the eval-health triple checkbox to "(orthogonal triple — shipped in schema_version 2 under SH-5784, retained in v3)". The triple was introduced in v2 and carried forward; the old wording misattributed its origin.
+- **`docs/single-skill-audit-checklist.md` § 5 Content quality** — added a previously-missing checkbox for `## Verification` section presence, cross-referencing `docs/skill-metadata-protocol.md § Archetype Section Map` and `scripts/lint/check-archetype-sections.js`. Lint already enforced the requirement for `capability` and `workflow` archetypes; the human checklist silently skipped it.
+- **`docs/field-decision-guide.md` § 1 Migration from v1** — collapsed the duplicated v1 → v2 scope rename table to a one-line pointer at `docs/field-reference.md § scope` plus a link to the `docs/manifest-contract.md § Migration Note — v2 → v3` codemod. Per the `documentation` skill's source-of-truth rule, canonical content lives in one place and is indexed elsewhere.
+- **`skills/skill-router/SKILL.md` § description** — opener rewritten from "MUST be used when …" to "Use when …" for parity with the other seven starter descriptions. The description-opener convention documented in `docs/skill-metadata-protocol.md § Description Opener Convention` prefers "Use when"; the voice drift made the router skill stylistically louder than its siblings without adding routing precision.
+- **`skills/testing-strategy/SKILL.md` § description** — negative-boundary clause tightened to name replacement skills inline: `debugging` (for chasing a known failure), `documentation` (for pure doc writing), and "no dedicated skill yet" (for conceptual architecture discussion). Prior version named only one of the three, leaving two implicit.
+- **`examples/skills.manifest.sample.json`** — regenerated via `node scripts/generate-manifest.js --include-template --output examples/skills.manifest.sample.json` to reflect the updated `skill-router` and `testing-strategy` descriptions. Verified clean by `node scripts/check-contract-consistency.js` (C1–C6, 0 warnings) and `node scripts/skill-lint.js --include-template` (9 files, 0 errors).
+
+### Added
+- **`docs/plans/consultant-showcase-prompt.md`** — reusable layered prompt designed to work unchanged across Opus (Claude Code), GPT-5.4 (Codex plugin), and Gemini Pro. Teaches the 7-layer model of Skill Graph (Contract · Explanation · Enforcement · Consumer · Specimens · Knowledge · Graph, with Evolution as an orthogonal cross-cut) and requires consulting models to produce a layer map as Artifact 1 so they prove multi-layer understanding before proposing any changes. Includes dispatch instructions for all three CLIs plus guidance on the `gemini-2.5-pro` fallback (the `gemini` CLI on this machine does not expose `gemini-3-pro` as a valid alias — verified 2026-04-19).
+
+### Design rationale (recorded for future diagram work)
+Diagrams in this repo follow progressive disclosure — each answers exactly one question and states that question in the caption. The 32-field list lives once, in the schema, and is indexed (not duplicated) by the Anatomy section table, satisfying the `documentation` skill's source-of-truth rule. Every diagram has a legend block naming what each shape/colour means, a ~12-node ceiling, and a rendered PNG companion so readers in any viewer see the image. These rules were informed by a three-way consultation (Opus, Codex / GPT-5.4 via the in-session plugin, Gemini 2.5 Pro) plus web research on progressive-disclosure limits (max 2 levels before readers get lost — the C4-model rationale).
+
+## [0.4.0] — 2026-04-18
+
+The "v3 contract + reference consumer + multi-project workspace" release. A breaking schema bump (v2 → v3) coordinated with new authoring fields, executable drift evidence, multi-root workspace support, and two new reference consumer tools that exercise the full graph contract end-to-end.
+
+### Added
+- **`schemas/skill.v3.schema.json` + `schemas/manifest.v3.schema.json`** — pinned v3 copies. The unversioned schemas now track v3; v2 pinned copies remain in the repo as frozen prior-version stable copies.
+- **`scripts/migrate-skill-v2-to-v3.js`** — line-based codemod that preserves author YAML style (comments, quoting, indentation). Applies the four v2 → v3 transformations: `schema_version: 2 → 3`, `family → category`, scalar `drift_check` → object with `last_verified`, scalar `compatibility` → object with `notes`.
+- **`scripts/skill-graph-route.js`** — the reference consumer. Graph-aware skill selector that uses `relations` (all four kinds), `grounding.truth_sources`, `eval_state`, `drift_check`, `lifecycle`, and `workspace_tags` to make routing decisions visible. Emits ranked lists with per-skill reasons explaining why each skill was selected, co-loaded via `verify_with` / `depends_on`, or excluded via `boundary`. Supports `--project`, `--max`, `--min-eval-state`, `--path`, `--manifest`, `--json`.
+- **`scripts/skill-graph-drift.js`** — the drift sentinel. Hashes every `grounding.truth_sources` entry with SHA-256, compares against the stored `drift_check.truth_source_hashes` baseline, and reports DRIFT / BROKEN / STALE / NO_BASELINE states. `--record --apply` updates the SKILL.md frontmatter in place with current hashes and today's date.
+- **`.skill-graph/config.json`** (optional workspace config) — declares `skill_roots` (multiple directories the generator unions into one manifest) and `projects` (literal handle → `semantic_tags` mapping). Fallback to single-root `skills/` when absent. Documented in `docs/plans/multi-root-workspace.md`.
+- **Four new optional v3 fields** in the authored frontmatter contract:
+  - `category` — hierarchical browse path (`ecommerce/integrations/shopify`), pattern-validated.
+  - `workspace_tags` — array of literal project handles or semantic tags for multi-project filtering. Absent = ambient/cross-project.
+  - `lifecycle` — object with `stale_after_days` and `review_cadence`. Drives the drift sentinel's staleness flag.
+  - `runtime_telemetry` — object with `feedback_source` path, `last_updated`, and optional success-rate metrics. Enables closing the loop from self-reported `eval_state` to externally-observed success/failure.
+- **Relation item object form** — `relations.boundary` items may now be `{skill, reason}` objects (back-compat with bare strings), and `relations.depends_on` items may be `{skill, min_version}` objects. Reasons make the anti-ownership field self-documenting.
+- **Manifest-level generated fields**: `workspace` block echoing the config, `summary.by_project` rollup, `skills[].project` handle, `skills[].category`, `skills[].workspace_tags`, `health.lifecycle`, `health.runtime_telemetry`, `health.drift_detected` (computed by the generator when hashes are recorded).
+- **Paths negation** — `paths` globs may now be prefixed with `!` for gitignore-style exclusion, matching how real file scanners work.
+- **`docs/plans/multi-root-workspace.md`** — design reference for the hybrid layout, config format, scope placement rules, and migration path from single-root to multi-root.
+- **`docs/field-decision-guide.md` § 4–5** — new decision tables for `workspace_tags` (literal vs semantic tags, when to tag vs leave ambient) and a cross-cutting table disambiguating `category` vs `category` vs `workspace_tags` vs `routing_bundles`.
+
+### Changed (breaking)
+- **`schema_version`: 2 → 3.** All v2 field names and scalar shapes that change are hard-rejected by the v3 schema's `additionalProperties: false` and type constraints. Lint emits friendlier WARN lines pointing at the rename for the first v3 minor release window.
+- **`family` → `category`** (rename). Values unchanged. The v2 name invited misuse as a routing signal; the v3 name makes the browse-taxonomy intent explicit.
+- **`drift_check` shape: date string → object.** v2: `drift_check: "2026-04-15"`. v3: `drift_check: { last_verified: "2026-04-15", truth_source_hashes?: { ... } }`. The new hash map is optional but strongly recommended — it turns drift detection from self-asserted into evidence-backed.
+- **`compatibility` shape: free-text string → object.** v2: `compatibility: "Node.js 18+, Git"`. v3: `compatibility: { runtimes?: [...], node?: string, notes?: string }`. The codemod moves the old string verbatim into `compatibility.notes`; authors upgrade to structured fields manually.
+- **`summary.by_family` → `summary.by_category`** in the manifest projection. Consumers reading the old key must update.
+- **`scripts/skill-lint.js`** — `DEPRECATED_V1_FIELDS` becomes `DEPRECATED_V1_FIELDS` for v1 names plus new v2 → v3 warnings for `family`, scalar `drift_check`, scalar `compatibility`. `AUTHORED_FIELDS_MUST_FLOW` adds `category`, `workspace_tags`, `category`.
+- **`scripts/check-contract-consistency.js` C6** — now version-aware: resolves the current schema version from the unversioned schema, checks parity against the matching pinned copy, treats all prior versions as frozen (must exist, not checked for parity).
+- **`scripts/generate-manifest.js`** — reads `.skill-graph/config.json` when present and walks multiple skill roots; falls back to single-root `skills/` otherwise. Computes SHA-256 on truth sources and emits `health.drift_detected` when baselines exist. `schema_version` written as `3`.
+- **`scripts/export-skill.js`** — flattens the v3 `compatibility` object to a single string for SKILL.md export, concatenating `runtimes`, `node`, and `notes`. New v3 fields flow through the `metadata:` envelope without special handling.
+- **`scripts/lib/parse-frontmatter.js`** — extended to parse block sequences of map entries (needed for v3 `boundary: [{skill, reason}]` and `depends_on: [{skill, min_version}]` shapes).
+- **`examples/skill-metadata-template.md`** — upgraded to v3, now exercises `category`, `category`, object `drift_check`, object `compatibility`, object `boundary` with reason, and `lifecycle`.
+- **All 8 starter skills** migrated to v3 via the codemod.
+- **All 5 SKILL.md exports** regenerated with the flattened v3 `compatibility`.
+- **`examples/skills.manifest.sample.json`** regenerated with v3 shape (nine skill entries: 8 starters + template).
+
+### Migration
+- Run `node scripts/migrate-skill-v2-to-v3.js` against any v2 skill directory to apply all four transformations automatically.
+- See `docs/manifest-contract.md § Migration Note — v2 → v3` for the full mapping table.
+- See `docs/field-reference.md` for per-field rules, v3 examples, and v2 → v3 migration notes inline with each changed field.
+
+### Verification
+- `node scripts/skill-lint.js --include-template` → 0 errors across 8 starters + template.
+- `node scripts/check-contract-consistency.js` → C1–C6 OK, 0 warnings. C6 confirms v3 tracks unversioned and v2 is correctly frozen.
+- `node scripts/generate-manifest.js --include-template --validate-only` → manifest valid against `schemas/manifest.schema.json`.
+- `node scripts/skill-graph-route.js "accessibility screen reader"` → produces expected selection + co-load + boundary-exclusion output with per-skill reasons.
+- `node scripts/skill-graph-drift.js` → reports baseline status for every skill with truth sources.
+
+## [0.3.0] — 2026-04-17
+
+The "contract honesty + graded audits" release. Three priorities from the internal-only OSS roadmap (`docs/plans/skill-graph-oss-roadmap.md`): narrow the `portability.targets` enum to what actually has a working transform (P1), promote the audit runner from a lint-stub seeder to a real prompt-driven grader (P2), and close the versioning-policy-to-reality gap with pinned v2 schema files (P3). No GitHub remote, no npm publish — this release matures the contract for internal use.
+
+### Added
+- `scripts/lib/audit-prompt-builder.js` — 7-dimension registry, context collector (reads `SKILL.md` plus `grounding.truth_sources`), IDENTITY-STEPS-OUTPUT prompt composer, response parser (requires a `<verdict>…</verdict>` JSON block), and coarse verdict aggregator. Powers the new graded audit mode.
+- `scripts/skill-audit.js --graded` mode — calls an explicit external grader CLI once per scorecard dimension and merges the responses into `findings.md` / `verdict.md` / `scorecard.md`, replacing TODO placeholders with evidence-backed PASS / PASS WITH FIXES / FAIL verdicts. Grader CLI is user-supplied via `--grader-cli`; no API key is embedded and no default provider is selected by the script.
+- `scripts/lib/mock-grader.js` — deterministic stand-in grader that produces canned `<verdict>` blocks per dimension. Lets CI smoke-test the graded pipeline without an API key and powers the `examples/audits/documentation/` graded fixture.
+- `schemas/skill.v2.schema.json` and `schemas/manifest.v2.schema.json` — pinned v2 copies of the unversioned schemas, content-identical modulo `$id` and `title`. Consumers that want stability across a future v3 bump pin to these; consumers that want to follow latest use the unversioned files.
+- `check-contract-consistency.js` C6 — enforces parity between the versioned and unversioned schemas. Drift is an error; the v2 files must track the unversioned files exactly until v3 ships.
+- `CHANGELOG.md` (this file) — Keep-a-Changelog-formatted history seeded with the current bundle. Future releases get entries under `## [Unreleased]` as they land.
+
+### Changed
+- `examples/audits/documentation/` regenerated via the mock grader to demonstrate what `--graded` output looks like: real scores, `N/A` for grounding on a portable skill, evidence-cited findings.
+- `docs/integrations/github-actions.md` — installation guidance rewritten so the primary path for that release was clone-and-vendor. The then-future `npm install --save-dev skill-graph` / `npx skill-graph-lint` snippets were preserved as a secondary **WHEN PUBLISHED** section so no reader mistook them for current 0.3.0 guidance.
+- `docs/skill-metadata-protocol.md § Schema Versioning Policy` — rewrites policy point 3 as a current-state description now that the versioned schema files exist.
+- `README.md` Status section — audit runner moves from "stub generator" bullet to a two-mode description and out of the Planned list. Validation table expands to six checks (adds C6). Quick Tour lists unversioned and v2 schemas side by side.
+- `docs/plans/scripts-roadmap.md § Audit runner` — marked SHIPPED with full two-mode description, grader-CLI discipline, and links to the new `scripts/lib/audit-prompt-builder.js` and `scripts/lib/mock-grader.js`.
+
+### Removed (breaking)
+- `portability.targets` enum values `cursor`, `windsurf`, `copilot`, and `agents-md`. Only `skill-md` has a working transform (`scripts/export-skill.js`); the other four were compatibility goals that violated the contract's `additionalProperties: false` strictness rule. The enum now accepts only `["skill-md"]`. Re-adding a runtime is gated on a new RFC and the same PR that ships its transform. Starter skills, the template, the sample manifest, the exports fixtures, and all docs that mentioned the removed values were updated to match.
+
+### Verification
+- `node scripts/skill-lint.js --strict` → 0 errors across 8 starters.
+- `node scripts/check-contract-consistency.js` → C1–C6 OK, 0 warnings.
+- `node scripts/generate-manifest.js --validate-only` → manifest valid.
+- `node scripts/skill-audit.js documentation --graded --grader-cli "node scripts/lib/mock-grader.js" --force` → 7 dimensions processed (6 grader calls + 1 N/A skip), 3 graded findings, 0 grader errors, non-TODO verdicts in all 3 artifact files.
+
+## [0.2.0] — 2026-04-17 (pre-changelog, reconstructed from git)
+
+The "v2 contract + scripts toolchain" release. Before 0.3.0 the project did not maintain a running changelog; this section reconstructs the bundle from the git history (commits `34bf6c0` through `3b2cec0`). Use this as a guide for pinning older consumers, not as a complete line-by-line history.
+
+### Added
+- `schema_version: 2` contract — split `eval_status` into the `eval_artifacts` / `eval_state` / `routing_eval` triple, renamed `scope` enum values (`generic` → `portable`, `operational` → `codebase`), renamed `portability.level` → `readiness` and `portability.exports` → `targets`, renamed `route_bundles` → `routing_bundles` (`6727a71`, SH-5784).
+- Eight starter skills across all four archetypes and all three scopes: `a11y`, `debugging`, `documentation`, `refactor`, `testing-strategy`, `skill-router` (`router`), `lint-overlay` (`overlay`), `graph-audit` (`codebase` with a full `grounding` block). (`17c6609`, `823f19f`, SH-5783.)
+- Five shipping scripts, all self-contained (Node built-ins only): `scripts/skill-lint.js` (schema + structural validation with code-frame diagnostics and archetype-aware section validator), `scripts/generate-manifest.js` (authored → generated projection), `scripts/export-skill.js` (SKILL.md export transform — single target: `skill-md`), `scripts/check-contract-consistency.js` (C1–C5 cross-artifact checks), `scripts/skill-audit.js` (lint-seeded stub generator). (`747f446`, `5c2ae16`, `d98a6a7`, `b88c61b`, `aad2e87`.)
+- GitHub Actions self-CI workflow and a copy-paste consumer integration doc (`7fa5af6`, SH-5786).
+- Authored-to-generated bridge doc, Schema Versioning Policy, relation-semantics decision tables, and the authoring-via-self-referential-template pattern (`6c2f694`, `a9cdd42`, `760e083`, `4194d54`).
+
+### Changed
+- `docs/skill-metadata-protocol.md` split into three focused files: overview + archetype map, field reference, and manifest contract (`90f78e5`, SH-5782).
+- Renamed frontmatter fields: `domain_frame` → `grounding`, `evaluation_mode` → `grounding_mode` (`5862283`, SH-5779).
+
+### Fixed
+- Restored four optional schema fields that were accidentally dropped in an earlier manifest refactor (`8791558`, SH-5776).
+- Repaired six factual errors in the shipped worked examples (`873c463`, SH-5777).
+
+[Unreleased]: https://github.com/jacob-balslev/skill-graph/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/jacob-balslev/skill-graph/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/jacob-balslev/skill-graph/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/jacob-balslev/skill-graph/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/jacob-balslev/skill-graph/releases/tag/v0.2.0

package/LICENSE

@@ -0,0 +1,200 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept and charge a
+      fee for, or grant additional rights consistent with, this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Jacob Balslev
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,62 @@
+Skill Graph
+
+Copyright 2026 Jacob Balslev
+
+================================================================================
+Dual-licensing
+================================================================================
+
+This package contains TWO bodies of work under different licenses:
+
+1. CODE — everything outside `skills/**`
+   Licensed under the Apache License, Version 2.0.
+   See LICENSE for the full text. http://www.apache.org/licenses/LICENSE-2.0
+
+2. SKILL CONTENT — markdown files under `skills/**`
+   Licensed under the Creative Commons Attribution 4.0 International License
+   (CC-BY-4.0). See https://creativecommons.org/licenses/by/4.0/ for the full
+   text.
+
+When redistributing or building derivative works from skills, attribute as:
+
+   "Skills from Skill Graph
+    (https://github.com/jacob-balslev/skill-graph),
+    licensed CC-BY-4.0."
+
+The two licenses cover non-overlapping files. Building a derivative work that
+combines code + skill content (e.g., a hosted service, a SaaS product, an
+adapted skill catalog) requires complying with BOTH licenses for their
+respective files.
+
+================================================================================
+Disclaimers
+================================================================================
+
+This project is NOT affiliated with, endorsed by, sponsored by, or in any way
+officially connected to:
+
+- Anthropic, PBC (Claude, Claude Code, Claude API)
+- OpenAI, Inc. (ChatGPT, GPT models, OpenAI API, Codex)
+- Google LLC / Alphabet Inc. (Gemini, Google Cloud, Gemini CLI)
+- GitHub, Inc. / Microsoft Corporation (GitHub Copilot)
+- The Model Context Protocol working group / contributors
+
+References to these companies, their products, or trademarks in code,
+documentation, examples, or model descriptors are descriptive only and do not
+constitute endorsement in either direction.
+
+================================================================================
+Third-party software
+================================================================================
+
+This project has zero runtime dependencies. Build and test tooling is listed
+in package.json devDependencies under their respective licenses (Vitest MIT,
+TypeScript Apache-2.0, etc.).
+
+================================================================================
+Skill content provenance
+================================================================================
+
+Skills under `skills/**` are the public subset intended for reuse in open
+source SKILL.md libraries. Private, customer-specific, and project-specific
+skills were intentionally excluded from this distribution.