@xemahq/kernel-contracts 0.1.0

package/src/skill/lib/skill-enums.ts

@@ -0,0 +1,124 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Skill — closed-domain enums ──
+//
+// A Skill is a FOLDER (SKILL.md + recommended reference/scripts/assets +
+// nested sub-skills). Only SKILL.md is a strict contract; the directory
+// layout is a recommended convention so externally-authored skills with
+// different internal structures are still accepted.
+//
+// These enums are the closed sets every consumer (skill-registry-api,
+// the composer, the Studio) must agree on.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Who owns a skill and who may manage it.
+ * Precedence (most specific wins): User > Project > Org > Biome > System.
+ */
+export enum SkillSpace {
+  /** Kernel/platform-shipped. Immutable from the UI. */
+  System = 'system',
+  /** Contributed by an installed biome's `skills/` folder. */
+  Biome = 'biome',
+  /** Authored by an organization. */
+  Org = 'org',
+  /** Scoped to a single project. */
+  Project = 'project',
+  /** Authored by a single user. */
+  User = 'user',
+}
+
+/**
+ * Where a skill bundle physically came from.
+ */
+export enum SkillSourceKind {
+  /**
+   * Kernel-shipped, auto-injected into every agent. Seeded from the
+   * `@xemahq/system-skills` package's `skills/` folder at boot. Owned by
+   * `SkillSpace.System`; immutable from the UI.
+   */
+  System = 'system',
+  /** Seeded from a biome's `skills/` folder at boot. */
+  Biome = 'biome',
+  /** Created/edited in the Agent Studio, stored in skill-registry-api. */
+  Authored = 'authored',
+  /** Ingested from a registered git repository (`**\/SKILL.md`). */
+  GitRepo = 'git_repo',
+}
+
+/**
+ * Closed taxonomy of a skill's purpose.
+ */
+export enum SkillKind {
+  /** Teaches "how" — the default for hand-authored skills. */
+  Procedural = 'procedural',
+  /** Read-only projection of a deliverable spec (see deliverable-specs-api). */
+  Deliverable = 'deliverable',
+  /** Always-on platform skill (e.g. `memorizing`, `recalling`). */
+  System = 'system',
+}
+
+/**
+ * Type of a non-SKILL.md file bundled inside a skill directory. Used to
+ * classify bundle resources for mounting and governance risk scanning.
+ */
+export enum SkillResourceType {
+  /** Markdown loaded on demand (progressive disclosure). */
+  Reference = 'reference',
+  /** Executable utility — executed, never loaded into context. */
+  Script = 'script',
+  /** Binary resource (image, data file, …). */
+  Asset = 'asset',
+  /** Starter template — a recommendation, never mandatory. */
+  Template = 'template',
+  /** A nested sub-skill directory (recursive). */
+  SubSkill = 'sub_skill',
+}
+
+/**
+ * When a skill's metadata is offered to an agent.
+ * - `Always`: baseline skill, listed for every relevant invocation.
+ * - `ContextDependent`: listed only when the dimensional resolver selects it.
+ */
+export enum SkillInjectionMode {
+  Always = 'always',
+  ContextDependent = 'context_dependent',
+}
+
+/**
+ * Closed surface taxonomy a skill applies to.
+ *
+ * Mirrors the kernel `ManifestSurface` enum value-identically (`workflow` /
+ * `agent-session`). Skill-contracts is the pure leaf package and may not
+ * depend on `@xemahq/workflow-contracts`, so the values are restated here.
+ * Drift is prevented by a CI parity check (and by treating these as the
+ * single source of truth a skill author sees in frontmatter).
+ *
+ * Semantics — a skill MAY declare `surfaces: [...]` in its frontmatter
+ * to opt OUT of one surface. Omitting `surfaces` means the skill applies
+ * to BOTH surfaces (the natural default for procedural skills).
+ */
+export enum SkillSurface {
+  Workflow = 'workflow',
+  AgentSession = 'agent-session',
+}
+
+export const SKILL_SURFACES: readonly SkillSurface[] = [
+  SkillSurface.Workflow,
+  SkillSurface.AgentSession,
+] as const;
+
+/**
+ * Layer a skill was resolved from. Layers merge in precedence order
+ * System > Base > Pinned > Context; on collision the highest-precedence
+ * layer wins.
+ */
+export enum SkillLayer {
+  /** Platform-wide skill injected for ALL agents. Cannot be removed. */
+  System = 'system',
+  /** Agent-intrinsic skill declared on the agent definition. */
+  Base = 'base',
+  /** Project-level pinned skill. */
+  Pinned = 'pinned',
+  /** Selected by the dimensional resolver for the current context. */
+  Context = 'context',
+}

