@skill-graph/cli 0.5.6

package/examples/evals/testing-strategy.json

@@ -0,0 +1,118 @@
+{
+  "skill_name": "testing-strategy",
+  "subject": "Verification planning for bug fixes, features, and refactors: test scope, test-level selection, effort-to-risk matching, regression targeting, evidence quality, and failure-case coverage",
+  "adjacent_concepts": ["debugging", "refactor", "lint-overlay"],
+  "grounding_note": "This skill is self-grounding. Its evals validate internal consistency against the SKILL.md body — the skill does not anchor to an external canonical source (e.g., a specific testing-pyramid paper) because the doctrine here is synthesized from industry practice rather than derived from one authoritative text. Evals cite SKILL.md line ranges deliberately; add external truth_sources only if the skill is later narrowed to a specific external framework. Line-range stability is enforced by the `checkEvalTruthSourceRanges` lint check (scripts/skill-lint.js D2) — every edit that moves a cited range out of file bounds fails lint before commit, so drift surfaces immediately rather than silently degrading grader grounding.",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "An engineer is adding a new feature that involves a pure function with no I/O composed inside a service that calls a payment processor over the network. According to the testing-strategy skill's Test-Level Selection table, which test level applies to which piece and why?",
+      "dimension": "definition",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "code_verification",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": ["skills/testing-strategy/SKILL.md:84-91"]
+    },
+    {
+      "id": 2,
+      "prompt": "The skill's Philosophy says \"a test that never fails is noise.\" Explain the mental model behind that claim — why does the skill treat a non-failing test as a cost rather than a free safety net, and what does it imply about coverage-percentage targets?",
+      "dimension": "mental_model",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": ["skills/testing-strategy/SKILL.md:76-78"]
+    },
+    {
+      "id": 3,
+      "prompt": "A bug has already landed in production. An engineer wants to use the testing-strategy skill to chase it. Should they? Cite the negative-routing rule that decides this and name the skill that applies to an already-failing behavior.",
+      "dimension": "boundary",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "code_verification",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": ["skills/testing-strategy/SKILL.md:111-116"]
+    },
+    {
+      "id": 4,
+      "prompt": "A team writes a unit test for a function by mocking its only external collaborator. The test passes. According to the testing-strategy's level-selection anti-patterns, what is wrong with this approach and what is the correct fix?",
+      "dimension": "application",
+      "substance": "domain",
+      "calibration": "process",
+      "truth_mode": "process_correctness",
+      "skill_type": "workflow",
+      "criticality": "high",
+      "truth_sources": ["skills/testing-strategy/SKILL.md:93-98"]
+    },
+    {
+      "id": 5,
+      "prompt": "A bug slipped past unit tests and reached production. The team asks where to put the regression test. According to the testing-strategy skill's Test-Level Selection table, what is the answer and why is adding a new unit test at the same level a poor choice?",
+      "dimension": "purpose",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "critical",
+      "truth_sources": ["skills/testing-strategy/SKILL.md:84-91"]
+    },
+    {
+      "id": 6,
+      "prompt": "A contributor argues that adding a test is always net-positive because more coverage can never be bad. According to the testing-strategy skill, is that correct? Cite the row in the Test-Level Selection table that contradicts this and explain the cost that the argument ignores.",
+      "dimension": "application",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "critical",
+      "truth_sources": ["skills/testing-strategy/SKILL.md:84-91", "skills/testing-strategy/SKILL.md:93-98"]
+    },
+    {
+      "id": 7,
+      "prompt": "A team asks the testing-strategy skill to review whether their architecture diagram correctly describes the service boundaries — there is no pending change, no failure, and no verification target. Should the skill accept? Cite the negative-routing rule.",
+      "dimension": "boundary",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "code_verification",
+      "skill_type": "concept",
+      "criticality": "normal",
+      "truth_sources": ["skills/testing-strategy/SKILL.md:111-116"]
+    },
+    {
+      "id": 8,
+      "prompt": "A test plan for a new feature states: \"The QA team will manually walk through the checkout flow each week and sign off in Slack.\" According to the testing-strategy skill's Verification checklist, does this satisfy the evidence-quality gate? If not, explain what \"concrete, reproducible verification\" requires and what the correct response to this plan is.",
+      "dimension": "application",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": ["skills/testing-strategy/SKILL.md:104-109"]
+    },
+    {
+      "id": 9,
+      "prompt": "A test plan for a new discount-code redemption feature covers the happy path (valid code applied) but has no tests for expired codes, maxed-out codes, or malformed codes. According to the testing-strategy skill's Verification checklist, which gate fails, and what is the prescribed response from the skill when asked to sign off on this plan?",
+      "dimension": "application",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": ["skills/testing-strategy/SKILL.md:104-109"]
+    },
+    {
+      "id": 10,
+      "prompt": "A utility function for formatting phone numbers has been stable and unchanged for two years, with no bug history. Its behavior is covered only indirectly by integration tests of the features that call it. A compliance auditor has flagged that the codebase needs explicit test coverage for every public utility used in customer-facing flows, and the engineering team is onboarding five new contributors next quarter who will benefit from clearer specs. According to the testing-strategy skill's Test-Level Selection table — specifically the `No new test` row which reads \"Behavior that is 'obviously correct,' unchanged for a year, no external pressure\" — does the compliance and onboarding context shift the verdict? Apply the qualifier \"no external pressure\" correctly and recommend what the skill would actually prescribe here.",
+      "dimension": "application",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": ["skills/testing-strategy/SKILL.md:84-91"]
+    }
+  ]
+}

