@eir-labs/coltrane 0.4.0

package/domain_types/user-flow-verdict.json

@@ -0,0 +1,60 @@
+{
+  "slug": "user-flow-verdict",
+  "version": 1,
+  "extends": "Interpretation",
+  "domain": "self_judge",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "criteria": {
+        "type": "object",
+        "properties": {
+          "tool_pick_appropriate": {
+            "type": "object",
+            "properties": {
+              "score": { "type": ["number", "null"] },
+              "rationale": { "type": "string" }
+            }
+          },
+          "response_faithful": {
+            "type": "object",
+            "properties": {
+              "score": { "type": ["number", "null"] },
+              "rationale": { "type": "string" }
+            }
+          },
+          "genome_state_valid": {
+            "type": "object",
+            "properties": {
+              "score": { "type": ["number", "null"] },
+              "rationale": { "type": "string" }
+            }
+          },
+          "typed_error_on_malformed": {
+            "type": "object",
+            "properties": {
+              "score": { "type": ["number", "null"] },
+              "rationale": { "type": "string" }
+            }
+          },
+          "multi_turn_continuity": {
+            "type": "object",
+            "properties": {
+              "score": { "type": ["number", "null"] },
+              "rationale": { "type": "string" }
+            }
+          }
+        }
+      },
+      "overall_score": { "type": ["number", "null"] },
+      "overall_pass": { "type": "boolean" },
+      "top_finding": { "type": "string" }
+    }
+  },
+  "required_fields": [
+    "criteria",
+    "overall_pass",
+    "claims"
+  ]
+}

package/domain_types/verdict-record.json

@@ -0,0 +1,39 @@
+{
+  "slug": "verdict-record",
+  "version": 1,
+  "extends": "Verdict",
+  "domain": "patent-triage",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "recommended": {
+        "type": "string",
+        "enum": [
+          "FILEABLE",
+          "REFINE-FIRST",
+          "NOT-FILEABLE",
+          "INSUFFICIENT-EVIDENCE"
+        ]
+      },
+      "disclosure_input_sha": {
+        "type": "string"
+      },
+      "coverage_report_sha": {
+        "type": "string"
+      },
+      "examine_round_record_sha": {
+        "type": "string"
+      },
+      "caveat": {
+        "type": "string"
+      }
+    }
+  },
+  "required_fields": [
+    "disclosure_input_sha",
+    "coverage_report_sha",
+    "examine_round_record_sha",
+    "checks"
+  ]
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@eir-labs/coltrane",
+  "version": "0.4.0",
+  "description": "A methodology engine — a typed substrate for defining agents, composing multi-phase standards, dispatching gigs, and sealing every output to a content-addressed ledger. Ships as an MCP server.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Eir",
+  "homepage": "https://github.com/eir-dev/coltrane#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eir-dev/coltrane.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eir-dev/coltrane/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "agents",
+    "methodology",
+    "workflow-engine"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "coltrane-server": "./dist/src/server_entry.js"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/src",
+    "agents",
+    "standards",
+    "skills",
+    "domain_types",
+    "core_types",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && cp src/skill_runner.mjs dist/src/ && chmod +x dist/src/server_entry.js dist/src/server_relay.js",
+    "dev": "tsc --watch",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "verify": "tsc --noEmit && vitest run && npm run test:failure-modes && npm run test:honest-broker && npm run test:security && npm run e2e:offline",
+    "e2e": "npm run build && vitest run --config tests/e2e/vitest.config.ts",
+    "e2e:offline": "npm run build && vitest run --config tests/e2e/vitest.offline.config.ts",
+    "test:failure-modes": "vitest run --config tests/failure_modes/vitest.config.ts",
+    "test:honest-broker": "vitest run --config tests/honest_broker/vitest.config.ts",
+    "test:security": "vitest run --config tests/security/vitest.config.ts",
+    "lint:imports": "git ls-files 'src/**/*.ts' 'src/**/*.tsx' 'src/**/*.js' 'src/**/*.mjs' 'src/**/*.cjs' 'tests/**/*.ts' 'tests/**/*.tsx' 'tests/**/*.js' 'tests/**/*.mjs' 'tests/**/*.cjs' | bash scripts/check_imports.sh"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@slack/socket-mode": "^2.0.7",
+    "@slack/web-api": "^7.16.0",
+    "ajv": "^8.17.0",
+    "ajv-formats": "^3.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.6",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}

