@skill-graph/cli 0.5.6

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

@@ -0,0 +1,221 @@
+# Migration: schema_version 5 → 6
+
+> **Status:** Active. Created 2026-05-17.
+> **Additive structural change.** v6 promotes the nested `concept` block to flat top-level fields and adds the Health Block (audit-loop-written fields). The v5 nested `concept` shape remains accepted in v6 for v5 skills not yet migrated; the schema `anyOf` rule lets the comprehension-state requirement be satisfied by either shape. No values are removed, no fields are renamed, no requirements are tightened against existing v5 skills.
+> **Plan:** `docs/plans/skill-audit-loop-simplification.md` (in the Development workspace) — outer frame and design rationale.
+> **Tier C″ codification:** the cross-domain `relations.boundary[]` doctrine, codified after empirical 30-query baseline sweep on 2026-05-17. See § Cross-Domain Boundary Doctrine below.
+
+## What changed
+
+### 1. The seven-field `concept` block is flattened to top-level fields
+
+v5's nested `concept` block:
+
+```yaml
+metadata:
+  comprehension_state: present
+  concept:
+    definition: "..."
+    mental_model: "..."
+    purpose: "..."
+    boundary: "..."
+    taxonomy: "..."
+    analogy: "..."
+    misconception: "..."
+```
+
+v6's flat shape:
+
+```yaml
+comprehension_state: present
+mental_model: "..."   # primitives and their relationships
+purpose: "..."        # the problem this concept solves
+boundary: "..."       # what this concept is NOT (mechanism, not label)
+analogy: "..."        # one-sentence metaphor
+misconception: "..."  # wrong mental model people bring
+```
+
+The two retired sub-fields:
+
+| v5 sub-field | v6 home | Why retired |
+|---|---|---|
+| `concept.definition` | `description` | The v5 `description` is the routing contract — first-person prose explaining what the skill covers. v6 keeps it as the routing contract AND promotes it to also carry the concept definition. There is no separate "the concept *is* …" surface needed; the routing contract subsumes it. |
+| `concept.taxonomy` | `category` + `relations.broader` | Taxonomy = "where does this sit relative to neighbors?" `category` answers the browse-shelf question; `relations.broader` answers the cross-skill generalization question. The two together encode what `concept.taxonomy` was for. |
+
+The body section `## Concept Card` is also retired. The flat frontmatter fields are now the canonical location — no in-body teaching block.
+
+**Why flat?** The nested `concept` block was an iteration, not the goal. Every other authored teaching field on a skill is flat. Nesting just one set under `concept.*` made authors learn a special access pattern, made schema readers walk an extra level, and made the comprehension grader synthesize information from two locations (the body's `## Concept Card` section AND the frontmatter `concept` object) that should have been one.
+
+### 2. The Health Block — seven flat fields recording the audit fingerprint
+
+v6 adds seven flat top-level fields that record a skill's audit state directly in its frontmatter, replacing the v5 model of scattered log files (`eval-history.jsonl`, `routing-misses.jsonl`, `.opencode/progress/skill-audit-*`, `health-ledger.jsonl`, `findings/*.md` — five places to know one skill's status):
+
+```yaml
+# Health Block (written by the audit loop — do not hand-author)
+last_audited: 2026-05-17                       # ISO date `audit` last ran
+last_changed: 2026-05-15                       # ISO date the skill was last edited
+audit_verdict: PASS                            # PASS | PASS_WITH_FIXES | PARTIAL | FAIL | UNKNOWN
+eval_score: 4.2                                # 0.0–5.0 latest aggregate eval grade
+eval_failed_ids: []                            # failing eval IDs (empty when clean)
+lint_verdict: PASS                             # PASS | FAIL | UNKNOWN
+drift_status: OK                               # OK | DRIFT | BROKEN | STALE | NO_BASELINE | EXTERNAL_UNHASHED | UNKNOWN
+```
+
+**Authorship rule:** these fields are stamped by `scripts/skill/skill-audit.js`, `scripts/skill/evaluate-skill.js`, and `scripts/skill-graph-drift.js`. Do not hand-author them — the next `audit` run will overwrite hand-edits with the loop's authoritative values.
+
+**Loop reads, log writes retire after one corpus walk.** During the v5→v6 migration window, the audit-loop scripts write to both the flat Health Block fields AND the legacy log files. After one full corpus walk, the log writes are retired and the flat fields are the single source of truth.
+
+### 3. `comprehension_state: present` accepts either shape
+
+The v6 schema's `allOf` rule that enforces `comprehension_state: present` was:
+
+```json
+// v5
+"then": { "required": ["concept"] }
+```
+
+In v6 it becomes:
+
+```json
+// v6
+"then": {
+  "anyOf": [
+    { "required": ["mental_model", "purpose", "boundary", "analogy", "misconception"] },
+    { "required": ["concept"] }
+  ]
+}
+```
+
+The author can satisfy the requirement by populating the five flat fields (preferred), the nested `concept` block (v5 back-compat), or both (flat fields win when both are present).
+
+### 4. Cross-Domain Boundary Doctrine — codified
+
+`relations.boundary[]` is a Skill-Graph-specific routing-layer predicate, NOT formal class disjointness. Its runtime semantic was discovered empirically during the Wave 6 routing-tuning work and is codified in v6:
+
+**Runtime mechanic:** `if (target.score >= declarer.score) skip target` — the declarer can exclude the target *only when the declarer is currently outscoring it on the query*. This INVERTS the surface reading "I am NOT B; defer to B" — boundary entries protect the declarer's wins, not the target's wins. Source: `skill-graph/scripts/skill-graph-route.js:548`.
+
+**Doctrine — SAME-DOMAIN ONLY:**
+
+1. `boundary[]` entries should declare same-domain handoffs only (same `category` AND same `domain` sub-tree). Example: `engineering/frontend` ↔ `engineering/frontend` is fine.
+2. Cross-category or cross-sub-domain handoffs belong in `anti_examples` + `relations.related`, NOT in `boundary[]`. The `anti_examples` array preserves routing-visible documentation as wrong-use phrases; `relations.related` signals the semantic adjacency without invoking the score-aware exclusion mechanic.
+3. Empirical justification (Tier C″ sweep, 2026-05-17): removing 16 cross-domain `boundary[]` entries across 8 Wave 6 skills caused **0 top-1 routing changes** on the 30-query baseline; only 3/30 low-confidence unmaskings of legitimate alternatives at score 3 surfaced. The cross-domain entries were performing silent low-confidence exclusion only — exactly the silent-failure risk the doctrine prevents.
+
+**Author rule:** if you would write a `boundary[]` entry whose target lives in a different `category` or different `domain` sub-tree than the declarer, move the entry to `anti_examples` (wrong-use phrase, routing-visible) + `relations.related` (semantic adjacency signal). Lint (planned, not yet implemented) will warn on cross-domain boundary declarations.
+
+## Migration procedure for skill authors
+
+For every SKILL.md with `comprehension_state: present`:
+
+### Required edits
+
+1. Change the schema_version field:
+
+   ```yaml
+   # Before (v5)
+   metadata:
+     schema_version: "5"
+
+   # After (v6)
+   metadata:
+     schema_version: "6"
+   ```
+
+2. Populate the five flat Understanding fields with real content (not pipe-empty placeholders):
+
+   ```yaml
+   # Before (v5 — nested with placeholders)
+   metadata:
+     concept:
+       definition: "<populated text>"
+       mental_model: "|"   # placeholder — fails comprehension grader
+       purpose: "|"
+       boundary: "|"
+       taxonomy: "|"
+       analogy: "|"
+       misconception: "|"
+
+   # After (v6 — flat with real content)
+   mental_model: "Skill metadata defines the routing contract, classification, health state, and grounding evidence each SKILL.md carries. The schema validator checks the shape; the lint pass checks the semantics; the manifest generator emits the consumer-readable aggregate."
+   purpose: "Without machine-readable metadata, agents cannot route to the right skill, verify a skill's claims against repo truth, or detect when a skill goes stale. The Protocol replaces the prior model of in-prose-only skills with structured signals every consumer can parse."
+   boundary: "The Protocol is NOT a content authoring style guide (use the skill-scaffold archetype contract for that). It is also NOT a routing algorithm (use skill-graph-route.js for that). The Protocol defines what every skill MUST declare; the algorithm decides which skill activates."
+   analogy: "The Protocol is to skills what package.json is to npm packages: a structured manifest every consumer reads to know what the artifact claims to do, how to verify it, and how to depend on it."
+   misconception: "Authors often think the Protocol is bureaucratic overhead. The reality is the opposite: without the Protocol's structured fields, agents must scan free-form prose to make routing decisions — costing tokens and producing inconsistent results. The Protocol is a compression scheme for relevance."
+   ```
+
+3. (Optional) Remove the nested `concept` block once the flat fields are populated. The schema accepts both during migration; removing `concept` removes a deprecated indirection.
+
+### Conditional edits
+
+| If your skill has... | Then... |
+|---|---|
+| `comprehension_state: present` AND nested `concept` with pipe-empty (`"\|"`) placeholders | Populate the five flat fields with real content. Pipe-empty placeholders fail the comprehension grader. |
+| `comprehension_state: present` AND fully-populated nested `concept` | Optional: migrate to flat fields for v6 alignment. Both shapes validate against the v6 schema during the migration window. |
+| `relations.boundary[]` entries pointing to skills in a *different* `category` or `domain` sub-tree | Move those entries to `anti_examples` (wrong-use phrase, routing-visible) + `relations.related` (semantic adjacency signal). |
+| No comprehension grading declared (`comprehension_state: absent` or omitted) | Bump `schema_version` to 6 and skip the Understanding-fields edit — they're not required without `comprehension_state: present`. |
+
+### Codemod available
+
+```bash
+# 1. 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: "5"/schema_version: "6"/g' {} +
+
+# 2. (Planned) Backfill the flat Understanding fields from the nested concept block
+node scripts/migrate-skill-v5-to-v6.js --backfill --dry-run
+# Review the diff, then:
+node scripts/migrate-skill-v5-to-v6.js --backfill --apply
+
+# 3. Verify lint baseline against the new schema
+cd /Users/jacobbalslev/Development/skill-graph
+SKILL_GRAPH_WORKSPACE=/Users/jacobbalslev/Development/skills node scripts/skill-lint.js
+```
+
+The `--backfill` codemod is the v6 equivalent of the v3→v4 migrate script. It reads the nested `concept` sub-fields and writes them to the flat top-level fields. Where sub-fields are pipe-empty placeholders, the codemod leaves the flat field unpopulated for human authorship (the comprehension grader will then surface the gap on the next eval run).
+
+## Backward compatibility
+
+| Direction | Compatible? | Note |
+|---|---|---|
+| v5 tool reads v6 SKILL.md | ⚠ Partial | v5 schema's `additionalProperties: false` rejects the new flat fields (`mental_model`, `purpose`, `boundary`, `analogy`, `misconception`, `last_audited`, `last_changed`, `audit_verdict`, `eval_score`, `eval_failed_ids`, `lint_verdict`, `drift_status`). Use `normalizeFrontmatter()` from `skill-graph/scripts/lib/parse-frontmatter.js` for forward-compat reads. |
+| v6 tool reads v5 SKILL.md | ✓ via `anyOf` | The v6 schema's `comprehension_state: present` allOf rule accepts either shape (nested `concept` OR flat Understanding fields), so v5 skills with populated `concept` blocks pass v6 validation unchanged. |
+| Mixed v5 / v6 corpus | ✓ During migration | The `anyOf` rule and the deprecated-but-accepted `concept` field allow a corpus to migrate one skill at a time. Author convention: bump `schema_version` to `6` only after the flat Understanding fields are populated. |
+
+**Recommendation:** apply the migration in batches grouped by `comprehension_state` value. Skills with `comprehension_state: absent` (no Understanding fields needed) can be bumped to v6 in a single sweep; skills with `comprehension_state: present` need per-skill authoring of the flat fields and should land in smaller PRs.
+
+## Verification checklist
+
+After running the v5→v6 migration:
+
+- [ ] Every SKILL.md has `schema_version: "6"`
+- [ ] Every skill with `comprehension_state: present` has either the five flat Understanding fields OR the nested `concept` block (verified by v6 schema validation)
+- [ ] Every skill with `comprehension_state: present` and populated flat fields has no pipe-empty (`"|"`) placeholder strings
+- [ ] No `relations.boundary[]` entries point to skills in a different `category` or `domain` sub-tree (cross-domain entries moved to `anti_examples` + `relations.related`)
+- [ ] `node scripts/skill-lint.js` baseline unchanged (no new errors from migration)
+- [ ] `node scripts/generate-manifest.js --output skills.manifest.json` succeeds
+- [ ] Health Block fields are present on at least the skills that have been through one `audit` cycle since the v6 bump (initial state: all `UNKNOWN`; populated by the first audit walk)
+- [ ] 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: "6"/schema_version: "5"/g' {} +
+```
+
+The flat Understanding fields and Health Block fields are not removed by the rollback — they remain in the YAML but are rejected by v5 schema validation (which has `additionalProperties: false`). To fully roll back, either:
+
+1. Use `normalizeFrontmatter()` to strip unknown fields during the rollback sweep, OR
+2. Manually delete the flat Understanding fields and Health Block from each affected skill.
+
+Recommended: do not roll back — instead, identify the failing skills, fix the v6 authoring, and re-verify. The migration is additive; a partial v6 corpus is structurally safe (it just means some skills don't yet have flat Understanding fields populated).
+
+## Related artifacts
+
+- `schemas/skill.v6.schema.json` — JSON schema with flat Understanding fields and Health Block
+- `SKILL_METADATA_PROTOCOL.md` — v6 protocol contract (flat fields, Health Block, boundary doctrine)
+- `docs/skill-metadata-protocol.md` — v6 design rationale and field-count table
+- `Development/docs/plans/skill-audit-loop-simplification.md` — outer plan that motivated the v6 simplification (collapse 13 audit commands to 4 operations, eliminate scattered log files via flat Health Block)
+- `Development/docs/plans/skills-sh-marketshare-strategy.md` § Tier C″ — empirical sweep of 16 cross-domain `boundary[]` entries across 8 Wave 6 skills, confirming the SAME-DOMAIN doctrine
+- `skill-graph/scripts/skill-graph-route.js:548` — runtime source for the score-aware boundary exclusion mechanic

package/docs/name-exceptions.yaml

@@ -0,0 +1,37 @@
+# Skill name exceptions registry.
+#
+# Skills whose names violate the head-noun-glossary rule (no verb prefix,
+# noun-anchored compound) but are kept as-is because the name is an established
+# industry term-of-art. Adding an entry requires a citation field.
+#
+# See docs/head-noun-glossary.md for the rule.
+# See SKILL_METADATA_PROTOCOL.md § name for the schema pattern.
+
+exceptions:
+  - name: code-review
+    reason: "Industry term-of-art since Fagan inspection."
+    citation: "Fagan, M. E. (1976). Design and code inspections to reduce errors in program development. IBM Systems Journal, 15(3), 182–211."
+
+  - name: design-review
+    reason: "Established industry practice across engineering and design orgs."
+    citation: "Cooper, A., Reimann, R., Cronin, D., & Noessel, C. (2014). About Face: The Essentials of Interaction Design (4th ed.), Chapter on design reviews."
+
+  - name: event-storming
+    reason: "Named methodology, not a verb command."
+    citation: "Brandolini, A. (2013, originally posted). Introducing EventStorming. https://www.eventstorming.com"
+
+  - name: graph-audit
+    reason: "Audit is the noun reading (the artifact), not the verb (the activity). This is a graph audit, not the act of auditing a graph."
+    citation: "Skill Graph internal terminology; pairs with skill-census.js output naming."
+
+  - name: skill-scaffold
+    reason: "Scaffold is the artifact/template, not the verb. This skill provides the authoring scaffold."
+    citation: "Skill Graph internal terminology; matches scaffold tooling vocabulary (e.g. Rails scaffold, Nx scaffold)."
+
+  - name: writing-humanizer
+    reason: "Humanizer is the noun reading (the transformation tool); compound `writing-humanizer` is the named artifact."
+    citation: "Industry usage in style-tooling (Grammarly humanizer, OpenAI text humanizer). Skill represents the discipline, not the command."
+
+  - name: cron-scheduling
+    reason: "Scheduling is the discipline noun; compound `cron-scheduling` names the surface."
+    citation: "POSIX cron(8); Vixie cron documentation."

package/docs/plans/marketplace-p1-public-migration-plan.md

@@ -0,0 +1,41 @@
+# Marketplace P1 Public Migration Plan
+
+> Status: execution plan for the 2026-05-14 skills.sh consolidation pass.
+
+## Goal
+
+Move public-safe Development skills that were listed as `public-after-migration` in `docs/marketplace-skill-candidate-list.md` into canonical Skill Metadata Protocol source under `skills/<slug>/SKILL.md`, then export them through the generated marketplace surface.
+
+## Inclusion Rules
+
+- Import only rows that are not already present in canonical `skills/`.
+- Normalize nested names to flat marketplace slugs. `token-cost-estimation/findings` becomes `token-cost-estimation-findings` if and when it is safe to migrate.
+- Reject any row whose full source body contains local agent-profile paths, private project names, personal paths, email addresses, or token-like strings.
+- Keep canonical Skill Graph as the source of truth. Do not publish legacy/plain Development files directly.
+- Preserve body content for imported skills except for replacing legacy frontmatter with schema_version 4 frontmatter.
+- Keep eval claims honest: migrated skills start with `eval_artifacts: planned`, `eval_state: unverified`, and `routing_eval: absent`.
+- Keep only frontmatter relations whose targets exist in the final canonical library.
+
+## Import Set
+
+The clean P1 rows to import in this batch are:
+
+`background-jobs`, `command-palette`, `compression`, `content-monitor`, `cron-scheduling`, `diff-analysis`, `entity-relationship-modeling`, `evaluation`, `governance`, `guardrails`, `keywords`, `merge-queue`, `methodology`, `mobile-responsive-ux`, `ontology`, `prioritization`, `real-time-updates`, `reasoning`, `seo-strategy`, `spec-driven-development`, `summarization`, `vercel-composition-patterns`.
+
+## Rejections For This Batch
+
+Duplicate P1 rows already owned by canonical Skill Graph skills are rejected in favor of the canonical source.
+
+Rows with body-level privacy or local-runtime findings are deferred until rewritten as general public skills. One private-named row is withheld from row-level public documentation: `agent-session-handoff`, `agent-task-delegation`, `autonomous-loop-patterns`, `chat-interface`, `cost-aggregation`, `dispatch-loop`, `ghostty`, `git-worktree`, `harness-engineering`, `hook-patterns`, `methodical`, `orchestration`, `perspective`, `quality-doctrine`, `self-evaluation`, `sequential-thinking`, `session-lifecycle`, `streaming`, `task-lifecycle`, `task-path-optimization`, `task-progression`, `task-sizing`, `threaded-conversations`, `token-cost-estimation-findings`, `token-efficiency`, `tui`, `vibe-kanban`.
+
+## Verification
+
+After import, run the standard gates plus marketplace-specific validation:
+
+- `npm.cmd run verify`
+- `node scripts/verify-skill-md-export.js`
+- `node scripts/check-markdown-links.js`
+- `node scripts/export-marketplace-skills.js --validate-only`
+- privacy scan over generated marketplace export
+- public CLI list count against `jacob-balslev/skills`
+- live skills.sh canonical and owner pages

package/docs/plans/multi-root-workspace.md

@@ -0,0 +1,148 @@
+# Multi-Root Workspace Plan
+
+> **Status.** Shipped in v0.4.0 (schema_version 3). This document is the design reference for the workspace config format and the skill-root resolution rules.
+> **Audience.** Consumers of Skill Graph who maintain more than one project in a single repo, and contributors extending the generator, router, or drift sentinel.
+
+## Problem
+
+Skill Graph v0.3.0 assumed a single `skills/` directory at the repo root. That worked for a single-project workspace. It broke the moment a developer had more than one project:
+
+- **Codebase-scoped skills** (skills with `scope: codebase` and concrete file paths in `grounding.truth_sources`) cannot live in a central `skills/` folder because their truth sources reference files in a specific project. Moving them to the central folder either invalidates the paths or picks one project over another.
+- **Cross-project skills** (GDPR, a11y, react-best-practices) should not be duplicated per project — duplication leads to drift.
+- **Project-specific skills** (e.g. `<project-a>-orders`, `<project-b>-seo` — names tied to one project's domain) should not pollute the shared namespace.
+
+The existing single-root design forced authors to either duplicate skills or invent contract-breaking workarounds.
+
+## Design — hybrid layout with a workspace config
+
+v3 adds an optional workspace config at `.skill-graph/config.json` that declares multiple skill roots. When the config is present, the generator walks every declared root and unions the result into one manifest. Each skill entry carries a `project` field identifying which root it came from.
+
+### Directory layout
+
+```
+workspace/
+  .skill-graph/
+    config.json                  # workspace definition
+  skills/                        # shared / ambient skills (scope: portable | reference)
+    gdpr/SKILL.md
+    a11y/SKILL.md
+    react-best-practices/SKILL.md
+  <project-a>/                   # project 1 (placeholder name — adopters use their own)
+    .skill-graph/skills/
+      <project-a>-orders/SKILL.md
+      <project-a>-billing/SKILL.md
+  <project-b>/                   # project 2
+    .skill-graph/skills/
+      <project-b>-seo/SKILL.md
+      <project-b>-keywords/SKILL.md
+  shared-skills/                 # optional alternative shared root
+      cross-project-onboarding/SKILL.md
+```
+
+Three layout styles this design accommodates:
+
+| Layout | Shape | Best for |
+|---|---|---|
+| **A — single root** | `skills/` at repo root, no config file | One project. Tutorial default. Skill Graph repo itself. |
+| **B — per-project only** | `<project>/.skill-graph/skills/` roots, no shared root | Projects with zero shared skills (rare). |
+| **C — hybrid** | Shared root + per-project roots | Most multi-project workspaces. Default recommendation. |
+
+### Config format
+
+`.skill-graph/config.json`:
+
+```json
+{
+  "workspace": {
+    "skill_roots": [
+      { "path": "skills",                              "project": null },
+      { "path": "<project-a>/.skill-graph/skills",     "project": "<project-a>" },
+      { "path": "<project-b>/.skill-graph/skills",     "project": "<project-b>" }
+    ],
+    "projects": {
+      "<project-a>":  { "semantic_tags": ["ecommerce", "saas", "b2b"] },
+      "<project-b>":  { "semantic_tags": ["ecommerce", "b2c"] }
+    }
+  }
+}
+```
+
+(`<project-a>` and `<project-b>` are placeholder handles — adopters use whatever kebab-case names they choose for their projects.)
+
+**Fields:**
+
+- `workspace.skill_roots` (required): ordered list of skill root directories. Each entry declares:
+  - `path`: repo-relative directory to walk. The generator expects each subdirectory under the path to contain a `SKILL.md`.
+  - `project`: literal project handle stamped onto every skill loaded from this root. `null` means "shared / ambient" — skills loaded without a project owner.
+- `workspace.projects` (optional): map of literal project handle → `{ semantic_tags: string[] }`. The router expands the active project into this semantic set before matching skills' `workspace_tags`.
+
+### Single-root fallback
+
+When `.skill-graph/config.json` is absent, the generator falls back to the default single-root mode: walk `skills/`, stamp no project. This keeps v2-era consumers and the Skill Graph repo itself working unchanged.
+
+## Resolution rules
+
+### Skill discovery
+
+1. Generator loads the workspace config (or falls back to `[{ path: "skills", project: null }]`).
+2. For each root, walks direct children. Each child directory with a `SKILL.md` becomes a skill.
+3. The same skill path cannot be loaded twice — the first root to claim a path wins. Roots are processed in declaration order.
+4. Skill `id` is the directory name; `project` is the root's declared project (or absent if null).
+5. Manifest output adds a top-level `workspace` block echoing the config so downstream consumers don't need to re-read it.
+
+### Router project matching
+
+When a consumer calls `skill-graph route <query> --project <handle>`, the router:
+
+1. Reads `manifest.workspace.projects[<handle>].semantic_tags` to expand the project handle into a set of matchable tags.
+2. For each skill:
+   - If `workspace_tags` is absent → skill is ambient, matches.
+   - If `workspace_tags` contains the literal project handle → matches.
+   - If `workspace_tags` contains any of the project's expanded semantic tags → matches.
+   - Otherwise → excluded with reason `workspace_tags [...] exclude project "<handle>"`.
+
+### Drift sentinel scope
+
+`skill-graph drift` walks the same skill roots as the generator. When run without arguments, it checks every skill in every root. When run with an explicit skill directory, it checks only that skill.
+
+## Scope placement rules
+
+| Skill scope | Preferred root |
+|---|---|
+| `scope: portable` | Shared root (`skills/`). The skill makes no repo-specific claims, so it lives outside any project. |
+| `scope: reference` | Shared root. Documentation-style skill anchored to a contract document. |
+| `scope: codebase` | Project root (`<project>/.skill-graph/skills/`). The skill's `grounding.truth_sources` reference files inside that project. Placing it in the shared root creates paths that resolve relative to the repo root and break when the project moves. |
+
+Lint warns when a skill's placement contradicts its scope (shared root with `scope: codebase`, or project root with `scope: portable`). The warning is advisory — in some unusual cases the placement is correct and the scope declaration is wrong.
+
+## Migration path from single-root
+
+For an existing v2/v3 single-root repo that wants to adopt multi-root:
+
+1. Create `.skill-graph/config.json` with the current `skills/` directory as the first root:
+   ```json
+   {
+     "workspace": {
+       "skill_roots": [{ "path": "skills", "project": null }]
+     }
+   }
+   ```
+2. Run `node scripts/generate-manifest.js` and confirm the manifest is identical to before (plus the new top-level `workspace` block).
+3. Add per-project roots one at a time, moving `scope: codebase` skills into them.
+4. Add `workspace_tags` to skills that should be filtered by project; leave ambient skills untouched.
+5. For large libraries, also add hierarchical `category` values to the moved skills — a tree helps readers find skills in a workspace with dozens of per-project skills.
+
+## Non-goals
+
+- **No cross-workspace linking.** The manifest only unions skills within one repo. Pulling skills from a sibling repo is out of scope (and is SKILL.md' job via export).
+- **No runtime skill-root mounting.** The set of skill roots is read at manifest generation time. A consumer cannot add a root at query time.
+- **No glob-based skill-root declarations.** Each root is a literal directory path. Glob patterns in the config file are a footgun and are not supported.
+
+## Reference
+
+- `scripts/generate-manifest.js` — workspace config loader and multi-root walker.
+- `scripts/skill-graph-route.js` — project-aware filter using semantic-tag expansion.
+- `scripts/skill-graph-drift.js` — walks all workspace roots in default mode.
+- `docs/field-reference.md § workspace_tags` — authored-side semantics.
+- `docs/field-decision-guide.md § 4. How do I tag a skill for multiple projects?` — decision tables.
+- `schemas/manifest.schema.json § workspace` — machine-enforceable config shape in the manifest.

package/docs/plans/scripts-roadmap.md

@@ -0,0 +1,107 @@
+# Scripts Roadmap
+
+This document tracks the script surfaces planned for Skill Graph. The goal is the smallest coherent toolchain that makes Skill Metadata Protocol and audit system executable.
+
+## Status
+
+| Script | State | Notes |
+|---|---|---|
+| `scripts/skill-lint.js` | **Shipping** | Validates frontmatter against the schema, enforces parent-dir-matches-name, verifies relation targets exist, checks eval coherence, archetype sections, routing quality; `--strict` mode promotes warnings to errors |
+| `scripts/generate-manifest.js` | **Shipping** | Walks `skills/**/SKILL.md`, applies the rename map from `docs/manifest-field-mapping.md`, emits deterministic validated manifest; `examples/skills.manifest.sample.json` is generated output, not hand-written |
+| `scripts/export-skill.js` | **Shipping** | SKILL.md export target only; transforms Skill Graph extensions under `metadata:` key. Five fixtures in `examples/exports/`. Other runtimes (cursor, windsurf, copilot, agents-md) were removed from the `portability.targets` enum in 0.3.0 — re-add via a new RFC and the PR that ships the transform |
+| `scripts/check-protocol-consistency.js` | **Shipping** | Cross-artifact consistency — field-set parity, authored-to-generated parity, example truth invariants, versioned schema parity, generated field-reference parity, and JSON-LD context coverage (C1–C8 checks) |
+| `scripts/skill-audit.js` | **Shipping** | Stub mode seeds `audits/<skill>/{findings,verdict,scorecard}.md` from lint output (unchanged). `--graded` mode composes per-dimension prompts via `scripts/lib/audit-prompt-builder.js`, calls an external model CLI for each of the seven scorecard dimensions, and writes evidence-backed verdicts into the artifact files replacing TODO placeholders. A deterministic mock grader ships at `scripts/lib/mock-grader.js` for CI smoke-tests |
+
+## Priority Order
+
+### 1. Manifest generation
+
+Target file:
+
+- `scripts/generate-manifest.js`
+
+Purpose:
+
+- walk `skills/**/SKILL.md`
+- parse frontmatter
+- normalize activation, relations, portability, and health fields
+- output `skills.manifest.json`
+- validate against `schemas/manifest.schema.json`
+
+Minimum output:
+
+- `schema_version`
+- `generated_at`
+- `summary`
+- `skills[]`
+
+A hand-written sample manifest showing the exact output shape ships today at `examples/skills.manifest.sample.json`.
+
+### 2. Skill lint (SHIPPED)
+
+Target file:
+
+- `scripts/skill-lint.js`
+
+Shipping today. Covers:
+
+1. required fields present and well-typed
+2. valid `type` enum
+3. valid `scope` enum
+4. `extends` required for overlays (schema conditional)
+5. `grounding` required for `scope: codebase` (schema conditional)
+6. relation targets (`adjacent`, `boundary`, `verify_with`, `depends_on`) exist as sibling skills
+7. parent directory name matches the authored `name` (SKILL.md compatibility)
+8. `eval_artifacts: present` is backed by a real eval file under `examples/evals/`
+
+Run with `node scripts/skill-lint.js` (see `README.md § Validation`). Exit 0 on success, 1 on any failure.
+
+Planned extensions:
+
+- flag deprecated or legacy contract usage
+- stricter SKILL.md name pattern mode (reject `/` and `:`)
+- integration with `generate-manifest.js` for combined health reporting
+
+### 3. Audit runner (SHIPPED)
+
+Target file:
+
+- `scripts/skill-audit.js`
+
+Purpose:
+
+- audit one skill at a time using `SKILL_AUDIT_CHECKLIST.md`
+- write findings, verdict, and scorecard artifacts
+- optionally run deterministic validation after fixes
+
+Shipping today. Two modes:
+
+1. **Stub mode** (default) — runs `scripts/skill-lint.js` and seeds `audits/<skill>/{findings,verdict,scorecard}.md` with lint-derived findings and human-TODO placeholders for the seven qualitative dimensions.
+2. **`--graded` mode** — on top of the stub, composes per-dimension prompts via `scripts/lib/audit-prompt-builder.js` and calls an external model CLI (`--grader-cli`, default `claude -p`) once per dimension. Each response must return a `<verdict>…</verdict>` JSON block matching the fixed schema (dimension / score / verdict / justification / findings[]). The runner parses, validates, and merges these into the artifact files, replacing TODO placeholders with structured PASS / PASS WITH FIXES / FAIL verdicts with evidence quotes.
+
+Related files:
+
+- `scripts/lib/audit-prompt-builder.js` — dimension registry, context collector, prompt composer, response parser, verdict aggregator
+- `scripts/lib/mock-grader.js` — deterministic canned-response grader for CI smoke-tests and reproducible examples (prints fixed `<verdict>` blocks per dimension)
+
+Grader CLI discipline: the runner NEVER embeds API keys. Auth is delegated to the external CLI on the host (see `.claude/rules/cli-first.md`). `--grader-cli "claude -p"` and `--grader-cli "codex exec"` both work when the respective CLIs are authenticated.
+
+## Suggested Follow-on Scripts
+
+After the first 5 scripts exist (all Shipping as of 2026-04-17), the next useful additions are:
+
+1. `scripts/skill-overlap.js` — detect semantic and scope-range overlap between skills
+2. `scripts/skill-router.js` — simulate routing decisions against a test corpus
+3. `scripts/build-coverage.js` — build-time coverage report (keywords × triggers × archetypes)
+4. Export transforms for `cursor`, `windsurf`, `copilot`, or `agents-md` targets — removed from scope in 0.3.0. Re-add via RFC + the PR that ships the transform.
+
+## Non-Goals For The First Cut
+
+Do not build these first:
+
+- telemetry dashboards
+- model-specific grading infrastructure
+- marketplace packaging layers
+- runtime execution or skill hosting
+
+These are useful later. They are not required for a credible starter toolchain around Skill Metadata Protocol.