package/examples/evals/type-safety.json

@@ -0,0 +1,249 @@
+{
+  "skill_name": "type-safety",
+  "subject": "Type-safety as a discipline: what static type systems guarantee, the difference between sound and unsound systems, structural vs nominal typing, type narrowing, the runtime boundary problem, the discipline of validating at I/O boundaries and trusting types inside, and the connection from compile-time guarantees to runtime correctness",
+  "adjacent_concepts": ["api-design", "testing-strategy", "data-modeling", "code-review"],
+  "grounding_note": "Truth sources cite line ranges in skills/type-safety/SKILL.md (frontmatter concept block at lines 63-116, body Verification at 254-262, Do NOT Use When at 264-272). Cases are authored against the v4 SKILL.md as of 2026-05-16. Comprehension-dimension extensions (comprehension_dimension, concept_field, transfer, expected_behaviors) are additive — graders that don't consume them treat them as no-ops.",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Explain what type safety is, to a product manager who has never written code. Do not use the phrases from the type-safety skill body verbatim.",
+      "dimension": "definition",
+      "comprehension_dimension": "C1",
+      "concept_field": "definition",
+      "transfer": "near",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": [
+        "skills/type-safety/SKILL.md:64",
+        "skills/type-safety/SKILL.md#type-safety"
+      ],
+      "expected_behaviors": [
+        { "id": "names_primary_category", "kind": "positive", "description": "Names compile-time error detection as the category" },
+        { "id": "states_observable_effect", "kind": "positive", "description": "States that types rule out a class of runtime errors" },
+        { "id": "no_verbatim_span", "kind": "negative", "description": "No 6-gram span shared with skills/type-safety/SKILL.md concept.definition or body" },
+        { "id": "no_fabricated_specificity", "kind": "negative", "description": "Does not invent claims about specific languages, line counts, or guarantees not in concept.definition" }
+      ],
+      "expected_reasoning": "A correct answer names the category (compile-time error detection), the effect (rules out a class of runtime errors), the cost (annotation burden up-front), and the benefit (compounding safety). It does NOT verbatim-copy the concept.definition's first sentence, which is the canonical body phrasing."
+    },
+    {
+      "id": 2,
+      "prompt": "A team is migrating a Python service that uses dict[str, Any] for inbound API payloads to a TypeScript rewrite. They're debating between Record<string, unknown> and Record<string, any>. Apply type-safety's mental model primitives to this case. The skill body discusses JSON.parse but does not enumerate this specific Python-to-TypeScript migration scenario.",
+      "dimension": "mental_model",
+      "comprehension_dimension": "C2",
+      "concept_field": "mental_model",
+      "transfer": "far",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "critical",
+      "truth_sources": [
+        "skills/type-safety/SKILL.md:65-78",
+        "skills/type-safety/SKILL.md:208-239",
+        "skills/type-safety/SKILL.md#the-runtime-boundary"
+      ],
+      "expected_behaviors": [
+        { "id": "invokes_runtime_boundary_primitive", "kind": "positive", "description": "Identifies API payloads as crossing the runtime boundary, where type information stops" },
+        { "id": "invokes_narrowing_or_validation_primitive", "kind": "positive", "description": "Invokes either the narrowing primitive (unknown forces narrowing) or the validation primitive (parse at boundary)" },
+        { "id": "distinguishes_any_from_unknown", "kind": "positive", "description": "Names that any opts out of type-checking, unknown forces narrowing" },
+        { "id": "conclusion_consistent_with_skill", "kind": "positive", "description": "Concludes Record<string, unknown> + validator at the boundary preserves type-safety; Record<string, any> silently disables it" },
+        { "id": "scenario_not_in_body", "kind": "negative", "description": "Body does not mention Python-to-TypeScript migration; the answer is far transfer, not retrieval" }
+      ],
+      "expected_reasoning": "API payloads are an I/O boundary; their types are unverified bytes until parsed. unknown forces narrowing (the type-safe answer to 'I don't know what this is yet'); any disables checking entirely. The right answer is Record<string, unknown> at the type level plus a schema validator (Zod, io-ts) at the boundary to produce typed values. Record<string, any> would compile but silently destroy the discipline."
+    },
+    {
+      "id": 3,
+      "prompt": "Why does the discipline of type-safety exist as a thing teams choose to invest in? What did practitioners do before it was widely adopted, and what was specifically broken about that approach?",
+      "dimension": "purpose",
+      "comprehension_dimension": "C3",
+      "concept_field": "purpose",
+      "transfer": "near",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": [
+        "skills/type-safety/SKILL.md:79-84"
+      ],
+      "expected_behaviors": [
+        { "id": "names_pain_point", "kind": "positive", "description": "Names the pain point — runtime bugs becoming production incidents or silent data corruption" },
+        { "id": "names_prior_alternative", "kind": "positive", "description": "Names the prior alternative — dynamic languages relying on tests, docs, and reader vigilance to communicate contracts" },
+        { "id": "names_improvement_mechanism", "kind": "positive", "description": "States that types make contracts checkable at compile time and visible at call sites; scales with team size and code size" },
+        { "id": "no_fabricated_purpose", "kind": "negative", "description": "Does not add purposes not in the skill — e.g., does not claim types are about performance" }
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "We're designing the JSON shape of a new outbound webhook event for the orders service. Apply type-safety to decide the field structure and naming.",
+      "dimension": "boundary",
+      "comprehension_dimension": "C4",
+      "concept_field": "boundary",
+      "transfer": "near",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "code_verification",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": [
+        "skills/type-safety/SKILL.md:85-94",
+        "skills/type-safety/SKILL.md:264-272",
+        "skills/type-safety/SKILL.md#do-not-use-when"
+      ],
+      "expected_behaviors": [
+        { "id": "identifies_cross_into_api_design", "kind": "positive", "description": "Recognizes that JSON-shape design of an API surface is api-design, not type-safety" },
+        { "id": "names_api_design_as_owner", "kind": "positive", "description": "Names api-design as the correct owner skill" },
+        { "id": "explains_mechanism_of_difference", "kind": "positive", "description": "States api-design owns the external surface contract; type-safety owns the discipline of expressing internal program correctness as types" },
+        { "id": "no_partial_comply_in_type_safety_voice", "kind": "negative", "description": "Does not provide JSON shape recommendations in type-safety's voice before handing off" }
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Where does Haskell's Generalized Algebraic Data Types (GADTs) feature sit in type-safety's taxonomy? It allows types to depend on values like dependent types but is more constrained. Place it using the skill's taxonomy vocabulary, or explain why it doesn't fit.",
+      "dimension": "mental_model",
+      "comprehension_dimension": "C5",
+      "concept_field": "taxonomy",
+      "transfer": "far",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "normal",
+      "truth_sources": [
+        "skills/type-safety/SKILL.md:95-103"
+      ],
+      "expected_behaviors": [
+        { "id": "uses_taxonomy_vocab", "kind": "positive", "description": "Uses one or more of the schema's taxonomy relationship types: subset, alternative, prerequisite, composition, specialization" },
+        { "id": "places_between_dependent_and_refinement", "kind": "positive", "description": "Places GADTs near dependent and refinement types, recognizing the partial dependency" },
+        { "id": "preserves_existing_relationships", "kind": "positive", "description": "Placement does not contradict the relationships among existing taxonomy entries (sound vs unsound, structural vs nominal)" },
+        { "id": "admits_imperfect_fit_or_extends", "kind": "positive", "description": "Either admits the fit is imperfect and proposes how to extend, or fits with a clear relationship-type justification" }
+      ],
+      "expected_reasoning": "GADTs sit between Haskell's vanilla parametric polymorphism and full dependent types — types can be refined by pattern-matching on constructors, but not by arbitrary value expressions. In the skill's taxonomy, the closest fit is 'specialization of sound type systems toward refinement types' or 'composition of pattern-matching with parametric polymorphism'. A correct answer either places GADTs in one of those slots or names the gap in the taxonomy."
+    },
+    {
+      "id": 6,
+      "prompt": "Part A: The type-safety skill compares a type system to a building's structural engineering. Use that analogy to explain how `npm audit` differs from type-checking — does the analogy place npm audit as a type-check, as a different kind of check, or outside the scope of the analogy?\n\nPart B: Where does the structural-engineering analogy break down? Give one concrete case where applying the analogy would mislead someone.",
+      "dimension": "mental_model",
+      "comprehension_dimension": "C6",
+      "concept_field": "analogy",
+      "transfer": "far",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "normal",
+      "truth_sources": [
+        "skills/type-safety/SKILL.md:104-107"
+      ],
+      "expected_behaviors": [
+        { "id": "part_a_distinguishes_npm_audit", "kind": "positive", "description": "Part A: Identifies npm audit as a different class of check (fire-marshal inspection vs structural design) — checking for vulnerabilities found AFTER the build, not for the threat class the design accounted for" },
+        { "id": "part_b_names_real_break", "kind": "positive", "description": "Part B: Names a concrete way the analogy misleads — e.g., structural engineering is stamped once vs type-check runs every change; or escape hatches are gated in engineering but not in TypeScript by default" },
+        { "id": "preserves_structural_relationships", "kind": "positive", "description": "Part A's mapping preserves the analogy's load-bearing relationship (build-time design verification vs runtime threat tolerance)" },
+        { "id": "no_under_claim_on_break", "kind": "negative", "description": "Part B does not refuse to identify a break ('the analogy holds') — the analogy DOES break in identifiable ways and a refusal indicates non-engagement" }
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "Our backend team has been told that since we use TypeScript with strict mode enabled, the JSON parsed from our customer API responses is automatically validated at compile time. We've been planning the next quarter's work and someone proposed dropping our Zod schemas to reduce maintenance overhead. Walk me through whether that's a sensible plan.",
+      "dimension": "anti_pattern",
+      "comprehension_dimension": "C7",
+      "concept_field": "misconception",
+      "transfer": "near",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "critical",
+      "truth_sources": [
+        "skills/type-safety/SKILL.md:108-115",
+        "skills/type-safety/SKILL.md:208-239",
+        "skills/type-safety/SKILL.md#the-runtime-boundary"
+      ],
+      "expected_behaviors": [
+        { "id": "flags_misconception_unprompted", "kind": "positive", "description": "Recognizes 'JSON parsed... automatically validated at compile time' as the misconception without being told it's wrong" },
+        { "id": "corrects_via_runtime_boundary", "kind": "positive", "description": "Corrects using the runtime boundary primitive — TypeScript types are claims about values; values from network/disk are not types until parsed" },
+        { "id": "rejects_dropping_zod", "kind": "positive", "description": "Recommends keeping Zod (or equivalent) for I/O boundary validation; dropping it would silently disable runtime safety" },
+        { "id": "explains_mechanism_of_mislead", "kind": "positive", "description": "States that the misconception conflates 'static type assertion' with 'runtime verification' — JSON.parse(input) as User is a claim, not a check" },
+        { "id": "no_partial_validation_of_misconception", "kind": "negative", "description": "Does not validate the misconception even partially (e.g., 'mostly true, but...')" }
+      ],
+      "expected_reasoning": "The misconception is that TypeScript catches runtime errors. It does not. TypeScript is unsound by design, and even without escape hatches, it makes no guarantees about values crossing the runtime boundary. JSON.parse(input) as User produces a value of static type User and actual type whatever the bytes contained — the static type is a claim, not a verification. Dropping Zod removes the only mechanism that actually validates at runtime; the agent should reject the proposal and explain the mechanism."
+    },
+    {
+      "id": 8,
+      "prompt": "Review this TypeScript snippet for type-safety. Snippet (payments.ts): `export async function fetchPaymentMethod(userId: string) { const response = await fetch('/api/users/' + userId + '/payment'); const data: any = await response.json(); return data as PaymentMethod; } function getUserBalance(user: User): number { const cents = user.balance; return cents / 100; } function summarize(records: PaymentRecord[]): string { return records.map(r => r.amount.toFixed(2)).join(', '); }`. What's your assessment?",
+      "dimension": "application",
+      "comprehension_dimension": "C8",
+      "concept_field": null,
+      "transfer": "near",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": [
+        "skills/type-safety/SKILL.md:254-262",
+        "skills/type-safety/SKILL.md#verification"
+      ],
+      "expected_behaviors": [
+        { "id": "invokes_verification_checklist_unprompted", "kind": "positive", "description": "Walks through ≥3 items from the type-safety Verification checklist without being told to" },
+        { "id": "flags_any_without_comment", "kind": "positive", "description": "Flags `any: any` on the data variable without justification" },
+        { "id": "flags_as_cast_without_comment", "kind": "positive", "description": "Flags `as PaymentMethod` cast on the unvalidated response.json() result" },
+        { "id": "flags_missing_runtime_validation", "kind": "positive", "description": "Flags the fetch boundary as missing runtime validation (Zod/io-ts/valibot)" },
+        { "id": "anchors_to_line_numbers", "kind": "positive", "description": "References specific lines or function names from the snippet, not abstract restatements" },
+        { "id": "no_verdict_without_anchor", "kind": "negative", "description": "Does not provide an overall verdict without anchoring each judgment to a Verification criterion" }
+      ],
+      "expected_reasoning": "The Verification checklist requires (paraphrased): strict mode on, noUncheckedIndexedAccess on, no `any` without justification comment, no `as Type` without justification comment, every I/O boundary parses with a validator, discriminated unions have exhaustiveness, public APIs have explicit return types. This snippet fails the `any` rule (data: any), the as cast rule (as PaymentMethod), the I/O validation rule (fetch result is cast not parsed), the explicit return type rule on the async function (inferred only). It passes 'no @ts-ignore'. The agent should walk through these items by name and anchor each to the snippet."
+    },
+    {
+      "id": 9,
+      "prompt": "Help me design a Postgres schema for storing user-uploaded file metadata. I want to use type-safety to decide which columns should be NOT NULL, which should be enums, and how to express the relationships between the tables.",
+      "dimension": "boundary",
+      "comprehension_dimension": "C9",
+      "concept_field": null,
+      "transfer": "near",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "code_verification",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": [
+        "skills/type-safety/SKILL.md:264-272",
+        "skills/type-safety/SKILL.md#do-not-use-when"
+      ],
+      "expected_behaviors": [
+        { "id": "refuses_schema_design_in_type_safety_voice", "kind": "positive", "description": "Does not produce a column list with NOT NULL or enum suggestions in type-safety's voice" },
+        { "id": "names_data_modeling_as_owner", "kind": "positive", "description": "Names data-modeling as the correct owner skill" },
+        { "id": "explains_mechanism", "kind": "positive", "description": "States that data-modeling owns persistence shape; type-safety owns in-memory type contracts that consume that shape" },
+        { "id": "no_partial_comply", "kind": "negative", "description": "Does not provide partial schema recommendations before refusing" },
+        { "id": "no_overrefuse", "kind": "negative", "description": "If the user asks a follow-up about the TypeScript types that consume the schema once data-modeling has produced it, the agent re-engages — does not blanket-refuse all related work" }
+      ]
+    },
+    {
+      "id": 10,
+      "prompt": "A team has heard that 'type assertions in TypeScript are like runtime casts in C++ — they check the type at runtime and fail if it's wrong.' Walk me through whether this comparison is accurate.",
+      "dimension": "anti_pattern",
+      "comprehension_dimension": "C7",
+      "concept_field": "misconception",
+      "transfer": "far",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": [
+        "skills/type-safety/SKILL.md:108-115",
+        "skills/type-safety/SKILL.md#any-vs-unknown-vs-never"
+      ],
+      "expected_behaviors": [
+        { "id": "flags_misconception_about_as", "kind": "positive", "description": "Recognizes that TypeScript `as` is NOT a runtime check; C++ dynamic_cast is. The comparison is wrong." },
+        { "id": "states_as_compiles_to_nothing", "kind": "positive", "description": "States that `as` compiles to nothing — it is a directive to the type checker only, no runtime code is emitted" },
+        { "id": "distinguishes_static_directive_from_runtime_check", "kind": "positive", "description": "Distinguishes a static directive ('trust me, this is the type') from a runtime check (`instanceof`, validator parse)" },
+        { "id": "no_partial_validation", "kind": "negative", "description": "Does not say 'yes, with some caveats' — the comparison is structurally wrong, not just imprecise" }
+      ],
+      "expected_reasoning": "TypeScript `as` is a static directive, not a runtime check. It compiles to nothing. C++ `dynamic_cast` IS a runtime check (returns nullptr or throws). C-style casts in C++ are closer to TypeScript `as`. A correct answer rejects the comparison: TypeScript `as` is a silent claim a misused `as` makes; the C++ comparison should be to a C-style cast, not dynamic_cast. The body's misconception field explicitly names this trap."
+    }
+  ]
+}