package/skills/citation-verify/fixtures/basic.json

@@ -0,0 +1,14 @@
+{
+  "id": "grounded",
+  "description": "a claim whose terms appear in the fetched text is verified via fetch",
+  "input": {
+    "claim": "Deno enforces permissions through runtime interception",
+    "fetched_text": "The security model is enforced by the Deno runtime through interception of permission-bearing operations, and is not dependent on the underlying operating system.",
+    "method": "fetch"
+  },
+  "assertions": [
+    { "path": "verified", "op": "is_boolean" },
+    { "path": "method", "op": "equals", "value": "fetch" },
+    { "path": "coverage", "op": "is_number" }
+  ]
+}

package/skills/citation-verify/meta.json

@@ -0,0 +1,10 @@
+{
+  "slug": "citation-verify",
+  "version": 1,
+  "skill_type": "verification",
+  "input_type": "citation-claim",
+  "output_type": "citation-verdict",
+  "determinism_ratio": 1.0,
+  "permission": { "tier": 0 },
+  "description": "Ground a claim about a source against the source's FETCHED text: returns verified + the supporting quote, or unverified. Codifies retrieved-not-recalled — a claim is verified only when its key terms actually appear in the fetched text, never from a snippet or memory."
+}

package/skills/citation-verify/skill.mjs

@@ -0,0 +1,26 @@
+// citation-verify — is a claim about a source actually grounded in that source's FETCHED text?
+// Pure/deterministic given { claim, fetched_text }: a claim is verified only when enough of its
+// content terms appear in the fetched text, and the method is recorded as 'fetch' (vs 'snippet').
+// This is the retrieved-not-recalled gate: no fetched_text -> unverified, never a guess.
+const STOP = new Set(["a","an","the","of","to","for","and","or","with","is","in","on","by","at","from","as","that","it","its","this","these","those","not","does","do"]);
+
+function terms(text) {
+  return String(text).toLowerCase().replace(/[^a-z0-9 ]/g, " ").split(/\s+/).filter((w) => w.length > 3 && !STOP.has(w));
+}
+
+export default function run(input) {
+  const claim = input && input.claim ? String(input.claim) : "";
+  const fetched = input && typeof input.fetched_text === "string" ? input.fetched_text : null;
+  const method = input && input.method === "snippet" ? "snippet" : "fetch";
+  if (fetched === null) {
+    return { verified: false, method, reason: "no fetched_text — cannot ground a claim without retrieving the source", matched_terms: [] };
+  }
+  const hay = fetched.toLowerCase();
+  const t = terms(claim);
+  const matched = t.filter((w) => hay.includes(w));
+  const ratio = t.length ? matched.length / t.length : 0;
+  // a claim is grounded only when most of its content terms are present in the fetched text,
+  // and only fetched (not snippet) provenance can support an anticipation finding.
+  const verified = method === "fetch" && ratio >= 0.6;
+  return { verified, method, coverage: ratio, matched_terms: matched };
+}

package/skills/claim-element-decompose/fixtures/basic.json

@@ -0,0 +1,11 @@
+{
+  "id": "three-elements",
+  "description": "a comprising-claim with two clauses + a wherein splits into elements",
+  "input": {
+    "claim_text": "A method comprising: spawning a process with permission flags from a declared grant; verifying a content hash of the code unit, wherein a mismatch substitutes a model-reasoning resolution."
+  },
+  "assertions": [
+    { "path": "elements", "op": "exists" },
+    { "path": "elements.0", "op": "is_string" }
+  ]
+}