package/src/skill/lib/skill-governance.ts

@@ -0,0 +1,281 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Skill governance & lifecycle contracts ──
+//
+// Git/user-authored skills must be vetted before deployment. The lifecycle
+// state machine + risk tier + evaluation suite are the closed contracts the
+// governance module (skill-registry-api, extending biome-governance) writes.
+//
+// The EVALUATION model below follows the eval-driven iteration loop:
+//   1. test cases (prompt + expected output + assertions),
+//   2. each case run twice — with the skill and without it (the baseline),
+//   3. assertions graded PASS/FAIL with concrete evidence,
+//   4. an aggregated benchmark whose `delta` shows what the skill BUYS
+//      (higher pass rate) versus what it COSTS (time, tokens).
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Risk tier computed from declared indicators (bundled scripts, MCP/tool
+ * references, network calls, path traversal, hardcoded-credential scans).
+ * High-risk bundles require explicit approval.
+ */
+export enum SkillRiskTier {
+  Low = 'low',
+  Medium = 'medium',
+  High = 'high',
+}
+
+/**
+ * Closed, documented set of deterministic indicators the risk scanner looks
+ * for in a skill bundle. Each indicator that fires contributes a fixed tier;
+ * the bundle's tier is the maximum across all fired indicators. The scan is
+ * fully reproducible — every indicator is a literal substring / structural
+ * check, never a fuzzy heuristic. The set is closed: adding an indicator is
+ * a one-line enum extension plus a row in the scanner's indicator table.
+ *
+ * Frontend Agent Studio displays these so a reviewer sees exactly WHY a
+ * bundle was tiered the way it was — hence a kernel-shared contract.
+ */
+export enum SkillRiskIndicator {
+  /** The bundle ships one or more `scripts/*` executable resources. */
+  ScriptResource = 'script_resource',
+  /** SKILL.md declares MCP servers / external tool usage. */
+  McpToolReference = 'mcp_tool_reference',
+  /** A bundled file contains an outbound network-call pattern (curl/fetch/…). */
+  NetworkCall = 'network_call',
+  /** A bundled file contains a path-traversal pattern (`../`, absolute `/etc`). */
+  PathTraversal = 'path_traversal',
+  /** A bundled file contains a hardcoded-credential pattern (token/key/secret). */
+  HardcodedCredential = 'hardcoded_credential',
+  /** A bundled file invokes a shell / process-spawn primitive. */
+  ShellInvocation = 'shell_invocation',
+}
+
+/**
+ * A governance lifecycle transition action. Mirrors the Prisma
+ * `SkillGovernanceAction` enum so the append-only audit log agrees DB↔TS.
+ */
+export enum SkillGovernanceAction {
+  SubmitForReview = 'submit_for_review',
+  Approve = 'approve',
+  Reject = 'reject',
+  Deprecate = 'deprecate',
+  Rollback = 'rollback',
+}
+
+/**
+ * Lifecycle of a single skill version. Linear forward progression;
+ * separation of duties forbids an author approving their own skill.
+ * System/`@xema` skills are created pre-`Approved`.
+ */
+export enum SkillLifecycleState {
+  Draft = 'draft',
+  InReview = 'in_review',
+  Approved = 'approved',
+  Deprecated = 'deprecated',
+}
+
+// ─── Eval test cases ────────────────────────────────────────────────────────
+
+/**
+ * Whether a test case expects the skill to ACTIVATE (load into context) for
+ * its prompt. Xema governance cares about triggering accuracy in addition to
+ * output quality — a skill that fires when it should stay dormant pollutes
+ * the agent context and a skill that stays dormant when it should fire never
+ * helps. Every case declares its triggering expectation; the runner records
+ * whether the skill actually loaded.
+ */
+export enum SkillTriggerExpectation {
+  /** The skill SHOULD load into the agent's context for this prompt. */
+  ShouldTrigger = 'should_trigger',
+  /** The skill SHOULD NOT load — the prompt is out of the skill's domain. */
+  ShouldNotTrigger = 'should_not_trigger',
+}
+
+/**
+ * One eval test case. A realistic user message plus a human-readable success
+ * description and a set of verifiable assertions. 3–5 cases per suite is the
+ * recommended band; vary phrasing/formality and cover at least one edge case.
+ */
+export interface SkillEvalCase {
+  /** Stable author-supplied identifier, unique within the suite. */
+  readonly id: string;
+  /** A realistic user message — the prompt sent to the agent. */
+  readonly prompt: string;
+  /** Human-readable description of what a successful output looks like. */
+  readonly expectedOutput: string;
+  /**
+   * Verifiable, specific, observable statements graded against the actual
+   * output (e.g. "The output file is valid JSON", "The report includes at
+   * least 3 recommendations"). NOT vague, NOT brittle exact-phrase matches.
+   */
+  readonly assertions: readonly string[];
+  /**
+   * Whether the skill is expected to activate for this prompt. The methodology
+   * focuses on output quality; Xema additionally gates on triggering accuracy.
+   */
+  readonly triggerExpectation: SkillTriggerExpectation;
+  /**
+   * Optional input files seeded into the sandbox `/workspace/` before the run
+   * (e.g. a starter document the skill is asked to transform).
+   */
+  readonly files?: readonly SkillEvalCaseFile[];
+}
+
+/** One input file seeded into the sandbox workspace for a test case. */
+export interface SkillEvalCaseFile {
+  /** Forward-slash path relative to `/workspace/`. */
+  readonly path: string;
+  /** UTF-8 file content. */
+  readonly content: string;
+}
+
+/**
+ * The evaluation suite an author submits with a skill. Approval requires the
+ * latest run's with-skill benchmark to PASS and to beat its baseline.
+ */
+export interface SkillEvalSuite {
+  readonly skillSlug: string;
+  readonly cases: readonly SkillEvalCase[];
+}
+
+// ─── Eval run configs ───────────────────────────────────────────────────────
+
+/**
+ * The two A/B configurations every test case is run under. The point of the
+ * methodology is the DELTA between them.
+ */
+export enum SkillEvalRunConfig {
+  /** The skill under test is mounted into the sandbox agent. */
+  WithSkill = 'with_skill',
+  /** The baseline — the same generic agent + prompt, skill NOT mounted. */
+  WithoutSkill = 'without_skill',
+}
+
+/**
+ * Lifecycle state of an eval run. A run is one full iteration: every case
+ * executed under both configs, graded, and aggregated into a benchmark.
+ */
+export enum SkillEvalRunStatus {
+  /** Sandboxes are being created / prompts driven / outputs graded. */
+  Running = 'running',
+  /** Every case completed and the benchmark was aggregated. */
+  Completed = 'completed',
+  /** The run aborted — sandbox provisioning or grading failed irrecoverably. */
+  Failed = 'failed',
+}
+
+// ─── Grading ────────────────────────────────────────────────────────────────
+
+/** Verdict of a single graded assertion. */
+export enum SkillAssertionVerdict {
+  Pass = 'pass',
+  Fail = 'fail',
+}
+
+/**
+ * How an assertion was graded. Mechanical assertions (valid JSON, file exists,
+ * row count) are graded by deterministic code; prose assertions are graded by
+ * an LLM judge. Recorded so a reviewer knows the provenance of each verdict.
+ */
+export enum SkillAssertionGradingMethod {
+  /** Deterministic code evaluated the assertion against the raw output. */
+  Mechanical = 'mechanical',
+  /** An LLM judge (via llm-gateway) evaluated a prose assertion. */
+  LlmJudge = 'llm_judge',
+}
+
+/** The graded result of one assertion against one config's output. */
+export interface SkillAssertionResult {
+  /** The assertion text, copied verbatim from the test case. */
+  readonly assertion: string;
+  readonly verdict: SkillAssertionVerdict;
+  readonly method: SkillAssertionGradingMethod;
+  /**
+   * Concrete evidence for the verdict — a quote from the actual output (or a
+   * mechanical observation). A PASS requires real evidence, never an opinion.
+   */
+  readonly evidence: string;
+}
+
+/** Aggregate grading summary for one config's output of one test case. */
+export interface SkillCaseGradingSummary {
+  readonly passed: number;
+  readonly failed: number;
+  readonly total: number;
+  /** `passed / total`, in `[0, 1]`. `0` for a suite with no assertions. */
+  readonly passRate: number;
+}
+
+/** Wall-clock + token cost of one config's run of one test case. */
+export interface SkillEvalTiming {
+  /** Sum of input + output tokens across every step of the turn. */
+  readonly totalTokens: number;
+  /** End-to-end turn duration in milliseconds. */
+  readonly durationMs: number;
+}
+
+/**
+ * The full result of running ONE test case under ONE config: the captured
+ * output, whether the skill triggered, the timing, and the per-assertion
+ * grading.
+ */
+export interface SkillEvalCaseConfigResult {
+  readonly caseId: string;
+  readonly config: SkillEvalRunConfig;
+  /** The agent's final assistant reply text. */
+  readonly output: string;
+  /** Whether the skill under test actually loaded into the agent context. */
+  readonly skillTriggered: boolean;
+  readonly timing: SkillEvalTiming;
+  readonly assertionResults: readonly SkillAssertionResult[];
+  readonly grading: SkillCaseGradingSummary;
+  /**
+   * Whether the observed triggering matched `triggerExpectation`. A
+   * with-skill `should_trigger` case where the skill did not load fails this.
+   * Always `true` for the without-skill baseline (the skill is not mounted).
+   */
+  readonly triggeringCorrect: boolean;
+}
+
+// ─── Benchmark ──────────────────────────────────────────────────────────────
+
+/** Aggregate metrics for one config across every test case in a run. */
+export interface SkillEvalConfigBenchmark {
+  readonly config: SkillEvalRunConfig;
+  /** Mean assertion pass rate across all cases, in `[0, 1]`. */
+  readonly passRate: number;
+  /** Fraction of cases whose triggering matched expectation, in `[0, 1]`. */
+  readonly triggeringAccuracy: number;
+  /** Total tokens summed across every case run under this config. */
+  readonly totalTokens: number;
+  /** Total wall-clock duration summed across every case, in milliseconds. */
+  readonly totalDurationMs: number;
+}
+
+/**
+ * The aggregated benchmark of a full eval run — the per-config metrics plus
+ * the DELTA (with-skill minus without-skill). The delta is the point: it
+ * shows what the skill buys (a positive `passRateDelta`) versus what it costs
+ * (`totalTokensDelta`, `totalDurationMsDelta`). A skill that does not beat its
+ * baseline is not adding value and the governance gate refuses to approve it.
+ */
+export interface SkillEvalBenchmark {
+  readonly withSkill: SkillEvalConfigBenchmark;
+  readonly withoutSkill: SkillEvalConfigBenchmark;
+  /** `withSkill.passRate - withoutSkill.passRate`. Positive = the skill helps. */
+  readonly passRateDelta: number;
+  /** `withSkill.triggeringAccuracy - withoutSkill.triggeringAccuracy`. */
+  readonly triggeringAccuracyDelta: number;
+  /** `withSkill.totalTokens - withoutSkill.totalTokens`. Positive = the skill costs. */
+  readonly totalTokensDelta: number;
+  /** `withSkill.totalDurationMs - withoutSkill.totalDurationMs`. */
+  readonly totalDurationMsDelta: number;
+}
+
+/**
+ * The minimum with-skill assertion pass rate the governance gate requires.
+ * Configurable per deployment via the `SKILL_EVAL_PASS_RATE_THRESHOLD` env
+ * var; this is the default. A run that meets the threshold AND has a positive
+ * `passRateDelta` is a passing run.
+ */
+export const SKILL_EVAL_DEFAULT_PASS_RATE_THRESHOLD = 0.8;

