@skill-graph/cli 0.5.6

package/docs/_archived/marketplace-publication-priority-2026-05-18.md

@@ -0,0 +1,239 @@
+# Marketplace Publication Priority — 2026-05-18 (ARCHIVED)
+
+> **Archived 2026-05-18:** Superseded by [`../marketplace-publication-queue.generated.md`](../marketplace-publication-queue.generated.md), which is auto-generated by `skill-audit-loop@0.3.0` from [`../../data/publication-classification.json`](../../data/publication-classification.json). This snapshot is preserved for audit-trail grep and to document the curatorial reasoning that seeded the ledger.
+>
+> Updates and supersedes prior tier ordering in
+> [`../marketplace-skill-candidate-list.md`](../marketplace-skill-candidate-list.md) (2026-05-13 inventory + 2026-05-14 migration)
+> and [`../research/skill-demand-gap-roadmap-2026-05-16.md`](../research/skill-demand-gap-roadmap-2026-05-16.md).
+>
+> **Purpose:** prioritized publication queue for `github.com/jacob-balslev/skills` / `skills.sh/jacob-balslev/skills/`,
+> ranked by **expected popularity** given current marketplace demand signals.
+>
+> **Scope filter (per [ADR 0008](./adr/0008-skill-surface-split-and-curation-policy.md)):**
+> Sales-Hub-bound, customer-data-bearing, and personal/PII-bound skills are listed in the
+> "Excluded" sections so the decision is auditable — none are recommended for publication
+> in this pass.
+
+## Current state (2026-05-18)
+
+| Surface | Count | Notes |
+|---|---:|---|
+| Already published (jacob-balslev/skills) | 142 | mirrored at `skills/skills/` and `skill-graph/marketplace/skills/` |
+| Personal-only candidates inspected | 204 | files in `~/Development/skills/` not in `skills/skills/` |
+| → Classified PUBLISHABLE (this report) | **121** | tiered below |
+| → Classified SALES-HUB-BOUND (excluded) | 41 | listed in § Excluded |
+| → Classified PERSONAL-INFRA (excluded) | 42 | listed in § Excluded |
+
+## Demand evidence refreshed 2026-05-18
+
+| Source | Signal |
+|---|---|
+| skills.sh leaderboard | `find-skills` 1.5M, `frontend-design` 418k, `vercel-react-best-practices` 403k, `agent-browser` 277k, `skill-creator` 211k, `shadcn` 144k |
+| SkillsMP corpus | 280k+ skills indexed by 2026-05; top categories Tools, Business, Development, Testing & Security, Data & AI, DevOps, Documentation |
+| Anthropic official skills | `algorithmic-art`, `brand-guidelines`, `canvas-design`, `claude-api`, `doc-coauthoring`, `docx`, `frontend-design`, `internal-comms`, `mcp-builder`, `pdf`, `pptx`, `skill-creator`, `slack-gif-creator`, `theme-factory`, `web-artifacts-builder`, `webapp-testing`, `xlsx` |
+| Firecrawl 2026 review | Top picks: Firecrawl, GStack, Superpowers, Frontend Design, Vercel React Best Practices, Composition Patterns, PDF/DOCX/XLSX/PPTX, Webapp Testing, Trail of Bits Security, Remotion, Skill Creator, Corey Haines Marketing |
+| aitmpl.com | Featured: Bright Data Web Data, TinyFish Web Agents, ClaudeKit, BrainGrid Planning |
+
+## How to read this list
+
+- **Sanitize?** = SKILL.md body or description currently names Sales Hub, Printify shop IDs, `org_id`, or internal scripts and must be rewritten before publication.
+- **Source** = `port` (rewrite root skill body unchanged where possible), `port+sanitize`, `rewrite` (deferred per 2026-05-14 privacy review), `author` (no root source — write from scratch).
+- **Pop** = 1–5 expected install/usage popularity. 5★ maps directly to a top-10 skills.sh skill OR an Anthropic official slot. 4★ maps to a documented demand cluster.
+- Per the repo's complete-reporting rule, **every** publishable candidate appears below. The user decides which to skip; nothing is filtered out unilaterally.
+
+---
+
+## Tier S — Publish immediately (5★, n=18)
+
+These map directly to top demand signals and have working source in `~/Development/skills/` or a clean rewrite path.
+
+| # | Skill | Pop | Source | Sanitize? | Demand signal |
+|---:|---|---:|---|---|---|
+| 1 | `mcp-builder` | 5 | port | no | Anthropic official slot; "mcp server" search demand |
+| 2 | `playwright-cli` *(→ playwright-browser-automation)* | 5 | port | minor | Anthropic `webapp-testing` analog; firecrawl 2026 top pick |
+| 3 | `react-best-practices` | 5 | port+sanitize | yes | `vercel-react-best-practices` 403k installs |
+| 4 | `next-best-practices` | 5 | port+sanitize | yes | skills.sh nextjs topic dedicated category |
+| 5 | `next-cache-components` | 5 | port | minor | Next 16 `use cache` / `cacheLife` named on skills.sh |
+| 6 | `hook-patterns` | 5 | port | minor | Claude Code hook lifecycle has no public canonical skill yet |
+| 7 | `advanced-css-layout` | 5 | port | no | Subgrid + container queries + `:has()` + `@layer` — high evergreen demand |
+| 8 | `pdf` | 5 | port | minor | Anthropic official slot |
+| 9 | `vercel` *(→ vercel-deployment)* | 5 | port | minor | skills.sh Next/Vercel topic |
+| 10 | `git-worktree` | 5 | rewrite | yes | skills.sh agent-workflows topic; parallel agents |
+| 11 | `radix-ui` | 5 | port+sanitize | yes | `shadcn` 144k installs → Radix is the substrate |
+| 12 | `autonomous-loop-patterns` | 5 | rewrite | yes | skills.sh "Ralph loops" + autonomous task loops |
+| 13 | `dispatch-loop` | 5 | rewrite | yes | multi-agent dispatch — companion to autonomous-loop-patterns |
+| 14 | `linear` *(→ linear-cli)* | 5 | port+sanitize | yes | Linear API/CLI integration — strong demand, no public canonical |
+| 15 | `human-in-the-loop` | 5 | port | minor | every agent system needs this; no Anthropic equivalent yet |
+| 16 | `chrome-devtools-mcp` | 5 | port | no | Chrome DevTools MCP is hot; debugging companion to playwright |
+| 17 | `docker` | 5 | port | minor | every DevOps stack; firecrawl 2026 lists `infra-team` skills |
+| 18 | `cursor` | 5 | port | minor | `.cursor/rules` authoring; cross-CLI portability angle |
+
+## Tier A — High demand, second wave (4★, n=29)
+
+Solid universal utility; clear demand cluster on skills.sh / SkillsMP.
+
+| # | Skill | Pop | Source | Sanitize? | Notes |
+|---:|---|---:|---|---|---|
+| 19 | `agent-task-delegation` | 4 | rewrite | yes | subagent + dispatch patterns; skills.sh agent-workflows |
+| 20 | `agent-messaging` | 4 | port+sanitize | yes | cross-agent comm patterns; companion to a2a-protocol |
+| 21 | `agent-session-handoff` | 4 | rewrite | yes | session continuity; matches multi-agent demand |
+| 22 | `chat-interface` | 4 | rewrite | yes | chat UI patterns; demand from AI app builders |
+| 23 | `dark-mode` | 4 | port | minor | skills.sh design topic; companion to `dark-mode-implementation` (already pub) |
+| 24 | `doc-co-authoring` | 4 | port | no | Anthropic official slot is `doc-coauthoring` |
+| 25 | `doc-updater` | 4 | port+sanitize | yes | doc routing protocol — high demand |
+| 26 | `docs-development` | 4 | port | minor | docs-as-code; broad audience |
+| 27 | `editorial-standards` | 4 | port | no | doc quality bar; complements writing-humanizer |
+| 28 | `email-templates` | 4 | port+sanitize | yes | email patterns; transactional + marketing |
+| 29 | `form-input-ux` | 4 | port | minor | every app has forms |
+| 30 | `frontend` | 4 | port | minor | umbrella router skill |
+| 31 | `frontend-structure` | 4 | port | minor | folder + module conventions |
+| 32 | `graphql` | 4 | port+sanitize | yes | GraphQL patterns; broad demand |
+| 33 | `i18n` | 4 | port | minor | internationalization — every consumer app |
+| 34 | `knowledge-graph` | 4 | port | minor | Skill Graph differentiation; complements `context-graph` |
+| 35 | `linting` | 4 | port+sanitize | yes | ESLint + custom rule patterns |
+| 36 | `memory-gardener` | 4 | port | minor | agent memory CRUD/index |
+| 37 | `memory-prune` | 4 | port | minor | agent memory hygiene |
+| 38 | `middleware-architecture` | 4 | port | no | Next.js/Express middleware patterns |
+| 39 | `motion-design` | 4 | port | no | skills.sh design topic; `delight` adjacent |
+| 40 | `no-cutting-corners` | 4 | port | no | quality doctrine; companion to `methodical` |
+| 41 | `quality-doctrine` | 4 | port | no | per-artifact quality definitions |
+| 42 | `methodical` | 4 | rewrite | yes | RLHF anti-patterns; very portable methodology |
+| 43 | `self-evaluation` | 4 | port | no | 1-5 self-score pattern; agent quality |
+| 44 | `self-review-pattern` | 4 | port | no | generate-critique-revise; eval discipline |
+| 45 | `task-execution` | 4 | port | minor | task workflow; complements `prioritization` (already pub) |
+| 46 | `task-lifecycle` | 4 | rewrite | yes | task state machine; agent ops |
+| 47 | `wardley-mapping` | 4 | port | no | strategic mapping — surging demand 2026 |
+
+## Tier B — Standard utility (3★, n=42)
+
+Broad-audience publishables that round out the library.
+
+| # | Skill | Pop | Source | Sanitize? | Notes |
+|---:|---|---:|---|---|---|
+| 48 | `adr` | 3 | port | no | already partial dup of `architecture-decision-records` — merge or supersede |
+| 49 | `agent-behavior` | 3 | port | minor | agent behavior patterns |
+| 50 | `agent-code-documentation` | 3 | port | no | code doc patterns for agent-edited code |
+| 51 | `agent-loop-infra` | 3 | rewrite | yes | loop checkpoint state machine |
+| 52 | `agent-observability` | 3 | port | minor | telemetry pipeline patterns |
+| 53 | `agent-script-control` | 3 | port | minor | agent-driven shell control |
+| 54 | `agent-task-brief` | 3 | port | minor | task spec authoring for agents |
+| 55 | `agent-to-agent` | 3 | port | minor | A2A protocol primer |
+| 56 | `agents` | 3 | port | minor | agent system overview |
+| 57 | `ai-coding-agents` | 3 | port+sanitize | yes | agent roster + routing — popular topic |
+| 58 | `backend` | 3 | port | minor | backend patterns umbrella |
+| 59 | `backend-structure` | 3 | port | minor | backend folder/module conventions |
+| 60 | `breakpoint-strategy` | 3 | port | no | responsive breakpoint design |
+| 61 | `browser-support` | 3 | port | no | browser compat decisions |
+| 62 | `categorization` | 3 | port | no | classification methodology |
+| 63 | `code-logic` | 3 | port | minor | code reasoning patterns |
+| 64 | `codebase-search` | 3 | port | minor | grep / glob / agent search patterns |
+| 65 | `composition-theory` | 3 | port | no | composition primitives |
+| 66 | `content-strategy` | 3 | port | no | content audit + lifecycle |
+| 67 | `contracts` | 3 | port+sanitize | yes | software contract patterns |
+| 68 | `copywriting` | 3 | port+sanitize | yes | marketing copy; sales-hub-flavored body |
+| 69 | `csv` | 3 | port | no | CSV format patterns |
+| 70 | `data-architect` | 3 | port | minor | data architecture role/patterns |
+| 71 | `data-science` | 3 | port | minor | data science workflow |
+| 72 | `data-sync` | 3 | port | minor | data sync patterns |
+| 73 | `data-table-ux` | 3 | port | minor | TanStack Table adjacent |
+| 74 | `data-viz` | 3 | port+sanitize | yes | chart selection patterns |
+| 75 | `dead-code-detection` | 3 | port | minor | knip / ts-prune patterns |
+| 76 | `dependency-management` | 3 | port | no | npm/pnpm patterns |
+| 77 | `design-execution` | 3 | port+sanitize | yes | design implementation workflow |
+| 78 | `design-guide` | 3 | port | yes | design system authoring |
+| 79 | `design-qa-gate` | 3 | port | minor | design QA pattern |
+| 80 | `design-review` | 3 | port | minor | design review checklist |
+| 81 | `design-token-architecture` | 3 | port | minor | design token system |
+| 82 | `digital-empire` | 3 | port | yes | business model patterns; consider rename |
+| 83 | `dnd-kit` | 3 | port | no | drag-and-drop patterns |
+| 84 | `dorothy` | 3 | port | yes | dialog/decision methodology; consider rename |
+| 85 | `ecosystem-modeling` | 3 | port | minor | ecosystem mapping |
+| 86 | `edge-case-matrix` | 3 | port | no | edge case enumeration |
+| 87 | `experiment` | 3 | port | minor | experimentation workflow |
+| 88 | `feature-gating` | 3 | port | minor | feature flag patterns |
+| 89 | `feedback-collection` | 3 | port | minor | feedback loop patterns |
+
+## Tier C — Niche but publishable (2★, n=32)
+
+Lower demand or narrower audience. Phase 3 batch.
+
+| # | Skill | Pop | Source | Sanitize? | Notes |
+|---:|---|---:|---|---|---|
+| 90 | `file-splitting` | 2 | port | no | file size discipline |
+| 91 | `folder-structure` | 2 | port | minor | folder org patterns |
+| 92 | `ghostty` | 2 | port | minor | Ghostty terminal config |
+| 93 | `glossary` | 2 | port | no | terminology management |
+| 94 | `identifying-bottlenecks` | 2 | port | minor | perf bottleneck triage |
+| 95 | `ontology` | 2 | port | no | already partial dup of `ontology-modeling` — merge |
+| 96 | `ooda-loop` | 2 | port | no | OODA methodology |
+| 97 | `orchestration` | 2 | rewrite | yes | orchestration patterns |
+| 98 | `perceptual-integration` | 2 | port | minor | UX perception patterns |
+| 99 | `perspective` | 2 | rewrite | yes | viewpoint/framing methodology |
+| 100 | `provider-abstraction` | 2 | port+sanitize | yes | provider adapter patterns |
+| 101 | `rate-limiting` | 2 | port | minor | rate limiting patterns |
+| 102 | `repository-structure` | 2 | port | minor | monorepo structure patterns |
+| 103 | `responsive` | 2 | port | no | responsive design patterns |
+| 104 | `review-tooling` | 2 | port | minor | code review tools survey |
+| 105 | `scss-expert` | 2 | port | no | SCSS patterns |
+| 106 | `seo-audit` | 2 | port+sanitize | yes | SEO audit checklist |
+| 107 | `sequential-thinking` | 2 | rewrite | yes | sequential reasoning method |
+| 108 | `session-lifecycle` | 2 | rewrite | yes | session hygiene |
+| 109 | `session-progression` | 2 | port | minor | session state progression |
+| 110 | `session-structure` | 2 | port | minor | session shape patterns |
+| 111 | `shape-up` | 2 | port | no | Basecamp Shape Up methodology |
+| 112 | `site-architecture` | 2 | port | minor | IA patterns |
+| 113 | `skill-evolution` | 2 | port | minor | corpus walker pattern |
+| 114 | `skill-portability` | 2 | port | minor | cross-CLI conversion |
+| 115 | `streaming` | 2 | rewrite | yes | streaming patterns |
+| 116 | `task-evaluation` | 2 | port | minor | task quality scoring |
+| 117 | `task-path-optimization` | 2 | port | minor | task graph optimization |
+| 118 | `task-progression` | 2 | rewrite | yes | task state progression |
+| 119 | `task-sizing` | 2 | rewrite | yes | task sizing methodology |
+| 120 | `task-structure` | 2 | port | minor | task shape patterns |
+| 121 | `taxonomy` | 2 | port | no | already partial dup of `taxonomy-design` — merge |
+| 122 | `teaching-patterns` | 2 | port | no | teaching/onboarding patterns |
+| 123 | `technical-debt` | 2 | port | no | tech debt tracking |
+| 124 | `test-coverage` | 2 | port+sanitize | yes | dup of `test-coverage-strategy` — merge |
+| 125 | `test-generator` | 2 | port | minor | test scaffolding patterns |
+| 126 | `theme-factory` | 2 | port | no | Anthropic official slot — port may conflict |
+| 127 | `threaded-conversations` | 2 | rewrite | yes | threaded UI patterns |
+| 128 | `todo-lists` | 2 | port | no | TODO/task UI patterns |
+| 129 | `token-cost-estimation` | 2 | rewrite | yes | LLM token cost math |
+| 130 | `token-efficiency` | 2 | rewrite | yes | token-efficient agent patterns |
+| 131 | `tui` | 2 | rewrite | yes | terminal UI patterns |
+| 132 | `typography` | 2 | port | no | dup of `typography-system` — merge |
+| 133 | `ui-ux` | 2 | port+sanitize | yes | UI/UX checklist |
+| 134 | `ux-ui-patterns` | 2 | port | no | UX pattern library |
+| 135 | `value-engineering` | 2 | port | no | value engineering methodology |
+| 136 | `visual-design` | 2 | port | no | dup of `visual-design-foundations` — merge |
+
+---
+
+## Excluded — Sales-Hub-bound (41, not recommended)
+
+Listed for auditability. These name internal schemas (`order_events`, `orgQuery`, Printify shop IDs), customer-data flows, or vendor reconciliation logic specific to my product:
+
+`a2a-protocol`, `anomaly-detection`, `api-key-management`, `audit-traceability`, `backfill-patterns`, `banking`, `benchmarking-engine`, `bulk-operations`, `business-structure`, `canonical-unification`, `configuration-patterns`, `connector-blueprint`, `cost-aggregation`, `credential-encryption`, `csv-import-adapters`, `customer-journey`, `dashboard-modules`, `data-reconciliation`, `demo-data-seeding`, `deterministic`, `domain-modeling`, `duplicate-detection`, `encryption`, `entity-resolution`, `entity-status`, `financial-allocation`, `financial-display-contract`, `financial-metrics`, `fulfillment`, `gdpr-compliance`, `inngest-orchestration`, `invoice`, `kpi-cards`, `materialization-expert`, `multi-tenancy-rls`, `nextauth-patterns`, `page-cro`, `payment-lifecycle`, `product-photo`, `receipts`, `sales-channels`, `security-scanning`, `state-machine-patterns`, `stripe-ledger-recon`, `structured-logging`, `system-resilience`, `system-watchdog`, `temporal-data-patterns`, `troubleshooting`, `url-state-management`, `user-research-synthesis`, `vulnerability`, `websocket`
+
+## Excluded — Personal-infra / monorepo-only (42, not recommended)
+
+These describe my `~/Development` orchestration stack (`/workflow/` commands, Ghostty tabs, grind-loop, dispatch-loop scripts, Linear team SH-XXXX, agent-orchestration state files) and have no audience outside this monorepo:
+
+`agent-control`, `agent-engineering`, `agent-governance`, `agent-identity`, `agent-information-ontology`, `agent-infrastructure`, `agent-orchestration`, `board-triage`, `color-science`, `conductor`, `cron-scheduling`, `design-thinking`, `diff-analysis`, `environment`, `error-tracking`, `evaluation`, `harness-engineering`, `module-components`, `orchestrator-ui`, `prioritization`, `problem-locating-solving`, `refactor`, `shopify`, `skill-infrastructure`, `skill-scaffold`, `vibe-kanban`, `writing-humanizer`
+
+---
+
+## Recommended execution batches
+
+| Batch | Cohort | Skills | Effort | Owner |
+|---|---|---|---|---|
+| **P1** | Tier S #1-9 | mcp-builder, playwright-browser-automation, react-best-practices, next-best-practices, next-cache-components, hook-patterns, advanced-css-layout, pdf, vercel-deployment | ~9 ports, 4 needing light sanitization | skill-graph |
+| **P2** | Tier S #10-18 + privacy rewrites | git-worktree, radix-ui, autonomous-loop-patterns, dispatch-loop, linear-cli, human-in-the-loop, chrome-devtools-mcp, docker, cursor | ~5 ports + 4 privacy rewrites | skill-graph |
+| **P3** | Tier A docs + agent ops | doc-updater, doc-co-authoring, docs-development, editorial-standards, no-cutting-corners, methodical, quality-doctrine, self-evaluation, self-review-pattern | mostly direct ports | skill-graph |
+| **P4** | Tier A frontend + UX | dark-mode, form-input-ux, frontend, frontend-structure, motion-design, i18n, middleware-architecture, graphql, email-templates | mix of port + sanitize | skill-graph |
+| **P5** | Tier A agent comms | agent-task-delegation, agent-messaging, agent-session-handoff, chat-interface, knowledge-graph, memory-gardener, memory-prune | privacy rewrites + ports | skill-graph |
+| **P6** | Tier B + C catch-up | remainder, run through `node skill-graph/scripts/export-marketplace-skills.js` after sanitization batch | bulk port pipeline | skill-graph |
+
+## Completeness claim
+
+This report covers **all 121 publishable candidates** identified across the 204 personal-only skills (`~/Development/skills/` minus `~/Development/skills/skills/`). Sales-Hub-bound (41) and personal-infra (42) candidates are listed by name for auditability; none are recommended in this pass. The total of 121 + 41 + 42 = 204 reconciles to the diff size.