package/skills/claim-element-decompose/meta.json

@@ -0,0 +1,10 @@
+{
+  "slug": "claim-element-decompose",
+  "version": 1,
+  "skill_type": "extraction",
+  "input_type": "claim-text",
+  "output_type": "claim-elements",
+  "determinism_ratio": 1.0,
+  "permission": { "tier": 0 },
+  "description": "Split an independent claim into its functional elements on 'comprising' / ';' / 'wherein'. Pure/deterministic — the element list feeds prior-art search and the element-mapping matrix."
+}

package/skills/claim-element-decompose/skill.mjs

@@ -0,0 +1,14 @@
+// claim-element-decompose — independent claim text -> functional elements. Pure/deterministic.
+// Splits on the preamble 'comprising:' then on ';' (the standard element separators), with
+// 'wherein' clauses kept as their own elements. Same claim -> same elements.
+export default function run(input) {
+  const text = input && input.claim_text ? String(input.claim_text) : "";
+  const afterPreamble = text.split(/comprising:?/i).slice(1).join("comprising") || text;
+  const raw = afterPreamble
+    .split(/;|\bwherein\b/i)
+    .map((s) => s.replace(/\s+/g, " ").trim())
+    .filter((s) => s.length > 0);
+  // drop a trailing bare period fragment
+  const elements = raw.filter((s) => s.replace(/[.\s]/g, "").length > 2);
+  return { elements };
+}

package/skills/diamond-cutting-discipline/fixtures/basic.json

@@ -0,0 +1,13 @@
+{
+  "id": "basic",
+  "description": "contract: produces the typed output. Runs once the reasoning half is resolved in eval mode — see skills open questions.",
+  "input": {
+    "idea": "a method that cleaves prior art along a single named plane"
+  },
+  "assertions": [
+    {
+      "path": "verdict",
+      "op": "is_string"
+    }
+  ]
+}

package/skills/diamond-cutting-discipline/meta.json

@@ -0,0 +1,19 @@
+{
+  "slug": "diamond-cutting-discipline",
+  "version": 1,
+  "skill_type": "analysis",
+  "permission": {
+    "tier": 0
+  },
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "verdict": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "verdict"
+    ]
+  }
+}

package/skills/diamond-cutting-discipline/skill.md

