@skill-graph/cli 0.5.6

package/examples/projects/markdown-static-site/skills/link-rot-detection/SKILL.md

@@ -0,0 +1,103 @@
+---
+# yaml-language-server: $schema=https://skillgraph.dev/schemas/skill.v4.schema.json
+schema_version: 4
+name: link-rot-detection
+description: "Use when authoring or reviewing a periodic-scan job that walks every external link in a markdown content set and flags 404s, redirects to unrelated content, and connection failures. Activate this skill whenever the task says 'check our links' or mentions a link-rot scan, broken-link audit, or link-health report. Do NOT use for live runtime link checking inside the rendered page (use a frontend a11y / UX skill) or for chasing a specific broken-link incident from a user report (use debugging)."
+version: 0.1.0
+type: capability
+category: content
+domain: content/maintenance
+scope: portable
+owner: markdown-static-site-maintainer
+freshness: "2026-05-06"
+drift_check:
+  last_verified: "2026-05-06"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: MIT
+compatibility:
+  runtimes:
+    - node
+  node: ">=20"
+  notes: "Portable across any markdown-content project; no codebase grounding required."
+allowed-tools: Read Grep Bash
+keywords:
+  - link rot
+  - link-rot detection
+  - broken link audit
+  - link health
+  - dead link scan
+  - 404 audit
+  - external link check
+  - periodic scan
+  - markdown link extraction
+  - link-rot report
+triggers:
+  - link-rot-detection
+examples:
+  - "design a periodic link-rot scan that runs nightly and posts a report"
+  - "review the link-rot detector — does it handle redirects correctly?"
+  - "explain how to test the link-rot scanner against a fixture set without hitting the network"
+  - "should the scan retry on transient 5xx, or only flag persistent failures?"
+anti_examples:
+  - "validate this internal route in the live app"
+  - "the link to example.com just broke for one user"
+  - "design the rendering of broken-link badges in the UI"
+relations:
+  boundary:
+    - skill: documentation
+      reason: "documentation writes prose about link-health policy; this skill enforces the detection primitive in code"
+    - skill: debugging
+      reason: "debugging chases a specific reported broken link; this skill is the periodic audit applied before user reports"
+    - skill: refactor
+      reason: "refactor changes scanner code shape; this skill enforces the detection contract that any refactor must preserve"
+  verify_with:
+    - testing-strategy
+portability:
+  readiness: scripted
+  targets:
+    - skill-md
+workspace_tags:
+  - content
+  - markdown
+lifecycle:
+  stale_after_days: 180
+  review_cadence: quarterly
+---
+
+# Link-Rot Detection
+
+## Coverage
+
+- Markdown link extraction — pulling every `[text](url)` and `[text][ref]` reference link out of every `.md` and `.mdx` file in the content tree
+- External vs internal classification — what counts as external (different host) and what gets skipped (relative path, anchor link, mailto, tel)
+- Status-code interpretation — 200 is healthy, 301/308 is a redirect (record the new URL but don't fail), 302/307 is transient (re-check next run), 404/410 is dead (flag), 5xx is transient (retry with backoff before flagging)
+- Soft-404 detection — pages that return HTTP 200 but render an "unknown page" interstitial (compare body length / content against known soft-404 patterns)
+- Rate-limiting and politeness — concurrent request budget per origin host, honoring `robots.txt` crawl-delay, exponential backoff on 429
+- Reporting shape — the scanner's output is a structured report (JSON + markdown summary), not a live alert; the report is the audit artifact
+
+## Philosophy
+
+External links rot. Every site that's older than two years has at least a few. The choice is between knowing about them on a schedule or finding out from a user. A periodic scan with a published report turns link health into a maintenance task instead of an emergency. The discipline is to be conservative — distinguish persistent failures (404 across 3 runs) from transient ones (one 503 on a Tuesday) — and to never let the scanner itself become a denial-of-service vector against the targets it's checking.
+
+## Verification
+
+Before merging any change to the link-rot scanner or its config:
+
+- [ ] The scanner extracts every link in `[text](url)` and `[text][ref]` form from `.md` and `.mdx` files; reference links resolve their targets before classification
+- [ ] Internal links (relative paths, same-host absolute, anchors, mailto, tel) are explicitly excluded — confirmed by a fixture test with mixed link types
+- [ ] Persistent failures are distinguished from transient ones — a link is only flagged after N consecutive failures across separate runs (default N=3)
+- [ ] The scanner respects per-host concurrency limits and honors `robots.txt` crawl-delay; a single host getting many requests in tight sequence is a bug
+- [ ] Soft-404 detection has a defined pattern set and an explicit "unknown" bucket for cases that don't match any known soft-404
+- [ ] The scanner produces both a JSON report (machine-readable) and a markdown summary (human-readable) with link, status code, last-seen-OK timestamp, and recommendation
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| (a frontend a11y / UX skill) | The task is rendering a "this link may be broken" badge in the live UI |
+| `debugging` | A specific link broke for a specific user and you need to reproduce |
+| `documentation` | The task is writing the link-health policy doc, not the scanner |
+| `refactor` | The task is restructuring the scanner without changing the detection contract |

package/examples/projects/markdown-static-site/skills/markdown-post-frontmatter-validation/SKILL.md

@@ -0,0 +1,133 @@
+---
+# yaml-language-server: $schema=https://skillgraph.dev/schemas/skill.v4.schema.json
+schema_version: 4
+name: markdown-post-frontmatter-validation
+description: "Use when authoring or reviewing the frontmatter of a markdown post — checking required fields (title, date, slug, tags), validating against the content schema in `lib/content/schema.ts`, catching ambiguous date formats or tags not in the controlled vocabulary, and ensuring the slug matches the file path. Activate this skill whenever the task touches files under `content/posts/**/*.md`, the `parsePostFrontmatter()` helper, or any code path that reads YAML frontmatter from a content file. Do NOT use for general YAML schema design (use a generic schema-design skill) or for chasing a specific build-time validation failure (use debugging)."
+version: 0.1.0
+type: capability
+category: content
+domain: content/markdown/frontmatter
+scope: codebase
+owner: markdown-static-site-maintainer
+freshness: "2026-05-06"
+drift_check:
+  last_verified: "2026-05-06"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: MIT
+compatibility:
+  runtimes:
+    - node
+  node: ">=20"
+  notes: "Astro / Next / Eleventy / Hugo all read YAML frontmatter; the validation pattern is portable across them."
+allowed-tools: Read Grep
+keywords:
+  - markdown frontmatter
+  - post frontmatter
+  - frontmatter validation
+  - content schema
+  - parsePostFrontmatter
+  - YAML frontmatter
+  - title required
+  - tag vocabulary
+  - slug mismatch
+  - date format
+  - controlled vocabulary
+  - markdown post metadata
+triggers:
+  - markdown-post-frontmatter-validation
+paths:
+  - "content/posts/**/*.md"
+  - "lib/content/schema.ts"
+  - "lib/content/parse-frontmatter.ts"
+  - "!**/*.test.md"
+examples:
+  - "validate the frontmatter of a new post against our content schema"
+  - "why does the build fail when I add a tag like `Politics` (capital P)?"
+  - "review this post's frontmatter — is the date format correct?"
+  - "explain how the slug is derived from the file path"
+anti_examples:
+  - "design a YAML schema for a different domain"
+  - "the build is failing — what's the actual error?"
+  - "rewrite parsePostFrontmatter for performance"
+relations:
+  boundary:
+    - skill: documentation
+      reason: "documentation writes prose explaining the frontmatter format; this skill enforces the validation contract in code"
+    - skill: debugging
+      reason: "debugging chases a specific build-time validation failure from logs; this skill is the authoring discipline applied before failure"
+    - skill: refactor
+      reason: "refactor changes code shape; this skill enforces a specific validation contract that must survive any refactor"
+  verify_with:
+    - testing-strategy
+grounding:
+  domain_object: "Markdown post frontmatter — the YAML block at the top of every content file that drives the site's index, routing, and rendering"
+  grounding_mode: repo_specific
+  truth_sources:
+    - content/posts/_template.md
+    - lib/content/schema.ts
+    - lib/content/parse-frontmatter.ts
+  failure_modes:
+    - missing_required_title_field
+    - ambiguous_date_format_no_timezone
+    - tag_not_in_controlled_vocabulary
+    - slug_mismatch_with_file_path
+    - frontmatter_block_not_terminated
+  evidence_priority: repo_code_first
+portability:
+  readiness: scripted
+  targets:
+    - skill-md
+workspace_tags:
+  - content
+  - static-site
+  - markdown
+lifecycle:
+  stale_after_days: 90
+  review_cadence: quarterly
+---
+
+# Markdown Post Frontmatter Validation
+
+## Coverage
+
+- Required-field enforcement — every post must declare `title`, `date`, `slug`, and `tags`; missing fields fail the build at parse time
+- Date format discipline — ISO 8601 with explicit timezone (`2026-05-06T12:00:00Z`); ambiguous formats like `2026-05-06` or `5/6/26` are rejected
+- Slug-to-path consistency — the `slug` field must match the post's directory name; out-of-sync slugs cause silent route conflicts
+- Controlled-vocabulary tagging — every tag in the post's `tags` array must appear in `lib/content/tag-vocabulary.ts`; lowercase, hyphen-separated, no synonyms
+- Schema evolution — when `lib/content/schema.ts` changes, every post's frontmatter is re-validated; existing posts that violate the new schema are flagged before the next build runs
+- Reserved-field protection — fields like `_id`, `_internal`, or any underscore-prefixed key are reserved for the build pipeline and rejected in author-facing frontmatter
+
+## Philosophy
+
+The frontmatter block is the contract every post makes with the site's index, the router, and the renderer. If that contract is loose — if posts can omit fields, use ambiguous dates, or invent ad-hoc tags — the index drifts, routes silently overlap, and the search surface degrades. The cost of catching frontmatter bugs at build time is one re-run; the cost of catching them in production is a broken page or a missing entry in the archive. The rule is: validate at parse time, fail loud, and keep the schema small enough that authors can hold it in their head.
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `content/posts/_template.md` | The canonical template every new post copies — its frontmatter is the worked example of every required field |
+| `lib/content/schema.ts` | The TypeScript schema (Zod or equivalent) that runtime validation calls |
+| `lib/content/parse-frontmatter.ts` | The thin wrapper that reads the YAML block and runs `schema.parse()` — the failure surface for build-time errors |
+
+## Verification
+
+Before merging any change to a post's frontmatter or to the schema:
+
+- [ ] Every post has the four required fields: `title`, `date`, `slug`, `tags`
+- [ ] `date` is ISO 8601 with timezone (no naked `YYYY-MM-DD`, no locale-formatted dates)
+- [ ] `slug` matches the post's directory name exactly — not derived from `title` at runtime
+- [ ] Every tag in `tags` is present in `lib/content/tag-vocabulary.ts` (run `npm run check:tags` to confirm)
+- [ ] No underscore-prefixed fields (`_id`, `_internal`, etc.) — those are reserved for the pipeline
+- [ ] Schema changes (`lib/content/schema.ts`) are paired with a `npm run validate:posts` pass against the entire `content/posts/**/*.md` set
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| (a generic schema-design skill) | The task is designing a new YAML schema for an unrelated domain |
+| `debugging` | A specific build is failing and you need to reproduce the validation error from logs |
+| `documentation` | The task is writing a runbook or contributor doc about the frontmatter format |
+| `refactor` | The task is restructuring `parse-frontmatter.ts` without changing the validation contract |

package/examples/projects/markdown-static-site/skills/migrate-posts-to-v2-frontmatter/SKILL.md

@@ -0,0 +1,140 @@
+---
+# yaml-language-server: $schema=https://skillgraph.dev/schemas/skill.v4.schema.json
+schema_version: 4
+name: migrate-posts-to-v2-frontmatter
+description: "Use when migrating every existing post in `content/posts/**/*.md` to the v2 frontmatter schema — adding the new required `summary` field, normalizing `tags` to the controlled vocabulary, converting bare-date `date` strings to ISO 8601 with timezone, and re-validating every post against the v2 schema before the next build runs. Activate this skill whenever the task references migration `0007-frontmatter-v2`, the v2 frontmatter rollout, or asks how to safely change a required-field set across a populated content tree without breaking the build. Do NOT use for unrelated migrations (use a generic content-migration skill or write a fresh one) or for general schema-design questions (use a schema-design skill)."
+version: 0.1.0
+type: workflow
+category: content
+domain: content/migrations
+scope: codebase
+owner: markdown-static-site-maintainer
+freshness: "2026-05-06"
+drift_check:
+  last_verified: "2026-05-06"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: MIT
+compatibility:
+  runtimes:
+    - node
+  node: ">=20"
+  notes: "Markdown content tree under content/posts/; assumes Zod or similar runtime validator."
+allowed-tools: Read Grep Bash
+keywords:
+  - migrate posts
+  - frontmatter v2 migration
+  - 0007 frontmatter v2
+  - content schema migration
+  - tag vocabulary normalization
+  - bare-date conversion
+  - safe content migration
+  - post backfill
+  - frontmatter migration
+triggers:
+  - migrate-posts-to-v2-frontmatter
+paths:
+  - "scripts/migrate-frontmatter-v2.ts"
+  - "lib/content/schema.ts"
+  - "lib/content/tag-vocabulary.ts"
+examples:
+  - "run the v2 frontmatter migration on every post in `content/posts/`"
+  - "the v2 migration's tag-normalization step is rejecting some valid tags — what's safe to do?"
+  - "verify that every post passes the v2 schema before flipping the validator"
+  - "design migration 0008 to drop the legacy `excerpt` field now that `summary` is canonical"
+anti_examples:
+  - "design a new frontmatter schema for a different domain"
+  - "the migration is failing in CI — what's wrong?"
+  - "write the v2 frontmatter doc for new contributors"
+relations:
+  boundary:
+    - skill: documentation
+      reason: "documentation writes prose explaining the schema migration; this workflow is the procedural enforcement"
+    - skill: debugging
+      reason: "debugging chases a specific migration failure from logs; this workflow is the pre-failure procedure"
+    - skill: refactor
+      reason: "refactor changes code shape with no behavior change; a content-schema migration changes the validation contract — different problem, different gates"
+  verify_with:
+    - testing-strategy
+  depends_on:
+    - skill: testing-strategy
+      min_version: "^1.0.0"
+grounding:
+  domain_object: "The 0007 frontmatter-v2 migration — a multi-step procedure that adds a required field, normalizes the tag vocabulary, converts bare-date strings to ISO 8601, and re-validates every post against the v2 schema before the validator is flipped"
+  grounding_mode: repo_specific
+  truth_sources:
+    - scripts/migrate-frontmatter-v2.ts
+    - lib/content/schema.ts
+    - lib/content/tag-vocabulary.ts
+  failure_modes:
+    - validator_flipped_before_backfill_complete
+    - tag_normalization_drops_a_valid_tag_silently
+    - bare_date_conversion_picks_wrong_timezone
+    - migration_runs_outside_dry_run_gate_first
+    - rollback_step_overwrites_authored_summary_field
+  evidence_priority: repo_code_first
+portability:
+  readiness: scripted
+  targets:
+    - skill-md
+workspace_tags:
+  - content
+  - static-site
+  - migrations
+lifecycle:
+  stale_after_days: 30
+  review_cadence: quarterly
+---
+
+# Migrate Posts to v2 Frontmatter
+
+## Coverage
+
+- The four-phase pattern for adding a required field to a populated content tree — *add as nullable → backfill from existing data → verify → flip the validator to require it* — and why collapsing any two phases into one is unsafe
+- The backfill query — generating a `summary` from each post's first paragraph, with a per-post manual-override fallback for cases where the auto-summary is wrong
+- The verification gate between backfill and validator-flip — running `validate-posts.ts` against the entire `content/posts/**/*.md` tree must return zero errors before the schema is updated
+- The tag-normalization step — mapping every tag to its canonical form in `tag-vocabulary.ts`, with a deny-list for tags that should be removed entirely (e.g., legacy synonyms now folded into a canonical tag)
+- The dry-run gate — the migration script always runs in dry-run by default, printing the diff per post; the `--apply` flag is opt-in and never the CI default
+- The rollback path — what `ROLLBACK.md` for this migration looks like and why "regenerate every summary" is wrong (overwrites authored summaries); the correct rollback restores the per-post `.bak` file the migration writes alongside each edit
+
+## Philosophy
+
+A content-schema migration is a rare migration where being careful is cheaper than being clever. The temptation to combine the four phases into one "atomic" pass fails because the backfill produces some surprising auto-summaries, the human reviewer needs time to override them, and flipping the validator before the human pass is done means every build between then and the override fails. The four-phase pattern is verbose but unambiguous: each phase has a clear success criterion, each phase is re-runnable, and the rollback at any phase is well-defined. Pay the verbosity cost; the alternative is a build outage on a non-emergency migration.
+
+## Workflow
+
+Each step has a clear precondition and a clear success criterion. Do not skip steps; the steps exist because skipping them is how content migrations corrupt authored data.
+
+| Step | Precondition | Action | Success criterion |
+|---|---|---|---|
+| 1. Add nullable `summary` | The schema has no `summary` field | `lib/content/schema.ts`: add `summary: z.string().optional()` (no `required`). Deploy. | The schema accepts posts both with and without `summary`; the build does not fail on existing posts. |
+| 2. Backfill | Step 1 deployed | Run `scripts/migrate-frontmatter-v2.ts --apply --field summary` which generates a draft summary per post from the first paragraph and writes a `.bak` for each modified file. | Verification query reports 0 posts where `summary` is null or empty. |
+| 3. Human review of auto-summaries | Step 2 success | Each post author reviews their auto-summary. Override by editing the post's frontmatter manually; the migration script will not re-run on a post whose `summary` was edited after step 2's `.bak` was written. | Author sign-off recorded in `audits/0007-frontmatter-v2/sign-off.md`. |
+| 4. Flip the validator | Step 3 sign-off committed | `lib/content/schema.ts`: change `summary: z.string().optional()` to `summary: z.string().min(40)` (required, with a minimum length). Deploy. | Builds fail on any post that doesn't pass the v2 schema; the failure surface is the build log, not user-facing pages. |
+
+### When to back out
+
+- Step 2 backfill produces too many surprising auto-summaries → reduce the auto-summary rule (e.g., first-sentence-only); the migration is still safe to resume from the same `.bak` set.
+- Step 3 reveals that some posts genuinely have no extractable summary → those posts need authored summaries before step 4; do NOT flip the validator with placeholder summaries in place.
+- Step 4 is flipped and the build fails on a post whose summary was edited but didn't trip the `min(40)` floor → revert step 4 (`.optional()` again), have the author rewrite the summary, re-flip.
+
+## Verification
+
+- [ ] Step 1 added the field as `.optional()`, not as required
+- [ ] Step 2 was run with `--apply` only after a `--dry-run` was reviewed (the dry-run output is committed under `audits/0007-frontmatter-v2/dry-run.md`)
+- [ ] Step 2's `.bak` files exist for every modified post and are committed (so rollback is a one-command restore)
+- [ ] Step 3 sign-off is recorded for every post in `content/posts/**/*.md` — no post moved past step 3 without explicit author confirmation
+- [ ] Step 4 was applied AFTER step 3 sign-off — never before, even if the author backlog is taking longer than expected
+- [ ] The rollback path in `ROLLBACK.md` does NOT include "regenerate every summary" — that overwrites authored content. Rollback is `mv <post>.md.bak <post>.md` per file, with the `.bak`s already committed.
+- [ ] An end-to-end CI test runs the migration in dry-run mode against the live `content/posts/` set and reports the diff in the PR description before any human merges step 4
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `markdown-post-frontmatter-validation` | The task is reviewing or authoring a single post's frontmatter, not the migration that adds a new required field |
+| `debugging` | A specific migration step is failing in CI and you need to reproduce |
+| `documentation` | The task is writing a runbook or contributor doc about the migration |
+| (a generic migration skill) | The task is a different content migration with no relation to the v2 frontmatter rollout |

package/examples/projects/saas-stripe-postgres/README.md

@@ -0,0 +1,208 @@
+# saas-stripe-postgres — Skill Graph Example Project
+
+This directory is an OSS specimen demonstrating Skill Graph on a realistic SaaS stack: Next.js App Router + Stripe webhooks + Postgres with row-level security. It is a documentation artifact, not a maintained starter kit.
+
+**Purpose:** Show developers how to author, relate, and route skills for a payment-integrated, multi-tenant SaaS — so they can build their own skill library using the same patterns.
+
+---
+
+## Skill Graph Structure
+
+Five specimen skills, each representing a distinct layer of the stack:
+
+```
+stripe-webhook-signature-verification
+  │  depends_on  ──────────────────────────────────────┐
+  │  boundary with nextjs-server-action-validation     │
+  │  verify_with nextjs-server-action-validation       │
+  ▼                                                     ▼
+payment-provider-router              postgres-rls-pattern
+  │  depends_on                          │  verify_with
+  │  stripe-webhook-signature-verification│  migrate-orders-to-canonical-schema
+  ▼                                     ▼
+nextjs-server-action-validation  migrate-orders-to-canonical-schema
+  │  depends_on postgres-rls-pattern      │  depends_on postgres-rls-pattern
+  │  boundary stripe-webhook-...          │  boundary payment-provider-router
+```
+
+| Skill | Type | Scope | Domain |
+|---|---|---|---|
+| `stripe-webhook-signature-verification` | capability | portable | engineering/payments |
+| `postgres-rls-pattern` | capability | portable | engineering/database |
+| `nextjs-server-action-validation` | capability | portable | engineering/web |
+| `payment-provider-router` | router | portable | engineering/payments |
+| `migrate-orders-to-canonical-schema` | workflow | codebase | engineering/database |
+
+---
+
+## Routing Trace
+
+**Query:** "How do I safely handle a Stripe webhook in a Next.js API route?"
+
+This is the kind of question that activates multiple skills in sequence. Here is the routing trace showing which skills fire and why:
+
+```
+Input: "How do I safely handle a Stripe webhook in a Next.js API route?"
+
+Step 1 — Router resolves candidates:
+  MATCH  stripe-webhook-signature-verification
+         trigger: "stripe-webhook-signature-verification"
+         keywords: ["stripe webhook signature verification",
+                    "webhook hmac verification",
+                    "stripe constructEvent"]
+         score: HIGH
+
+  MATCH  payment-provider-router
+         keywords: ["payment event routing", "stripe event type dispatch"]
+         score: MEDIUM
+
+  NO MATCH  nextjs-server-action-validation
+            anti_examples: ["validate the stripe-signature header in a
+                             webhook route handler"]
+            → excluded by anti_example match
+
+  NO MATCH  postgres-rls-pattern
+            → no keyword/trigger overlap with webhook routing
+
+Step 2 — Relation graph consulted:
+  stripe-webhook-signature-verification.depends_on → postgres-rls-pattern
+  (idempotency key INSERT runs inside orgQuery)
+  → postgres-rls-pattern co-activated at lower priority
+
+  stripe-webhook-signature-verification.boundary → payment-provider-router
+  (verification is a precondition for routing)
+  → payment-provider-router activated as step 2
+
+Step 3 — Activation order:
+  1. stripe-webhook-signature-verification  ← verify authenticity
+  2. payment-provider-router                ← route to handler
+  3. postgres-rls-pattern                   ← query layer (co-activated)
+
+Output: Three skills activated in dependency order.
+```
+
+**Paste-able verification** (run from `examples/projects/saas-stripe-postgres/`):
+
+```bash
+# Verify the 5 skills pass schema validation (run from skill-graph repo root)
+cd ~/Development/skill-graph
+node scripts/skill-lint.js \
+  examples/projects/saas-stripe-postgres/skills/stripe-webhook-signature-verification/SKILL.md \
+  examples/projects/saas-stripe-postgres/skills/postgres-rls-pattern/SKILL.md \
+  examples/projects/saas-stripe-postgres/skills/nextjs-server-action-validation/SKILL.md \
+  examples/projects/saas-stripe-postgres/skills/payment-provider-router/SKILL.md \
+  examples/projects/saas-stripe-postgres/skills/migrate-orders-to-canonical-schema/SKILL.md
+```
+
+Expected output (all 5 pass T5):
+```
+OK   [T5]  stripe-webhook-signature-verification/SKILL.md
+OK   [T5]  postgres-rls-pattern/SKILL.md
+OK   [T5]  nextjs-server-action-validation/SKILL.md
+OK   [T5]  payment-provider-router/SKILL.md
+OK   [T5]  migrate-orders-to-canonical-schema/SKILL.md
+5 file(s) checked, 0 error(s)
+```
+
+---
+
+## What Each Skill Demonstrates
+
+### `stripe-webhook-signature-verification` — Skill Graph Contract: Pushy Description + Negative Boundary
+
+The description reads as a command: "Use when validating incoming Stripe webhook requests... Do NOT use for general HTTP signature validation (use a generic crypto-signature skill)."
+
+This is the Skill Graph pattern for descriptions: pushy trigger phrase + explicit negative boundary. Claude tends to under-trigger skills with polite descriptions ("This skill provides..."). Command-form descriptions force the router to match.
+
+### `postgres-rls-pattern` — Skill Graph Contract: Portability
+
+`scope: portable` + `portability.readiness: portable` declares this skill is codebase-agnostic. The orgQuery wrapper pattern works on any Postgres + Node.js project without modification.
+
+### `nextjs-server-action-validation` — Skill Graph Contract: Anti-Examples
+
+The `anti_examples` field prevents false positives:
+```yaml
+anti_examples:
+  - "validate the stripe-signature header in a webhook route handler"
+```
+Without this, the router might activate this skill for a webhook validation query — both are about "validation". The anti_example explicitly signals: if the user is asking about `stripe-signature`, route to `stripe-webhook-signature-verification` instead.
+
+### `payment-provider-router` — Skill Graph Contract: Router Archetype + Depends-On
+
+`type: router` activates the router archetype section map: `## Coverage`, `## Routing Rules`, `## Do NOT Use When` (no Philosophy section). The `depends_on` relation declares that `stripe-webhook-signature-verification` must run before this router sees the event.
+
+### `migrate-orders-to-canonical-schema` — Skill Graph Contract: Grounding
+
+`scope: codebase` + `grounding.truth_sources` anchors this skill to actual files in the example project (`db/migrations/0004_canonicalize_orders.sql`, `db/schema.sql`). When those files change, the drift sentinel flags the skill as potentially stale. This is how Skill Graph prevents skills from becoming documentation that drifts from the code.
+
+---
+
+## Drift-Check Baseline
+
+The drift sentinel records a content hash for `truth_sources` files. When either file changes, the skill's `drift_check.last_verified` becomes stale.
+
+To record the current baseline (run from skill-graph repo root):
+
+```bash
+node scripts/skill-graph-drift.js \
+  --record \
+  --apply \
+  examples/projects/saas-stripe-postgres/skills/migrate-orders-to-canonical-schema
+```
+
+The command reads the `truth_sources` paths from the skill frontmatter, hashes the file contents, and writes the hashes to `drift_check.truth_source_hashes`. Future runs of `npm run drift` compare the live hashes against the recorded baseline and report STALE when they diverge.
+
+After recording, the skill frontmatter gains a `truth_source_hashes` block:
+
+```yaml
+drift_check:
+  last_verified: "2026-05-18"
+  truth_source_hashes:
+    examples/projects/saas-stripe-postgres/db/migrations/0004_canonicalize_orders.sql: "sha256:<hash>"
+    examples/projects/saas-stripe-postgres/db/schema.sql: "sha256:<hash>"
+```
+
+---
+
+## Skills Referenced vs. Skills in This Project
+
+The 5 skills cross-reference each other via `relations`. They also reference skills from the main Skill Graph library (e.g., `documentation`, `refactor`) via the `boundary` predicate — those skills must exist in the configured skill root (`../skills/skills/`) for the lint check to pass.
+
+**Skills referenced from the library root** (must exist in `../skills/skills/`):
+
+| Referenced by | Skill referenced | Via predicate |
+|---|---|---|
+| (all skills) | Standard library skills | (none in this example — intra-project only) |
+
+These 5 specimens only cross-reference each other. They are self-contained within the example project.
+
+---
+
+## File Structure
+
+```
+examples/projects/saas-stripe-postgres/
+├── README.md                        ← this file
+├── db/
+│   ├── schema.sql                   ← canonical table + RLS policy definitions
+│   └── migrations/
+│       └── 0004_canonicalize_orders.sql  ← Phase 1+2 of orders canonicalization
+└── skills/
+    ├── stripe-webhook-signature-verification/SKILL.md
+    ├── postgres-rls-pattern/SKILL.md
+    ├── nextjs-server-action-validation/SKILL.md
+    ├── payment-provider-router/SKILL.md
+    └── migrate-orders-to-canonical-schema/SKILL.md
+```
+
+---
+
+## Why These 5 Skills?
+
+These specimens were chosen by the IMPROVEMENT_PLAN 2026-05-06 board meeting (U19 edit) to demonstrate Skill Graph's contract on a realistic stack:
+
+- **Stripe webhook + RLS + Server Action** covers the three most common "how do I do this securely?" questions in a SaaS codebase
+- **Payment router** demonstrates the `type: router` archetype, distinct from `capability` and `workflow`
+- **Migration** demonstrates `scope: codebase` grounding and the four-phase procedure pattern — the hardest migration category to get right
+
+Each skill is a specimen for learning, not a production recommendation. The patterns are generic; adopt them and adapt them to your own codebase.

package/examples/projects/saas-stripe-postgres/db/migrations/0004_canonicalize_orders.sql

@@ -0,0 +1,37 @@
+-- Migration 0004: Canonicalize orders table
+-- Changes: Stripe-specific column names → provider-agnostic names
+--   stripe_session_id   → provider_order_id
+--   stripe_customer_id  → provider_customer_id
+--   (new) provider column set to 'stripe' for all existing rows
+--
+-- SAFE MIGRATION — four-phase procedure:
+--   Phase 1: Add nullable columns (this file, deploy first)
+--   Phase 2: Backfill data (this file, run after Phase 1 deploys)
+--   Phase 3: Update application code to read new columns (manual, 24h observation)
+--   Phase 4: Drop legacy columns (separate migration file 0004b)
+--
+-- Do NOT run Phase 4 (0004b) until 0 reads of stripe_session_id appear in logs
+-- for at least 24 hours after Phase 3 application deployment.
+
+-- ─── Phase 1: Add nullable canonical columns ─────────────────────────────────
+ALTER TABLE orders
+  ADD COLUMN IF NOT EXISTS provider TEXT,
+  ADD COLUMN IF NOT EXISTS provider_order_id TEXT,
+  ADD COLUMN IF NOT EXISTS provider_customer_id TEXT;
+
+-- ─── Phase 2: Backfill from Stripe-specific columns ──────────────────────────
+-- Run: psql $DATABASE_URL -f 0004_canonicalize_orders.sql
+-- Or: node scripts/migrate-orders.ts --apply (dry-run by default)
+
+UPDATE orders
+SET
+  provider = 'stripe',
+  provider_order_id = stripe_session_id,
+  provider_customer_id = stripe_customer_id
+WHERE provider IS NULL;
+
+-- Verify: SELECT COUNT(*) FROM orders WHERE provider IS NULL;
+-- Expected: 0 rows
+
+-- ─── Phase 4 is in 0004b_drop_legacy_columns.sql ────────────────────────────
+-- Only run 0004b after Phase 3 observation period (24h, zero old-column reads).