package/src/skill/lib/skill-source.ts

@@ -0,0 +1,41 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Skill git-repository source ──
+//
+// A skill source of kind `GitRepo` is a registered repository whose tree
+// contains `**\/SKILL.md` bundles. skill-registry-api clones/pulls the repo
+// (reusing the existing scm-integration checkout), scans for SKILL.md files,
+// and ingests each as a Skill. The git ref is the version.
+//
+// Kept deliberately simple — no bespoke machinery.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * A registered git repository that supplies skills.
+ */
+export interface SkillRepositorySpec {
+  /** Stable id of the registered repository. */
+  readonly id: string;
+  /** Clone URL (https or ssh). */
+  readonly url: string;
+  /** Branch, tag, or commit to ingest. Defaults to the repo's default branch. */
+  readonly ref?: string;
+  /**
+   * Optional sub-directory to scan; when omitted the whole tree is scanned
+   * for `**\/SKILL.md`.
+   */
+  readonly rootPath?: string;
+}
+
+/**
+ * Outcome of a single repository sync.
+ */
+export interface SkillRepositorySyncResult {
+  readonly repositoryId: string;
+  /** Git ref actually ingested (resolved commit sha). */
+  readonly resolvedRef: string;
+  /** Slugs of skills upserted by this sync. */
+  readonly ingestedSkillSlugs: readonly string[];
+  /** Slugs removed because they no longer exist in the repo. */
+  readonly removedSkillSlugs: readonly string[];
+  readonly syncedAt: string;
+}