@@ -0,0 +1,46 @@
+## The diamond-cutting discipline
+
+The principle the patent-triage pipeline runs on. Every phase grounds in this distinction.
+
+### Empty vs invariant
+
+- The **empty** part of an idea is its *representation*: the vocabulary, the file format, the programming language, the library, the vendor, the specific implementation. Empty does not mean unimportant — it means re-statable without loss.
+- The **invariant** part is the *territory*: the single plane the idea splits the world along — what may be practiced freely and what is excluded.
+
+Claims are vehicles. What an inventor owns is not the claim's words; it is the territory the words exclude from public practice. Many phrasings would bound the same territory with the same fidelity. The words are a surveyor's stake; the land is what gets enforced.
+
+### The two errors
+
+- **Welding to the representation.** A claim welded to a specific hash function, library, or vendor looks precise but shatters when the representation ages out, while the territory it was meant to hold never moved. Hard is not tough.
+- **Drifting from the invariant.** Treating the territory as something to restate loosely. The stake still stands but no longer marks land anyone would fight over. Broad enough to read onto prior art, or so narrow a competitor walks around it.
+
+The ideal is the narrow band of scope at which the cleave clears the prior art and stays enabled — the broadest reach that still bounds.
+
+### The four cuts (run in order, before drafting any claim language)
+
+1. **Name the cleave in one sentence,** in plain language, stripped of any specific format, library, vendor, or programming language. If the sentence will not form, there is no invention yet — only an implementation description. (The point of novelty.)
+2. **Name three to five things this is** *not.* Each is a piece of prior art that comes close but bounds a different space. These are sharper boundary markers than the cleave-description alone. (Distinguishing the art; negative limitations.)
+3. **Name three ways the cleave could fail.** Where does the territory actually end? The abstractness objection, the enablement gap, the over-broad reading — the validity attack surface (§101 / §112). Naming them is the only way to know what you hold.
+4. **Re-state the cleave in different representations.** Plain English, sketch, another language, pitch to a non-engineer. If a phrasing breaks it, that phrasing was load-bearing — refine until the cleave survives re-description. This is the doctrine of equivalents (*Graver Tank*) run in reverse: stress-test your own cleave against the very test a court would later use against an infringer.
+
+Only after the four cuts do you write the claim.
+
+### Cleave-grade vocabulary
+
+- **TIGHT** — single sentence, one independent claim, ≤3 functional elements joined by `comprising`, every word load-bearing, an explicit distancing limitation when prior art names a close hit.
+- **LOOSE** — survives re-statement but still carries representation-level load (a library name, a format, a vendor) that should be stripped. Drives REFINE-FIRST.
+- **UNBOUNDED** — no single plane named; the claim reads broadly enough to anticipate or be anticipated. Drives REFINE-FIRST or NOT-FILEABLE depending on novelty.
+
+### Triage verdict vocabulary
+
+- **FILEABLE** — cleave is TIGHT, novelty PASS, ≥3 failure modes named with bounds, ≥5 what-this-is-NOT distinctions. A provisional-draft skeleton accompanies the verdict.
+- **REFINE-FIRST** — one or more axes are marginal. The verdict names the axis (novelty / scope / clarity / enablement) and the refinement direction.
+- **NOT-FILEABLE** — prior art anticipates, or no single-sentence claim can be drawn. The verdict cites the prior art (or the missing plane) in plain English.
+
+### What this discipline excludes
+
+- Vocabulary lock-in. Each phase's output must survive translation into a different representation. If swapping the library or vendor name breaks the claim, the claim was welded to the representation.
+- Drafting before reading. The four cuts come before any claim language. A pipeline that drafts before reading is sawing across the grain.
+- Verdicts without named axes. Every REFINE-FIRST names the axis; every NOT-FILEABLE cites the anticipating art or the missing plane; every FILEABLE attaches the draft skeleton.
+
+*Know the empty from the invariant. Read before you cut. Name the plane, name what it is not, name where it breaks, restate it until it survives restating. Then strike once, cleanly, and let the words be only the stake.*

package/skills/element-mapping-matrix/fixtures/basic.json

@@ -0,0 +1,13 @@
+{
+  "id": "coverage",
+  "description": "2 elements x 1 ref with one present cell -> matrix + coverage_fraction 0.5",
+  "input": {
+    "elements": ["spawn with declared grant", "hash-mismatch to model reasoning"],
+    "references": ["NodeShield"],
+    "cells": { "0:0": "present", "1:0": "absent" }
+  },
+  "assertions": [
+    { "path": "coverage_fraction", "op": "equals", "value": 0.5 },
+    { "path": "matrix.0.cells.0.status", "op": "equals", "value": "present" }
+  ]
+}

package/skills/element-mapping-matrix/meta.json

@@ -0,0 +1,10 @@
+{
+  "slug": "element-mapping-matrix",
+  "version": 1,
+  "skill_type": "analysis",
+  "input_type": "elements-and-refs",
+  "output_type": "anticipation-matrix",
+  "determinism_ratio": 1.0,
+  "permission": { "tier": 0 },
+  "description": "Scaffold the element x reference anticipation matrix (rows = claim elements, cols = prior-art refs, cells default 'unmapped') and compute coverage_fraction from any filled cells. The deterministic structure the model then fills cell-by-cell — replaces a hand-typed confidence with a recomputable measure."
+}