package/examples/evals/visual-design-foundations.json

@@ -0,0 +1,52 @@
+{
+  "skill_name": "visual-design-foundations",
+  "subject": "Visual craft decisions for color, typography, spacing, density, hierarchy, elevation, and motion feel",
+  "adjacent_concepts": ["semiotics", "design-system-architecture", "layout-composition", "a11y"],
+  "grounding_note": "Truth sources cite the whole SKILL.md file to keep the initial eval surface stable while the new skill settles.",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "A dense internal admin tool feels noisy and hard to scan. The task structure is settled. Which visual-design-foundations method steps apply first?",
+      "dimension": "application",
+      "substance": "domain",
+      "calibration": "process",
+      "truth_mode": "process_correctness",
+      "skill_type": "concept",
+      "criticality": "high",
+      "truth_sources": ["skills/visual-design-foundations/SKILL.md"]
+    },
+    {
+      "id": 2,
+      "prompt": "A green badge means both 'healthy' and 'cost increased' in a finance UI. Should visual-design-foundations own the meaning problem?",
+      "dimension": "boundary",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "code_verification",
+      "skill_type": "concept",
+      "criticality": "normal",
+      "truth_sources": ["skills/visual-design-foundations/SKILL.md"]
+    },
+    {
+      "id": 3,
+      "prompt": "A designer wants raw hex colors wired into reusable component variants. Which boundary decides whether visual-design-foundations or design-system-architecture should own the work?",
+      "dimension": "boundary",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "code_verification",
+      "skill_type": "concept",
+      "criticality": "normal",
+      "truth_sources": ["skills/visual-design-foundations/SKILL.md"]
+    },
+    {
+      "id": 4,
+      "prompt": "A product card has oversized headings, inconsistent metadata text, and heavy borders around every element. What verification checks should visual-design-foundations apply?",
+      "dimension": "application",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "concept",
+      "criticality": "normal",
+      "truth_sources": ["skills/visual-design-foundations/SKILL.md"]
+    }
+  ]
+}