package/src/skill/lib/skill.ts

@@ -0,0 +1,150 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Skill — core types ──
+//
+// A Skill is a first-class platform primitive: a folder bundle whose only
+// STRICT part is SKILL.md (required frontmatter `name` + `description`).
+// Skills are hierarchical (nested sub-skills), multi-resource (reference
+// files, scripts, assets, templates) and discovered by progressive
+// disclosure — metadata first, full body on demand.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type {
+  SkillSpace,
+  SkillSourceKind,
+  SkillKind,
+  SkillResourceType,
+  SkillInjectionMode,
+  SkillLayer,
+  SkillSurface,
+} from './skill-enums';
+import type { SkillRiskTier, SkillLifecycleState } from './skill-governance';
+
+/**
+ * A stable reference to a skill, optionally version-pinned. Production
+ * compositions/workflows pin a version; an omitted version resolves to the
+ * latest `Approved` version.
+ */
+export interface SkillRef {
+  /** Hierarchical slug, e.g. `software-engineering/requirements`. */
+  readonly slug: string;
+  /** Pinned version; omitted = latest approved. */
+  readonly version?: string;
+}
+
+/**
+ * The STRICT contract: frontmatter parsed from SKILL.md. `name` +
+ * `description` are required and validated; the rest is platform-managed
+ * metadata an author may set in frontmatter. Everything ELSE in a skill
+ * bundle is free-form and never validated.
+ */
+export interface SkillFrontmatter {
+  /** Required. Lowercase letters, numbers, hyphens. Drives `/skill` naming. */
+  readonly name: string;
+  /** Required. What the skill does + when to use it — drives discovery. */
+  readonly description: string;
+  readonly kind?: SkillKind;
+  readonly injectionMode?: SkillInjectionMode;
+  /** Free-form grouping tag (not a closed enum — skills are flexible). */
+  readonly category?: string;
+  readonly tags?: readonly string[];
+  /**
+   * Optional surface gate.
+   *
+   * Closed set (`@xemahq/skill-contracts` `SkillSurface`): `workflow` and
+   * `agent-session`. When omitted, the skill applies to BOTH surfaces — the
+   * default for procedural skills.
+   *
+   * Server-resolved consumers (the always-on skill resolver in
+   * `llm-registry-api`) filter their listing by this field against the
+   * requesting surface. A skill declaring `surfaces: [workflow]` is not
+   * mounted into an agent session, and vice-versa.
+   *
+   * Authors set this in SKILL.md frontmatter:
+   *
+   * ```yaml
+   * ---
+   * name: deliverable-contract
+   * description: …
+   * surfaces: [workflow]
+   * ---
+   * ```
+   */
+  readonly surfaces?: readonly SkillSurface[];
+}
+
+/**
+ * A non-SKILL.md file inside a skill bundle. Resources are mounted as-is
+ * and never parsed by the platform.
+ */
+export interface SkillResource {
+  /** Forward-slash path relative to the skill directory. */
+  readonly relPath: string;
+  readonly type: SkillResourceType;
+  /** Size in bytes; absent for sub-skill directory entries. */
+  readonly sizeBytes?: number;
+}
+
+/**
+ * Identity + metadata of a stored skill version — everything except the
+ * SKILL.md body and resource contents.
+ */
+export interface SkillManifest {
+  /** Hierarchical slug; the path identity within the registry. */
+  readonly slug: string;
+  readonly name: string;
+  readonly description: string;
+  readonly kind: SkillKind;
+  readonly scope: SkillSpace;
+  readonly sourceKind: SkillSourceKind;
+  readonly injectionMode: SkillInjectionMode;
+  /** Semver or git-ref version of this skill. */
+  readonly version: string;
+  /** Parent skill slug for nested sub-skills; `null` for a top-level skill. */
+  readonly parentSlug: string | null;
+  readonly lifecycleState: SkillLifecycleState;
+  readonly riskTier: SkillRiskTier;
+  /** Content checksum, verified at mount time. */
+  readonly checksum: string;
+  /** Non-SKILL.md files bundled with the skill. */
+  readonly resources: readonly SkillResource[];
+  /**
+   * Surface gate (server-resolved from frontmatter, defaults to `null` =
+   * applies to both surfaces). When non-null, the always-on resolver filters
+   * this skill against the requesting surface.
+   */
+  readonly surfaces: readonly SkillSurface[] | null;
+}
+
+/**
+ * A node in the skill hierarchy tree — a manifest plus its nested
+ * sub-skills. Returned by the registry's `get tree` endpoint.
+ */
+export interface SkillNode {
+  readonly manifest: SkillManifest;
+  readonly children: readonly SkillNode[];
+}
+
+/**
+ * A complete skill: its manifest plus the raw SKILL.md content. Resource
+ * file bodies are fetched separately (progressive disclosure).
+ */
+export interface Skill {
+  readonly manifest: SkillManifest;
+  /** Raw SKILL.md content (frontmatter + body). */
+  readonly skillMarkdown: string;
+}
+
+/**
+ * A skill resolved for injection into an OpenCode worker. Mounted under
+ * `/workspace/.opencode/skills/<slug>/`. The body is the SKILL.md content;
+ * resources are mounted alongside as part of the bundle.
+ */
+export interface ResolvedSkill {
+  readonly slug: string;
+  readonly name: string;
+  readonly description: string;
+  /** SKILL.md content. */
+  readonly content: string;
+  /** Which layer selected this skill (for precedence + debugging). */
+  readonly layer: SkillLayer;
+}

package/src/space/index.ts

@@ -0,0 +1,3 @@
+export * from './lib/space';
+export * from './lib/space-ref-parser';
+export * from './lib/space-traversal';