From e705370b1a72bb70d633c8c8da0a27ebadcfb276 Mon Sep 17 00:00:00 2001
From: Gianluca Carucci <gianluca@carucci.org>
Date: Sun, 12 Jul 2026 20:18:05 +0200
Subject: [PATCH 1/4] [#313] feat: T7 trigger-eval harness + skills conformance
 gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- eval prompt sets (79 prompts, 12 families, all 35 skills) + runner README
- baseline run committed: 76 PASS / 3 AMBIGUOUS (all assess-* overlap — motivates T3)
- scripts/skills-conformance-check.js: frontmatter portability, name+description <=1024,
  pointer resolution, catalog counts (warning-only until #313/T1)
- wired as skills:conformance in quality-gate + CI; 18 unit tests

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |   2 +
 package.json                                  |   3 +-
 packages/knowledge-hub/eval/README.md         |  72 +++
 .../eval/results/2026-07-12-baseline.md       | 206 ++++++
 .../knowledge-hub/eval/trigger-prompts.json   | 594 ++++++++++++++++++
 .../src/skills-conformance-check.test.ts      | 199 ++++++
 scripts/skills-conformance-check.js           | 237 +++++++
 7 files changed, 1312 insertions(+), 1 deletion(-)
 create mode 100644 packages/knowledge-hub/eval/README.md
 create mode 100644 packages/knowledge-hub/eval/results/2026-07-12-baseline.md
 create mode 100644 packages/knowledge-hub/eval/trigger-prompts.json
 create mode 100644 packages/knowledge-hub/src/skills-conformance-check.test.ts
 create mode 100644 scripts/skills-conformance-check.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 812c3eeb..d8caca8d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -63,6 +63,8 @@ jobs:
         run: pnpm hygiene:check
       - name: Run docs-staleness check
         run: pnpm docs:staleness
+      - name: Run skills-conformance check
+        run: pnpm skills:conformance
       - name: Run duplication check
         run: pnpm dup:check
       - name: Install Playwright browsers
diff --git a/package.json b/package.json
index b215bc1d..4906245c 100644
--- a/package.json
+++ b/package.json
@@ -25,8 +25,9 @@
     "a11y:report:html": "turbo a11y:report:html",
     "hygiene:check": "node scripts/code-hygiene-check.js",
     "docs:staleness": "node scripts/docs-staleness-check.js",
+    "skills:conformance": "node scripts/skills-conformance-check.js",
     "dup:check": "jscpd apps packages",
-    "quality-gate": "turbo ts:check test lint && turbo prettier:fix mdlint:fix && ./tools/markdownlint-config/bin/markdownlint-fix.sh '*.md' && pnpm hygiene:check && pnpm docs:staleness && pnpm dup:check",
+    "quality-gate": "turbo ts:check test lint && turbo prettier:fix mdlint:fix && ./tools/markdownlint-config/bin/markdownlint-fix.sh '*.md' && pnpm hygiene:check && pnpm docs:staleness && pnpm skills:conformance && pnpm dup:check",
     "e2e": "pnpm --filter @pair/website e2e",
     "smoke-tests": "./scripts/smoke-tests/run-all.sh --cleanup"
   },
diff --git a/packages/knowledge-hub/eval/README.md b/packages/knowledge-hub/eval/README.md
new file mode 100644
index 00000000..ce1ba2a7
--- /dev/null
+++ b/packages/knowledge-hub/eval/README.md
@@ -0,0 +1,72 @@
+# Skill Trigger Eval
+
+Trigger/effectiveness eval harness for the skill corpus (story #313, T7). It measures whether the
+frontmatter `description` of each skill in `packages/knowledge-hub/dataset/.skills/**` routes an
+LLM executor to the right skill — the experiment behind principle 9 ("Evaluation") of the
+authoring standard (`apps/website/content/docs/contributing/writing-skills.mdx`): a description
+rewrite is a hypothesis; this eval is the experiment.
+
+## Contents
+
+- `trigger-prompts.json` — should-trigger / should-not-trigger prompt sets, one entry per skill
+  family. Every skill has at least one should-trigger prompt; near-miss prompts name the sibling
+  skill they are a decoy for (`near_miss_for`) and the correct destination (`expected`, `none`
+  when no skill applies).
+- `results/` — committed evidence, one file per run, named `YYYY-MM-DD-<label>.md`.
+
+## Procedure
+
+1. **Build the catalog** — extract the current name+description pairs (descriptions only, no
+   skill bodies):
+
+   ```bash
+   for f in packages/knowledge-hub/dataset/.skills/next/SKILL.md \
+            packages/knowledge-hub/dataset/.skills/*/*/SKILL.md; do
+     awk '/^---$/{c++; next} c==1 && (/^name:/ || /^description:/)' "$f"; echo
+   done
+   ```
+
+2. **Run each prompt in a fresh session** — triggering is a cold-start behavior; conversation
+   history invalidates the result. Present the executor with the full catalog and one prompt, and
+   ask: *"Given only these skill names and descriptions, which single skill would you load for
+   this request? Answer `none` if no skill applies. If two or more descriptions claim the prompt
+   equally, name all of them."*
+
+3. **Record per prompt** — id, expected, selected, verdict:
+   - `PASS` — selected matches expected.
+   - `AMBIGUOUS` — executor names two or more candidates (counts against the corpus: two
+     executors could disagree).
+   - `FAIL` — selected differs from expected.
+
+   Record honestly, including near-ties resolved by a judgment call (`PASS` with a note).
+
+4. **Summarize** — pass rate per prompt type (should-trigger / should-not-trigger), list of
+   ambiguities/failures with the competing descriptions, methodology statement (model, passes,
+   executor identity). Commit the file under `results/`.
+
+## Before/after comparison (gating a description rewrite)
+
+When a skill's description changes (e.g. T3 of #313):
+
+1. Run the full set against the **old** descriptions (or reuse the latest committed baseline if
+   descriptions are unchanged since).
+2. Apply the rewrite; run the same set against the **new** descriptions, same procedure, fresh
+   sessions.
+3. Compare per skill. **A regression on any prompt reverts that skill's description** — iterate
+   on the description, not on the eval. Improvements on previously ambiguous/failing prompts are
+   the acceptance evidence.
+4. Commit both result files; reference them in the PR.
+
+## Maintaining the prompt set
+
+- New skill ⇒ add at least one should-trigger prompt and one family near-miss.
+- Keep prompts realistic user phrasing, not description echoes — a prompt that quotes the
+  description verbatim tests nothing.
+- Prompts are grounded in current descriptions; when a trigger branch is added or removed, add or
+  retire the matching prompts in the same PR.
+
+## Related gates
+
+Static conformance (frontmatter portability, size limits, pointer resolution, catalog counts) is
+enforced separately by `pnpm skills:conformance` (`scripts/skills-conformance-check.js`), wired
+into `quality-gate` and CI.
diff --git a/packages/knowledge-hub/eval/results/2026-07-12-baseline.md b/packages/knowledge-hub/eval/results/2026-07-12-baseline.md
new file mode 100644
index 00000000..81ba40f1
--- /dev/null
+++ b/packages/knowledge-hub/eval/results/2026-07-12-baseline.md
@@ -0,0 +1,206 @@
+# Trigger Eval — Baseline (2026-07-12)
+
+Baseline run of `../trigger-prompts.json` against the **current** frontmatter descriptions
+(pre-T3 rewrite), corpus at 35 skills. This is the "before" half of the before/after evidence
+required by AC7 of story #313 and principle 9 of the authoring standard.
+
+## Methodology
+
+- **Executor**: single LLM (Claude, Fable 5), single pass per prompt. The executor was shown the
+  full catalog of 35 `name` + `description` pairs (frontmatter only — no skill bodies, no `next`
+  routing tables) and one prompt at a time, cold (no conversation history about the corpus).
+- **Instruction**: pick the single skill you would load, `none` if no skill applies, name all
+  candidates when two or more descriptions claim the prompt equally.
+- **Bias disclosure**: the prompt author and the executor are the same model/session lineage;
+  ambiguity may be *under*-reported. Near-ties resolved by judgment are marked PASS with a note
+  rather than silently passed.
+- **Verdicts**: PASS (selected = expected), AMBIGUOUS (≥2 candidates named — counts as failure:
+  two executors could disagree), FAIL (selected ≠ expected).
+
+## Summary
+
+| Type | Prompts | PASS | AMBIGUOUS | FAIL | Strict pass rate |
+| ---- | ------- | ---- | --------- | ---- | ---------------- |
+| should-trigger | 53 | 51 | 2 | 0 | 96.2% |
+| should-not-trigger | 26 | 25 | 1 | 0 | 96.2% |
+| **Total** | **79** | **76** | **3** | **0** | **96.2%** |
+
+### Ambiguities (all involve the assess-* family)
+
+| Id | Prompt (abridged) | Expected | Candidates named | Root cause |
+| -- | ----------------- | -------- | ---------------- | ---------- |
+| AD-12 | "Recommend where we should track our work items" | assess-pm | assess-pm, setup-pm | Both descriptions claim tool *selection*: assess-pm "proposes a tool choice" vs setup-pm "guiding selection from supported options" |
+| AD-14 | "Add Redis as a dependency — check whether that's consistent with our stack" | assess-stack | assess-stack, verify-adoption | assess-stack's branch is buried in the cryptic clause "implementation (add dependency)"; verify-adoption's "checks code and configuration against project adoption files" claims the same prompt |
+| PB-N2 | "We haven't picked a tracker yet — what should we use?" | assess-pm | assess-pm, setup-pm | Same assess-pm / setup-pm selection overlap as AD-12 |
+
+### assess-* near-clone evidence (motivates T3)
+
+The 10 assess-* descriptions share ~60% of their text verbatim ("resolution cascade (Argument >
+Adoption > Assessment)", "emits rendered adoption content + target (output-only, writes
+nothing)", "the caller persists via /record-decision", "Idempotent"). In this run **all routing
+inside the family was carried by the single domain noun** (architecture, infrastructure,
+observability, …); the shared scaffold contributed zero discrimination while consuming most of
+the description budget. Consequences observed:
+
+- Both ambiguities on the decision side (AD-12, PB-N2, AD-14) sit exactly where the domain noun
+  stops discriminating (pm vs setup-pm; stack vs verify-adoption).
+- Domain-keyword prompts pass, but only because the eval prompts contain the noun; prompts
+  phrased without it (AD-02 "bring Copilot into our workflow", AD-10 "zero telemetry") were
+  near-ties resolved by judgment (see notes below).
+- SNT decoys aimed at the family (AD-N3 "assess the security posture") produce a felt pull toward
+  the family before resolving to `none` — the word "assess" alone activates 10 near-identical
+  candidates.
+
+### Other description defects noticed during the run (not counted, feed T1/T3)
+
+- `grill` and `checkpoint` descriptions reference non-existent skills (`/brainstorm`, "a future
+  `/publish-pr`") as live composition targets.
+- `next`'s catalog/count issue is router-level (33 vs 35, checkpoint and grill unreachable) and
+  is not exercised by this description-only eval — covered by the conformance gate's
+  warning-only catalog-count rule until T1.
+- Only `next` has when-to-use phrasing; every other description is a capability summary, so
+  passes lean on noun overlap between prompt and description rather than trigger branches.
+
+## Per-prompt results
+
+Verdict key: PASS / AMBIGUOUS / FAIL. Notes flag near-ties resolved by judgment (pull =
+competing description considered and rejected).
+
+### router
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| RT-01 | ST | next | next | PASS | |
+| RT-02 | ST | next | next | PASS | |
+| RT-N1 | SNT | refine-story | refine-story | PASS | pull: next ("what to work on"); resolved by refine-story's "Todo to Refined ... selection" |
+
+### assess-decision
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| AD-01 | ST | assess-ai | assess-ai | PASS | |
+| AD-02 | ST | assess-ai | assess-ai | PASS | near-tie: assess-stack's "add dependency" branch competes for "bring Copilot into our workflow"; resolved because Copilot is named an AI tool |
+| AD-03 | ST | assess-architecture | assess-architecture | PASS | |
+| AD-04 | ST | assess-architecture | assess-architecture | PASS | |
+| AD-05 | ST | assess-infrastructure | assess-infrastructure | PASS | |
+| AD-06 | ST | assess-infrastructure | assess-infrastructure | PASS | |
+| AD-07 | ST | assess-methodology | assess-methodology | PASS | |
+| AD-08 | ST | assess-methodology | assess-methodology | PASS | "iterations, ceremonies" absent from description; routed on "development process" ≈ methodology |
+| AD-09 | ST | assess-observability | assess-observability | PASS | |
+| AD-10 | ST | assess-observability | assess-observability | PASS | "telemetry" absent from description; routed via monitoring/logging/tracing synonymy |
+| AD-11 | ST | assess-pm | assess-pm | PASS | |
+| AD-12 | ST | assess-pm | assess-pm, setup-pm | AMBIGUOUS | see summary table |
+| AD-13 | ST | assess-stack | assess-stack | PASS | |
+| AD-14 | ST | assess-stack | assess-stack, verify-adoption | AMBIGUOUS | see summary table |
+| AD-15 | ST | assess-testing | assess-testing | PASS | |
+| AD-16 | ST | assess-testing | assess-testing | PASS | keyword collision: "coverage" also in assess-code-quality; resolved by "should we aim for" = strategy |
+| AD-N1 | SNT | setup-pm | setup-pm | PASS | "already decided" defuses assess-pm |
+| AD-N2 | SNT | record-decision | record-decision | PASS | |
+| AD-N3 | SNT | none | none | PASS | felt pull toward assess-* family from the bare word "assess"; no description covers security |
+| AD-N4 | SNT | none | none | PASS | assess-testing proposes strategy, does not write tests |
+
+### assess-report
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| AR-01 | ST | assess-code-quality | assess-code-quality | PASS | |
+| AR-02 | ST | assess-code-quality | assess-code-quality | PASS | |
+| AR-03 | ST | assess-debt | assess-debt | PASS | |
+| AR-04 | ST | assess-debt | assess-debt | PASS | |
+| AR-N1 | SNT | verify-quality | verify-quality | PASS | "quality gate" discriminates from assess-code-quality |
+| AR-N2 | SNT | none | none | PASS | pull: assess-debt ("debt" keyword); defused by its "output-only, returns a report" |
+
+### verification
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| VF-01 | ST | verify-quality | verify-quality | PASS | |
+| VF-02 | ST | verify-quality | verify-quality | PASS | |
+| VF-03 | ST | verify-done | verify-done | PASS | |
+| VF-04 | ST | verify-adoption | verify-adoption | PASS | |
+| VF-N1 | SNT | none | none | PASS | verify-* descriptions are detection-only |
+| VF-N2 | SNT | review | review | PASS | |
+
+### decision-recording
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| DR-01 | ST | record-decision | record-decision | PASS | |
+| DR-02 | ST | record-decision | record-decision | PASS | |
+| DR-N1 | SNT | assess-stack | assess-stack | PASS | |
+
+### pm-and-backlog
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| PB-01 | ST | write-issue | write-issue | PASS | |
+| PB-02 | ST | write-issue | write-issue | PASS | |
+| PB-03 | ST | setup-pm | setup-pm | PASS | |
+| PB-04 | ST | estimate | estimate | PASS | |
+| PB-N1 | SNT | plan-tasks | plan-tasks | PASS | |
+| PB-N2 | SNT | assess-pm | assess-pm, setup-pm | AMBIGUOUS | see summary table |
+
+### ddd-mapping
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| DM-01 | ST | map-subdomains | map-subdomains | PASS | |
+| DM-02 | ST | map-contexts | map-contexts | PASS | |
+| DM-N1 | SNT | none | none | PASS | |
+| DM-N2 | SNT | none | none | PASS | pull: map-subdomains ("domain" keyword) |
+
+### session-continuity
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| SC-01 | ST | checkpoint | checkpoint | PASS | |
+| SC-02 | ST | checkpoint | checkpoint | PASS | "resume mode" named in description |
+| SC-03 | ST | grill | grill | PASS | |
+| SC-04 | ST | grill | grill | PASS | name match carries it |
+| SC-N1 | SNT | none | none | PASS | pull: checkpoint ("so work survives") |
+| SC-N2 | SNT | none | none | PASS | |
+
+### manual-testing
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| MT-01 | ST | design-manual-tests | design-manual-tests | PASS | |
+| MT-02 | ST | execute-manual-tests | execute-manual-tests | PASS | |
+| MT-N1 | SNT | assess-testing | assess-testing | PASS | |
+| MT-N2 | SNT | verify-quality | verify-quality | PASS | "automated" defuses execute-manual-tests |
+
+### setup-ops
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| SO-01 | ST | setup-gates | setup-gates | PASS | |
+| SO-02 | ST | manage-flags | manage-flags | PASS | |
+| SO-N1 | SNT | verify-quality | verify-quality | PASS | |
+| SO-N2 | SNT | none | none | PASS | config option ≠ feature flag |
+
+### planning-processes
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| PP-01 | ST | specify-prd | specify-prd | PASS | |
+| PP-02 | ST | specify-prd | specify-prd | PASS | |
+| PP-03 | ST | plan-initiatives | plan-initiatives | PASS | |
+| PP-04 | ST | plan-epics | plan-epics | PASS | |
+| PP-05 | ST | plan-stories | plan-stories | PASS | |
+| PP-06 | ST | plan-tasks | plan-tasks | PASS | |
+| PP-07 | ST | refine-story | refine-story | PASS | |
+| PP-N1 | SNT | write-issue | write-issue | PASS | pull: plan-epics ("epic" keyword); "from this text I already wrote" defuses breakdown |
+| PP-N2 | SNT | none | none | PASS | |
+| PP-N3 | SNT | estimate | estimate | PASS | |
+
+### execution-orchestrators
+
+| Id | Type | Expected | Selected | Verdict | Note |
+| -- | ---- | -------- | -------- | ------- | ---- |
+| EO-01 | ST | bootstrap | bootstrap | PASS | |
+| EO-02 | ST | bootstrap | bootstrap | PASS | |
+| EO-03 | ST | implement | implement | PASS | |
+| EO-04 | ST | review | review | PASS | |
+| EO-N1 | SNT | none | none | PASS | pull: implement; a one-line typo is not a story |
+| EO-N2 | SNT | none | none | PASS | pull: bootstrap ("project setup"); CLI install is not skill territory |
+| EO-N3 | SNT | verify-quality | verify-quality | PASS | "no full review needed" defuses review |
diff --git a/packages/knowledge-hub/eval/trigger-prompts.json b/packages/knowledge-hub/eval/trigger-prompts.json
new file mode 100644
index 00000000..43f08919
--- /dev/null
+++ b/packages/knowledge-hub/eval/trigger-prompts.json
@@ -0,0 +1,594 @@
+{
+  "$comment": "Trigger eval prompt sets (story #313, T7). One entry per skill family. Prompt types: should-trigger (expected = the skill an executor must load) and should-not-trigger (expected = the correct destination — a sibling skill or 'none'; near_miss_for = the skill the prompt is a decoy for and must NOT fire). Prompts are grounded in the frontmatter descriptions of packages/knowledge-hub/dataset/.skills/**/SKILL.md. Run procedure: see README.md in this directory.",
+  "corpus_size": 35,
+  "families": [
+    {
+      "family": "router",
+      "skills": ["next"],
+      "prompts": [
+        {
+          "id": "RT-01",
+          "type": "should-trigger",
+          "expected": "next",
+          "prompt": "I just opened this project and have no idea where things stand. What should we work on?"
+        },
+        {
+          "id": "RT-02",
+          "type": "should-trigger",
+          "expected": "next",
+          "prompt": "We finished the last story. Figure out what the most useful next step is for this repo."
+        },
+        {
+          "id": "RT-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "next",
+          "expected": "refine-story",
+          "prompt": "Pick the next Todo story from the backlog and get it ready for the sprint."
+        }
+      ]
+    },
+    {
+      "family": "assess-decision",
+      "skills": [
+        "assess-ai",
+        "assess-architecture",
+        "assess-infrastructure",
+        "assess-methodology",
+        "assess-observability",
+        "assess-pm",
+        "assess-stack",
+        "assess-testing"
+      ],
+      "prompts": [
+        {
+          "id": "AD-01",
+          "type": "should-trigger",
+          "expected": "assess-ai",
+          "prompt": "Which AI coding assistants and agent tools should this team adopt, and in what versions?"
+        },
+        {
+          "id": "AD-02",
+          "type": "should-trigger",
+          "expected": "assess-ai",
+          "prompt": "We want to bring Copilot or something similar into our workflow — evaluate the options for us."
+        },
+        {
+          "id": "AD-03",
+          "type": "should-trigger",
+          "expected": "assess-architecture",
+          "prompt": "Propose an architecture pattern for this service — layered, hexagonal, or something else."
+        },
+        {
+          "id": "AD-04",
+          "type": "should-trigger",
+          "expected": "assess-architecture",
+          "prompt": "Should this app be a modular monolith or split into microservices? Give us a recommendation."
+        },
+        {
+          "id": "AD-05",
+          "type": "should-trigger",
+          "expected": "assess-infrastructure",
+          "prompt": "Evaluate where we should host this system and how CI/CD should deploy it."
+        },
+        {
+          "id": "AD-06",
+          "type": "should-trigger",
+          "expected": "assess-infrastructure",
+          "prompt": "We need a plan for cloud provider, environments and release pipeline for this product."
+        },
+        {
+          "id": "AD-07",
+          "type": "should-trigger",
+          "expected": "assess-methodology",
+          "prompt": "Should this team run Scrum or Kanban? Assess what fits us."
+        },
+        {
+          "id": "AD-08",
+          "type": "should-trigger",
+          "expected": "assess-methodology",
+          "prompt": "Recommend how we should organize our development process — iterations, ceremonies, flow."
+        },
+        {
+          "id": "AD-09",
+          "type": "should-trigger",
+          "expected": "assess-observability",
+          "prompt": "Propose a monitoring, logging and tracing strategy for production."
+        },
+        {
+          "id": "AD-10",
+          "type": "should-trigger",
+          "expected": "assess-observability",
+          "prompt": "We have zero telemetry — how will we even know when production breaks? Work out what we need."
+        },
+        {
+          "id": "AD-11",
+          "type": "should-trigger",
+          "expected": "assess-pm",
+          "prompt": "Which project management tool fits this project — Jira, Linear, or GitHub Projects?"
+        },
+        {
+          "id": "AD-12",
+          "type": "should-trigger",
+          "expected": "assess-pm",
+          "prompt": "Recommend where we should track our work items going forward."
+        },
+        {
+          "id": "AD-13",
+          "type": "should-trigger",
+          "expected": "assess-stack",
+          "prompt": "Evaluate a tech stack for this new web app — language, framework, database."
+        },
+        {
+          "id": "AD-14",
+          "type": "should-trigger",
+          "expected": "assess-stack",
+          "prompt": "I want to add Redis as a dependency — check whether that's consistent with our stack."
+        },
+        {
+          "id": "AD-15",
+          "type": "should-trigger",
+          "expected": "assess-testing",
+          "prompt": "Propose a testing strategy and framework choice for this repo."
+        },
+        {
+          "id": "AD-16",
+          "type": "should-trigger",
+          "expected": "assess-testing",
+          "prompt": "How much unit vs integration coverage should we aim for, and with which tools?"
+        },
+        {
+          "id": "AD-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "assess-pm",
+          "expected": "setup-pm",
+          "prompt": "Set up GitHub Projects as the tracker for this repo — we already decided on it."
+        },
+        {
+          "id": "AD-N2",
+          "type": "should-not-trigger",
+          "near_miss_for": "assess-stack",
+          "expected": "record-decision",
+          "prompt": "We already agreed on Postgres yesterday — write that down properly as an architecture decision."
+        },
+        {
+          "id": "AD-N3",
+          "type": "should-not-trigger",
+          "near_miss_for": "assess-*",
+          "expected": "none",
+          "prompt": "Assess the security posture of our login flow."
+        },
+        {
+          "id": "AD-N4",
+          "type": "should-not-trigger",
+          "near_miss_for": "assess-testing",
+          "expected": "none",
+          "prompt": "Write unit tests for the parser module."
+        }
+      ]
+    },
+    {
+      "family": "assess-report",
+      "skills": ["assess-code-quality", "assess-debt"],
+      "prompts": [
+        {
+          "id": "AR-01",
+          "type": "should-trigger",
+          "expected": "assess-code-quality",
+          "prompt": "Give me a code quality report for this repo — complexity, size, coverage, the works."
+        },
+        {
+          "id": "AR-02",
+          "type": "should-trigger",
+          "expected": "assess-code-quality",
+          "prompt": "How maintainable is this codebase right now? Score it."
+        },
+        {
+          "id": "AR-03",
+          "type": "should-trigger",
+          "expected": "assess-debt",
+          "prompt": "Catalog our technical debt and tell us what to fix first."
+        },
+        {
+          "id": "AR-04",
+          "type": "should-trigger",
+          "expected": "assess-debt",
+          "prompt": "The code is full of TODO and FIXME comments — prioritize the cleanup for us."
+        },
+        {
+          "id": "AR-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "assess-code-quality",
+          "expected": "verify-quality",
+          "prompt": "Is the quality gate passing? Run lint, tests and type-check and tell me."
+        },
+        {
+          "id": "AR-N2",
+          "type": "should-not-trigger",
+          "near_miss_for": "assess-debt",
+          "expected": "none",
+          "prompt": "Refactor the auth module to pay down its debt."
+        }
+      ]
+    },
+    {
+      "family": "verification",
+      "skills": ["verify-quality", "verify-done", "verify-adoption"],
+      "prompts": [
+        {
+          "id": "VF-01",
+          "type": "should-trigger",
+          "expected": "verify-quality",
+          "prompt": "Run the quality gates and report what fails."
+        },
+        {
+          "id": "VF-02",
+          "type": "should-trigger",
+          "expected": "verify-quality",
+          "prompt": "Before I push, check whether lint, tests and type-check all pass."
+        },
+        {
+          "id": "VF-03",
+          "type": "should-trigger",
+          "expected": "verify-done",
+          "prompt": "Is PR #42 actually done per our Definition of Done?"
+        },
+        {
+          "id": "VF-04",
+          "type": "should-trigger",
+          "expected": "verify-adoption",
+          "prompt": "Check whether the code in packages/api follows our adopted architecture and tech-stack decisions."
+        },
+        {
+          "id": "VF-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "verify-quality",
+          "expected": "none",
+          "prompt": "Fix the three failing lint errors in src/utils.ts."
+        },
+        {
+          "id": "VF-N2",
+          "type": "should-not-trigger",
+          "near_miss_for": "verify-done",
+          "expected": "review",
+          "prompt": "Give PR #42 a full review and decide whether it can merge."
+        }
+      ]
+    },
+    {
+      "family": "decision-recording",
+      "skills": ["record-decision"],
+      "prompts": [
+        {
+          "id": "DR-01",
+          "type": "should-trigger",
+          "expected": "record-decision",
+          "prompt": "Record the decision to use Postgres as an ADR."
+        },
+        {
+          "id": "DR-02",
+          "type": "should-trigger",
+          "expected": "record-decision",
+          "prompt": "We agreed sessions live in Redis — log that decision in the project's decision records."
+        },
+        {
+          "id": "DR-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "record-decision",
+          "expected": "assess-stack",
+          "prompt": "Which database should we use for this service?"
+        }
+      ]
+    },
+    {
+      "family": "pm-and-backlog",
+      "skills": ["write-issue", "setup-pm", "estimate"],
+      "prompts": [
+        {
+          "id": "PB-01",
+          "type": "should-trigger",
+          "expected": "write-issue",
+          "prompt": "Create a bug issue in our tracker for the login timeout, formatted per our template."
+        },
+        {
+          "id": "PB-02",
+          "type": "should-trigger",
+          "expected": "write-issue",
+          "prompt": "Update story #42's body in GitHub so it matches the user-story template."
+        },
+        {
+          "id": "PB-03",
+          "type": "should-trigger",
+          "expected": "setup-pm",
+          "prompt": "Configure Jira as this project's PM tool and wire up our way of working."
+        },
+        {
+          "id": "PB-04",
+          "type": "should-trigger",
+          "expected": "estimate",
+          "prompt": "How many story points is story #87? Estimate it with our adopted method."
+        },
+        {
+          "id": "PB-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "write-issue",
+          "expected": "plan-tasks",
+          "prompt": "Break story #87 into implementation tasks."
+        },
+        {
+          "id": "PB-N2",
+          "type": "should-not-trigger",
+          "near_miss_for": "setup-pm",
+          "expected": "assess-pm",
+          "prompt": "We haven't picked a tracker yet — what should we use?"
+        }
+      ]
+    },
+    {
+      "family": "ddd-mapping",
+      "skills": ["map-subdomains", "map-contexts"],
+      "prompts": [
+        {
+          "id": "DM-01",
+          "type": "should-trigger",
+          "expected": "map-subdomains",
+          "prompt": "Classify our business capabilities into core, supporting and generic subdomains."
+        },
+        {
+          "id": "DM-02",
+          "type": "should-trigger",
+          "expected": "map-contexts",
+          "prompt": "Map our subdomains to bounded contexts and derive the integration patterns between them."
+        },
+        {
+          "id": "DM-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "map-contexts",
+          "expected": "none",
+          "prompt": "Draw a network diagram of our AWS VPCs and subnets."
+        },
+        {
+          "id": "DM-N2",
+          "type": "should-not-trigger",
+          "near_miss_for": "map-subdomains",
+          "expected": "none",
+          "prompt": "Register the domain name for our new product website."
+        }
+      ]
+    },
+    {
+      "family": "session-continuity",
+      "skills": ["checkpoint", "grill"],
+      "prompts": [
+        {
+          "id": "SC-01",
+          "type": "should-trigger",
+          "expected": "checkpoint",
+          "prompt": "Save our progress on story #313 so we can resume after a context reset."
+        },
+        {
+          "id": "SC-02",
+          "type": "should-trigger",
+          "expected": "checkpoint",
+          "prompt": "Resume work on story #256 from where the last session left off."
+        },
+        {
+          "id": "SC-03",
+          "type": "should-trigger",
+          "expected": "grill",
+          "prompt": "Interview me one question at a time until we're fully aligned on this story's scope."
+        },
+        {
+          "id": "SC-04",
+          "type": "should-trigger",
+          "expected": "grill",
+          "prompt": "Before we start, grill me on the requirements — I want us to reach explicit shared understanding."
+        },
+        {
+          "id": "SC-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "checkpoint",
+          "expected": "none",
+          "prompt": "Commit my work so it isn't lost."
+        },
+        {
+          "id": "SC-N2",
+          "type": "should-not-trigger",
+          "near_miss_for": "grill",
+          "expected": "none",
+          "prompt": "Summarize what we discussed in this conversation."
+        }
+      ]
+    },
+    {
+      "family": "manual-testing",
+      "skills": ["design-manual-tests", "execute-manual-tests"],
+      "prompts": [
+        {
+          "id": "MT-01",
+          "type": "should-trigger",
+          "expected": "design-manual-tests",
+          "prompt": "Create a manual test suite with critical paths for validating our releases."
+        },
+        {
+          "id": "MT-02",
+          "type": "should-trigger",
+          "expected": "execute-manual-tests",
+          "prompt": "Run the manual test suite against the v0.4 release and produce the report."
+        },
+        {
+          "id": "MT-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "design-manual-tests",
+          "expected": "assess-testing",
+          "prompt": "Design our overall automated testing approach — pyramid, tools, coverage targets."
+        },
+        {
+          "id": "MT-N2",
+          "type": "should-not-trigger",
+          "near_miss_for": "execute-manual-tests",
+          "expected": "verify-quality",
+          "prompt": "Run the automated test suite and tell me if everything passes."
+        }
+      ]
+    },
+    {
+      "family": "setup-ops",
+      "skills": ["setup-gates", "manage-flags"],
+      "prompts": [
+        {
+          "id": "SO-01",
+          "type": "should-trigger",
+          "expected": "setup-gates",
+          "prompt": "Configure CI quality gates and husky pre-push hooks for this repo."
+        },
+        {
+          "id": "SO-02",
+          "type": "should-trigger",
+          "expected": "manage-flags",
+          "prompt": "Create a feature flag for the new checkout flow and plan its cleanup."
+        },
+        {
+          "id": "SO-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "setup-gates",
+          "expected": "verify-quality",
+          "prompt": "Is CI green on this branch?"
+        },
+        {
+          "id": "SO-N2",
+          "type": "should-not-trigger",
+          "near_miss_for": "manage-flags",
+          "expected": "none",
+          "prompt": "Add a new option to the app's settings.json config."
+        }
+      ]
+    },
+    {
+      "family": "planning-processes",
+      "skills": [
+        "specify-prd",
+        "plan-initiatives",
+        "plan-epics",
+        "plan-stories",
+        "plan-tasks",
+        "refine-story"
+      ],
+      "prompts": [
+        {
+          "id": "PP-01",
+          "type": "should-trigger",
+          "expected": "specify-prd",
+          "prompt": "Create a PRD for this product idea."
+        },
+        {
+          "id": "PP-02",
+          "type": "should-trigger",
+          "expected": "specify-prd",
+          "prompt": "Our PRD is missing the success-metrics section — update it."
+        },
+        {
+          "id": "PP-03",
+          "type": "should-trigger",
+          "expected": "plan-initiatives",
+          "prompt": "Turn the PRD into prioritized strategic initiatives."
+        },
+        {
+          "id": "PP-04",
+          "type": "should-trigger",
+          "expected": "plan-epics",
+          "prompt": "Break the onboarding initiative down into epics."
+        },
+        {
+          "id": "PP-05",
+          "type": "should-trigger",
+          "expected": "plan-stories",
+          "prompt": "Slice the payments epic into user stories."
+        },
+        {
+          "id": "PP-06",
+          "type": "should-trigger",
+          "expected": "plan-tasks",
+          "prompt": "Story #313 is refined — break it into implementation tasks with a dependency graph."
+        },
+        {
+          "id": "PP-07",
+          "type": "should-trigger",
+          "expected": "refine-story",
+          "prompt": "Refine story #250 so it's sprint-ready, with Given-When-Then acceptance criteria."
+        },
+        {
+          "id": "PP-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "plan-epics",
+          "expected": "write-issue",
+          "prompt": "Create an epic issue in GitHub from this text I already wrote."
+        },
+        {
+          "id": "PP-N2",
+          "type": "should-not-trigger",
+          "near_miss_for": "plan-stories",
+          "expected": "none",
+          "prompt": "Split this oversized pull request into smaller ones."
+        },
+        {
+          "id": "PP-N3",
+          "type": "should-not-trigger",
+          "near_miss_for": "refine-story",
+          "expected": "estimate",
+          "prompt": "Story #250 is already refined — just size it."
+        }
+      ]
+    },
+    {
+      "family": "execution-orchestrators",
+      "skills": ["bootstrap", "implement", "review"],
+      "prompts": [
+        {
+          "id": "EO-01",
+          "type": "should-trigger",
+          "expected": "bootstrap",
+          "prompt": "This is a brand-new project — set up everything: standards, quality gates, PM tool, the full onboarding."
+        },
+        {
+          "id": "EO-02",
+          "type": "should-trigger",
+          "expected": "bootstrap",
+          "prompt": "Run the project setup checklist from PRD verification through PM configuration."
+        },
+        {
+          "id": "EO-03",
+          "type": "should-trigger",
+          "expected": "implement",
+          "prompt": "Implement story #250, working through its tasks one at a time, and open a PR at the end."
+        },
+        {
+          "id": "EO-04",
+          "type": "should-trigger",
+          "expected": "review",
+          "prompt": "Review PR #310 end to end and decide whether it merges."
+        },
+        {
+          "id": "EO-N1",
+          "type": "should-not-trigger",
+          "near_miss_for": "implement",
+          "expected": "none",
+          "prompt": "Fix this one-line typo in the README."
+        },
+        {
+          "id": "EO-N2",
+          "type": "should-not-trigger",
+          "near_miss_for": "bootstrap",
+          "expected": "none",
+          "prompt": "Install the pair CLI in this repo."
+        },
+        {
+          "id": "EO-N3",
+          "type": "should-not-trigger",
+          "near_miss_for": "review",
+          "expected": "verify-quality",
+          "prompt": "Quick sanity check that my branch builds and tests pass — no full review needed."
+        }
+      ]
+    }
+  ]
+}
diff --git a/packages/knowledge-hub/src/skills-conformance-check.test.ts b/packages/knowledge-hub/src/skills-conformance-check.test.ts
new file mode 100644
index 00000000..69137c0a
--- /dev/null
+++ b/packages/knowledge-hub/src/skills-conformance-check.test.ts
@@ -0,0 +1,199 @@
+import { describe, it, expect, afterAll } from 'vitest'
+import { createRequire } from 'node:module'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+interface Frontmatter {
+  keys: string[]
+  values: Record<string, string>
+  body: string
+}
+
+interface RunResult {
+  errors: string[]
+  warnings: string[]
+  skillCount: number
+}
+
+interface ConformanceModule {
+  parseFrontmatter(content: string): Frontmatter | null
+  checkFrontmatterFields(keys: string[]): string[]
+  checkSizeLimits(name?: string, description?: string): string[]
+  extractLinkTargets(body: string): string[]
+  isCheckableTarget(target: string): boolean
+  checkLinks(filePath: string, body: string): string[]
+  checkCatalogCounts(nextContent: string, actualCount: number): string[]
+  collectSkillFiles(skillsDir: string): string[]
+  runChecks(skillsDir: string): RunResult
+  SPEC_FIELDS: string[]
+  PAIR_EXTENSIONS: string[]
+}
+
+const requireCjs = createRequire(import.meta.url)
+const mod = requireCjs('../../../scripts/skills-conformance-check.js') as ConformanceModule
+
+const {
+  parseFrontmatter,
+  checkFrontmatterFields,
+  checkSizeLimits,
+  extractLinkTargets,
+  isCheckableTarget,
+  checkCatalogCounts,
+  runChecks,
+} = mod
+
+describe('parseFrontmatter', () => {
+  it('parses top-level keys and quoted values', () => {
+    const fm = parseFrontmatter('---\nname: foo\ndescription: "Does things."\n---\nBody here')
+    expect(fm).not.toBeNull()
+    expect(fm?.keys).toEqual(['name', 'description'])
+    expect(fm?.values['description']).toBe('Does things.')
+    expect(fm?.body).toBe('Body here')
+  })
+
+  it('returns null when frontmatter is missing', () => {
+    expect(parseFrontmatter('# Just markdown')).toBeNull()
+  })
+
+  it('returns null when frontmatter is unterminated', () => {
+    expect(parseFrontmatter('---\nname: foo\n')).toBeNull()
+  })
+
+  it('ignores indented continuation lines as keys', () => {
+    const fm = parseFrontmatter('---\nmetadata:\n  author: someone\n---\n')
+    expect(fm?.keys).toEqual(['metadata'])
+  })
+})
+
+describe('checkFrontmatterFields', () => {
+  it('accepts spec fields plus the tolerated Pair extension', () => {
+    expect(
+      checkFrontmatterFields([
+        'name',
+        'description',
+        'license',
+        'metadata',
+        'allowed-tools',
+        'version',
+        'author',
+      ]),
+    ).toEqual([])
+  })
+
+  it('rejects assistant-specific fields', () => {
+    const errors = checkFrontmatterFields(['name', 'description', 'disable-model-invocation'])
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('disable-model-invocation')
+  })
+
+  it('requires name and description', () => {
+    const errors = checkFrontmatterFields(['version'])
+    expect(errors.some(e => e.includes('"name"'))).toBe(true)
+    expect(errors.some(e => e.includes('"description"'))).toBe(true)
+  })
+})
+
+describe('checkSizeLimits', () => {
+  it('passes within limits', () => {
+    expect(checkSizeLimits('foo', 'a short description')).toEqual([])
+  })
+
+  it('fails name over 64 chars', () => {
+    expect(checkSizeLimits('x'.repeat(65), 'ok')).toHaveLength(1)
+  })
+
+  it('fails description over 1024 chars and the combined bound', () => {
+    const errors = checkSizeLimits('foo', 'x'.repeat(1025))
+    expect(errors.some(e => e.includes('description is 1025'))).toBe(true)
+    expect(errors.some(e => e.includes('combined'))).toBe(true)
+  })
+
+  it('fails the combined bound even when each field is individually legal', () => {
+    const errors = checkSizeLimits('x'.repeat(60), 'y'.repeat(1000))
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('combined')
+  })
+})
+
+describe('isCheckableTarget', () => {
+  it('skips URLs, anchors, absolute and placeholder paths', () => {
+    expect(isCheckableTarget('https://agentskills.io')).toBe(false)
+    expect(isCheckableTarget('mailto:x@y.z')).toBe(false)
+    expect(isCheckableTarget('#some-section')).toBe(false)
+    expect(isCheckableTarget('/rooted/path.md')).toBe(false)
+    expect(isCheckableTarget('adoption/tech/adr/adr-NNN-topic.md')).toBe(false)
+    expect(isCheckableTarget('decision-log/YYYY-MM-DD-topic.md')).toBe(false)
+    expect(isCheckableTarget('subdomain/<slug>.md')).toBe(false)
+    expect(isCheckableTarget('CP{N}-{slug}.md')).toBe(false)
+    expect(isCheckableTarget('CP*.md')).toBe(false)
+  })
+
+  it('accepts plain relative paths', () => {
+    expect(isCheckableTarget('../../../.pair/adoption/tech/way-of-working.md')).toBe(true)
+    expect(isCheckableTarget('sibling-reference.md')).toBe(true)
+  })
+})
+
+describe('extractLinkTargets', () => {
+  it('extracts markdown link targets', () => {
+    expect(extractLinkTargets('See [guide](../guide.md) and [spec](https://x.io).')).toEqual([
+      '../guide.md',
+      'https://x.io',
+    ])
+  })
+
+  it('ignores links inside fenced code blocks', () => {
+    const body = 'Real [a](./a.md)\n```md\n[example](./not-checked.md)\n```\n'
+    expect(extractLinkTargets(body)).toEqual(['./a.md'])
+  })
+})
+
+describe('checkCatalogCounts', () => {
+  it('warns on every stated count that mismatches the corpus', () => {
+    const content =
+      'Covers the full 33-skill catalog.\n## Skill Catalog (33 skills)\nany of the 33 skills'
+    const warnings = checkCatalogCounts(content, 35)
+    expect(warnings).toHaveLength(3)
+    expect(warnings[0]).toContain('35')
+  })
+
+  it('stays silent when counts match', () => {
+    expect(checkCatalogCounts('all 35 skills are routable', 35)).toEqual([])
+  })
+})
+
+describe('runChecks (fixture corpus)', () => {
+  const root = mkdtempSync(join(tmpdir(), 'skills-conformance-'))
+  afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+  const skill = (dir: string, frontmatter: string, body = '') => {
+    mkdirSync(join(root, dir), { recursive: true })
+    writeFileSync(join(root, dir, 'SKILL.md'), `---\n${frontmatter}\n---\n${body}`)
+  }
+
+  skill('capability/good', 'name: good\ndescription: "Fine."\nversion: 0.1.0\nauthor: Foomakers')
+  skill(
+    'capability/bad-field',
+    'name: bad-field\ndescription: "Has a Claude-only field."\ndisable-model-invocation: true',
+  )
+  skill(
+    'capability/broken-link',
+    'name: broken-link\ndescription: "Points nowhere."',
+    'See [x](./missing.md).',
+  )
+  skill('next', 'name: next\ndescription: "Router."', 'Covers the full 2-skill catalog.')
+
+  it('reports violations per file, catalog warnings, and the corpus count', () => {
+    const { errors, warnings, skillCount } = runChecks(root)
+    expect(skillCount).toBe(4)
+    expect(
+      errors.some(e => e.includes('bad-field') && e.includes('disable-model-invocation')),
+    ).toBe(true)
+    expect(errors.some(e => e.includes('broken-link') && e.includes('./missing.md'))).toBe(true)
+    expect(errors.some(e => e.includes('good/SKILL.md'))).toBe(false)
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0]).toContain('2-skill')
+    expect(warnings[0]).toContain('4 skills')
+  })
+})
diff --git a/scripts/skills-conformance-check.js b/scripts/skills-conformance-check.js
new file mode 100644
index 00000000..c0d574de
--- /dev/null
+++ b/scripts/skills-conformance-check.js
@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * Skills Conformance Check — static conformance gate for the dataset skill corpus.
+ *
+ * Enforces the authoring effectiveness standard (story #313, principle 8 "constraints"
+ * of contributing/writing-skills) over packages/knowledge-hub/dataset/.skills/:
+ *
+ *   1. Frontmatter portability — only agentskills.io-core top-level fields
+ *      (name, description, license, compatibility, metadata, allowed-tools)
+ *      plus the tolerated Pair extension (version, author, kept top-level for
+ *      provenance). Assistant-specific fields (e.g. disable-model-invocation)
+ *      are portability violations.
+ *   2. Size limits — name ≤ 64 chars, description ≤ 1024 chars (spec), and
+ *      name+description combined ≤ 1024 chars (Pair's stricter bound).
+ *   3. Pointer resolution — relative file links in SKILL.md bodies resolve to
+ *      existing files/dirs in the dataset.
+ *   4. Catalog counts — every "N skills"/"N-skill" figure stated in next's
+ *      SKILL.md matches the real corpus dir count.
+ *      TODO(#313/T1): promote catalog-count findings from warning to error once
+ *      T1 regenerates next's catalog (currently states 33, corpus has 35).
+ *
+ * Exit 0 = conformant (warnings allowed), Exit 1 = violations.
+ */
+const fs = require('fs')
+const path = require('path')
+
+const ROOT = path.resolve(__dirname, '..')
+const SKILLS_DIR = path.join(ROOT, 'packages/knowledge-hub/dataset/.skills')
+
+// agentskills.io spec top-level fields
+const SPEC_FIELDS = ['name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools']
+// Tolerated Pair extension: provenance kept top-level (see writing-skills principle 8)
+const PAIR_EXTENSIONS = ['version', 'author']
+
+const NAME_MAX = 64
+const DESCRIPTION_MAX = 1024
+const COMBINED_MAX = 1024
+
+// --- Frontmatter ---
+
+function parseFrontmatter(content) {
+  const lines = content.split('\n')
+  if (lines[0] !== '---') return null
+  const end = lines.indexOf('---', 1)
+  if (end === -1) return null
+  const keys = []
+  const values = {}
+  for (const line of lines.slice(1, end)) {
+    const m = line.match(/^([A-Za-z][A-Za-z0-9_-]*):(.*)$/)
+    if (!m) continue // continuation or nested (indented) line — not a top-level key
+    keys.push(m[1])
+    let value = m[2].trim()
+    if (
+      (value.startsWith('"') && value.endsWith('"') && value.length > 1) ||
+      (value.startsWith("'") && value.endsWith("'") && value.length > 1)
+    ) {
+      value = value.slice(1, -1)
+    }
+    values[m[1]] = value
+  }
+  return { keys, values, body: lines.slice(end + 1).join('\n') }
+}
+
+function checkFrontmatterFields(keys) {
+  const errors = []
+  const allowed = new Set([...SPEC_FIELDS, ...PAIR_EXTENSIONS])
+  for (const key of keys) {
+    if (!allowed.has(key)) {
+      errors.push(
+        `non-portable frontmatter field "${key}" (allowed: spec fields ${SPEC_FIELDS.join(', ')} + tolerated Pair extension ${PAIR_EXTENSIONS.join(', ')})`,
+      )
+    }
+  }
+  for (const required of ['name', 'description']) {
+    if (!keys.includes(required)) {
+      errors.push(`missing required frontmatter field "${required}"`)
+    }
+  }
+  return errors
+}
+
+function checkSizeLimits(name, description) {
+  const errors = []
+  const nameLen = (name || '').length
+  const descLen = (description || '').length
+  if (nameLen > NAME_MAX) {
+    errors.push(`name is ${nameLen} chars (spec max ${NAME_MAX})`)
+  }
+  if (descLen > DESCRIPTION_MAX) {
+    errors.push(`description is ${descLen} chars (spec max ${DESCRIPTION_MAX})`)
+  }
+  if (nameLen + descLen > COMBINED_MAX) {
+    errors.push(`name+description is ${nameLen + descLen} chars combined (Pair max ${COMBINED_MAX})`)
+  }
+  return errors
+}
+
+// --- Pointer resolution ---
+
+function extractLinkTargets(body) {
+  // Markdown links, excluding fenced code blocks (examples often contain template paths)
+  const withoutFences = body.replace(/```[\s\S]*?```/g, '')
+  const targets = []
+  for (const m of withoutFences.matchAll(/\]\(([^)]+)\)/g)) {
+    targets.push(m[1].split(' ')[0].trim())
+  }
+  return targets
+}
+
+function isCheckableTarget(target) {
+  if (!target) return false
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target)) return false // URL scheme (http:, mailto:, …)
+  if (target.startsWith('#')) return false // in-document anchor
+  if (target.startsWith('/')) return false // absolute path — install-time, not dataset-relative
+  if (/[<>{}*[\]]/.test(target)) return false // placeholder/template path
+  if (/\bNNN\b|\bYYYY\b/.test(target)) return false // pattern path (adr-NNN-…, YYYY-MM-DD-…)
+  return true
+}
+
+function checkLinks(filePath, body) {
+  const errors = []
+  const dir = path.dirname(filePath)
+  for (const target of extractLinkTargets(body)) {
+    if (!isCheckableTarget(target)) continue
+    const resolved = path.resolve(dir, target.split('#')[0])
+    if (!fs.existsSync(resolved)) {
+      errors.push(`broken relative reference "${target}"`)
+    }
+  }
+  return errors
+}
+
+// --- Catalog counts ---
+
+function checkCatalogCounts(nextContent, actualCount) {
+  const warnings = []
+  for (const m of nextContent.matchAll(/(\d+)[-\s]skills?\b/g)) {
+    const stated = parseInt(m[1], 10)
+    if (stated !== actualCount) {
+      warnings.push(`next/SKILL.md states "${m[0]}" but the corpus has ${actualCount} skills`)
+    }
+  }
+  return warnings
+}
+
+// --- Corpus walk ---
+
+function collectSkillFiles(skillsDir) {
+  const files = []
+  const categories = fs
+    .readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+  for (const cat of categories) {
+    const catDir = path.join(skillsDir, cat.name)
+    const subdirs = fs
+      .readdirSync(catDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+    if (subdirs.length > 0) {
+      for (const sub of subdirs) {
+        const f = path.join(catDir, sub, 'SKILL.md')
+        if (fs.existsSync(f)) files.push(f)
+      }
+    } else if (fs.existsSync(path.join(catDir, 'SKILL.md'))) {
+      // Meta skill: category dir itself contains SKILL.md (e.g. next)
+      files.push(path.join(catDir, 'SKILL.md'))
+    }
+  }
+  return files
+}
+
+function runChecks(skillsDir) {
+  const errors = []
+  const warnings = []
+  const files = collectSkillFiles(skillsDir)
+
+  for (const file of files) {
+    const rel = path.relative(skillsDir, file)
+    const content = fs.readFileSync(file, 'utf-8')
+    const fm = parseFrontmatter(content)
+    if (!fm) {
+      errors.push(`${rel}: missing or malformed YAML frontmatter`)
+      continue
+    }
+    for (const e of checkFrontmatterFields(fm.keys)) errors.push(`${rel}: ${e}`)
+    for (const e of checkSizeLimits(fm.values.name, fm.values.description)) {
+      errors.push(`${rel}: ${e}`)
+    }
+    for (const e of checkLinks(file, fm.body)) errors.push(`${rel}: ${e}`)
+  }
+
+  const nextFile = files.find((f) => path.basename(path.dirname(f)) === 'next')
+  if (nextFile) {
+    warnings.push(...checkCatalogCounts(fs.readFileSync(nextFile, 'utf-8'), files.length))
+  }
+
+  return { errors, warnings, skillCount: files.length }
+}
+
+// --- CLI ---
+
+if (require.main === module) {
+  const { errors, warnings, skillCount } = runChecks(SKILLS_DIR)
+
+  console.log('Skills Conformance Check')
+  console.log('========================')
+
+  if (warnings.length > 0) {
+    console.log(`WARN — ${warnings.length} non-blocking finding${warnings.length > 1 ? 's' : ''} (error once #313/T1 lands):\n`)
+    for (const w of warnings) console.log(`  • ${w}`)
+    console.log()
+  }
+
+  if (errors.length === 0) {
+    console.log(`PASS — ${skillCount} skills conformant (frontmatter portability, size limits, pointer resolution)`)
+    process.exit(0)
+  } else {
+    console.log(`FAIL — ${errors.length} violation${errors.length > 1 ? 's' : ''}\n`)
+    for (const e of errors) console.log(`  • ${e}`)
+    console.log()
+    process.exit(1)
+  }
+}
+
+module.exports = {
+  parseFrontmatter,
+  checkFrontmatterFields,
+  checkSizeLimits,
+  extractLinkTargets,
+  isCheckableTarget,
+  checkLinks,
+  checkCatalogCounts,
+  collectSkillFiles,
+  runChecks,
+  SPEC_FIELDS,
+  PAIR_EXTENSIONS,
+}

From 7c81769561a508a6e18e3daf033fea114520158a Mon Sep 17 00:00:00 2001
From: Gianluca Carucci <gianluca@carucci.org>
Date: Mon, 13 Jul 2026 08:12:26 +0200
Subject: [PATCH 2/4] [#313] refactor: T7 conformance logic into tested module,
 CLI calls it (review)

- port scripts/skills-conformance-check.js -> packages/knowledge-hub/src/skills-conformance-check.ts
  (typed ESM module, check-broken-links.ts style; require.main CLI guard prints same PASS/WARN/FAIL)
- sibling test imports the module directly (drop createRequire bridge); 18 cases unchanged
- package script skills:conformance = ts-node src/skills-conformance-check.ts (mirrors check:links)
- root skills:conformance delegates to the package; quality-gate + CI unchanged
- delete root script (single source of truth); eval README path ref updated

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 package.json                                  |   2 +-
 packages/knowledge-hub/eval/README.md         |   4 +-
 packages/knowledge-hub/package.json           |   3 +-
 .../src/skills-conformance-check.test.ts      |  35 +---
 .../src/skills-conformance-check.ts           | 170 +++++++++---------
 5 files changed, 97 insertions(+), 117 deletions(-)
 rename scripts/skills-conformance-check.js => packages/knowledge-hub/src/skills-conformance-check.ts (56%)

diff --git a/package.json b/package.json
index 4906245c..34c98a72 100644
--- a/package.json
+++ b/package.json
@@ -25,7 +25,7 @@
     "a11y:report:html": "turbo a11y:report:html",
     "hygiene:check": "node scripts/code-hygiene-check.js",
     "docs:staleness": "node scripts/docs-staleness-check.js",
-    "skills:conformance": "node scripts/skills-conformance-check.js",
+    "skills:conformance": "pnpm --filter @pair/knowledge-hub skills:conformance",
     "dup:check": "jscpd apps packages",
     "quality-gate": "turbo ts:check test lint && turbo prettier:fix mdlint:fix && ./tools/markdownlint-config/bin/markdownlint-fix.sh '*.md' && pnpm hygiene:check && pnpm docs:staleness && pnpm skills:conformance && pnpm dup:check",
     "e2e": "pnpm --filter @pair/website e2e",
diff --git a/packages/knowledge-hub/eval/README.md b/packages/knowledge-hub/eval/README.md
index ce1ba2a7..524d5326 100644
--- a/packages/knowledge-hub/eval/README.md
+++ b/packages/knowledge-hub/eval/README.md
@@ -68,5 +68,5 @@ When a skill's description changes (e.g. T3 of #313):
 ## Related gates
 
 Static conformance (frontmatter portability, size limits, pointer resolution, catalog counts) is
-enforced separately by `pnpm skills:conformance` (`scripts/skills-conformance-check.js`), wired
-into `quality-gate` and CI.
+enforced separately by `pnpm skills:conformance` (`src/skills-conformance-check.ts`, run via
+`ts-node`), wired into `quality-gate` and CI.
diff --git a/packages/knowledge-hub/package.json b/packages/knowledge-hub/package.json
index 51f6aefb..8f11d96e 100644
--- a/packages/knowledge-hub/package.json
+++ b/packages/knowledge-hub/package.json
@@ -18,7 +18,8 @@
     "mdlint:check": "markdownlint-check",
     "mdlint:fix": "markdownlint-fix",
     "check:links": "ts-node src/check-broken-links.ts",
-    "transfer:dataset": "ts-node src/transfer-dataset.ts"
+    "transfer:dataset": "ts-node src/transfer-dataset.ts",
+    "skills:conformance": "ts-node src/skills-conformance-check.ts"
   },
   "devDependencies": {
     "@pair/eslint-config": "workspace:*",
diff --git a/packages/knowledge-hub/src/skills-conformance-check.test.ts b/packages/knowledge-hub/src/skills-conformance-check.test.ts
index 69137c0a..ae42ff6b 100644
--- a/packages/knowledge-hub/src/skills-conformance-check.test.ts
+++ b/packages/knowledge-hub/src/skills-conformance-check.test.ts
@@ -1,39 +1,8 @@
 import { describe, it, expect, afterAll } from 'vitest'
-import { createRequire } from 'node:module'
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-
-interface Frontmatter {
-  keys: string[]
-  values: Record<string, string>
-  body: string
-}
-
-interface RunResult {
-  errors: string[]
-  warnings: string[]
-  skillCount: number
-}
-
-interface ConformanceModule {
-  parseFrontmatter(content: string): Frontmatter | null
-  checkFrontmatterFields(keys: string[]): string[]
-  checkSizeLimits(name?: string, description?: string): string[]
-  extractLinkTargets(body: string): string[]
-  isCheckableTarget(target: string): boolean
-  checkLinks(filePath: string, body: string): string[]
-  checkCatalogCounts(nextContent: string, actualCount: number): string[]
-  collectSkillFiles(skillsDir: string): string[]
-  runChecks(skillsDir: string): RunResult
-  SPEC_FIELDS: string[]
-  PAIR_EXTENSIONS: string[]
-}
-
-const requireCjs = createRequire(import.meta.url)
-const mod = requireCjs('../../../scripts/skills-conformance-check.js') as ConformanceModule
-
-const {
+import {
   parseFrontmatter,
   checkFrontmatterFields,
   checkSizeLimits,
@@ -41,7 +10,7 @@ const {
   isCheckableTarget,
   checkCatalogCounts,
   runChecks,
-} = mod
+} from './skills-conformance-check'
 
 describe('parseFrontmatter', () => {
   it('parses top-level keys and quoted values', () => {
diff --git a/scripts/skills-conformance-check.js b/packages/knowledge-hub/src/skills-conformance-check.ts
similarity index 56%
rename from scripts/skills-conformance-check.js
rename to packages/knowledge-hub/src/skills-conformance-check.ts
index c0d574de..3036b155 100644
--- a/scripts/skills-conformance-check.js
+++ b/packages/knowledge-hub/src/skills-conformance-check.ts
@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /**
  * Skills Conformance Check — static conformance gate for the dataset skill corpus.
  *
@@ -10,59 +9,81 @@
  *      plus the tolerated Pair extension (version, author, kept top-level for
  *      provenance). Assistant-specific fields (e.g. disable-model-invocation)
  *      are portability violations.
- *   2. Size limits — name ≤ 64 chars, description ≤ 1024 chars (spec), and
- *      name+description combined ≤ 1024 chars (Pair's stricter bound).
+ *   2. Size limits — name <= 64 chars, description <= 1024 chars (spec), and
+ *      name+description combined <= 1024 chars (Pair's stricter bound).
  *   3. Pointer resolution — relative file links in SKILL.md bodies resolve to
  *      existing files/dirs in the dataset.
  *   4. Catalog counts — every "N skills"/"N-skill" figure stated in next's
  *      SKILL.md matches the real corpus dir count.
  *      TODO(#313/T1): promote catalog-count findings from warning to error once
- *      T1 regenerates next's catalog (currently states 33, corpus has 35).
+ *      T1 (#325) regenerates next's catalog (currently states 33, corpus has 35).
  *
- * Exit 0 = conformant (warnings allowed), Exit 1 = violations.
+ * Runnable as a CLI via `ts-node src/skills-conformance-check.ts`
+ * (package script `skills:conformance`). Exit 0 = conformant (warnings allowed),
+ * Exit 1 = violations.
  */
-const fs = require('fs')
-const path = require('path')
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { basename, dirname, join, relative, resolve } from 'path'
 
-const ROOT = path.resolve(__dirname, '..')
-const SKILLS_DIR = path.join(ROOT, 'packages/knowledge-hub/dataset/.skills')
+const ROOT = join(__dirname, '..')
+const SKILLS_DIR = join(ROOT, 'dataset', '.skills')
 
 // agentskills.io spec top-level fields
-const SPEC_FIELDS = ['name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools']
+export const SPEC_FIELDS = [
+  'name',
+  'description',
+  'license',
+  'compatibility',
+  'metadata',
+  'allowed-tools',
+]
 // Tolerated Pair extension: provenance kept top-level (see writing-skills principle 8)
-const PAIR_EXTENSIONS = ['version', 'author']
+export const PAIR_EXTENSIONS = ['version', 'author']
 
 const NAME_MAX = 64
 const DESCRIPTION_MAX = 1024
 const COMBINED_MAX = 1024
 
+export interface Frontmatter {
+  keys: string[]
+  values: Record<string, string>
+  body: string
+}
+
+export interface RunResult {
+  errors: string[]
+  warnings: string[]
+  skillCount: number
+}
+
 // --- Frontmatter ---
 
-function parseFrontmatter(content) {
+function unquote(value: string): string {
+  const quoted =
+    (value.startsWith('"') && value.endsWith('"') && value.length > 1) ||
+    (value.startsWith("'") && value.endsWith("'") && value.length > 1)
+  return quoted ? value.slice(1, -1) : value
+}
+
+export function parseFrontmatter(content: string): Frontmatter | null {
   const lines = content.split('\n')
   if (lines[0] !== '---') return null
   const end = lines.indexOf('---', 1)
   if (end === -1) return null
-  const keys = []
-  const values = {}
+  const keys: string[] = []
+  const values: Record<string, string> = {}
   for (const line of lines.slice(1, end)) {
     const m = line.match(/^([A-Za-z][A-Za-z0-9_-]*):(.*)$/)
     if (!m) continue // continuation or nested (indented) line — not a top-level key
-    keys.push(m[1])
-    let value = m[2].trim()
-    if (
-      (value.startsWith('"') && value.endsWith('"') && value.length > 1) ||
-      (value.startsWith("'") && value.endsWith("'") && value.length > 1)
-    ) {
-      value = value.slice(1, -1)
-    }
-    values[m[1]] = value
+    const key = m[1] as string
+    keys.push(key)
+    values[key] = unquote((m[2] as string).trim())
   }
   return { keys, values, body: lines.slice(end + 1).join('\n') }
 }
 
-function checkFrontmatterFields(keys) {
-  const errors = []
+export function checkFrontmatterFields(keys: string[]): string[] {
+  const errors: string[] = []
   const allowed = new Set([...SPEC_FIELDS, ...PAIR_EXTENSIONS])
   for (const key of keys) {
     if (!allowed.has(key)) {
@@ -79,8 +100,8 @@ function checkFrontmatterFields(keys) {
   return errors
 }
 
-function checkSizeLimits(name, description) {
-  const errors = []
+export function checkSizeLimits(name?: string, description?: string): string[] {
+  const errors: string[] = []
   const nameLen = (name || '').length
   const descLen = (description || '').length
   if (nameLen > NAME_MAX) {
@@ -90,24 +111,26 @@ function checkSizeLimits(name, description) {
     errors.push(`description is ${descLen} chars (spec max ${DESCRIPTION_MAX})`)
   }
   if (nameLen + descLen > COMBINED_MAX) {
-    errors.push(`name+description is ${nameLen + descLen} chars combined (Pair max ${COMBINED_MAX})`)
+    errors.push(
+      `name+description is ${nameLen + descLen} chars combined (Pair max ${COMBINED_MAX})`,
+    )
   }
   return errors
 }
 
 // --- Pointer resolution ---
 
-function extractLinkTargets(body) {
+export function extractLinkTargets(body: string): string[] {
   // Markdown links, excluding fenced code blocks (examples often contain template paths)
   const withoutFences = body.replace(/```[\s\S]*?```/g, '')
-  const targets = []
+  const targets: string[] = []
   for (const m of withoutFences.matchAll(/\]\(([^)]+)\)/g)) {
-    targets.push(m[1].split(' ')[0].trim())
+    targets.push((m[1] as string).split(' ')[0]!.trim())
   }
   return targets
 }
 
-function isCheckableTarget(target) {
+export function isCheckableTarget(target: string): boolean {
   if (!target) return false
   if (/^[a-z][a-z0-9+.-]*:/i.test(target)) return false // URL scheme (http:, mailto:, …)
   if (target.startsWith('#')) return false // in-document anchor
@@ -117,13 +140,13 @@ function isCheckableTarget(target) {
   return true
 }
 
-function checkLinks(filePath, body) {
-  const errors = []
-  const dir = path.dirname(filePath)
+export function checkLinks(filePath: string, body: string): string[] {
+  const errors: string[] = []
+  const dir = dirname(filePath)
   for (const target of extractLinkTargets(body)) {
     if (!isCheckableTarget(target)) continue
-    const resolved = path.resolve(dir, target.split('#')[0])
-    if (!fs.existsSync(resolved)) {
+    const resolved = resolve(dir, target.split('#')[0]!)
+    if (!existsSync(resolved)) {
       errors.push(`broken relative reference "${target}"`)
     }
   }
@@ -132,10 +155,10 @@ function checkLinks(filePath, body) {
 
 // --- Catalog counts ---
 
-function checkCatalogCounts(nextContent, actualCount) {
-  const warnings = []
+export function checkCatalogCounts(nextContent: string, actualCount: number): string[] {
+  const warnings: string[] = []
   for (const m of nextContent.matchAll(/(\d+)[-\s]skills?\b/g)) {
-    const stated = parseInt(m[1], 10)
+    const stated = parseInt(m[1] as string, 10)
     if (stated !== actualCount) {
       warnings.push(`next/SKILL.md states "${m[0]}" but the corpus has ${actualCount} skills`)
     }
@@ -145,60 +168,55 @@ function checkCatalogCounts(nextContent, actualCount) {
 
 // --- Corpus walk ---
 
-function collectSkillFiles(skillsDir) {
-  const files = []
-  const categories = fs
-    .readdirSync(skillsDir, { withFileTypes: true })
-    .filter((d) => d.isDirectory())
+export function collectSkillFiles(skillsDir: string): string[] {
+  const files: string[] = []
+  const categories = readdirSync(skillsDir, { withFileTypes: true }).filter(d => d.isDirectory())
   for (const cat of categories) {
-    const catDir = path.join(skillsDir, cat.name)
-    const subdirs = fs
-      .readdirSync(catDir, { withFileTypes: true })
-      .filter((d) => d.isDirectory())
-      .map((d) => d.name)
+    const catDir = join(skillsDir, cat.name)
+    const subdirs = readdirSync(catDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name)
     if (subdirs.length > 0) {
       for (const sub of subdirs) {
-        const f = path.join(catDir, sub, 'SKILL.md')
-        if (fs.existsSync(f)) files.push(f)
+        const f = join(catDir, sub, 'SKILL.md')
+        if (existsSync(f)) files.push(f)
       }
-    } else if (fs.existsSync(path.join(catDir, 'SKILL.md'))) {
+    } else if (existsSync(join(catDir, 'SKILL.md'))) {
       // Meta skill: category dir itself contains SKILL.md (e.g. next)
-      files.push(path.join(catDir, 'SKILL.md'))
+      files.push(join(catDir, 'SKILL.md'))
     }
   }
   return files
 }
 
-function runChecks(skillsDir) {
-  const errors = []
-  const warnings = []
+export function runChecks(skillsDir: string): RunResult {
+  const errors: string[] = []
+  const warnings: string[] = []
   const files = collectSkillFiles(skillsDir)
 
   for (const file of files) {
-    const rel = path.relative(skillsDir, file)
-    const content = fs.readFileSync(file, 'utf-8')
+    const rel = relative(skillsDir, file)
+    const content = readFileSync(file, 'utf-8')
     const fm = parseFrontmatter(content)
     if (!fm) {
       errors.push(`${rel}: missing or malformed YAML frontmatter`)
       continue
     }
     for (const e of checkFrontmatterFields(fm.keys)) errors.push(`${rel}: ${e}`)
-    for (const e of checkSizeLimits(fm.values.name, fm.values.description)) {
+    for (const e of checkSizeLimits(fm.values['name'], fm.values['description'])) {
       errors.push(`${rel}: ${e}`)
     }
     for (const e of checkLinks(file, fm.body)) errors.push(`${rel}: ${e}`)
   }
 
-  const nextFile = files.find((f) => path.basename(path.dirname(f)) === 'next')
+  const nextFile = files.find(f => basename(dirname(f)) === 'next')
   if (nextFile) {
-    warnings.push(...checkCatalogCounts(fs.readFileSync(nextFile, 'utf-8'), files.length))
+    warnings.push(...checkCatalogCounts(readFileSync(nextFile, 'utf-8'), files.length))
   }
 
   return { errors, warnings, skillCount: files.length }
 }
 
-// --- CLI ---
-
 if (require.main === module) {
   const { errors, warnings, skillCount } = runChecks(SKILLS_DIR)
 
@@ -206,13 +224,17 @@ if (require.main === module) {
   console.log('========================')
 
   if (warnings.length > 0) {
-    console.log(`WARN — ${warnings.length} non-blocking finding${warnings.length > 1 ? 's' : ''} (error once #313/T1 lands):\n`)
+    console.log(
+      `WARN — ${warnings.length} non-blocking finding${warnings.length > 1 ? 's' : ''} (error once #313/T1 lands):\n`,
+    )
     for (const w of warnings) console.log(`  • ${w}`)
     console.log()
   }
 
   if (errors.length === 0) {
-    console.log(`PASS — ${skillCount} skills conformant (frontmatter portability, size limits, pointer resolution)`)
+    console.log(
+      `PASS — ${skillCount} skills conformant (frontmatter portability, size limits, pointer resolution)`,
+    )
     process.exit(0)
   } else {
     console.log(`FAIL — ${errors.length} violation${errors.length > 1 ? 's' : ''}\n`)
@@ -220,18 +242,6 @@ if (require.main === module) {
     console.log()
     process.exit(1)
   }
-}
-
-module.exports = {
-  parseFrontmatter,
-  checkFrontmatterFields,
-  checkSizeLimits,
-  extractLinkTargets,
-  isCheckableTarget,
-  checkLinks,
-  checkCatalogCounts,
-  collectSkillFiles,
-  runChecks,
-  SPEC_FIELDS,
-  PAIR_EXTENSIONS,
+} else {
+  // allow importing the module without executing
 }

From 1593ad22e0c371edc1e0d0dda6339a73b5a6c237 Mon Sep 17 00:00:00 2001
From: Gianluca Carucci <gianluca@carucci.org>
Date: Mon, 13 Jul 2026 08:57:15 +0200
Subject: [PATCH 3/4] [#313] refactor: role-based src/ layout (tools/ +
 conformance/) + baseline wording

- git mv 9 files: CLIs+siblings -> src/tools/, dataset-assertion tests -> src/conformance/
- path-depth fixups (one extra ..): tools/ ROOT/DATASET, conformance/ readFileSync dataset paths
- package.json check:links/transfer:dataset/skills:conformance -> src/tools/<file>.ts
- drop stale src/index.ts from vitest.config exclude
- eval baseline: 'Both ambiguities'->'two kinds' (review finding 2); README path

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/knowledge-hub/eval/README.md         |  4 ++--
 .../eval/results/2026-07-12-baseline.md       |  4 ++--
 packages/knowledge-hub/package.json           |  6 +++---
 .../src/{ => conformance}/agents-md.test.ts   |  2 +-
 .../assess-output-only.test.ts                |  4 ++--
 .../{ => conformance}/quality-model.test.ts   | 21 ++++++++++---------
 .../{ => tools}/check-broken-links.test.ts    |  0
 .../src/{ => tools}/check-broken-links.ts     |  2 +-
 .../skills-conformance-check.test.ts          |  0
 .../{ => tools}/skills-conformance-check.ts   |  2 +-
 .../src/{ => tools}/transfer-dataset.test.ts  |  0
 .../src/{ => tools}/transfer-dataset.ts       |  6 +++---
 packages/knowledge-hub/vitest.config.ts       |  1 -
 13 files changed, 26 insertions(+), 26 deletions(-)
 rename packages/knowledge-hub/src/{ => conformance}/agents-md.test.ts (85%)
 rename packages/knowledge-hub/src/{ => conformance}/assess-output-only.test.ts (95%)
 rename packages/knowledge-hub/src/{ => conformance}/quality-model.test.ts (90%)
 rename packages/knowledge-hub/src/{ => tools}/check-broken-links.test.ts (100%)
 rename packages/knowledge-hub/src/{ => tools}/check-broken-links.ts (97%)
 rename packages/knowledge-hub/src/{ => tools}/skills-conformance-check.test.ts (100%)
 rename packages/knowledge-hub/src/{ => tools}/skills-conformance-check.ts (99%)
 rename packages/knowledge-hub/src/{ => tools}/transfer-dataset.test.ts (100%)
 rename packages/knowledge-hub/src/{ => tools}/transfer-dataset.ts (95%)

diff --git a/packages/knowledge-hub/eval/README.md b/packages/knowledge-hub/eval/README.md
index 524d5326..63760a55 100644
--- a/packages/knowledge-hub/eval/README.md
+++ b/packages/knowledge-hub/eval/README.md
@@ -68,5 +68,5 @@ When a skill's description changes (e.g. T3 of #313):
 ## Related gates
 
 Static conformance (frontmatter portability, size limits, pointer resolution, catalog counts) is
-enforced separately by `pnpm skills:conformance` (`src/skills-conformance-check.ts`, run via
-`ts-node`), wired into `quality-gate` and CI.
+enforced separately by `pnpm skills:conformance` (`src/tools/skills-conformance-check.ts`, run
+via `ts-node`), wired into `quality-gate` and CI.
diff --git a/packages/knowledge-hub/eval/results/2026-07-12-baseline.md b/packages/knowledge-hub/eval/results/2026-07-12-baseline.md
index 81ba40f1..dd256ef8 100644
--- a/packages/knowledge-hub/eval/results/2026-07-12-baseline.md
+++ b/packages/knowledge-hub/eval/results/2026-07-12-baseline.md
@@ -42,8 +42,8 @@ inside the family was carried by the single domain noun** (architecture, infrast
 observability, …); the shared scaffold contributed zero discrimination while consuming most of
 the description budget. Consequences observed:
 
-- Both ambiguities on the decision side (AD-12, PB-N2, AD-14) sit exactly where the domain noun
-  stops discriminating (pm vs setup-pm; stack vs verify-adoption).
+- The ambiguities fall into two kinds (AD-12, PB-N2, AD-14) — both sitting exactly where the
+  domain noun stops discriminating (pm vs setup-pm; stack vs verify-adoption).
 - Domain-keyword prompts pass, but only because the eval prompts contain the noun; prompts
   phrased without it (AD-02 "bring Copilot into our workflow", AD-10 "zero telemetry") were
   near-ties resolved by judgment (see notes below).
diff --git a/packages/knowledge-hub/package.json b/packages/knowledge-hub/package.json
index 8f11d96e..11747682 100644
--- a/packages/knowledge-hub/package.json
+++ b/packages/knowledge-hub/package.json
@@ -17,9 +17,9 @@
     "lint:fix": "lint-fix",
     "mdlint:check": "markdownlint-check",
     "mdlint:fix": "markdownlint-fix",
-    "check:links": "ts-node src/check-broken-links.ts",
-    "transfer:dataset": "ts-node src/transfer-dataset.ts",
-    "skills:conformance": "ts-node src/skills-conformance-check.ts"
+    "check:links": "ts-node src/tools/check-broken-links.ts",
+    "transfer:dataset": "ts-node src/tools/transfer-dataset.ts",
+    "skills:conformance": "ts-node src/tools/skills-conformance-check.ts"
   },
   "devDependencies": {
     "@pair/eslint-config": "workspace:*",
diff --git a/packages/knowledge-hub/src/agents-md.test.ts b/packages/knowledge-hub/src/conformance/agents-md.test.ts
similarity index 85%
rename from packages/knowledge-hub/src/agents-md.test.ts
rename to packages/knowledge-hub/src/conformance/agents-md.test.ts
index 2dbcaadc..58f399f6 100644
--- a/packages/knowledge-hub/src/agents-md.test.ts
+++ b/packages/knowledge-hub/src/conformance/agents-md.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect } from 'vitest'
 import { readFileSync } from 'fs'
 import { join } from 'path'
 
-const AGENTS_MD = readFileSync(join(__dirname, '../dataset/AGENTS.md'), 'utf-8')
+const AGENTS_MD = readFileSync(join(__dirname, '../../dataset/AGENTS.md'), 'utf-8')
 
 describe('dataset AGENTS.md paths', () => {
   it('does not reference the legacy adopted/knowledge-base scheme', () => {
diff --git a/packages/knowledge-hub/src/assess-output-only.test.ts b/packages/knowledge-hub/src/conformance/assess-output-only.test.ts
similarity index 95%
rename from packages/knowledge-hub/src/assess-output-only.test.ts
rename to packages/knowledge-hub/src/conformance/assess-output-only.test.ts
index 3a32c68d..bcbab685 100644
--- a/packages/knowledge-hub/src/assess-output-only.test.ts
+++ b/packages/knowledge-hub/src/conformance/assess-output-only.test.ts
@@ -6,8 +6,8 @@ import { join } from 'path'
 // record-decision is the sole adoption writer; assess-debt has no scan-mode.
 // See adr-009-assess-output-only.md.
 
-const DATASET = join(__dirname, '../dataset/.skills/capability')
-const MIRROR = join(__dirname, '../../../.claude/skills')
+const DATASET = join(__dirname, '../../dataset/.skills/capability')
+const MIRROR = join(__dirname, '../../../../.claude/skills')
 
 const ASSESS_SKILLS = [
   'ai',
diff --git a/packages/knowledge-hub/src/quality-model.test.ts b/packages/knowledge-hub/src/conformance/quality-model.test.ts
similarity index 90%
rename from packages/knowledge-hub/src/quality-model.test.ts
rename to packages/knowledge-hub/src/conformance/quality-model.test.ts
index fa748dc8..04fdb860 100644
--- a/packages/knowledge-hub/src/quality-model.test.ts
+++ b/packages/knowledge-hub/src/conformance/quality-model.test.ts
@@ -4,22 +4,19 @@ import { join } from 'path'
 
 const QUALITY_ASSURANCE_DIR = join(
   __dirname,
-  '../dataset/.pair/knowledge/guidelines/quality-assurance',
+  '../../dataset/.pair/knowledge/guidelines/quality-assurance',
 )
 
 const QUALITY_MODEL = readFileSync(
-  join(
-    __dirname,
-    '../dataset/.pair/knowledge/guidelines/quality-assurance/quality-model.md',
-  ),
+  join(__dirname, '../../dataset/.pair/knowledge/guidelines/quality-assurance/quality-model.md'),
   'utf-8',
 )
 const RISK_MATRIX_EXAMPLE = readFileSync(
-  join(__dirname, '../dataset/.pair/knowledge/assets/risk-matrix-example.md'),
+  join(__dirname, '../../dataset/.pair/knowledge/assets/risk-matrix-example.md'),
   'utf-8',
 )
 const QA_README = readFileSync(
-  join(__dirname, '../dataset/.pair/knowledge/guidelines/quality-assurance/README.md'),
+  join(__dirname, '../../dataset/.pair/knowledge/guidelines/quality-assurance/README.md'),
   'utf-8',
 )
 
@@ -65,7 +62,9 @@ describe('quality-model.md — structure', () => {
       /Reviewer counts and SLAs are \*\*KB defaults\*\*[\s\S]{0,300}Argument > Adoption > KB default/,
     )
     expect(QUALITY_MODEL).toContain('tier.red.reviewers: 2')
-    expect(QUALITY_MODEL).toMatch(/this part is not overridable, only the reviewer count and SLA are/)
+    expect(QUALITY_MODEL).toMatch(
+      /this part is not overridable, only the reviewer count and SLA are/,
+    )
   })
 
   it('defines the chromatic tag projection', () => {
@@ -85,7 +84,9 @@ describe('quality-model.md — structure', () => {
 
   it("documents classify's propose-then-write Tag Projection flow", () => {
     expect(QUALITY_MODEL).toMatch(/does `tech\/risk-matrix\.md` have a `## Tag Projection` section/)
-    expect(QUALITY_MODEL).toMatch(/No Tag Projection declared yet\. Activate `risk:green\|yellow\|red`/)
+    expect(QUALITY_MODEL).toMatch(
+      /No Tag Projection declared yet\. Activate `risk:green\|yellow\|red`/,
+    )
     expect(QUALITY_MODEL).toMatch(/records the opt-out so this isn't asked again/)
     expect(QUALITY_MODEL).toMatch(
       /the compiled matrix is written to the story\/PR body \*\*regardless of the answer\*\*/,
@@ -127,7 +128,7 @@ describe('quality-model.md — structure', () => {
 
   it('resolves every §7 nested-taxonomy pointer link to a file on disk', () => {
     const section = QUALITY_MODEL.split('## 7. Nested Taxonomy')[1]
-    const links = [...section.matchAll(/\]\(([^)]+)\)/g)].map((m) => m[1])
+    const links = [...section.matchAll(/\]\(([^)]+)\)/g)].map(m => m[1])
     expect(links.length).toBeGreaterThanOrEqual(9)
     for (const link of links) {
       expect(existsSync(join(QUALITY_ASSURANCE_DIR, link))).toBe(true)
diff --git a/packages/knowledge-hub/src/check-broken-links.test.ts b/packages/knowledge-hub/src/tools/check-broken-links.test.ts
similarity index 100%
rename from packages/knowledge-hub/src/check-broken-links.test.ts
rename to packages/knowledge-hub/src/tools/check-broken-links.test.ts
diff --git a/packages/knowledge-hub/src/check-broken-links.ts b/packages/knowledge-hub/src/tools/check-broken-links.ts
similarity index 97%
rename from packages/knowledge-hub/src/check-broken-links.ts
rename to packages/knowledge-hub/src/tools/check-broken-links.ts
index e8ef76e8..28f5b537 100644
--- a/packages/knowledge-hub/src/check-broken-links.ts
+++ b/packages/knowledge-hub/src/tools/check-broken-links.ts
@@ -2,7 +2,7 @@ import { join } from 'path'
 import { fileSystemService } from '@pair/content-ops'
 import { validatePathOps } from '@pair/content-ops'
 
-const ROOT = join(__dirname, '..')
+const ROOT = join(__dirname, '..', '..')
 const DATASET = join(ROOT, 'dataset')
 const ERRORS_PATH = join(ROOT, 'errors.txt')
 const EXCLUSION_LIST: string[] = [
diff --git a/packages/knowledge-hub/src/skills-conformance-check.test.ts b/packages/knowledge-hub/src/tools/skills-conformance-check.test.ts
similarity index 100%
rename from packages/knowledge-hub/src/skills-conformance-check.test.ts
rename to packages/knowledge-hub/src/tools/skills-conformance-check.test.ts
diff --git a/packages/knowledge-hub/src/skills-conformance-check.ts b/packages/knowledge-hub/src/tools/skills-conformance-check.ts
similarity index 99%
rename from packages/knowledge-hub/src/skills-conformance-check.ts
rename to packages/knowledge-hub/src/tools/skills-conformance-check.ts
index 3036b155..576e0a0b 100644
--- a/packages/knowledge-hub/src/skills-conformance-check.ts
+++ b/packages/knowledge-hub/src/tools/skills-conformance-check.ts
@@ -25,7 +25,7 @@
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import { basename, dirname, join, relative, resolve } from 'path'
 
-const ROOT = join(__dirname, '..')
+const ROOT = join(__dirname, '..', '..')
 const SKILLS_DIR = join(ROOT, 'dataset', '.skills')
 
 // agentskills.io spec top-level fields
diff --git a/packages/knowledge-hub/src/transfer-dataset.test.ts b/packages/knowledge-hub/src/tools/transfer-dataset.test.ts
similarity index 100%
rename from packages/knowledge-hub/src/transfer-dataset.test.ts
rename to packages/knowledge-hub/src/tools/transfer-dataset.test.ts
diff --git a/packages/knowledge-hub/src/transfer-dataset.ts b/packages/knowledge-hub/src/tools/transfer-dataset.ts
similarity index 95%
rename from packages/knowledge-hub/src/transfer-dataset.ts
rename to packages/knowledge-hub/src/tools/transfer-dataset.ts
index 043cc8e4..26cc298f 100644
--- a/packages/knowledge-hub/src/transfer-dataset.ts
+++ b/packages/knowledge-hub/src/tools/transfer-dataset.ts
@@ -4,7 +4,7 @@ import { movePathOps, copyPathOps } from '@pair/content-ops'
 import { stripAllMarkers, applyTransformCommands, validateMarkers } from '@pair/content-ops'
 import type { SyncOptions, SkillNameMap, CopyPathOpsResult } from '@pair/content-ops'
 
-const DATASET = join(__dirname, '..', 'dataset')
+const DATASET = join(__dirname, '..', '..', 'dataset')
 
 export function parseJson(arg: string): Record<string, unknown> {
   // try parse as JSON string first
@@ -180,8 +180,8 @@ if (require.main === module) {
     const [source, target, mode, optionsArg] = args
     if (!source || !target) {
       console.error(
-        'Usage: ts-node src/transfer-dataset.ts [--root <path>] <source> <target> [mode] [optionsJsonOrFile]\n' +
-          '       ts-node src/transfer-dataset.ts [--root <path>] --pipeline <json-array>',
+        'Usage: ts-node src/tools/transfer-dataset.ts [--root <path>] <source> <target> [mode] [optionsJsonOrFile]\n' +
+          '       ts-node src/tools/transfer-dataset.ts [--root <path>] --pipeline <json-array>',
       )
       process.exit(1)
     }
diff --git a/packages/knowledge-hub/vitest.config.ts b/packages/knowledge-hub/vitest.config.ts
index d1d0b637..b56b0fba 100644
--- a/packages/knowledge-hub/vitest.config.ts
+++ b/packages/knowledge-hub/vitest.config.ts
@@ -15,7 +15,6 @@ export default defineConfig({
         'coverage/',
         '**/*.test.ts',
         '**/*.spec.ts',
-        'src/index.ts',
         'vitest.config.ts',
       ],
       thresholds: {

From 1549fdc6cb0d8ba416651957d1c4c48456f3e714 Mon Sep 17 00:00:00 2001
From: Gianluca Carucci <gianluca@carucci.org>
Date: Mon, 13 Jul 2026 20:01:29 +0200
Subject: [PATCH 4/4] [#313] fix: close block-scalar size-gate bypass + cite
 principle-8 attribution (review)

- parseFrontmatter folds YAML block scalars (>, |, chomping) to real length so an
  over-1024 block-style description is measured, not read as len ~1 (was bypassable)
- negative tests: >1024 block-scalar description -> violation (drives CLI exit 1) + fold unit tests
- checkSizeLimits: comment citing principle 8 (per-field 1024 = spec, combined = Pair);
  labels verified correct, not flipped

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../tools/skills-conformance-check.test.ts    | 37 +++++++++++++
 .../src/tools/skills-conformance-check.ts     | 52 +++++++++++++++++--
 2 files changed, 84 insertions(+), 5 deletions(-)

diff --git a/packages/knowledge-hub/src/tools/skills-conformance-check.test.ts b/packages/knowledge-hub/src/tools/skills-conformance-check.test.ts
index ae42ff6b..3f0a3910 100644
--- a/packages/knowledge-hub/src/tools/skills-conformance-check.test.ts
+++ b/packages/knowledge-hub/src/tools/skills-conformance-check.test.ts
@@ -33,6 +33,20 @@ describe('parseFrontmatter', () => {
     const fm = parseFrontmatter('---\nmetadata:\n  author: someone\n---\n')
     expect(fm?.keys).toEqual(['metadata'])
   })
+
+  it('folds a `>` block scalar to its real length and resumes at the next key', () => {
+    const fm = parseFrontmatter(
+      '---\nname: foo\ndescription: >\n  line one\n  line two\nversion: 0.1.0\n---\n',
+    )
+    expect(fm?.keys).toEqual(['name', 'description', 'version'])
+    expect(fm?.values['description']).toBe('line one line two')
+    expect(fm?.values['version']).toBe('0.1.0')
+  })
+
+  it('folds a `|` block scalar (with chomping) into a measurable value', () => {
+    const fm = parseFrontmatter('---\ndescription: |-\n  alpha\n  beta\n---\n')
+    expect(fm?.values['description']).toBe('alpha beta')
+  })
 })
 
 describe('checkFrontmatterFields', () => {
@@ -166,3 +180,26 @@ describe('runChecks (fixture corpus)', () => {
     expect(warnings[0]).toContain('4 skills')
   })
 })
+
+describe('runChecks — block-scalar size-gate cannot be bypassed (finding 1)', () => {
+  const root = mkdtempSync(join(tmpdir(), 'skills-conformance-block-'))
+  afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+  it('an over-1024 `>` block-scalar description is a violation (drives CLI exit 1)', () => {
+    const longLine = 'x'.repeat(1100)
+    mkdirSync(join(root, 'capability/blocky'), { recursive: true })
+    writeFileSync(
+      join(root, 'capability/blocky', 'SKILL.md'),
+      `---\nname: blocky\ndescription: >\n  ${longLine}\n---\nbody`,
+    )
+    const { errors } = runChecks(root)
+    // Real folded length (~1100) is measured, so the ≤1024 cap catches it instead of
+    // reading the bare `>` as length ~1. A non-empty errors list ⇒ the CLI process.exit(1).
+    expect(
+      errors.some(
+        e => e.includes('blocky') && e.includes('description is') && e.includes('spec max'),
+      ),
+    ).toBe(true)
+    expect(errors.length).toBeGreaterThan(0)
+  })
+})
diff --git a/packages/knowledge-hub/src/tools/skills-conformance-check.ts b/packages/knowledge-hub/src/tools/skills-conformance-check.ts
index 576e0a0b..3ef9f8a8 100644
--- a/packages/knowledge-hub/src/tools/skills-conformance-check.ts
+++ b/packages/knowledge-hub/src/tools/skills-conformance-check.ts
@@ -18,7 +18,7 @@
  *      TODO(#313/T1): promote catalog-count findings from warning to error once
  *      T1 (#325) regenerates next's catalog (currently states 33, corpus has 35).
  *
- * Runnable as a CLI via `ts-node src/skills-conformance-check.ts`
+ * Runnable as a CLI via `ts-node src/tools/skills-conformance-check.ts`
  * (package script `skills:conformance`). Exit 0 = conformant (warnings allowed),
  * Exit 1 = violations.
  */
@@ -58,6 +58,9 @@ export interface RunResult {
 
 // --- Frontmatter ---
 
+// YAML block-scalar indicator as a value: `|`, `>`, with optional `-`/`+` chomping.
+const BLOCK_SCALAR_RE = /^[|>][+-]?$/
+
 function unquote(value: string): string {
   const quoted =
     (value.startsWith('"') && value.endsWith('"') && value.length > 1) ||
@@ -65,6 +68,31 @@ function unquote(value: string): string {
   return quoted ? value.slice(1, -1) : value
 }
 
+// Fold a YAML block scalar into a single measurable string so its real length is
+// counted by the size gate (a raw `description: >` line alone is length ~1 and would
+// otherwise bypass the ≤1024 check). Consumes indented continuation lines starting at
+// `start`; the block ends at the first line dedented to column 0 (next top-level key)
+// or at `end`. Returns the joined text and the index to resume top-level parsing from.
+function foldBlockScalar(
+  lines: string[],
+  start: number,
+  end: number,
+): { text: string; next: number } {
+  const parts: string[] = []
+  let i = start
+  for (; i < end; i++) {
+    const line = lines[i] as string
+    if (line.trim() === '') {
+      parts.push('')
+      continue
+    }
+    const indent = line.length - line.trimStart().length
+    if (indent === 0) break // dedented to key level — block ended
+    parts.push(line.trimStart())
+  }
+  return { text: parts.join(' ').trim(), next: i }
+}
+
 export function parseFrontmatter(content: string): Frontmatter | null {
   const lines = content.split('\n')
   if (lines[0] !== '---') return null
@@ -72,12 +100,24 @@ export function parseFrontmatter(content: string): Frontmatter | null {
   if (end === -1) return null
   const keys: string[] = []
   const values: Record<string, string> = {}
-  for (const line of lines.slice(1, end)) {
-    const m = line.match(/^([A-Za-z][A-Za-z0-9_-]*):(.*)$/)
-    if (!m) continue // continuation or nested (indented) line — not a top-level key
+  let i = 1
+  while (i < end) {
+    const m = (lines[i] as string).match(/^([A-Za-z][A-Za-z0-9_-]*):(.*)$/)
+    if (!m) {
+      i++ // continuation or nested (indented) line — not a top-level key
+      continue
+    }
     const key = m[1] as string
     keys.push(key)
-    values[key] = unquote((m[2] as string).trim())
+    const inline = (m[2] as string).trim()
+    if (BLOCK_SCALAR_RE.test(inline)) {
+      const folded = foldBlockScalar(lines, i + 1, end)
+      values[key] = folded.text
+      i = folded.next
+    } else {
+      values[key] = unquote(inline)
+      i++
+    }
   }
   return { keys, values, body: lines.slice(end + 1).join('\n') }
 }
@@ -104,6 +144,8 @@ export function checkSizeLimits(name?: string, description?: string): string[] {
   const errors: string[] = []
   const nameLen = (name || '').length
   const descLen = (description || '').length
+  // Attribution per principle 8: agentskills.io spec caps name (64) and description
+  // (1024) SEPARATELY (hence "spec max"); the combined ≤1024 is PAIR's stricter bound.
   if (nameLen > NAME_MAX) {
     errors.push(`name is ${nameLen} chars (spec max ${NAME_MAX})`)
   }