package/examples/evals/webhook-integration.json

@@ -0,0 +1,52 @@
+{
+  "skill_name": "webhook-integration",
+  "subject": "Inbound third-party webhook handler design for signature verification, idempotency, provider retry contracts, raw payload persistence, quarantine, secret rotation, and PII capture timing",
+  "adjacent_concepts": ["event-contract-design", "testing-strategy", "debugging", "owasp-security"],
+  "grounding_note": "Truth sources cite the whole SKILL.md file to keep the initial eval surface stable while routing boundaries are tightened.",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "A new third-party webhook handler must verify HMAC signatures on the raw body, dedupe retries, and choose 200 vs 500 behavior. Which skill owns this?",
+      "dimension": "application",
+      "substance": "domain",
+      "calibration": "process",
+      "truth_mode": "process_correctness",
+      "skill_type": "workflow",
+      "criticality": "high",
+      "truth_sources": ["skills/webhook-integration/SKILL.md"]
+    },
+    {
+      "id": 2,
+      "prompt": "A provider deletes customer data after 30 days and the handler must capture safe canonical data on first delivery. What should webhook-integration decide?",
+      "dimension": "application",
+      "substance": "domain",
+      "calibration": "semantic",
+      "truth_mode": "conceptual_correctness_plus_repo_application",
+      "skill_type": "workflow",
+      "criticality": "high",
+      "truth_sources": ["skills/webhook-integration/SKILL.md"]
+    },
+    {
+      "id": 3,
+      "prompt": "The product is an outbound webhook publisher that delivers customer-facing events. Should webhook-integration accept the contract design task?",
+      "dimension": "boundary",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "code_verification",
+      "skill_type": "concept",
+      "criticality": "normal",
+      "truth_sources": ["skills/webhook-integration/SKILL.md"]
+    },
+    {
+      "id": 4,
+      "prompt": "The webhook handler is already failing in production and the user wants root-cause debugging. Which boundary should webhook-integration respect?",
+      "dimension": "boundary",
+      "substance": "contradiction-check",
+      "calibration": "semantic",
+      "truth_mode": "code_verification",
+      "skill_type": "concept",
+      "criticality": "normal",
+      "truth_sources": ["skills/webhook-integration/SKILL.md"]
+    }
+  ]
+}

