@skill-graph/cli 0.5.6

package/docs/marketplace-syndication.md

@@ -0,0 +1,222 @@
+# Marketplace Syndication and Gap Discovery
+
+> **Audience.** Maintainers preparing Skill Graph and the full starter library for public discovery through `skills.sh`, SkillsMP, and other `SKILL.md` registries.
+>
+> **Status.** Working strategy. Update after each marketplace indexing experiment.
+>
+> **Last verified.** 2026-05-13.
+
+> **CLI vs skill library distribution:** This document covers skill library syndication — publishing `SKILL.md` files to registries like `skills.sh` and SkillsMP. CLI distribution via npm (`@skill-graph/cli`) is a separate concern: the CLI is published from this repo via the `.github/workflows/publish.yml` pipeline on `v*.*.*` tags. See `SH-6110` for install verification and the [Releasing section in README.md](../README.md#releasing-maintainers) for the release procedure.
+
+Skill Graph should use public skill marketplaces as discovery channels, not as the source of truth. The canonical artifacts stay in this repo: protocol-enriched `skills/**/SKILL.md` files, schemas, docs, evals, manifests, and reference tooling. Marketplaces receive plain `SKILL.md` exports or GitHub-indexable surfaces that point back to the canonical Skill Graph source.
+
+The goal is twofold:
+
+1. Syndicate the full library so people can discover and install the skills.
+2. Mine marketplace gaps and add new Skill Metadata Protocol skills where Skill Graph can contribute real coverage.
+
+This is additive. Do not shrink the library for marketplace presentation. Use indexes, generated views, metadata, and entry points.
+
+## Short Advertising Description
+
+Use this when a marketplace, README badge area, social post, repository description, or outreach note needs a compact project summary:
+
+```text
+Skills that know your project and codebase. Structured and categorized. Skill Metadata Protocol is a structured frontmatter contract for SKILL.md. Skill Graph is the local library tooling that works across those structured skills.
+```
+
+## Source Landscape
+
+| Surface | What it is useful for | Practical note |
+|---|---|---|
+| `skills.sh` | Installable `SKILL.md` discovery, install telemetry, leaderboard, README badge. | The docs show `npx skills add owner/repo` and a badge at `https://skills.sh/b/owner/repo`. |
+| SkillsMP | GitHub-scale discovery, keyword search, semantic search, categories, occupations, popularity/recent sorting. | The site describes public GitHub syncing and exposes `/api/v1/skills/search`; anonymous keyword search is rate-limited. |
+| Agent Skills spec | The base portability target. | The base shape supports `name`, `description`, optional `license`, optional `compatibility`, optional `metadata`, optional `allowed-tools`, plus body content and optional `scripts/`, `references/`, and `assets/`. |
+
+Source URLs:
+
+- `skills.sh` docs: https://www.skills.sh/docs
+- `skills.sh` CLI docs: https://www.skills.sh/docs/cli
+- SkillsMP: https://skillsmp.com/
+- SkillsMP API docs: https://skillsmp.com/docs/api
+- Agent Skills specification: https://agentskills.io/specification
+
+## Syndication Policy
+
+Syndicate all public Skill Graph skills that pass export validation. A short demo list is allowed only as a front door in docs, posts, and outreach. It is never a cap on what gets exported or indexed. This follows the repository quality doctrine: organize and adapt exports, do not trim the canonical source. See [`quality-doctrine.md`](quality-doctrine.md).
+
+The canonical source remains:
+
+```text
+skills/<skill-name>/SKILL.md
+```
+
+The plain marketplace artifact should be generated, not hand-edited. If a marketplace needs stricter base `SKILL.md` constraints than Skill Metadata Protocol uses internally, fix the export path or add an export-specific normalization step. Do not weaken the canonical protocol record just to satisfy a registry.
+
+## Release Target Decision
+
+Use a dedicated export repository as the public GitHub target:
+
+```text
+jacob-balslev/skills
+```
+
+Do not point marketplace indexers at this canonical protocol repo as the first
+install target. The canonical `skills/` directory intentionally contains
+Skill Metadata Protocol frontmatter, not plain marketplace frontmatter. A
+dedicated export repository avoids mixed indexing, keeps the marketplace surface
+small, and lets `skills/` sit at the repository root with one plain
+`SKILL.md` per public skill.
+
+The local staging surface is generated in this repo under:
+
+```text
+marketplace/skills/<name>/SKILL.md
+```
+
+After generation and verification, push that generated surface to the dedicated
+export repository. The install command to validate after publishing is:
+
+```bash
+npx skills add jacob-balslev/skills
+```
+
+## Export Provenance
+
+Marketplace exports should carry a small, factual provenance block in `metadata`. Do not put advertising copy in every skill body; the body is operational context loaded by agents.
+
+Use string values so the result stays compatible with the base `SKILL.md` metadata shape:
+
+```yaml
+metadata:
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: "Skill Metadata Protocol v4"
+  skill_graph_project: "Skill Graph"
+  skill_graph_canonical_skill: "skills/<name>/SKILL.md"
+```
+
+If a generated export already nests protocol fields under `metadata`, keep these `skill_graph_*` keys alongside that export metadata. The purpose is provenance, not keyword stuffing.
+
+## Marketplace Preparation Checklist
+
+Before publishing or asking a marketplace to index the library:
+
+- Use [`marketplace-release-agent-prompt.md`](marketplace-release-agent-prompt.md) when handing the export-surface implementation to another agent.
+- Run `npm run verify`.
+- Generate plain `SKILL.md` exports for the whole public library.
+- Generate the marketplace surface with `node scripts/export-marketplace-skills.js`.
+- Verify the generated surface with `node scripts/export-marketplace-skills.js --check`.
+- Verify the generated plain shape with `node scripts/verify-skill-md-export.js --plain marketplace/skills`.
+- Run a privacy gate before creating row-level marketplace lists or export surfaces.
+- Exclude any skill that exposes private projects, customer workflows, local runtime paths, personal names, email addresses, token-like strings, private repository names, or local operating context.
+- Keep excluded rows out of public reports, generated exports, marketplace metadata, social posts, and outreach notes until they are rewritten as general public skills and re-scanned cleanly.
+- Verify exported `name` values match the base `SKILL.md` pattern and parent directory names.
+- Verify exported `description` values fit the base `SKILL.md` limit.
+- Verify exported `compatibility` values are flattened strings, not objects.
+- Verify exported `metadata` values are string-to-string.
+- Add or update README install instructions for the export surface.
+- Add the `skills.sh` badge only after the install path works.
+- Confirm ignored local artifacts are not staged.
+- Review generated exports for secrets, private paths, telemetry, customer data, personal data, and accidental local-only research.
+
+## Gap Discovery Loop
+
+Run this loop periodically, especially before outreach or a release.
+
+1. Build the Skill Graph inventory from `examples/skills.manifest.sample.json` or a freshly generated manifest.
+2. Query `skills.sh` and SkillsMP for Skill Graph domains, adjacent domains, and obvious missing terms.
+3. Normalize marketplace results into a small working table: query, marketplace, skill name, repo, description, category, occupation, popularity signal, and last update when available.
+4. Classify each query result against the current library:
+   - `covered`: Skill Graph already has meaningful coverage.
+   - `covered-needs-syndication`: Skill Graph has coverage, but marketplace search cannot see it yet.
+   - `thin`: Skill Graph has adjacent coverage, but the marketplace exposes a real user task we should cover more directly.
+   - `gap`: The marketplace has demand or repeated examples and Skill Graph has no matching skill.
+   - `out-of-scope`: The gap belongs to a hosted service, proprietary workflow, prompt library, runtime implementation, or other excluded area.
+5. For `thin` and `gap`, write a short skill spec and plan before authoring content.
+6. Add the new skill under `skills/<skill-name>/SKILL.md` with the full Skill Metadata Protocol contract.
+7. Add `examples`, `anti_examples`, and `relations.boundary` so the new skill improves the graph instead of creating duplicate activation.
+8. Run lint, routing evals, overlap checks, and manifest validation.
+9. Re-export the full library and repeat the marketplace search to confirm the gap is now discoverable.
+
+The output of gap work is a better library, not a list of deleted or hidden skills.
+
+## Initial Query Set
+
+Use these queries as the first reproducible marketplace sweep. Add more as new domains appear.
+
+| Query | What it probes |
+|---|---|
+| `SKILL.md audit` | Whether registries have skills for checking skill quality and conformance. |
+| `skill routing` | Whether registries cover multi-skill routing and wrong-skill activation. |
+| `skill drift detection` | Whether registries cover stale grounded skills and truth-source drift. |
+| `skill manifest` | Whether registries expose generated inventory and library metadata workflows. |
+| `agent skill eval` | Whether registries cover eval artifacts, routing evals, and quality states. |
+| `skill overlap` | Whether registries cover duplicate activation and ownership boundaries. |
+| `skill provenance` | Whether registries cover source, license, and trust metadata. |
+| `skill graph` | Whether the Skill Graph concept itself is visible. |
+| `context graph` | Whether larger context-library architecture is covered. |
+| `tool call strategy` | Whether tool-use discipline is represented as a skill. |
+| `agent workflow design` | Whether workflow-level agent engineering is covered. |
+| `AI coding workspace` | Whether project-level AI workspace structure is covered. |
+| `design thinking agent skill` | Whether design methodology skills are discoverable. |
+| `ontology modeling agent skill` | Whether semantic modeling skills exist. |
+| `webhook integration skill` | Whether integration-specific skills exist and how they are framed. |
+| `Shopify skill` | Whether commerce-specific skills exist and where Skill Graph has differentiated coverage. |
+
+Treat this table as a starting queue. The gap ledger should record exact dates and marketplace responses, because both registries change over time.
+
+## Gap Candidates To Verify
+
+These are hypotheses, not claims. Validate them with the gap loop before creating new skills.
+
+| Candidate area | Why it may be useful | Likely Skill Graph shape |
+|---|---|---|
+| Skill registry hygiene | Marketplace users need to inspect third-party skills before installing them. | `capability`, portable, strong `relations.verify_with` to `security` and `graph-audit`. |
+| Skill provenance review | Public registries need source, license, compatibility, and trust review. | `workflow`, portable, grounded in Agent Skills spec and Skill Graph export docs. |
+| Marketplace export packaging | Authors need to publish Skill Metadata Protocol skills as plain `SKILL.md`. | `workflow`, reference or portable, tied to `scripts/export-skill.js`. |
+| Skill gap analysis | Teams need to compare their library against marketplace demand. | `workflow`, portable, depends on `skill-router`, `graph-audit`, and `skill-infrastructure`. |
+| Skill install risk triage | Installing a public skill is supply-chain work, not only copy-paste. | `capability`, portable, verify with `owasp-security` and `dependency-architecture`. |
+| Cross-runtime compatibility notes | Skills may behave differently across Claude Code, Codex, Cursor, Windsurf, and others. | `capability`, portable, with conservative compatibility language. |
+| Skill library release checklist | A multi-skill library needs release hygiene before public distribution. | `workflow`, portable, depends on `version-control`, `documentation`, and `graph-audit`. |
+
+Do not create a new skill just because a keyword is popular. Create one when Skill Graph can provide a useful, maintainable contract with clear activation, boundaries, relations, and verification.
+
+## Outreach Path
+
+Use a two-step outreach path:
+
+1. Ask maintainers for indexing and compatibility feedback.
+2. After the export and install path works, post the full project publicly.
+
+Suggested maintainer note:
+
+```text
+Skills that know your project and codebase. Structured and categorized. Skill Metadata Protocol is a structured frontmatter contract for SKILL.md. Skill Graph is the local library tooling that works across those structured skills.
+
+We are preparing to syndicate the full public starter library and would like feedback on the best shape for indexing generated exports while preserving canonical Skill Metadata Protocol metadata.
+
+Repo: https://github.com/jacob-balslev/skill-graph
+```
+
+Suggested public note:
+
+```text
+Skills that know your project and codebase. Structured and categorized. Skill Metadata Protocol is a structured frontmatter contract for SKILL.md. Skill Graph is the local library tooling that works across those structured skills.
+
+The full starter library is published from one canonical repo:
+https://github.com/jacob-balslev/skill-graph
+```
+
+For broader creator outreach, lead with the full library and the protocol/tooling story. Mention examples only as entry points.
+
+## Acceptance Criteria
+
+Marketplace syndication is ready when:
+
+- Every public skill has a generated plain `SKILL.md` export or a documented reason it is not exported yet.
+- Exported skills include factual Skill Graph provenance metadata.
+- The README explains how to install or inspect the exported library.
+- `skills.sh` can install the intended surface.
+- SkillsMP can discover the GitHub source or exports.
+- A gap ledger exists with dated marketplace queries and classifications.
+- New gap-driven skills go through the normal spec, plan, lint, manifest, routing, overlap, and export checks.

package/docs/migration-sample-review.md

@@ -0,0 +1,155 @@
+# Migration Sample Review — v4 → v5 Category Enum
+
+> **Status:** Active. Created 2026-05-16.
+> **Plan:** [`/Users/jacobbalslev/Development/docs/plans/skill-taxonomy-v5-and-gap-fill.md`](../../docs/plans/skill-taxonomy-v5-and-gap-fill.md) § Phase 0b.
+> **Gate verdict:** **PASS** — 26 of 30 assignments agree (86.67% ≥ 85% threshold). Phase 1 schema bump is unblocked, with four specific revisions recommended below.
+
+## Method
+
+The v5 category migration landed in skill-graph commit `210ac69` (2026-05-16) without a recorded reviewer-agreement check. This document supplies the missing gate retrospectively: a stratified sample of 30 skills spanning all 12 pre-migration `category` values, scored against the A′ mapping rules from the v5 plan, with disagreements flagged for follow-up.
+
+**Sampling.** Pre-migration categories extracted from `git show 210ac69^` (102 skills). Stratified to span every pre-migration value:
+
+| Pre-migration `category` | In-population N | Sample N | Coverage |
+|---|---|---|---|
+| `knowledge` | 29 | 5 | 17% |
+| `engineering` | 23 | 4 | 17% |
+| `design` | 15 | 3 | 20% |
+| `frontend` | 9 | 3 | 33% |
+| `ai-engineering` | 9 | 2 | 22% |
+| `quality` | 8 | 4 | 50% |
+| `integrations` | 2 | 2 | 100% |
+| `integration` | 2 | 2 | 100% |
+| `data` | 2 | 2 | 100% |
+| `workflow` | 1 | 1 | 100% |
+| `security` | 1 | 1 | 100% |
+| `product` | 1 | 1 | 100% |
+| **Total** | **102** | **30** | **29%** |
+
+Sample is deterministic (seeded `random.seed(20260516)`) so a second reviewer can reproduce it from `/tmp/sample-30.json` or re-sample with the same seed.
+
+**Scoring rules.** Each assignment scored AGREE / DISAGREE / BORDERLINE against the v5 plan's A′ rules:
+
+1. **Primary surface** — category names what the skill is *about*, not what it *enables*
+2. **Property vs subject** — a11y, perf, security, testing, type-safety are properties → `quality`; how to build is a subject → `engineering` / `design` / `agent`
+3. **`foundations` gate** — reserved for epistemic preconditions; skill must NOT be plausibly assignable to `agent` / `engineering` / `quality` / `design`
+4. **6-category enum**: `foundations` / `engineering` / `design` / `quality` / `agent` / `product`
+
+## Sample Results — All 30 Skills
+
+| # | Skill | Pre-migration | Post-migration (v5) | A′ Verdict | Notes |
+|---|---|---|---|---|---|
+| 1 | `command-palette` | `ai-engineering` | `design` | ✓ AGREE | Pure UI interaction pattern; pre-migration value was wrong |
+| 2 | `guardrails` | `ai-engineering` | `quality` | ✓ AGREE | Safety = quality property (Rule 2) |
+| 3 | `compression` | `data` | `engineering` | ✓ AGREE | Per plan: data → engineering w/ `domain: engineering/data` |
+| 4 | `entity-relationship-modeling` | `data` | `engineering` | ✓ AGREE | Same as #3 |
+| 5 | `color-system-design` | `design` | `design` | ✓ AGREE | No transition needed |
+| 6 | `design-module-composition` | `design` | `design` | ✓ AGREE | Component-system design |
+| 7 | `vercel-composition-patterns` | `design` | `design` | ❌ DISAGREE | Should be `engineering` w/ `domain: engineering/frontend`. The skill teaches React code patterns (compound components, render props, context providers, React 19 APIs) — engineering, not visual design. Vercel-Labs publishes this under the React / frontend topic shelf on skills.sh, not design. |
+| 8 | `architecture-decision-records` | `engineering` | `engineering` | ✓ AGREE | Engineering process artifact |
+| 9 | `event-storming` | `engineering` | `engineering` | ✓ AGREE | Domain discovery for engineering |
+| 10 | `framework-fit-analysis` | `engineering` | `engineering` | ✓ AGREE | Engineering technique |
+| 11 | `performance-engineering` | `engineering` | `engineering` | ❌ DISAGREE | Should be `quality` per Rule 2. Performance is one of the explicit `quality` properties listed in the v5 plan (alongside a11y, security, testing, type-safety). The "engineering" suffix in the skill name describes the *practice*, not the *category*. Co-located with `performance-budgets` (which IS in `quality`) — the two should share a primary surface. |
+| 12 | `form-ux-architecture` | `frontend` | `design` | ✓ AGREE | Form UX is design |
+| 13 | `interaction-patterns` | `frontend` | `design` | ✓ AGREE | UI controls are design |
+| 14 | `visual-design-foundations` | `frontend` | `design` | ✓ AGREE | Obviously design |
+| 15 | `cron-scheduling` | `integration` | `engineering` | ✓ AGREE | Per plan: integration → engineering w/ `domain: engineering/integrations` (or engineering/scheduling) |
+| 16 | `real-time-updates` | `integration` | `engineering` | ✓ AGREE | Same as #15 (also engineering/realtime) |
+| 17 | `printify` | `integrations` | `engineering` | ✓ AGREE | Vendor integration is engineering |
+| 18 | `shopify` | `integrations` | `engineering` | ✓ AGREE | Same as #17 |
+| 19 | `conceptual-modeling` | `knowledge` | `engineering` | ⚠ BORDERLINE-AGREE | Could plausibly be `foundations` (epistemic precondition for engineering). Accepted as `engineering` because the description emphasizes practical translation to DB schemas / API endpoints / DDD aggregates. If migration-sample reviewer disagrees, foundations is the strong alternative. |
+| 20 | `constraint-awareness` | `knowledge` | `foundations` | ✓ AGREE | Theory of Constraints = epistemic discipline; passes foundations-gate |
+| 21 | `semantic-center` | `knowledge` | `foundations` | ✓ AGREE | "How parts of a system connect" = epistemic reasoning; passes gate |
+| 22 | `semiotics` | `knowledge` | `foundations` | ❌ DISAGREE | Should be `design`. Description: "Use when designing or auditing icon systems, colors/badges/shapes, visual metaphors, interface signs..." — every use case is design. Fails the foundations-gate: the skill IS plausibly assignable to `design` (interface signs, icon design). Semiotic theory grounds design semantics, but applied semiotics is a design discipline. |
+| 23 | `skill-router` | `knowledge` | `agent` | ✓ AGREE | Agent-system tooling |
+| 24 | `keywords` | `product` | `product` | ✓ AGREE | Lone product skill; appropriate primary surface |
+| 25 | `agent-eval-design` | `quality` | `quality` | ⚠ BORDERLINE-AGREE | Evaluation is a quality property per Rule 2, so quality fits. **Plan tension:** `eval-driven-development` (Wave 3) is `agent`, not `quality`. The two are conceptually adjacent — eval-driven-development is the *practice* of evaluation while agent-eval-design is the *design* of evaluation artifacts. The plan should explicitly resolve whether evaluation is a `quality` property (per Rule 2) or an `agent` practice (per Wave 3). Recommendation: keep agent-eval-design in `quality`, surface `agent` via `relations.related`. |
+| 26 | `code-review` | `quality` | `quality` | ✓ AGREE | Quality workflow |
+| 27 | `lint-overlay` | `quality` | `quality` | ✓ AGREE | Linting is quality practice |
+| 28 | `ontology` | `quality` | `quality` | ❌ DISAGREE | Should be `engineering` (with strong `foundations` crossover). Description: "designing domain models that need formal type hierarchies, entity classification, knowledge-graph structure, category/type design, or ontology-driven APIs and databases." This is *not* about verifying quality of an artifact — it's about modeling domain structure. The pre-migration `quality` value appears to have been wrong, and the migration carried it forward unchanged. |
+| 29 | `owasp-security` | `security` | `quality` | ✓ AGREE | Security = quality property per Rule 2; aligns with plan's mapping |
+| 30 | `background-jobs` | `workflow` | `engineering` | ✓ AGREE | Workflow re-categorized by subject (engineering) — per plan |
+
+## Aggregate Results
+
+| Verdict | Count | % |
+|---|---|---|
+| AGREE | 26 | 86.67% |
+| DISAGREE | 4 | 13.33% |
+| BORDERLINE-AGREE | 2 (counted in AGREE) | — |
+
+**Threshold:** ≥ 85% reviewer-agreement on category gates Phase 1.
+**Outcome:** **PASS** (86.67%). The gate is just above threshold — Phase 1 schema bump is unblocked, but four specific revisions are recommended below to strengthen the mapping rules before bulk migration of the broader 287-skill library (Phase 5).
+
+## Disagreement Patterns
+
+Three structural patterns surface across the 4 DISAGREE cases:
+
+### Pattern 1: Properties-as-subject confusion (1 case)
+
+`performance-engineering` is in `engineering` but per A′ Rule 2 it's a quality property. The skill's *name* contains "engineering" but its *primary surface* is a non-functional property (latency, throughput, CWV).
+
+**Recommendation:** Move `performance-engineering` to `quality`. Verify against `performance-budgets` (already `quality`) — the two should share category. Add a lint warning: when a skill name ends in `-engineering` but its primary domain is a property in {a11y, performance, security, testing, type-safety, reliability}, propose `quality`.
+
+### Pattern 2: foundations-gate not enforced (1 case)
+
+`semiotics` is in `foundations` but is plausibly assignable to `design`. The plan's foundations-gate explicitly says: "the skill teaches an epistemic precondition AND the skill cannot be plausibly assigned to `agent`, `engineering`, `quality`, or `design`."
+
+**Recommendation:** Move `semiotics` to `design`. Apply the foundations-gate check to every other current foundations member. If `foundations` ends up smaller than 8 entries post-fix, the v5 plan's expected size (8–15) is itself the upper bound and the category remains valid.
+
+### Pattern 3: Carried-over wrong values (2 cases)
+
+`ontology` and `vercel-composition-patterns` had wrong values pre-migration that the codemod carried through unchanged. The migration only edited skills whose old value was in the deprecation list (`knowledge` / `frontend` / `ai-engineering` / `integration` / `integrations` / `data` / `workflow` / `security`); it didn't audit already-allowed values.
+
+**Recommendation:** Add a one-pass audit of all 137 skills' v5 category assignments against the A′ rules, not just the migrated values. The codemod was structurally one-directional and missed pre-existing miscategorizations.
+
+## Recommended Pre-Phase-1 Revisions
+
+Apply these 4 category corrections in a single commit before bumping `schema_version: 5`:
+
+```
+skills/vercel-composition-patterns/SKILL.md   design  → engineering
+skills/performance-engineering/SKILL.md       engineering → quality
+skills/semiotics/SKILL.md                     foundations → design
+skills/ontology/SKILL.md                      quality → engineering
+```
+
+Then re-run the routing-eval to confirm no `routing_eval: present` skill loses its tested examples. None of the 4 affected skills have `routing_eval: present` per a spot-check, so risk is low.
+
+## Open Questions Surfaced
+
+1. **`conceptual-modeling`** sits on the foundations / engineering boundary. Accepted as engineering but worth a second reviewer pass. If a second rater says foundations, the count flips to 25/30 = 83.3% — below threshold.
+2. **`agent-eval-design` vs `eval-driven-development`**: the plan should explicitly state whether evaluation is a quality property (→ `quality`) or an agent practice (→ `agent`). Currently the two skills sit in different categories despite conceptual adjacency.
+3. **Plan's deferred Open Question #2** (whether `product` retains its category) — the 1-skill sample (`keywords`) cleanly fits `product`; deferring to Phase 0a retrieval baseline as planned.
+
+## Reproducibility
+
+```bash
+# Re-extract pre-migration categories
+cd /Users/jacobbalslev/Development/skill-graph
+git ls-tree -r --name-only 210ac69^ | grep -E '^skills/[^/]+/SKILL\.md$' | while read f; do
+  skill=$(echo "$f" | sed 's|skills/||; s|/SKILL.md||')
+  cat=$(git show "210ac69^:$f" | grep -E '^category:' | head -1 | awk '{print $2}')
+  echo "$skill|$cat"
+done > /tmp/pre-migration-cats.txt
+
+# Re-run the deterministic sample
+python3 -c "
+import random; random.seed(20260516)
+# ... (sample logic from this review's audit script)
+"
+```
+
+Sample data also persisted at `/tmp/sample-30.json` for the duration of this session.
+
+## Verification Gate (this document)
+
+A future agent should consider this review complete when:
+
+- [x] 30 skills sampled spanning all 12 pre-migration category values
+- [x] Each assignment scored AGREE / DISAGREE / BORDERLINE
+- [x] Reviewer-agreement % computed and compared to 85% threshold
+- [x] Disagreement patterns extracted from the cases
+- [x] Specific revisions recommended before Phase 1 schema bump
+- [x] Reproducibility instructions provided
+- [ ] (Optional) Second independent rater agreement check — recommended but not required to clear the gate

package/docs/migrations/v4-to-v5.md

@@ -0,0 +1,168 @@
+# Migration: schema_version 4 → 5
+
+> **Status:** Active. Created 2026-05-16.
+> **Breaking change.** Closing the open-ended `category` field to a 6-value enum and removing 7 deprecated values is breaking. All skills must bump `schema_version` from `"4"` to `"5"`.
+> **Plan:** `docs/plans/skill-taxonomy-v5-and-gap-fill.md` (in the Development workspace).
+> **Phase 0b gate:** PASS — 26/30 = 86.67% reviewer-agreement on category. See [`skill-graph/docs/migration-sample-review.md`](../../../skill-graph/docs/migration-sample-review.md).
+
+## What changed
+
+### 1. `category` is now a closed enum of 6 values
+
+| Removed (v4) | Replaced by (v5) | Notes |
+|---|---|---|
+| `knowledge` | split by inspection — `foundations` (epistemics) / `engineering` (modeling) / `design` (design concepts) / `agent` (eval/grounding) | `knowledge` was the bucket-of-last-resort and dissolves |
+| `frontend` | `engineering` w/ `domain: engineering/frontend` OR `design` (when primary surface is visual/UX) | judgment per A′ Rule 1 (primary surface) |
+| `ai-engineering` | `agent` | the v5 name for AI/agent skills |
+| `integration` | `engineering` w/ `domain: engineering/integrations` | naming-drift dedup |
+| `integrations` | `engineering` w/ `domain: engineering/integrations` | naming-drift dedup |
+| `data` | `engineering` w/ `domain: engineering/data` | |
+| `workflow` | re-categorize by *subject* (`type: workflow` already carries method) | e.g. `background-jobs` → `engineering` |
+| `security` | `quality` | security is a quality property (A′ Rule 2) |
+| `engineering` | `engineering` (unchanged) | populate `domain` where missing |
+| `design` | `design` (unchanged) | |
+| `quality` | `quality` (unchanged) | promoted to 6th category — see Reconciliation Gate 2 in v5 plan |
+| `product` | `product` (unchanged) | |
+
+**New canonical enum (v5):** `foundations | engineering | design | quality | agent | product`
+
+The schema-level `enum` constraint is enforced in `schemas/skill.v5.schema.json`. Lint rejects any other value.
+
+### 2. `foundations` is the new browse home for epistemic preconditions
+
+`foundations` covers skills that teach how to think, how to ground, how to verify, how to learn — epistemic preconditions of being a competent agent or engineer. Examples: `epistemic-grounding`, `constraint-awareness`, `mental-models`, `semantic-center`, `reasoning`.
+
+**Foundations-gate anti-junk-drawer rule:**
+
+> Membership in `foundations` requires (a) the skill teaches an epistemic precondition AND (b) the skill cannot be plausibly assigned to `agent`, `engineering`, `quality`, or `design`. If the skill could plausibly fit another category, it goes there instead.
+
+Expected `foundations` size: 8–15 skills. If `foundations` exceeds 20 entries, the gate has failed and the migration is misrouted.
+
+`foundations` replaces the prior plan's `Meta Method` category — same conceptual slot, different name. See `docs/plans/skill-taxonomy-v5-and-gap-fill.md` § Reconciliation Gate 1.
+
+### 3. `quality` is promoted from facet to 6th category
+
+The prior plan (`docs/plans/skill-taxonomy-architecture.md`, 2026-04-03) treated quality as a `layerPrimary` facet. v5 promotes it to a 6th category because Phase 0a retrieval baseline showed quality-shaped queries (OWASP, Core Web Vitals, accessibility, mocking-strategy) routed poorly without quality-shaped homes.
+
+**A′ Rule 2 — Property vs subject:**
+
+> Properties of any artifact (a11y, perf, security, testing, type-safety, observability) → `quality`. How to build → `engineering` / `design` / `agent`.
+
+If a skill's primary surface is a non-functional property of an artifact, it belongs in `quality`. If it's about *building* something, it belongs in the subject category (engineering/design/agent).
+
+### 4. Naming convention shifts to head-noun glossary + allowed_exceptions registry
+
+The prior "two-anchor compound" naming rule and the banned-verb-prefix lint are replaced by:
+
+1. **Head-noun glossary** at `docs/head-noun-glossary.md` — each skill name must end with a head noun from this glossary (e.g. `architecture`, `design`, `system`, `flow`, `model`, `pattern`, `boundary`, `protocol`).
+2. **Optional modifiers** — pattern: `<modifier>-<head-noun>` or `<modifier>-<modifier>-<head-noun>` (max 2 modifiers).
+3. **`allowed_exceptions` registry** at `docs/name-exceptions.yaml` — established industry term-of-art exceptions with a citation per entry (e.g. `code-review`, `design-review`, `event-storming`).
+4. **Lint** in `scripts/skill-lint.js` checks head-noun + modifier-count + registry fallback.
+
+### 5. Concept-shape adoption rule is evidence-based
+
+`comprehension_state: present` requires **all four** conditions:
+
+1. `scope` ∈ {`portable`, `reference`}
+2. `type` = `capability`
+3. `grounding.external_sources` cites ≥2 non-repo references (spec, canonical book, vendor doc with industry adoption, peer-reviewed paper). Single-vendor-feature anchors do not count as two sources.
+4. The `concept` block (definition / mental_model / purpose / boundary / taxonomy / analogy / misconception) can be written *without any repo-specific noun* — no Sales Hub, no Shopify, no orchestrator-ui, no internal file paths.
+
+Lint emits a warning if `comprehension_state: present` is set but condition #3 or #4 fails. Stronger than the prior "social recognition" framing.
+
+### 6. `category` is framed as a browse facet, not ontology truth
+
+The v5 protocol doc explicitly states:
+
+> `category` answers one question only: *Where should a human browse to find this skill first?* It is a browse facet, not an ontological claim. Cross-cutting truth lives in `relations.related`.
+
+Skills that genuinely cross-cut (e.g., `command-palette` is a `design` skill that's used by agents) get a single primary category plus secondary categories via `relations.related` (max 5).
+
+## Migration procedure for skill authors
+
+For every SKILL.md you maintain:
+
+### Required edit
+
+Change the schema_version field:
+
+```yaml
+# Before (v4)
+metadata:
+  schema_version: "4"
+
+# After (v5)
+metadata:
+  schema_version: "5"
+```
+
+### Conditional edits
+
+| If your skill has... | Then... |
+|---|---|
+| `category: knowledge` | Re-route per the table above (most go to `foundations` or `engineering`) |
+| `category: frontend` | Re-route to `engineering` (with `domain: engineering/frontend`) or `design` (if visual/UX primary surface) |
+| `category: ai-engineering` | Re-route to `agent` |
+| `category: integration` / `integrations` | Re-route to `engineering` (with `domain: engineering/integrations`) |
+| `category: data` | Re-route to `engineering` (with `domain: engineering/data`) |
+| `category: workflow` | Re-route by subject — e.g. `background-jobs` → `engineering` |
+| `category: security` | Re-route to `quality` |
+| `category: foundations` | Verify foundations-gate: can this plausibly be `agent`/`engineering`/`quality`/`design`? If yes, move there. |
+| `comprehension_state: present` set | Verify `grounding.external_sources` has ≥2 non-repo entries AND concept block contains no repo-specific nouns |
+| Skill name violates head-noun pattern | Either rename to match head-noun-glossary OR add to `docs/name-exceptions.yaml` with citation |
+
+### Codemod available
+
+```bash
+# Bulk-bump schema_version in all SKILL.md files
+cd /Users/jacobbalslev/Development/skills
+find skills -name SKILL.md -exec sed -i '' 's/schema_version: "4"/schema_version: "5"/g' {} +
+
+# Verify lint baseline
+cd /Users/jacobbalslev/Development/skill-graph
+SKILL_GRAPH_WORKSPACE=/Users/jacobbalslev/Development/skills node scripts/skill-lint.js
+```
+
+The v5 category enum is already applied across the 137 live skills (skill-graph commit `210ac69`, 2026-05-16). The codemod above is the final schema_version bump.
+
+## Backward compatibility
+
+| Direction | Compatible? | Note |
+|---|---|---|
+| v4 tool reads v5 SKILL.md | ⚠ Partial | v4 tool will read the file but may not enforce v5 enum / foundations-gate / concept-shape rules. Old lint warnings will surface incorrectly. |
+| v5 tool reads v4 SKILL.md | ✓ via `normalizeFrontmatter()` | The skill-graph repo's `scripts/lib/parse-frontmatter.js` already normalizes marketplace-shape and pre-v5 shapes for forward-compat reads. |
+| Mixed v4 / v5 corpus | ❌ Not supported | Either everything is v5 or everything is v4. Mixing causes lint failures and routing inconsistencies. |
+
+**Recommendation:** apply the codemod in a single commit. Do not ship a partial-v5 corpus.
+
+## Verification checklist
+
+After running the v4→v5 codemod:
+
+- [ ] Every SKILL.md has `schema_version: "5"`
+- [ ] Every `category` value is one of `foundations | engineering | design | quality | agent | product`
+- [ ] `foundations` contains 8–15 skills (gate-pass)
+- [ ] `node scripts/skill-lint.js` baseline unchanged (no new errors from migration)
+- [ ] `node scripts/generate-manifest.js --output skills.manifest.json` succeeds
+- [ ] `by_category` in manifest shows exactly 6 keys
+- [ ] Sample retrieval-eval queries route the same or better post-migration
+
+## Rollback procedure
+
+If verification fails:
+
+```bash
+cd /Users/jacobbalslev/Development/skills
+find skills -name SKILL.md -exec sed -i '' 's/schema_version: "5"/schema_version: "4"/g' {} +
+```
+
+Then revert any `category` enum changes via `git checkout`. The v5 protocol doc and schema file can remain — they're additive references, not active constraints, until skills carry `schema_version: "5"`.
+
+## Related artifacts
+
+- `schemas/skill.v5.schema.json` — JSON schema with closed `category` enum
+- `SKILL_METADATA_PROTOCOL.md` — v5 protocol contract (browse-facet framing, foundations-gate, evidence-based concept-shape)
+- `docs/head-noun-glossary.md` — canonical head-noun list for skill names
+- `docs/name-exceptions.yaml` — established industry term-of-art exceptions
+- `skill-graph/docs/migration-sample-review.md` — Phase 0b reviewer-agreement check (86.67% pass)
+- `docs/plans/skill-taxonomy-v5-and-gap-fill.md` (in Development workspace) — full v5 plan with reconciliation decisions