package/docs/adr/0001-predicate-set.md

@@ -0,0 +1,69 @@
+# ADR 0001 — Relation Predicate Set
+
+- **Status:** Accepted with revision per ADR 0006 (the `boundary -> disjoint_with` rename in Decision #2 was reverted; Decisions #1, #3, and #4 stand unchanged).
+- **Original acceptance:** 2026-04-20
+- **Revision:** 2026-05-04 (see `docs/adr/0006-revise-predicate-rename.md`)
+- **Deciders:** Skill Graph maintainers
+- **Consulted:** SKOS Reference (W3C 2009), PROV-O (W3C 2013), Gruber 1995 on ontology design, Guarino & Welty OntoClean, Wilkinson et al. 2016 on FAIR
+
+## Context
+
+Skill Graph models inter-skill relationships with typed edges under `relations.*`. Through v3 the predicate set was four keys: `adjacent`, `boundary`, `verify_with`, `depends_on`. An external audit (2026-04-20) flagged that the chosen names diverge from established W3C vocabularies (SKOS, PROV-O, Dublin Core Terms), blocking FAIR Interoperability and making the graph harder to reuse in federated knowledge-graph tooling.
+
+The audit proposed:
+
+1. Rename `adjacent` → `related` to align with `skos:related`.
+2. Decompose `boundary` into an ownership-style `disjoint_with` (OWL `disjointWith` semantics) — `boundary` currently conflates "there is an edge" with "the edge is explicitly-not-ownership". **(Revised by ADR 0006: `boundary` and `owl:disjointWith` operate at different semantic layers — routing vs formal class-theory — so the two relations are not aliases. `boundary` stays canonical for routing-layer asymmetric handoff; `disjoint_with` becomes a separate orthogonal relation for formal OWL class-disjointness.)**
+3. Add `broader` / `narrower` to express cross-skill generalisation that `category` cannot capture.
+4. Keep `verify_with` and `depends_on` — they have no clean SKOS equivalent and map instead to `prov:wasInformedBy` and `dcterms:requires` respectively.
+
+## Decision
+
+Accept all four proposals, with an **additive, backward-compatible** rollout:
+
+1. Extend the `relations` schema to accept `related`, `broader`, `narrower`, and `disjoint_with` as optional predicates.
+2. Keep `adjacent` and `boundary` valid. `adjacent` becomes an alias for `related`. `boundary` ~~becomes an alias for `disjoint_with`~~ **stays canonical for routing-layer asymmetric handoff per ADR 0006; `disjoint_with` becomes a separate orthogonal relation for formal OWL class-disjointness, not an alias.**
+3. Emit a `skill-lint.js` warning (not error) when `adjacent` or `boundary` is used. The warning points at the preferred name and the v4 deprecation target.
+4. Map all six predicates to their W3C equivalents via `schemas/skill.context.jsonld`. Consumers gain RDF-projectable semantics without changing the authoring surface.
+5. Target v4 for removal of the deprecated names. No v3 skill needs to change. The predicate set does not become breaking until the v4 schema bump.
+
+## Rationale
+
+- **SKOS alignment is cheap and buys FAIR Interoperability.** `skos:related` is the 17-year-old W3C standard for symmetric associative relations between concepts. Using `related` as the preferred name means a third-party tool that already understands SKOS can consume the Skill Graph with a single `@context` declaration. No parser rewrites.
+- **`broader` / `narrower` close a real gap.** Cross-skill generalisation (e.g. "`react-best-practices` is narrower than `frontend`") is currently unexpressable — `category` captures only taxonomy-tree hierarchy within a category, not skill-to-skill generalisation. SKOS solved this exact problem. Adopting the solved solution is correct.
+- **`disjoint_with` makes anti-ownership semantics explicit.** `boundary` was invented vocabulary. Decomposing it into "there is a relation AND the relation is disjointness" matches OWL's `owl:disjointWith` and lets graph consumers reason about exclusion without special-casing a Skill-Graph-only predicate.
+- **Additive, backward-compatible rollout respects code in the wild.** Hundreds of skills in the Development workspace use `adjacent` / `boundary` today. A breaking rename would force a coordinated library-wide edit. Additive-with-deprecation costs one lint-warning pass and buys the same interoperability.
+- **`verify_with` and `depends_on` stay as-is.** `verify_with` is a provenance relation (PROV-O `wasInformedBy`) not a classification relation. `depends_on` is a pragmatic prerequisite (`dcterms:requires`) not a conceptual hierarchy. Neither has a SKOS analogue and both carry intent that would be lost if forced into SKOS naming.
+
+## Consequences
+
+### Positive
+
+- JSON-LD `@context` file (`schemas/skill.context.jsonld`) ships alongside this ADR; any Skill Graph SKILL.md can be projected into RDF/OWL consumers.
+- Cross-skill generalisation is now expressible via `broader` / `narrower` without changing the taxonomy tree.
+- Lint warnings surface the rename before v4 forces it.
+- FAIR Interoperability moves from *weak* to *strong* without changing the author-facing shape.
+
+### Negative
+
+- Two predicate names for the same concept during the v3 → v4 window. Authors must know that `adjacent` and `related` mean the same thing; the field-reference doc is extended to say so loudly.
+- Slight schema growth (four new optional keys). Mitigated because they are all optional, the JSON Schema cost is negligible, and the documentation grows proportionally.
+
+### Neutral
+
+- Consumers that only read `adjacent` / `boundary` continue to work unchanged.
+- Consumers written against `skos:related` / `skos:broader` etc. can be fed the @context-expanded JSON-LD projection with no Skill-Graph-specific code.
+
+## References
+
+- W3C SKOS Reference — https://www.w3.org/TR/skos-reference/
+- W3C PROV-O — https://www.w3.org/TR/prov-o/
+- Dublin Core Metadata Terms — https://www.dublincore.org/specifications/dublin-core/dcmi-terms/
+- Gruber, T. (1995). *Toward principles for the design of ontologies used for knowledge sharing.* International Journal of Human-Computer Studies 43(5-6):907-928.
+- Guarino, N. & Welty, C. *Evaluating Ontological Decisions with OntoClean.* Communications of the ACM 45(2):61-65.
+- Wilkinson, M. D. et al. (2016). *The FAIR Guiding Principles for scientific data management and stewardship.* Scientific Data 3:160018. DOI:10.1038/sdata.2016.18.
+- SPDX License List (ISO/IEC 5962:2021) — https://spdx.org/licenses/
+
+## Supersedes
+
+- Skill Graph v3.0 implicit predicate choice — this ADR documents the decision retrospectively so v3.x additions trace back to a cited rationale rather than "we invented these names".

package/docs/adr/0002-json-ld-context.md

@@ -0,0 +1,82 @@
+# ADR 0002 — JSON-LD @context for W3C Interoperability
+
+- **Status:** Accepted (2026-04-20)
+- **Deciders:** Skill Graph maintainers
+- **Relates to:** ADR 0001 (Predicate Set), FAIR Wilkinson et al. 2016
+
+## Context
+
+The external audit of 2026-04-20 identified **FAIR Interoperability** as the Skill Metadata Protocol's weakest dimension. The contract was self-consistent but isolated — no machine-readable mapping to established W3C vocabularies (SKOS, Dublin Core Terms, PROV-O, SPDX, schema.org). Third parties wanting to consume protocol metadata in a federated knowledge-graph tool or a generic RDF triplestore had no adapter path short of writing Skill-Metadata-Protocol-specific code.
+
+## Decision
+
+Ship `schemas/skill.context.jsonld` — a JSON-LD `@context` file that maps every authored Skill Graph field to its nearest W3C standard term. Authors do not need to change anything. Consumers that want RDF semantics apply the `@context` and receive standard SKOS / DC Terms / PROV-O triples.
+
+Field-to-vocabulary mapping summary:
+
+| Skill Graph | Mapped to | Vocabulary |
+|---|---|---|
+| `name` | `dcterms:identifier` | Dublin Core Terms |
+| `description` | `dcterms:description` | Dublin Core Terms |
+| `version` | `dcterms:hasVersion` | Dublin Core Terms |
+| `owner` | `dcterms:creator` | Dublin Core Terms |
+| `license` | `dcterms:license` | Dublin Core Terms (SPDX identifier) |
+| `freshness` | `dcterms:modified` (xsd:date) | Dublin Core Terms |
+| `superseded_by` | `prov:wasRevisionOf` | PROV-O |
+| `workspace_tags` | `dcterms:audience` (set) | Dublin Core Terms |
+| `keywords` | `dcat:keyword` (set) | DCAT |
+| `category` | `skos:broader` (chain) | SKOS |
+| `adjacent` / `related` | `skos:related` | SKOS |
+| `broader` | `skos:broader` | SKOS |
+| `narrower` | `skos:narrower` | SKOS |
+| `boundary` / `disjoint_with` | `sg:disjointOwnership` (custom; decomposes to `skos:related` + `owl:disjointWith`) | SKOS+OWL |
+| `verify_with` | `prov:wasInformedBy` | PROV-O |
+| `depends_on` | `dcterms:requires` | Dublin Core Terms |
+| `extends` | `prov:wasDerivedFrom` | PROV-O |
+| `truth_sources` | `dcterms:source` | Dublin Core Terms |
+| `drift_check.last_verified` | `prov:generatedAtTime` | PROV-O |
+| `type`, `scope`, `category`, `routing_bundles`, `grounding.*`, `eval_*`, `lifecycle.*`, `runtime_telemetry.*`, `portability.*`, `compatibility.*` | `sg:*` custom namespace | Skill Graph vocabulary (no W3C analogue) |
+
+Custom predicates live under `https://skillgraph.dev/vocab#` (`sg:` prefix). Everything that has a W3C equivalent is mapped to the equivalent, not rediscovered.
+
+## Rationale
+
+- **JSON-LD is additive, non-invasive.** Authors keep writing plain YAML. The `@context` file sits next to the schema. Consumers that want RDF apply it; consumers that don't, don't.
+- **W3C vocabularies are 15+ years old and have deep tooling support.** Adopting them is cheaper than publishing a competing vocabulary.
+- **Dual-layer mapping strategy.** Fields with clean W3C analogues (roughly 70% per audit) map to the analogue. Fields without (archetype, scope, eval-health triple, grounding, readiness) stay in the `sg:` namespace and are documented.
+- **SPDX is already an ISO standard.** Our `license` field already uses SPDX identifiers; JSON-LD makes that machine-resolvable.
+
+## Consequences
+
+### Positive
+
+- Skill Graph becomes one `@context` away from RDF — no parser changes.
+- Federated tools (Skosmos, WebVOWL, generic SPARQL endpoints) can ingest a Skill Graph library with zero Skill-Graph-specific adapter code.
+- FAIR Interoperability moves from Weak to Strong.
+- Future "cross-repo skill federation" work is unblocked.
+
+### Negative
+
+- One more file to keep in sync. Mitigated by the protocol-consistency checker: if `schemas/skill.v3.schema.json` adds a field, the `@context` must add a mapping.
+- The `sg:` custom namespace is not yet served from `https://skillgraph.dev/vocab#`. The ID is reserved; publishing the live resolvable vocabulary is tracked separately.
+
+### Neutral
+
+- Authors see no change.
+- CI runs no new check today; the consistency check is a follow-up.
+
+## Verification
+
+- `schemas/skill.context.jsonld` exists and is valid JSON.
+- Every required authored field (`schema_version`, `name`, `description`, `version`, `type`, `category`, `scope`, `owner`, `freshness`, `drift_check`, `eval_artifacts`, `eval_state`, `routing_eval`) has a mapping.
+- Every `relations.*` predicate has a mapping.
+- Custom `sg:` IRIs are defined consistently.
+
+## References
+
+- JSON-LD 1.1 — https://www.w3.org/TR/json-ld11/
+- DCMI Metadata Terms — https://www.dublincore.org/specifications/dublin-core/dcmi-terms/
+- SKOS Reference — https://www.w3.org/TR/skos-reference/
+- PROV-O — https://www.w3.org/TR/prov-o/
+- DCAT 3 — https://www.w3.org/TR/vocab-dcat-3/
+- FAIR Principles — Wilkinson et al. 2016, DOI:10.1038/sdata.2016.18

package/docs/adr/0003-ontoclean-rigidity-tags.md

@@ -0,0 +1,65 @@
+# ADR 0003 — OntoClean Rigidity Tags for Archetypes
+
+- **Status:** Accepted (2026-04-20)
+- **Deciders:** Skill Graph maintainers
+- **Relates to:** ADR 0001 (Predicate Set)
+- **Method:** Guarino & Welty, *Evaluating Ontological Decisions with OntoClean*
+
+## Context
+
+The external audit of 2026-04-20 flagged a latent modelling bug: the combination of `type: overlay` + `extends` + `category` can accidentally subsume a rigid category under an anti-rigid overlay. In OntoClean terms, an anti-rigid property cannot have a rigid property as its subclass — doing so produces unsatisfiable class hierarchies. The audit asked for explicit rigidity tagging on each archetype so authors and reviewers can recognise the violation before it ships.
+
+## Decision
+
+Annotate each archetype with four OntoClean meta-properties: **Rigidity (R)**, **Identity (I)**, **Unity (U)**, **Dependence (D)**.
+
+| Archetype | Rigidity | Identity | Unity | Dependence |
+|---|---|---|---|---|
+| `capability` | **+R** (rigid) — a capability is what the skill *is*, essentially | **+I** — has its own identity criteria | **+U** — unitary scope | **-D** — does not existentially depend on another skill |
+| `workflow` | **+R** (rigid) — the workflow is the essence | **+I** — has its own identity | **+U** — unitary procedure | **-D** — does not depend on another skill |
+| `router` | **~R** (semi-rigid) — the router is defined by what it dispatches to; its essence can shift | **-I** — identity is inherited from the dispatch set | **~U** — scope is the union of targets | **+D** — depends on target skills for meaning |
+| `overlay` | **-R** (anti-rigid) — an overlay's essence is "specialisation of X" and vanishes without X | **-I** — identity inherited from parent | **-U** — scope is parent-relative | **+D** — existentially depends on `extends` target |
+
+### The constraint
+
+OntoClean's key constraint: **an anti-rigid property cannot subsume a rigid property.** Applied here:
+
+- An `overlay` (-R) cannot have a `capability`/`workflow` (+R) as `extends` target such that the overlay would *replace* the capability's identity. Overlay must *specialise* — inherit identity from parent, not redefine it.
+- A `capability` (+R) cannot be declared an overlay of another `capability` — that is a +R under -R chain.
+
+### The test
+
+During skill authoring and review, for any `type: overlay`, answer yes to both:
+
+1. Does the overlay's identity *depend* on the parent's identity? (If the parent were deleted, would the overlay become meaningless?)
+2. Does the overlay *specialise* rather than *replace* the parent's scope?
+
+If either answer is no, the skill is not an overlay — it is a separate `capability` or `workflow`. Change the `type` accordingly.
+
+## Rationale
+
+- **OntoClean is a battle-tested method for catching exactly this class of bug.** Guarino & Welty demonstrated it against WordNet and found hundreds of subsumption errors that had sat undetected. Applying it to four archetypes is trivial by comparison.
+- **Explicit tags beat implicit assumptions.** Today the constraints exist informally — an author "just knows" that overlay specialises. The tags make the knowledge discoverable in the field-reference.
+- **The rigidity tags cost nothing at runtime.** They are documentation. No schema change, no lint rule.
+- **They unlock a future lint rule.** A v4 lint check can read the tags and warn when an overlay's body rewrites the parent's `## Coverage` (a signal of replacement, not specialisation). That is cheap to add once the tags are canonical.
+
+## Consequences
+
+### Positive
+
+- Documentation gains a principled explanation of why `overlay` is different from the other archetypes.
+- Future lint rules can reference the tags instead of inventing ad-hoc heuristics.
+- Authors writing their first overlay have a concrete test to run against.
+
+### Negative
+
+- Minor cognitive load in the field-reference. Mitigated by keeping the tags in a single summary table, not repeated per field.
+
+### Neutral
+
+- Existing skills do not need updating; the tags describe properties the archetypes already had implicitly.
+
+## References
+
+- Guarino, N. & Welty, C. A. (2002). *Evaluating Ontological Decisions with OntoClean.* Communications of the ACM 45(2):61-65.
+- Guarino, N. & Welty, C. *An Overview of OntoClean.* In *Handbook on Ontologies*, Springer 2009, pp. 201-220.

package/docs/adr/0004-persistent-identifiers.md

@@ -0,0 +1,74 @@
+# ADR 0004 — Persistent Identifiers via URN
+
+- **Status:** Accepted (2026-04-20)
+- **Deciders:** Skill Graph maintainers
+- **Relates to:** ADR 0002 (JSON-LD @context), FAIR Findability
+
+## Context
+
+The external audit of 2026-04-20 found that Skill Graph covers FAIR Findability well *within a single repository* (via `name`, `keywords`, `triggers`, `examples`, `category`) but has **no globally unique persistent identifier**. `name` is unique only inside one repo; two workspaces both shipping a skill called `knowledge-graph` have no way to be told apart. This blocks cross-repo federation, registry publication, and long-term citation.
+
+## Decision
+
+Introduce an **optional** top-level `urn` field in v3 (additive, non-breaking) and make it **required** in v4 (breaking, one major bump away). The URN follows the syntax:
+
+```
+urn:skill:<repo-slug>:<skill-name>
+```
+
+Examples:
+
+- `urn:skill:skill-graph:knowledge-graph`
+- `urn:skill:<placeholder-repo-a>:data-table-ux`
+- `urn:skill:<placeholder-repo-b>:order-fulfillment`
+- `urn:skill:<placeholder-repo-c>:seo-keywords`
+
+Rules:
+
+1. `<repo-slug>` is the publishing repo's canonical short handle. Lowercase, hyphen-separated, `[a-z0-9-]+`.
+2. `<skill-name>` must match the skill's `name` field.
+3. The `urn` value must be globally unique. A registry (future work) resolves URNs to skill manifests.
+4. Consumers treat the URN as the stable identity. `name` is display-layer.
+5. The URN is the `@id` in the JSON-LD projection (see ADR 0002).
+
+Regex: `^urn:skill:[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-/:]*$`
+
+## Rationale
+
+- **URN is the right tool.** RFC 8141 defines URNs as namespaced, resolvable-optional, persistent. The `urn:skill:` namespace can be registered with IANA later; the scheme is valid without registration because URNs are syntactic identifiers.
+- **Globally unique beats locally unique.** A federated registry, cross-repo import, or long-term citation all require global identity. `name` cannot carry that load.
+- **Optional-in-v3, required-in-v4 respects existing libraries.** No skill needs to ship a URN today. Authors can add them incrementally. The schema bump consolidates the change with other v4 breaking changes so there is no "URN-only bump".
+- **URN over URL.** URLs imply web resolvability; we are not yet running a resolver. URN is honest about the identifier-only role. If we ever add a resolver, the URN can still be the canonical ID and the URL becomes the resolution endpoint.
+
+## Consequences
+
+### Positive
+
+- FAIR Findability moves from "repo-local" to "global".
+- Cross-repo skill federation is unblocked.
+- Long-term citation is possible — an external doc can cite `urn:skill:skill-graph:knowledge-graph@1.0.0` as a stable reference.
+- JSON-LD projection gains a proper `@id` instead of inventing one from the `name`.
+
+### Negative
+
+- Skills without URNs in v3 are identifiable only by `name` + repo context. Acceptable because the field is optional.
+- v4 bump forces every skill to add one. Mitigated by a codemod (`scripts/migrate-v3-to-v4.js` — future work) that infers the URN from the repo root.
+
+### Neutral
+
+- Today's skills continue to validate without the field.
+- The JSON-LD `@context` already maps `urn` → `@id` (ADR 0002), so adding the field does not require a context update.
+
+## Implementation checklist
+
+- [x] Add optional `urn` field to `schemas/skill.v3.schema.json` with the regex above.
+- [x] Add optional `urn` field to `schemas/skill.schema.json` (mirror of v3).
+- [x] Add `urn` to `docs/field-reference.md` with a URN-authoring guide.
+- [x] Map `urn` to `@id` in `schemas/skill.context.jsonld`.
+- [ ] Ship `scripts/migrate-v3-to-v4.js` when v4 is cut (out of scope for this ADR).
+- [ ] Decide and publish the repo-slug-to-URN mapping rule for multi-root workspaces (out of scope for this ADR).
+
+## References
+
+- RFC 8141 — Uniform Resource Names (URNs) — https://datatracker.ietf.org/doc/html/rfc8141
+- FAIR Principles, F1 "(Meta)data are assigned a globally unique and persistent identifier" — Wilkinson et al. 2016

package/docs/adr/0005-freshness-consolidation.md

@@ -0,0 +1,70 @@
+# ADR 0005 — Freshness Field Consolidation (Proposal for v4)
+
+- **Status:** Proposed (2026-04-20)
+- **Deciders:** Skill Graph maintainers
+- **Target:** v4 schema bump (breaking change)
+
+## Context
+
+v3 has three overlapping freshness/staleness fields:
+
+| Field | Role |
+|---|---|
+| `freshness` | "When was this last *editorially* reviewed?" (ISO date, required) |
+| `drift_check.last_verified` | "When was this last *verified against truth sources*?" (ISO date, required) |
+| `lifecycle.stale_after_days` | "Days after `drift_check.last_verified` at which the skill is flagged stale" (integer, optional) |
+
+The external audit of 2026-04-20 flagged this as decomposable. Two problems:
+
+1. **Authors get confused.** `freshness` vs `drift_check.last_verified` is subtle — "editorial" vs "truth-source" review. In practice, most skills set them to the same date, and the distinction is rarely load-bearing.
+2. **Tools duplicate work.** The drift sentinel already reasons about `drift_check.last_verified + lifecycle.stale_after_days`. The `freshness` field is consulted by only one check (the >90-days editorial-review warning).
+
+## Decision (proposed)
+
+Collapse the three fields into two primitives in v4:
+
+| New field | Replaces | Shape |
+|---|---|---|
+| `asserted_at` | `freshness` + `drift_check.last_verified` | ISO date. "When was this skill last asserted to be correct? (Editorial = truth-source; if you need to separate them, the skill is probably too stale.)" |
+| `stale_after` | `lifecycle.stale_after_days` | ISO 8601 duration (`P90D`, `P6M`, `P1Y`). "How long after `asserted_at` is the skill considered stale?" |
+
+`drift_check.truth_source_hashes` stays where it is — it is content-addressable evidence, a different concern from date-based freshness.
+
+## Rationale
+
+- **Two fields are simpler than three.** Authors don't need to choose between editorial and truth-source review; both collapse into one "I asserted this is correct today" act.
+- **ISO 8601 durations are more expressive than integers.** `P90D` vs `P6M` vs `P1Y` read correctly; `stale_after_days: 90` vs `180` vs `365` requires translation.
+- **Tooling simplifies.** The drift sentinel reasons about `(today - asserted_at) > stale_after` as one comparison instead of joining three fields.
+- **Backward compatibility is preserved by the codemod.** `scripts/migrate-v3-to-v4.js` (future) maps `freshness || drift_check.last_verified` → `asserted_at` (prefer later date) and `lifecycle.stale_after_days` → `stale_after: "P${n}D"`.
+
+## Consequences
+
+### Positive
+
+- One fewer freshness concept to explain in the field-reference.
+- Duration values self-document (`P90D` is obviously 90 days, `P6M` obviously 6 months).
+- Drift-sentinel simpler.
+
+### Negative
+
+- Breaking change — requires v4 bump. Authors must run the codemod.
+- Loses the *theoretical* distinction between editorial and truth-source review. In practice the distinction was rarely used.
+
+### Neutral
+
+- `drift_check.truth_source_hashes` is unchanged — hash-based evidence is orthogonal to date-based freshness.
+
+## Not decided yet
+
+- Whether to keep `lifecycle.review_cadence` (`per-commit` / `weekly` / `quarterly` / `on-truth-source-change`) or fold it into `stale_after`. The cadence carries scheduling intent that duration alone does not. Lean toward keeping it.
+- Whether to require `asserted_at` or make it optional. Today's `freshness` is required. Lean toward required.
+- The exact codemod conflict-resolution rule when `freshness` and `drift_check.last_verified` disagree by more than 30 days — use the later, or warn and ask?
+
+## Status: Proposed, not accepted
+
+This ADR exists to make the v4 direction visible and invite feedback before v4 work begins. No changes to the current schema. No action required from authors. Revisit when v4 planning starts.
+
+## References
+
+- ISO 8601 duration format — https://en.wikipedia.org/wiki/ISO_8601#Durations
+- Audit that prompted this ADR — `skills/knowledge-graph/references/skill-graph-audit-standards-2026-04-20.md` § "Versioning and drift detection"