package/examples/exports/a11y.skill-md.md

@@ -0,0 +1,80 @@
+---
+name: a11y
+description: "Use when building or reviewing interactive UI, forms, navigation, or dynamic content. Covers semantic HTML, keyboard access, focus management, labeling, state-change announcement, and reduced-motion / high-contrast preferences. Do NOT use for color-palette creation, visual branding, feedback-state staging, or prose reading-level accessibility - those belong to `visual-design-foundations`, `interaction-feedback`, and documentation respectively."
+license: MIT
+compatibility: "Markdown, Git, any web stack"
+allowed-tools: Read Grep
+metadata:
+  schema_version: "4"
+  version: "1.0.0"
+  type: capability
+  category: frontend
+  scope: portable
+  owner: skill-graph-maintainer
+  freshness: "2026-04-18"
+  drift_check: "{\"last_verified\":\"2026-04-18\"}"
+  eval_artifacts: present
+  eval_state: passing
+  routing_eval: present
+  stability: experimental
+  keywords: "[\"accessibility\",\"a11y\",\"keyboard navigation\",\"screen reader\",\"focus management\",\"keyboard not working\",\"tab order\",\"missing aria label\",\"screen reader says\",\"reduced motion\",\"high contrast\",\"semantic html\",\"form labels\",\"form fields\",\"aria-label\",\"assistive tech\",\"assistive technology\",\"accessible labels\",\"proper labels\"]"
+  triggers: "[\"a11y-skill\"]"
+  paths: "[\"**/*.{html,tsx,jsx,vue,svelte}\",\"**/*.css\",\"!**/*.test.{ts,tsx,js,jsx}\",\"!**/dist/**\",\"!**/node_modules/**\"]"
+  examples: "[\"this modal is keyboard-trapped — users can't Escape to close it\",\"screen reader doesn't announce when the form validation state changes\",\"add proper labels to these form fields so assistive tech can read them\",\"review this dropdown menu for arrow-key navigation and focus return\"]"
+  anti_examples: "[\"rewrite this error message at a 6th-grade reading level\",\"clean up this accessibility code without changing how it behaves\"]"
+  relations: "{\"boundary\":[{\"skill\":\"refactor\",\"reason\":\"refactor is behavior-preserving code modification; a11y is observable user-facing behavior\"},{\"skill\":\"documentation\",\"reason\":\"documentation owns prose reading-level and audience fit; a11y owns assistive-tech behavior\"},{\"skill\":\"diagnosis\",\"reason\":\"diagnosis classifies failure symptoms (Logic / Runtime / Performance / etc.) for triage; a11y owns assistive-tech behavior. The phrase 'rewrite this error message...' is a documentation/UX concern, not a diagnosis or a11y concern — diagnosis is named here so the router excludes it from a11y's positive scope.\"},{\"skill\":\"visual-design-foundations\",\"reason\":\"visual-design-foundations owns palette, typography, spacing, and visual craft; a11y owns whether the resulting interaction is perceivable, operable, understandable, and robust\"},{\"skill\":\"interaction-feedback\",\"reason\":\"interaction-feedback owns feedback-state staging; a11y owns whether those state changes are announced and operable\"}],\"related\":[\"interaction-patterns\",\"form-ux-architecture\",\"interaction-feedback\",\"design-system-architecture\"],\"verify_with\":[\"testing-strategy\"]}"
+  portability: "{\"readiness\":\"scripted\",\"targets\":[\"skill-md\"]}"
+---
+
+# Accessibility
+
+## Coverage
+
+- Semantic HTML: choosing the right primitive elements so structure is meaningful to assistive technology
+- Keyboard access: making every interaction reachable and operable without a pointing device
+- Focus management: keeping focus visible, predictable, and correctly placed after navigation and state changes
+- Labeling and naming: ensuring every interactive element has a programmatic name that matches its visible label
+- State and change announcement: communicating dynamic updates (loading, errors, success) to assistive technology
+- Reduced-motion and high-contrast preferences: respecting user settings that affect interaction perception
+
+## Philosophy
+
+Accessible interaction is structural, not cosmetic. It is decided by the primitive you picked, the focus order you wrote, and the label that ships or doesn't — not by the audit that runs after. Teams that treat accessibility as a finishing pass pay for it twice: once in remediation work that was cheaper to avoid, and again when assistive-technology users hit the failure and bounce. The correct default is to build with those users in scope from the first commit, not after the first lawsuit.
+
+## Primitive Selection
+
+The single highest-leverage accessibility decision is picking the right HTML primitive before styling. A wrong primitive cannot be rescued by ARIA; the right primitive usually needs no ARIA at all.
+
+| User intent                          | Correct primitive                               | Wrong primitives (common mistakes)                      |
+| ------------------------------------ | ----------------------------------------------- | ------------------------------------------------------- |
+| Trigger an action on the same page   | `<button type="button">`                        | `<a href="#">`, `<div onclick>`, `<span role="button">` |
+| Navigate to a different URL          | `<a href="…">`                                  | `<button onclick=navigate>`, `<div onclick>`            |
+| Group related form controls          | `<fieldset>` + `<legend>`                       | `<div>` with a heading above it                         |
+| Label a form control                 | `<label for="…">` (or wrapping `<label>`)       | `<div>` text next to the input, `placeholder` only      |
+| Show a collapsible section           | `<details>` + `<summary>`                       | `<div>` with JS toggle and no ARIA                      |
+| Present tabular data                 | `<table>` + `<th scope="…">`                    | `<div>` grid, CSS grid with no semantic role            |
+| Announce a status change             | `<output>` or `role="status"` live region       | Toast that only renders visually                        |
+| Interactive widget not covered above | Native element + tested keyboard + ARIA pattern | Custom `<div>` with ad-hoc `role` and handlers          |
+
+### When ARIA is appropriate
+
+Only when no native primitive fits the interaction, and only when you also ship the keyboard behavior that matches the role. Adding `role="button"` to a `<div>` without Enter/Space handlers is worse than either the correct `<button>` or the untyped `<div>` alone.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/a11y.json`](../../examples/evals/a11y.json). The `Verification` checklist below is the authoring gate for a new interactive component; the eval file is how this skill is graded by `scripts/skill-audit.js --graded`. Do not conflate them — the checklist is for implementers, the eval is for the grader.
+
+## Verification
+
+- [ ] Interactive elements use the right semantic primitives
+- [ ] Keyboard-only flows remain usable
+- [ ] Focus is visible and lands in the correct place
+- [ ] Labels and state changes are perceivable
+- [ ] User preferences (reduced motion, high contrast) are respected
+
+## Do NOT Use When
+
+| Use instead     | When                                                                                                     |
+| --------------- | -------------------------------------------------------------------------------------------------------- |
+| `documentation` | The task is prose structure or reading-level clarity, not interaction accessibility                      |
+| `refactor`      | The task is behavior-preserving code cleanup — refactoring does not change what assistive tech perceives |