package/skills/element-mapping-matrix/skill.mjs

@@ -0,0 +1,20 @@
+// element-mapping-matrix — scaffold the element x reference anticipation grid + a recomputable
+// coverage_fraction. Pure/deterministic. Rows = claim elements, cols = prior-art references;
+// each cell defaults 'unmapped' unless a status is supplied in input.cells (keyed
+// "<elementIndex>:<refIndex>" -> "present"|"absent"|"partial"). coverage_fraction is the share
+// of (element x ref) cells judged present|partial — a derived number, not a hand-typed score.
+const FILLED = new Set(["present", "partial"]);
+export default function run(input) {
+  const elements = Array.isArray(input.elements) ? input.elements : [];
+  const references = Array.isArray(input.references) ? input.references : [];
+  const cells = (input && typeof input.cells === "object" && input.cells) || {};
+  const matrix = elements.map((el, i) => ({
+    element: el,
+    cells: references.map((ref, j) => ({ reference: ref, status: cells[`${i}:${j}`] ?? "unmapped" })),
+  }));
+  const total = elements.length * references.length;
+  let filled = 0;
+  for (const row of matrix) for (const c of row.cells) if (FILLED.has(c.status)) filled++;
+  const coverage_fraction = total > 0 ? filled / total : 0;
+  return { matrix, coverage_fraction, element_count: elements.length, reference_count: references.length };
+}

package/skills/number-adder/fixtures/basic.json

@@ -0,0 +1,9 @@
+{
+  "id": "basic",
+  "description": "3 + 5 = 8",
+  "input": { "a": 3, "b": 5 },
+  "expected_output": { "sum": 8, "source": "skill://number-adder@1" },
+  "assertions": [
+    { "path": "sum", "op": "equals", "value": 8 }
+  ]
+}

package/skills/number-adder/meta.json

@@ -0,0 +1,10 @@
+{
+  "slug": "number-adder",
+  "version": 1,
+  "skill_type": "extraction",
+  "input_type": "addends",
+  "output_type": "sum-result",
+  "determinism_ratio": 1.0,
+  "permission": { "tier": 0 },
+  "description": "Add two numbers. Pure, deterministic — the smallest skill that proves the package + fixtures + determinism loop."
+}

package/skills/number-adder/skill.mjs

@@ -0,0 +1,12 @@
+// number-adder — the execution half. Pure: input in, output out, no I/O, no LLM.
+// determinism_ratio 1.0 (the code resolves the entire output; the residual is empty).
+//
+// `source` is the skill's own identity. A skill-backed chair seals the skill's return value
+// verbatim, so when that chair is Signal-cored the skill is the only thing that can answer
+// "where did this come from" — and the #227 ruling makes that answer mandatory on every
+// Signal, bare or subtyped. It is a constant, so the skill stays pure and every field still
+// originates in code (determinism_ratio 1.0 is unchanged).
+export default function run(input) {
+  const { a, b } = input;
+  return { sum: a + b, source: "skill://number-adder@1" };
+}

package/skills/patent-fetch/fixtures/parse.json

@@ -0,0 +1,18 @@
+{
+  "id": "parse",
+  "description": "parses a PatentsView payload into structured hits, corpus tagged patentsview",
+  "input": {
+    "query": "permission tier subprocess sandbox",
+    "mock_response": {
+      "patents": [
+        { "patent_id": "US10000000", "patent_title": "Sandboxed execution of untrusted code", "patent_date": "2018-06-19", "patent_abstract": "A method for executing untrusted code in a permission-scoped subprocess." }
+      ]
+    }
+  },
+  "assertions": [
+    { "path": "corpus", "op": "equals", "value": "patentsview" },
+    { "path": "hits", "op": "exists" },
+    { "path": "hits.0.title", "op": "is_string" },
+    { "path": "hits.0.patent_number", "op": "equals", "value": "US10000000" }
+  ]
+}

