@graphorin/skills 0.5.0

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/errors/index.ts"],"sourcesContent":["/**\n * Typed error hierarchy for `@graphorin/skills`.\n *\n * Every error carries a stable lowercase `kind` discriminator so the\n * agent runtime, the CLI, and the audit emitter can branch without\n * resorting to `instanceof` chains, plus an optional `hint` field with\n * an actionable remediation step (a CLI command or a documentation\n * link).\n *\n * @packageDocumentation\n */\n\n/** Base class for every error thrown by `@graphorin/skills`. */\nexport abstract class GraphorinSkillsError extends Error {\n  abstract readonly kind: string;\n  readonly hint?: string;\n  override readonly cause?: unknown;\n  constructor(message: string, options?: { hint?: string; cause?: unknown }) {\n    super(message);\n    this.name = new.target.name;\n    if (options?.hint !== undefined) this.hint = options.hint;\n    if (options?.cause !== undefined) this.cause = options.cause;\n  }\n}\n\n/**\n * The frontmatter validator detected an Anthropic-base / `graphorin-*`\n * collision and the operator-resolved policy is `'error'`.\n */\nexport class SkillFrontmatterConflictError extends GraphorinSkillsError {\n  readonly kind = 'frontmatter:conflict' as const;\n  readonly skillName: string;\n  readonly field: string;\n  readonly conflictingFields: ReadonlyArray<string>;\n  constructor(\n    skillName: string,\n    field: string,\n    conflictingFields: ReadonlyArray<string>,\n    options?: { hint?: string },\n  ) {\n    super(\n      `Skill '${skillName}' frontmatter conflict on '${field}' (also set: ${conflictingFields\n        .filter((f) => f !== field)\n        .join(', ')}). Validator policy: 'error'.`,\n      options,\n    );\n    this.skillName = skillName;\n    this.field = field;\n    this.conflictingFields = conflictingFields;\n  }\n}\n\n/** A skill manifest could not be parsed (missing frontmatter / invalid YAML). */\nexport class SkillManifestParseError extends GraphorinSkillsError {\n  readonly kind = 'manifest:parse' as const;\n}\n\n/**\n * The runtime-compat declaration on a skill does not satisfy the\n * loader's installed runtime version.\n */\nexport class SkillRuntimeCompatError extends GraphorinSkillsError {\n  readonly kind = 'runtime-compat:mismatch' as const;\n  readonly skillName: string;\n  readonly declared: string;\n  readonly installed: string;\n  constructor(skillName: string, declared: string, installed: string, options?: { hint?: string }) {\n    super(\n      `Skill '${skillName}' declares runtime-compat '${declared}' which does not match installed Graphorin '${installed}'.`,\n      options,\n    );\n    this.skillName = skillName;\n    this.declared = declared;\n    this.installed = installed;\n  }\n}\n\n/** A required Anthropic-base field is missing from the frontmatter. */\nexport class SkillRequiredFieldMissingError extends GraphorinSkillsError {\n  readonly kind = 'frontmatter:missing-required' as const;\n  readonly field: string;\n  constructor(field: string, options?: { hint?: string }) {\n    super(`Skill frontmatter is missing required field '${field}'.`, options);\n    this.field = field;\n  }\n}\n\n/**\n * `Agent.toTool()` / `handoff(...)` would be invoked inside an\n * untrusted skill, but the skill did not declare\n * `graphorin-handoff-input-filter`. Throwing the error at activation\n * time prevents the runtime from materialising a sub-agent without an\n * explicit filter.\n */\nexport class InputFilterRequiredError extends GraphorinSkillsError {\n  readonly kind = 'handoff:input-filter-required' as const;\n  readonly skillName: string;\n  constructor(skillName: string, options?: { hint?: string; cause?: unknown }) {\n    super(\n      `Untrusted skill '${skillName}' uses Agent.toTool()/handoff() but did not declare 'graphorin-handoff-input-filter'.`,\n      {\n        hint:\n          options?.hint ??\n          \"Add 'graphorin-handoff-input-filter: lastUser' (or another supported value) to the SKILL.md frontmatter.\",\n        ...(options?.cause === undefined ? {} : { cause: options.cause }),\n      },\n    );\n    this.skillName = skillName;\n  }\n}\n\n/** A skill source could not be loaded from disk. */\nexport class SkillLoadError extends GraphorinSkillsError {\n  readonly kind = 'load:failed' as const;\n  readonly source: string;\n  constructor(source: string, message: string, options?: { hint?: string; cause?: unknown }) {\n    super(`Skill load failed (source='${source}'): ${message}`, options);\n    this.source = source;\n  }\n}\n\n/** A skill name in a registry registration collided with another already-loaded skill. */\nexport class SkillNameCollisionError extends GraphorinSkillsError {\n  readonly kind = 'registry:name-collision' as const;\n  readonly skillName: string;\n  constructor(skillName: string, options?: { hint?: string; cause?: unknown }) {\n    super(`Skill '${skillName}' is already registered.`, {\n      hint:\n        options?.hint ??\n        'Either rename one of the colliding skills or call `registry.unregister(name)` before re-registering.',\n      ...(options?.cause === undefined ? {} : { cause: options.cause }),\n    });\n    this.skillName = skillName;\n  }\n}\n\n/**\n * The slash-command parser received a string that did not match the\n * `/skill:<name>` grammar.\n */\nexport class SlashCommandParseError extends GraphorinSkillsError {\n  readonly kind = 'slash:parse' as const;\n  readonly raw: string;\n  constructor(raw: string, message: string, options?: { hint?: string; cause?: unknown }) {\n    super(`Slash command '${raw}': ${message}`, {\n      hint: options?.hint ?? 'Use `/skill:<name>` to activate a registered skill.',\n      ...(options?.cause === undefined ? {} : { cause: options.cause }),\n    });\n    this.raw = raw;\n  }\n}\n\n/** Convenience union — every `kind` discriminator the package may emit. */\nexport type GraphorinSkillsErrorKind =\n  | 'frontmatter:conflict'\n  | 'manifest:parse'\n  | 'runtime-compat:mismatch'\n  | 'frontmatter:missing-required'\n  | 'handoff:input-filter-required'\n  | 'load:failed'\n  | 'registry:name-collision'\n  | 'slash:parse';\n"],"mappings":";;;;;;;;;;;;;AAaA,IAAsB,uBAAtB,cAAmD,MAAM;CAEvD,AAAS;CACT,AAAkB;CAClB,YAAY,SAAiB,SAA8C;AACzE,QAAM,QAAQ;AACd,OAAK,OAAO,IAAI,OAAO;AACvB,MAAI,SAAS,SAAS,OAAW,MAAK,OAAO,QAAQ;AACrD,MAAI,SAAS,UAAU,OAAW,MAAK,QAAQ,QAAQ;;;;;;;AAQ3D,IAAa,gCAAb,cAAmD,qBAAqB;CACtE,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,AAAS;CACT,YACE,WACA,OACA,mBACA,SACA;AACA,QACE,UAAU,UAAU,6BAA6B,MAAM,eAAe,kBACnE,QAAQ,MAAM,MAAM,MAAM,CAC1B,KAAK,KAAK,CAAC,gCACd,QACD;AACD,OAAK,YAAY;AACjB,OAAK,QAAQ;AACb,OAAK,oBAAoB;;;;AAK7B,IAAa,0BAAb,cAA6C,qBAAqB;CAChE,AAAS,OAAO;;;;;;AAOlB,IAAa,0BAAb,cAA6C,qBAAqB;CAChE,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,AAAS;CACT,YAAY,WAAmB,UAAkB,WAAmB,SAA6B;AAC/F,QACE,UAAU,UAAU,6BAA6B,SAAS,8CAA8C,UAAU,KAClH,QACD;AACD,OAAK,YAAY;AACjB,OAAK,WAAW;AAChB,OAAK,YAAY;;;;AAKrB,IAAa,iCAAb,cAAoD,qBAAqB;CACvE,AAAS,OAAO;CAChB,AAAS;CACT,YAAY,OAAe,SAA6B;AACtD,QAAM,gDAAgD,MAAM,KAAK,QAAQ;AACzE,OAAK,QAAQ;;;;;;;;;;AAWjB,IAAa,2BAAb,cAA8C,qBAAqB;CACjE,AAAS,OAAO;CAChB,AAAS;CACT,YAAY,WAAmB,SAA8C;AAC3E,QACE,oBAAoB,UAAU,wFAC9B;GACE,MACE,SAAS,QACT;GACF,GAAI,SAAS,UAAU,SAAY,EAAE,GAAG,EAAE,OAAO,QAAQ,OAAO;GACjE,CACF;AACD,OAAK,YAAY;;;;AAKrB,IAAa,iBAAb,cAAoC,qBAAqB;CACvD,AAAS,OAAO;CAChB,AAAS;CACT,YAAY,QAAgB,SAAiB,SAA8C;AACzF,QAAM,8BAA8B,OAAO,MAAM,WAAW,QAAQ;AACpE,OAAK,SAAS;;;;AAKlB,IAAa,0BAAb,cAA6C,qBAAqB;CAChE,AAAS,OAAO;CAChB,AAAS;CACT,YAAY,WAAmB,SAA8C;AAC3E,QAAM,UAAU,UAAU,2BAA2B;GACnD,MACE,SAAS,QACT;GACF,GAAI,SAAS,UAAU,SAAY,EAAE,GAAG,EAAE,OAAO,QAAQ,OAAO;GACjE,CAAC;AACF,OAAK,YAAY;;;;;;;AAQrB,IAAa,yBAAb,cAA4C,qBAAqB;CAC/D,AAAS,OAAO;CAChB,AAAS;CACT,YAAY,KAAa,SAAiB,SAA8C;AACtF,QAAM,kBAAkB,IAAI,KAAK,WAAW;GAC1C,MAAM,SAAS,QAAQ;GACvB,GAAI,SAAS,UAAU,SAAY,EAAE,GAAG,EAAE,OAAO,QAAQ,OAAO;GACjE,CAAC;AACF,OAAK,MAAM"}

package/dist/frontmatter/index.d.ts

@@ -0,0 +1,120 @@
+import { FieldResolution, FrontmatterDiagnostic, FrontmatterValidatorPolicy, HandoffInputFilterDeclaration, SkillToolDeclaration, UnknownFieldPolicy } from "../types/index.js";
+
+//#region src/frontmatter/index.d.ts
+
+/** Result of {@link splitSkillMd}. */
+interface SplitSkillMd {
+  readonly frontmatter: string;
+  readonly body: string;
+}
+/**
+ * Split a raw SKILL.md string into the YAML frontmatter and the
+ * markdown body. The frontmatter delimiter is the canonical
+ * `---\n…\n---\n` pair.
+ *
+ * @stable
+ */
+declare function splitSkillMd(skillMd: string): SplitSkillMd;
+/**
+ * Parse the YAML frontmatter into a record. Returns `{}` for an empty
+ * block.
+ *
+ * @stable
+ */
+declare function parseFrontmatterYaml(frontmatter: string): Record<string, unknown>;
+/**
+ * Resolve a single field across the four field-resolution tiers.
+ * Returns the resolved value plus the source tier the value came from
+ * AND the list of conflicting source names so the validator can
+ * surface a structured diagnostic.
+ *
+ * @stable
+ */
+declare function resolveSkillField<T = unknown>(frontmatter: Record<string, unknown>, field: string, fallback?: T): FieldResolution<T>;
+/**
+ * Options accepted by {@link validateFrontmatter}.
+ *
+ * @stable
+ */
+interface ValidateFrontmatterOptions {
+  /** Policy for direct collisions (Anthropic-base + `graphorin-*`). */
+  readonly conflictPolicy?: FrontmatterValidatorPolicy;
+  /** Policy for fields not part of the bundled snapshot or `graphorin-*` catalogue. */
+  readonly unknownFieldPolicy?: UnknownFieldPolicy;
+  /**
+   * Installed Graphorin runtime version. Used to validate
+   * `graphorin-runtime-compat` declarations against the running
+   * framework.
+   */
+  readonly runtimeVersion?: string;
+}
+/** Successful return of {@link validateFrontmatter}. */
+interface ValidatedFrontmatter {
+  readonly raw: Readonly<Record<string, unknown>>;
+  readonly diagnostics: ReadonlyArray<FrontmatterDiagnostic>;
+  readonly resolved: {
+    readonly name: FieldResolution<unknown>;
+    readonly description: FieldResolution<unknown>;
+    readonly license: FieldResolution<unknown>;
+    readonly compatibility: FieldResolution<unknown>;
+    readonly metadata: FieldResolution<unknown>;
+    readonly allowedTools: FieldResolution<unknown>;
+    readonly disableModelInvocation: FieldResolution<unknown>;
+    readonly trustLevel: FieldResolution<unknown>;
+    readonly runtimeCompat: FieldResolution<unknown>;
+    readonly sensitivity: FieldResolution<unknown>;
+    readonly sensitivityDefaults: FieldResolution<unknown>;
+    readonly sandbox: FieldResolution<unknown>;
+    readonly handoffInputFilter: FieldResolution<unknown>;
+    readonly anthropicSpec: FieldResolution<unknown>;
+    readonly version: FieldResolution<unknown>;
+    readonly tools: FieldResolution<unknown>;
+  };
+}
+/**
+ * Validate a parsed frontmatter against the bundled spec snapshot and
+ * the `graphorin-*` extension catalogue.
+ *
+ * @stable
+ */
+declare function validateFrontmatter(frontmatter: Record<string, unknown>, options?: ValidateFrontmatterOptions): ValidatedFrontmatter;
+/**
+ * Parse the `allowed-tools` field. Accepts either a string (with
+ * whitespace-separated entries) or a string array. Returns `null` for
+ * unsupported shapes so the validator can attach a typed diagnostic.
+ *
+ * @stable
+ */
+declare function parseAllowedToolsValue(value: unknown): ReadonlyArray<string> | null;
+/**
+ * Parse the `handoff-input-filter` field into a structured
+ * declaration. Returns `null` for unsupported shapes; callers should
+ * attach a diagnostic when the return value is `null` and the source
+ * value was non-undefined.
+ *
+ * @stable
+ */
+declare function parseHandoffInputFilter(value: unknown): HandoffInputFilterDeclaration | null;
+/**
+ * Parse the `tools` field. Accepts either an array of strings (tool
+ * names — the loader resolves modules through naming convention) or
+ * an array of objects with `name`, `module`, `description`, `tags`.
+ * Returns `null` for unsupported shapes.
+ *
+ * @stable
+ */
+declare function parseToolsField(value: unknown): ReadonlyArray<SkillToolDeclaration> | null;
+/**
+ * Best-effort semver-range satisfaction check. Supports the patterns
+ * the framework actually emits (`^x.y.z`, `~x.y.z`, `>=x.y.z`,
+ * `>x.y.z`, `<=x.y.z`, `<x.y.z`, plain `x.y.z`, the AND combinator
+ * with whitespace) without pulling a runtime dependency on `semver`.
+ * Unrecognised inputs return `false` so the validator emits a typed
+ * diagnostic.
+ *
+ * @stable
+ */
+declare function isRuntimeCompatSatisfied(range: string, version: string): boolean;
+//#endregion
+export { SplitSkillMd, ValidateFrontmatterOptions, ValidatedFrontmatter, isRuntimeCompatSatisfied, parseAllowedToolsValue, parseFrontmatterYaml, parseHandoffInputFilter, parseToolsField, resolveSkillField, splitSkillMd, validateFrontmatter };
+//# sourceMappingURL=index.d.ts.map

package/dist/frontmatter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/frontmatter/index.ts"],"sourcesContent":[],"mappings":";;;;;AAwK0B,UAlIT,YAAA,CAkIS;EACJ,SAAA,WAAA,EAAA,MAAA;EACM,SAAA,IAAA,EAAA,MAAA;;;;;;;;;AASK,iBAjIjB,YAAA,CAiIiB,OAAA,EAAA,MAAA,CAAA,EAjIc,YAiId;;;;;AAajC;;AAEW,iBA/HK,oBAAA,CA+HL,WAAA,EAAA,MAAA,CAAA,EA/HgD,MA+HhD,CAAA,MAAA,EAAA,OAAA,CAAA;;;AAoOX;AA0BA;AAmEA;AAqCA;;;iBA5cgB,4CACD,mDAEF,IACV,gBAAgB;;;;;;UAqDF,0BAAA;;4BAEW;;gCAEI;;;;;;;;;UAUf,oBAAA;gBACD,SAAS;wBACD,cAAc;;mBAEnB;0BACO;sBACJ;4BACM;uBACL;2BACI;qCACU;yBACZ;4BACG;0BACF;kCACQ;sBACZ;iCACW;4BACL;sBACN;oBACF;;;;;;;;;iBAUJ,mBAAA,cACD,mCACJ,6BACR;;;;;;;;iBAmOa,sBAAA,kBAAwC;;;;;;;;;iBA0BxC,uBAAA,kBAAyC;;;;;;;;;iBAmEzC,eAAA,kBAAiC,cAAc;;;;;;;;;;;iBAqC/C,wBAAA"}

package/dist/frontmatter/index.js

@@ -0,0 +1,451 @@
+import { SkillManifestParseError } from "../errors/index.js";
+import { compareAuthorSpecHint, getGraphorinMapping, getKnownField, getSpecSnapshot } from "../spec/index.js";
+import { parse } from "yaml";
+
+//#region src/frontmatter/index.ts
+/**
+* Frontmatter validator for `SKILL.md` files.
+*
+* Implements the field-resolution algorithm from ADR-043:
+*
+* 1. Anthropic-base (top-level, no prefix) — highest priority.
+* 2. `metadata.graphorin.<field>` bucket per upstream `metadata`
+*    convention.
+* 3. `graphorin-<field>` legacy top-level prefix.
+* 4. caller-supplied fallback.
+*
+* The validator surfaces every diagnostic through the typed
+* {@link FrontmatterDiagnostic} contract so callers can decide whether
+* to log, fail, or escalate without re-parsing human strings.
+*
+* @packageDocumentation
+*/
+/**
+* Split a raw SKILL.md string into the YAML frontmatter and the
+* markdown body. The frontmatter delimiter is the canonical
+* `---\n…\n---\n` pair.
+*
+* @stable
+*/
+function splitSkillMd(skillMd) {
+	const normalized = skillMd.replace(/^\uFEFF/u, "").replace(/\r\n/g, "\n");
+	const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/u.exec(normalized);
+	if (match === null) throw new SkillManifestParseError("SKILL.md must begin with a YAML frontmatter block delimited by `---` lines.");
+	return {
+		frontmatter: match[1] ?? "",
+		body: match[2] ?? ""
+	};
+}
+/**
+* Parse the YAML frontmatter into a record. Returns `{}` for an empty
+* block.
+*
+* @stable
+*/
+function parseFrontmatterYaml(frontmatter) {
+	if (frontmatter.trim().length === 0) return {};
+	let parsed;
+	try {
+		parsed = parse(frontmatter);
+	} catch (err) {
+		throw new SkillManifestParseError("SKILL.md frontmatter is not valid YAML.", { cause: err });
+	}
+	if (parsed === null || parsed === void 0) return {};
+	if (typeof parsed !== "object" || Array.isArray(parsed)) throw new SkillManifestParseError(`Top-level SKILL.md frontmatter must be an object; got '${Array.isArray(parsed) ? "array" : typeof parsed}'.`);
+	return parsed;
+}
+/**
+* Resolve a single field across the four field-resolution tiers.
+* Returns the resolved value plus the source tier the value came from
+* AND the list of conflicting source names so the validator can
+* surface a structured diagnostic.
+*
+* @stable
+*/
+function resolveSkillField(frontmatter, field, fallback) {
+	const conflictingSources = [];
+	const presentInBase = field in frontmatter;
+	const meta = frontmatter.metadata;
+	const presentInMeta = meta !== void 0 && meta !== null && typeof meta === "object" && !Array.isArray(meta) && `graphorin.${field}` in meta;
+	const presentInPrefix = `graphorin-${field}` in frontmatter;
+	if (presentInBase) conflictingSources.push(field);
+	if (presentInMeta) conflictingSources.push(`metadata.graphorin.${field}`);
+	if (presentInPrefix) conflictingSources.push(`graphorin-${field}`);
+	const conflicting = conflictingSources.length > 1;
+	if (presentInBase) return Object.freeze({
+		value: frontmatter[field],
+		source: "anthropic-base",
+		conflicting,
+		conflictingSources
+	});
+	if (presentInMeta) return Object.freeze({
+		value: meta[`graphorin.${field}`],
+		source: "metadata-graphorin",
+		conflicting,
+		conflictingSources
+	});
+	if (presentInPrefix) return Object.freeze({
+		value: frontmatter[`graphorin-${field}`],
+		source: "graphorin-prefix",
+		conflicting,
+		conflictingSources
+	});
+	return Object.freeze({
+		value: fallback,
+		source: "fallback",
+		conflicting: false,
+		conflictingSources: []
+	});
+}
+/**
+* Validate a parsed frontmatter against the bundled spec snapshot and
+* the `graphorin-*` extension catalogue.
+*
+* @stable
+*/
+function validateFrontmatter(frontmatter, options = {}) {
+	const conflictPolicy = options.conflictPolicy ?? "warn";
+	const unknownFieldPolicy = options.unknownFieldPolicy ?? "preserve";
+	const diagnostics = [];
+	const resolveAndDiag = (field, fallback) => {
+		const resolution = resolveSkillField(frontmatter, field, fallback);
+		if (resolution.conflicting) {
+			const message = `Both '${resolution.conflictingSources.join("' and '")}' are set for '${field}'. The Anthropic-base / metadata.graphorin.* tier wins; remove the lower-priority field to silence this diagnostic.`;
+			const hint = `Keep the highest-priority entry: '${resolution.source === "anthropic-base" ? field : resolution.source === "metadata-graphorin" ? `metadata.graphorin.${field}` : `graphorin-${field}`}'.`;
+			const severity = conflictPolicy === "error" ? "error" : "warn";
+			if (conflictPolicy !== "silent") diagnostics.push(Object.freeze({
+				kind: "conflict",
+				field,
+				severity,
+				message,
+				hint
+			}));
+		}
+		return resolution;
+	};
+	const name = resolveAndDiag("name");
+	const description = resolveAndDiag("description");
+	const license = resolveAndDiag("license");
+	const compatibility = resolveAndDiag("compatibility");
+	const metadata = resolveAndDiag("metadata");
+	const allowedTools = resolveAndDiag("allowed-tools");
+	const disableModelInvocation = resolveAndDiag("disable-model-invocation", false);
+	const trustLevel = resolveAndDiag("trust-level");
+	const runtimeCompat = resolveAndDiag("runtime-compat");
+	const version = resolveAndDiag("version");
+	const sensitivity = resolveAndDiag("sensitivity");
+	const sensitivityDefaults = resolveAndDiag("sensitivity-defaults");
+	const sandbox = resolveAndDiag("sandbox");
+	const handoffInputFilter = resolveAndDiag("handoff-input-filter");
+	const anthropicSpec = resolveAndDiag("anthropic-spec");
+	const tools = resolveAndDiag("tools");
+	if (typeof name.value !== "string" || name.value.trim().length === 0) diagnostics.push(Object.freeze({
+		kind: "missing-required-field",
+		field: "name",
+		severity: "error",
+		message: "Required field 'name' is missing or empty.",
+		hint: "Add a unique 'name' (kebab-case is conventional) to the SKILL.md frontmatter."
+	}));
+	if (typeof description.value !== "string" || description.value.trim().length === 0) diagnostics.push(Object.freeze({
+		kind: "missing-required-field",
+		field: "description",
+		severity: "error",
+		message: "Required field 'description' is missing or empty.",
+		hint: "Add a description that explains when the model should activate the skill."
+	}));
+	if (allowedTools.value !== void 0) {
+		if (parseAllowedToolsValue(allowedTools.value) === null) diagnostics.push(Object.freeze({
+			kind: "invalid-field-type",
+			field: "allowed-tools",
+			severity: "warn",
+			message: "'allowed-tools' must be a string ('read_file write_file') or an array (['read_file', 'write_file']).",
+			hint: "Switch to one of the two supported shapes; entries are split on whitespace for the string form."
+		}));
+	}
+	if (allowedTools.value !== void 0 && getKnownField("allowed-tools")?.stability === "experimental") diagnostics.push(Object.freeze({
+		kind: "experimental-field",
+		field: "allowed-tools",
+		severity: "info",
+		message: "'allowed-tools' is marked experimental in the bundled spec snapshot; behaviour may evolve."
+	}));
+	if (anthropicSpec.value !== void 0 && typeof anthropicSpec.value === "string") {
+		const compare = compareAuthorSpecHint(anthropicSpec.value);
+		if (compare === "newer") diagnostics.push(Object.freeze({
+			kind: "spec-newer-than-loader",
+			field: "anthropic-spec",
+			severity: "warn",
+			message: `Skill targets spec snapshot '${anthropicSpec.value}', newer than the bundled '${getSpecSnapshot().snapshotDate}'. Unknown fields will be preserved leniently.`
+		}));
+		else if (compare === "older") diagnostics.push(Object.freeze({
+			kind: "spec-older-than-loader",
+			field: "anthropic-spec",
+			severity: "info",
+			message: `Skill targets spec snapshot '${anthropicSpec.value}', older than the bundled '${getSpecSnapshot().snapshotDate}'.`
+		}));
+		else if (compare === "unparseable") diagnostics.push(Object.freeze({
+			kind: "invalid-field-type",
+			field: "anthropic-spec",
+			severity: "warn",
+			message: `'anthropic-spec' must be an ISO-8601 date string (YYYY-MM-DD); got '${String(anthropicSpec.value)}'.`
+		}));
+	}
+	if (runtimeCompat.value !== void 0 && typeof runtimeCompat.value === "string" && options.runtimeVersion !== void 0) {
+		if (!isRuntimeCompatSatisfied(runtimeCompat.value, options.runtimeVersion)) diagnostics.push(Object.freeze({
+			kind: "invalid-runtime-compat",
+			field: "runtime-compat",
+			severity: "error",
+			message: `Skill declares runtime-compat '${runtimeCompat.value}' which does not match installed Graphorin '${options.runtimeVersion}'.`,
+			hint: "Adjust the skill or upgrade Graphorin so the declared range covers the installed version."
+		}));
+	}
+	for (const key of Object.keys(frontmatter)) {
+		if (isRecognisedField(key)) continue;
+		if (key.startsWith("graphorin-")) {
+			if (unknownFieldPolicy === "reject") diagnostics.push(Object.freeze({
+				kind: "unknown-field",
+				field: key,
+				severity: "error",
+				message: `Unknown 'graphorin-*' field '${key}' rejected by unknownFieldPolicy='reject'.`
+			}));
+			else if (unknownFieldPolicy === "warn") diagnostics.push(Object.freeze({
+				kind: "unknown-field",
+				field: key,
+				severity: "warn",
+				message: `Unknown 'graphorin-*' field '${key}'. Will be preserved as opaque metadata.`
+			}));
+			continue;
+		}
+		if (unknownFieldPolicy === "reject") diagnostics.push(Object.freeze({
+			kind: "unknown-field",
+			field: key,
+			severity: "error",
+			message: `Unknown frontmatter field '${key}' rejected by unknownFieldPolicy='reject'.`
+		}));
+		else if (unknownFieldPolicy === "warn") diagnostics.push(Object.freeze({
+			kind: "unknown-field",
+			field: key,
+			severity: "warn",
+			message: `Unknown frontmatter field '${key}'. Will be preserved as opaque metadata.`
+		}));
+	}
+	return Object.freeze({
+		raw: Object.freeze({ ...frontmatter }),
+		diagnostics: Object.freeze(diagnostics),
+		resolved: Object.freeze({
+			name,
+			description,
+			license,
+			compatibility,
+			metadata,
+			allowedTools,
+			disableModelInvocation,
+			trustLevel,
+			runtimeCompat,
+			sensitivity,
+			sensitivityDefaults,
+			sandbox,
+			handoffInputFilter,
+			anthropicSpec,
+			version,
+			tools
+		})
+	});
+}
+/**
+* Parse the `allowed-tools` field. Accepts either a string (with
+* whitespace-separated entries) or a string array. Returns `null` for
+* unsupported shapes so the validator can attach a typed diagnostic.
+*
+* @stable
+*/
+function parseAllowedToolsValue(value) {
+	if (Array.isArray(value)) {
+		if (!value.every((entry) => typeof entry === "string" && entry.trim().length > 0)) return null;
+		return Object.freeze(value.map((entry) => entry.trim()));
+	}
+	if (typeof value === "string") {
+		const tokens = value.split(/\s+/u).map((tok) => tok.trim()).filter((tok) => tok.length > 0);
+		if (tokens.length === 0) return null;
+		return Object.freeze(tokens);
+	}
+	return null;
+}
+/**
+* Parse the `handoff-input-filter` field into a structured
+* declaration. Returns `null` for unsupported shapes; callers should
+* attach a diagnostic when the return value is `null` and the source
+* value was non-undefined.
+*
+* @stable
+*/
+function parseHandoffInputFilter(value) {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (trimmed === "lastUser") return Object.freeze({ kind: "lastUser" });
+		if (trimmed === "summary") return Object.freeze({ kind: "summary" });
+		if (trimmed === "full") return Object.freeze({ kind: "full" });
+		const lastN = /^lastN-(\d+)$/u.exec(trimmed);
+		if (lastN !== null) {
+			const n = Number.parseInt(lastN[1] ?? "0", 10);
+			if (Number.isFinite(n) && n > 0) return Object.freeze({
+				kind: "lastN",
+				n
+			});
+		}
+		return null;
+	}
+	if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+		const obj = value;
+		if (Array.isArray(obj.compose)) {
+			const steps = [];
+			for (const raw of obj.compose) {
+				const step = parseHandoffInputFilterStep(raw);
+				if (step === null) return null;
+				steps.push(step);
+			}
+			return Object.freeze({
+				kind: "compose",
+				steps: Object.freeze(steps)
+			});
+		}
+	}
+	return null;
+}
+function parseHandoffInputFilterStep(raw) {
+	if (typeof raw === "string") {
+		if (raw === "lastUser") return Object.freeze({ kind: "lastUser" });
+		if (raw === "summary") return Object.freeze({ kind: "summary" });
+		if (raw === "stripReasoning") return Object.freeze({ kind: "stripReasoning" });
+		return null;
+	}
+	if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+		const obj = raw;
+		if (typeof obj.lastN === "number" && Number.isFinite(obj.lastN) && obj.lastN > 0) return Object.freeze({
+			kind: "lastN",
+			n: obj.lastN
+		});
+		if (obj.stripSensitiveOutputs !== void 0 && typeof obj.stripSensitiveOutputs === "object" && obj.stripSensitiveOutputs !== null) {
+			const inner = obj.stripSensitiveOutputs;
+			const keepTier = typeof inner.keepTier === "string" ? inner.keepTier : void 0;
+			return Object.freeze({
+				kind: "stripSensitiveOutputs",
+				...keepTier === void 0 ? {} : { keepTier }
+			});
+		}
+		if (typeof obj.lastUser === "boolean") return Object.freeze({ kind: "lastUser" });
+		if (typeof obj.summary === "boolean") return Object.freeze({ kind: "summary" });
+		if (typeof obj.stripReasoning === "boolean") return Object.freeze({ kind: "stripReasoning" });
+	}
+	return null;
+}
+/**
+* Parse the `tools` field. Accepts either an array of strings (tool
+* names — the loader resolves modules through naming convention) or
+* an array of objects with `name`, `module`, `description`, `tags`.
+* Returns `null` for unsupported shapes.
+*
+* @stable
+*/
+function parseToolsField(value) {
+	if (!Array.isArray(value)) return null;
+	const out = [];
+	for (const entry of value) {
+		if (typeof entry === "string") {
+			if (entry.trim().length === 0) return null;
+			out.push(Object.freeze({ name: entry.trim() }));
+			continue;
+		}
+		if (entry !== null && typeof entry === "object" && !Array.isArray(entry)) {
+			const obj = entry;
+			if (typeof obj.name !== "string" || obj.name.trim().length === 0) return null;
+			const declaration = { name: obj.name.trim() };
+			if (typeof obj.module === "string" && obj.module.trim().length > 0) declaration.module = obj.module.trim();
+			if (typeof obj.description === "string") declaration.description = obj.description;
+			if (Array.isArray(obj.tags) && obj.tags.every((t) => typeof t === "string")) declaration.tags = Object.freeze([...obj.tags]);
+			out.push(Object.freeze(declaration));
+			continue;
+		}
+		return null;
+	}
+	return Object.freeze(out);
+}
+/**
+* Best-effort semver-range satisfaction check. Supports the patterns
+* the framework actually emits (`^x.y.z`, `~x.y.z`, `>=x.y.z`,
+* `>x.y.z`, `<=x.y.z`, `<x.y.z`, plain `x.y.z`, the AND combinator
+* with whitespace) without pulling a runtime dependency on `semver`.
+* Unrecognised inputs return `false` so the validator emits a typed
+* diagnostic.
+*
+* @stable
+*/
+function isRuntimeCompatSatisfied(range, version) {
+	const versionTuple = parseSemver(version);
+	if (versionTuple === null) return false;
+	const expressions = range.split(/\s+/u).filter((seg) => seg.length > 0);
+	for (const expression of expressions) if (!evaluateSemverExpression(expression, versionTuple)) return false;
+	return true;
+}
+function evaluateSemverExpression(expression, version) {
+	if (expression.startsWith("^")) {
+		const target$1 = parseSemver(expression.slice(1));
+		if (target$1 === null) return false;
+		if (target$1[0] === 0 && target$1[1] === 0) return version[0] === 0 && version[1] === 0 && version[2] === target$1[2];
+		if (target$1[0] === 0) return version[0] === 0 && version[1] === target$1[1] && cmpTuple(version, target$1) >= 0;
+		return version[0] === target$1[0] && cmpTuple(version, target$1) >= 0;
+	}
+	if (expression.startsWith("~")) {
+		const target$1 = parseSemver(expression.slice(1));
+		if (target$1 === null) return false;
+		return version[0] === target$1[0] && version[1] === target$1[1] && cmpTuple(version, target$1) >= 0;
+	}
+	if (expression.startsWith(">=")) {
+		const target$1 = parseSemver(expression.slice(2));
+		return target$1 !== null && cmpTuple(version, target$1) >= 0;
+	}
+	if (expression.startsWith(">")) {
+		const target$1 = parseSemver(expression.slice(1));
+		return target$1 !== null && cmpTuple(version, target$1) > 0;
+	}
+	if (expression.startsWith("<=")) {
+		const target$1 = parseSemver(expression.slice(2));
+		return target$1 !== null && cmpTuple(version, target$1) <= 0;
+	}
+	if (expression.startsWith("<")) {
+		const target$1 = parseSemver(expression.slice(1));
+		return target$1 !== null && cmpTuple(version, target$1) < 0;
+	}
+	if (expression === "*") return true;
+	const target = parseSemver(expression);
+	return target !== null && cmpTuple(version, target) === 0;
+}
+function parseSemver(value) {
+	const parts = (value.trim().replace(/^v/u, "").split(/[-+]/u, 1)[0] ?? "").split(".");
+	if (parts.length < 1 || parts.length > 3) return null;
+	const [major, minor, patch] = [
+		parts[0] ?? "0",
+		parts[1] ?? "0",
+		parts[2] ?? "0"
+	];
+	if (!/^\d+$/u.test(major) || !/^\d+$/u.test(minor) || !/^\d+$/u.test(patch)) return null;
+	return [
+		Number.parseInt(major, 10),
+		Number.parseInt(minor, 10),
+		Number.parseInt(patch, 10)
+	];
+}
+function cmpTuple(a, b) {
+	if (a[0] !== b[0]) return a[0] - b[0];
+	if (a[1] !== b[1]) return a[1] - b[1];
+	return a[2] - b[2];
+}
+function isRecognisedField(field) {
+	if (getKnownField(field) !== void 0) return true;
+	if (getGraphorinMapping(field) !== void 0) return true;
+	if (field === "metadata") return true;
+	return false;
+}
+
+//#endregion
+export { isRuntimeCompatSatisfied, parseAllowedToolsValue, parseFrontmatterYaml, parseHandoffInputFilter, parseToolsField, resolveSkillField, splitSkillMd, validateFrontmatter };
+//# sourceMappingURL=index.js.map