package/skills/patent-fetch/meta.json

@@ -0,0 +1,11 @@
+{
+  "slug": "patent-fetch",
+  "version": 1,
+  "skill_type": "extraction",
+  "input_type": "patent-query",
+  "output_type": "patent-hits",
+  "corpus": "patentsview",
+  "determinism_ratio": 1.0,
+  "permission": { "tier": 0 },
+  "description": "Query the USPTO PatentsView corpus for prior art. Deterministic core is the parser (mock_response -> structured hits); the live path fetches when given a query. corpus is always 'patentsview' so coverage-report can attest which corpus was searched."
+}

package/skills/patent-fetch/skill.mjs

@@ -0,0 +1,34 @@
+// patent-fetch — query USPTO PatentsView for prior art.
+//
+// The deterministic core is the PARSER: given input.mock_response (a PatentsView payload),
+// it maps patents -> structured hits with zero I/O (this is what the fixture exercises, so
+// determinism_ratio is 1.0). The live path fetches when given input.query; if the cage
+// blocks the network, it degrades to { hits: [], error } and the agent's own WebFetch grant
+// is the retrieval path. corpus is always 'patentsview' — coverage-report attests it.
+function parse(resp) {
+  const patents = resp && Array.isArray(resp.patents) ? resp.patents : [];
+  return patents.map((p) => ({
+    source: "USPTO PatentsView",
+    patent_number: p.patent_id ?? p.patent_number ?? "",
+    title: p.patent_title ?? p.title ?? "",
+    date: p.patent_date ?? p.date ?? "",
+    abstract: p.patent_abstract ?? p.abstract ?? "",
+  }));
+}
+
+export default async function run(input) {
+  const query = input && input.query ? String(input.query) : "";
+  if (input && input.mock_response) {
+    return { corpus: "patentsview", query, hits: parse(input.mock_response) };
+  }
+  const q = JSON.stringify({ _text_any: { patent_title: query } });
+  const f = JSON.stringify(["patent_id", "patent_title", "patent_date", "patent_abstract"]);
+  const url = `https://search.patentsview.org/api/v1/patent/?q=${encodeURIComponent(q)}&f=${encodeURIComponent(f)}`;
+  try {
+    const res = await fetch(url);
+    const json = await res.json();
+    return { corpus: "patentsview", query, hits: parse({ patents: json.patents ?? [] }) };
+  } catch (e) {
+    return { corpus: "patentsview", query, hits: [], error: String((e && e.message) || e) };
+  }
+}

package/skills/query-expand/fixtures/basic.json

@@ -0,0 +1,14 @@
+{
+  "id": "basic",
+  "description": "two claim elements expand to per-element keyword queries plus a combined query",
+  "input": {
+    "elements": [
+      "spawning a process with operating-system permission flags from a declared grant",
+      "content-hash verification of the code unit before execution"
+    ]
+  },
+  "assertions": [
+    { "path": "queries", "op": "exists" },
+    { "path": "queries.0", "op": "is_string" }
+  ]
+}

package/skills/query-expand/meta.json

@@ -0,0 +1,10 @@
+{
+  "slug": "query-expand",
+  "version": 1,
+  "skill_type": "extraction",
+  "input_type": "claim-elements",
+  "output_type": "search-queries",
+  "determinism_ratio": 1.0,
+  "permission": { "tier": 0 },
+  "description": "Turn a claim's functional elements into a deterministic set of prior-art search queries (keyword sets, stopwords stripped). Pure — no I/O, no model."
+}

package/skills/query-expand/skill.mjs

@@ -0,0 +1,29 @@
+// query-expand — claim elements -> prior-art search queries. Pure/deterministic.
+// Per element, strip patent boilerplate + stopwords to a keyword query; then a cross-element
+// query from the most frequent keywords. Same input -> same queries (determinism_ratio 1.0).
+const STOP = new Set([
+  "a", "an", "the", "of", "to", "for", "and", "or", "with", "is", "in", "on", "by", "at",
+  "from", "as", "that", "such", "said", "wherein", "comprising", "method", "system", "apparatus",
+]);
+
+function keywords(text) {
+  return String(text)
+    .toLowerCase()
+    .replace(/[^a-z0-9 ]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length > 2 && !STOP.has(w));
+}
+
+export default function run(input) {
+  const elements = Array.isArray(input.elements) ? input.elements : [];
+  const queries = [];
+  const freq = {};
+  for (const el of elements) {
+    const kws = keywords(el);
+    if (kws.length) queries.push(kws.slice(0, 6).join(" "));
+    for (const w of kws) freq[w] = (freq[w] || 0) + 1;
+  }
+  const top = Object.keys(freq).sort((x, y) => freq[y] - freq[x] || (x < y ? -1 : 1)).slice(0, 8);
+  if (top.length) queries.push(top.join(" "));
+  return { queries };
+}

package/skills/run-vitest-band/fixtures/basic.json

@@ -0,0 +1,9 @@
+{
+  "id": "basic",
+  "description": "contract: the verdict is a {passed, total} pair of numbers. (Not auto-run at load — it spawns the test command; the verdict shape is the contract.)",
+  "input": { "target": "tests/example_hello_band.test.ts" },
+  "assertions": [
+    { "path": "passed", "op": "is_number" },
+    { "path": "total", "op": "is_number" }
+  ]
+}

package/skills/run-vitest-band/meta.json

@@ -0,0 +1,18 @@
+{
+  "slug": "run-vitest-band",
+  "version": 1,
+  "skill_type": "orchestration",
+  "permission": { "tier": 2 },
+  "determinism_ratio": 1.0,
+  "input_type": "test-target",
+  "output_type": "test-verdict",
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "passed": { "type": "number" },
+      "total": { "type": "number" },
+      "failures": { "type": "array" }
+    },
+    "required": ["passed", "total"]
+  }
+}

package/skills/run-vitest-band/skill.mjs

@@ -0,0 +1,22 @@
+// Pure-code product skill (determinism 1.0): run the deterministic test command and parse
+// the verdict. This is the proper fix for "an LLM should not babysit a deterministic
+// command" — the command IS the answer; no model resolves any field. Tier 2 (spawns vitest).
+import { spawnSync } from "node:child_process";
+
+export default function run(input) {
+  const target = input && input.target ? String(input.target) : "";
+  const args = ["vitest", "run", "--reporter=json", ...(target ? [target] : [])];
+  const r = spawnSync("npx", args, { encoding: "utf-8", maxBuffer: 128 * 1024 * 1024 });
+  const out = r.stdout || "";
+  let report = null;
+  try {
+    report = JSON.parse(out.slice(out.indexOf("{")));
+  } catch {
+    return { passed: 0, total: 0, failures: ["could not parse vitest json report"] };
+  }
+  const total = report.numTotalTests ?? 0;
+  const passed = report.numPassedTests ?? 0;
+  const failures = (report.testResults ?? [])
+    .flatMap((f) => (f.assertionResults ?? []).filter((a) => a.status === "failed").map((a) => a.fullName ?? a.title));
+  return { passed, total, failures };
+}

package/skills/statutory-checklist/fixtures/basic.json

@@ -0,0 +1,16 @@
+{
+  "id": "one-open-statute",
+  "description": "all four statutes present; an unaddressed §112 keeps all_cleared false",
+  "input": {
+    "assessments": {
+      "§101": { "cleared": true },
+      "§102": { "cleared": true },
+      "§103": { "cleared": true }
+    }
+  },
+  "assertions": [
+    { "path": "all_cleared", "op": "equals", "value": false },
+    { "path": "statutes_checked", "op": "exists" },
+    { "path": "checklist.3.cleared", "op": "equals", "value": false }
+  ]
+}