@dot-skill/protocol 0.4.2 → 0.5.0

package/README.md

@@ -0,0 +1,36 @@
+# `@dot-skill/protocol`
+
+Types, schemas, and completeness rules for the [Open `.skill` Protocol](https://github.com/dot-skill/dot-skill).
+
+Defines **SkillContract**, **SkillSource**, section shapes, assessment helpers, and the JSON Schema used for transferable authoring. This package is the semantic source of truth; it does not pack or run skills.
+
+## Install
+
+```bash
+npm i @dot-skill/protocol
+```
+
+## What you get
+
+- `SkillContract` / `SkillSource` TypeScript types
+- Completeness assessment and explanation APIs
+- Multi-skill extract helpers (`extractSkillCandidates`, `agentCreateGuide`)
+- `skill-contract.schema.json` (JSON Schema export)
+- Adapter types for external capture formats (mapped into SkillSource before compile)
+
+## Vocabulary
+
+Protocol terms: **section**, **SkillSource**, **SkillContract**, **extract/segment**, **compile**, **mint**, **load**.
+
+Product-specific capture words map into this model via adapters; they are not protocol vocabulary.
+
+## Related
+
+- [`@dot-skill/core`](https://www.npmjs.com/package/@dot-skill/core) — compile / pack / mint
+- [`skillerr`](https://www.npmjs.com/package/skillerr) — public install (`skill` CLI)
+
+Docs: [PROTOCOL.md](https://github.com/dot-skill/dot-skill/blob/main/docs/PROTOCOL.md) · [AUTHORING-CONTRACT.md](https://github.com/dot-skill/dot-skill/blob/main/docs/AUTHORING-CONTRACT.md)
+
+## License
+
+MIT

package/dist/authoring.d.ts

@@ -0,0 +1,14 @@
+import type { ContractAssessment, ContractField } from "./contract.js";
+import type { SkillCompileProfile } from "./types.js";
+/** Assess a full or partial contract without compiling it. */
+export declare function assessSkillContract(value: unknown, profile?: SkillCompileProfile): ContractAssessment;
+/** Machine-readable authoring template. Placeholder values intentionally fail assessment. */
+export declare function scaffoldSkillContract(): Record<string, unknown>;
+export declare function explainContractAssessment(assessment: ContractAssessment): {
+    complete: boolean;
+    fixes: Array<{
+        field: ContractField;
+        message: string;
+        fix: string;
+    }>;
+};

package/dist/authoring.js

@@ -0,0 +1,260 @@
+const DECLARATIONS = [
+    "triggers",
+    "inputs",
+    "preconditions",
+    "steps",
+    "branches",
+    "human_decisions",
+    "capabilities",
+    "permissions",
+    "forbidden_actions",
+    "outputs",
+    "recovery",
+    "verification",
+    "corrections",
+];
+function declarationIssue(field, value, profile) {
+    if (!value || typeof value !== "object") {
+        return {
+            field,
+            code: "missing",
+            message: `${field} is absent; omission is not an explicit declaration`,
+            fix: `Set ${field} to {status:"specified",items:[...]} or an allowed explicit {status:"none"|"not_applicable",reason:"..."}.`,
+        };
+    }
+    const declaration = value;
+    if (declaration.status === "specified") {
+        if (!Array.isArray(declaration.items) || declaration.items.length === 0) {
+            return {
+                field,
+                code: "empty",
+                message: `${field} is specified but has no items`,
+                fix: `Add at least one structured ${field} item or explicitly declare none/not_applicable with a reason.`,
+            };
+        }
+        return;
+    }
+    if (declaration.status !== "none" && declaration.status !== "not_applicable") {
+        return {
+            field,
+            code: "invalid",
+            message: `${field}.status is invalid`,
+            fix: `Use specified, none, or not_applicable.`,
+        };
+    }
+    if (!("reason" in declaration) || typeof declaration.reason !== "string" || !declaration.reason.trim()) {
+        return {
+            field,
+            code: "invalid",
+            message: `${field} ${declaration.status} declaration needs a reason`,
+            fix: `Add a concrete reason explaining why ${field} is ${declaration.status}.`,
+        };
+    }
+    if (profile === "release" &&
+        (field === "triggers" || field === "steps" || field === "verification")) {
+        return {
+            field,
+            code: "profile_required",
+            message: `${field} must be specified for release`,
+            fix: `Provide at least one structured ${field} item. Release skills must be discoverable, actionable, and verifiable.`,
+        };
+    }
+    return;
+}
+/** Assess a full or partial contract without compiling it. */
+export function assessSkillContract(value, profile = "release") {
+    const issues = [];
+    const contract = (value ?? {});
+    const addMissingText = (field, value) => {
+        if (typeof value !== "string" || !value.trim()) {
+            issues.push({
+                field,
+                code: "missing",
+                message: `${field} is required`,
+                fix: `Set ${field} to a precise, non-empty string.`,
+            });
+        }
+    };
+    if (contract.kind !== "skill_contract" || contract.contract_version !== "0.5") {
+        issues.push({
+            field: "contract",
+            code: "invalid",
+            message: "Expected kind=skill_contract and contract_version=0.5",
+            fix: "Start from scaffoldSkillContract() and preserve its kind/version fields.",
+        });
+    }
+    addMissingText("title", contract.title);
+    addMissingText("intent", contract.intent);
+    if (!["knowledge", "procedure", "integration"].includes(contract.skill_kind ?? "")) {
+        issues.push({
+            field: "skill_kind",
+            code: "missing",
+            message: "skill_kind must classify the contract",
+            fix: "Choose knowledge, procedure, or integration.",
+        });
+    }
+    if (!["private", "shareable_redacted", "public"].includes(contract.sensitivity ?? "")) {
+        issues.push({
+            field: "sensitivity",
+            code: "missing",
+            message: "sensitivity is required",
+            fix: "Choose private, shareable_redacted, or public.",
+        });
+    }
+    for (const field of DECLARATIONS) {
+        const issue = declarationIssue(field, contract[field], profile);
+        if (issue)
+            issues.push(issue);
+    }
+    const validateItems = (field, declaration, requiredKeys) => {
+        const d = declaration;
+        if (d?.status !== "specified" || !Array.isArray(d.items))
+            return;
+        d.items.forEach((item, index) => {
+            if (!item || typeof item !== "object")
+                return;
+            const missing = requiredKeys.filter((key) => !(key in item));
+            if (missing.length) {
+                issues.push({
+                    field,
+                    code: "invalid",
+                    message: `${field}.items[${index}] lacks ${missing.join(", ")}`,
+                    fix: `Add ${missing.join(", ")} to ${field}.items[${index}].`,
+                });
+            }
+        });
+    };
+    validateItems("triggers", contract.triggers, ["id", "description"]);
+    validateItems("inputs", contract.inputs, [
+        "name",
+        "description",
+        "schema",
+        "required",
+        "sensitivity",
+        "source",
+        "ask_when",
+        "approval",
+    ]);
+    validateItems("preconditions", contract.preconditions, ["id", "assertion", "check", "on_failure"]);
+    validateItems("steps", contract.steps, ["id", "title", "kind"]);
+    validateItems("branches", contract.branches, ["id", "condition", "then"]);
+    validateItems("human_decisions", contract.human_decisions, [
+        "id",
+        "prompt",
+        "required_before",
+        "irreversible",
+        "approval",
+    ]);
+    validateItems("capabilities", contract.capabilities, [
+        "name",
+        "description",
+        "side_effect_class",
+        "fallback",
+        "required",
+    ]);
+    validateItems("permissions", contract.permissions, [
+        "id",
+        "side_effect_class",
+        "description",
+        "consent",
+    ]);
+    validateItems("forbidden_actions", contract.forbidden_actions, [
+        "id",
+        "description",
+        "enforcement",
+    ]);
+    validateItems("outputs", contract.outputs, [
+        "name",
+        "description",
+        "schema",
+        "required",
+    ]);
+    validateItems("recovery", contract.recovery, ["id", "from_step", "condition", "action"]);
+    validateItems("verification", contract.verification, [
+        "id",
+        "assertion",
+        "check",
+        "required",
+    ]);
+    validateItems("corrections", contract.corrections, ["id", "lesson"]);
+    const provenance = contract.provenance;
+    for (const [field, value] of [
+        ["provenance.evidence", provenance?.evidence],
+        ["provenance.limitations", provenance?.limitations],
+    ]) {
+        const issue = declarationIssue(field, value, profile);
+        if (issue)
+            issues.push(issue);
+    }
+    if (!provenance?.human_review) {
+        issues.push({
+            field: "provenance.human_review",
+            code: "missing",
+            message: "human review state is absent",
+            fix: 'Declare {status:"not_reviewed"} or provide reviewed actor, time, scope, and optional digest.',
+        });
+    }
+    else if (profile === "release" && provenance.human_review.status !== "reviewed") {
+        issues.push({
+            field: "provenance.human_review",
+            code: "profile_required",
+            message: "release requires recorded human semantic review",
+            fix: "Have a human review the contract and record actor, timestamp, scope, and preferably the reviewed digest. A CLI flag cannot create this evidence.",
+        });
+    }
+    else if (provenance.human_review.status === "reviewed" &&
+        (!provenance.human_review.actor?.trim() ||
+            !provenance.human_review.at?.trim() ||
+            !provenance.human_review.scope?.length)) {
+        issues.push({
+            field: "provenance.human_review",
+            code: "approval_invalid",
+            message: "reviewed status lacks actor, timestamp, or scope evidence",
+            fix: "Record the real reviewer actor, review timestamp, and non-empty semantic scope.",
+        });
+    }
+    const complete = issues.length === 0;
+    return {
+        kind: "contract_assessment",
+        profile,
+        complete,
+        release_eligible: profile === "release" && complete,
+        issues,
+    };
+}
+/** Machine-readable authoring template. Placeholder values intentionally fail assessment. */
+export function scaffoldSkillContract() {
+    const declaration = { status: "__required__: specified|none|not_applicable", items: [] };
+    return {
+        kind: "skill_contract",
+        contract_version: "0.5",
+        skill_kind: "__required__: knowledge|procedure|integration",
+        title: "",
+        intent: "",
+        sensitivity: "__required__: private|shareable_redacted|public",
+        triggers: structuredClone(declaration),
+        inputs: structuredClone(declaration),
+        preconditions: structuredClone(declaration),
+        steps: structuredClone(declaration),
+        branches: structuredClone(declaration),
+        human_decisions: structuredClone(declaration),
+        capabilities: structuredClone(declaration),
+        permissions: structuredClone(declaration),
+        forbidden_actions: structuredClone(declaration),
+        outputs: structuredClone(declaration),
+        recovery: structuredClone(declaration),
+        verification: structuredClone(declaration),
+        corrections: structuredClone(declaration),
+        provenance: {
+            evidence: structuredClone(declaration),
+            limitations: structuredClone(declaration),
+            human_review: { status: "__required__: not_reviewed|reviewed" },
+        },
+    };
+}
+export function explainContractAssessment(assessment) {
+    return {
+        complete: assessment.complete,
+        fixes: assessment.issues.map(({ field, message, fix }) => ({ field, message, fix })),
+    };
+}

package/dist/contract.d.ts

@@ -0,0 +1,190 @@
+import type { AskWhen, CapabilityFallback, InputSource, JsonSchema, PackageSensitivity, SensitivityLevel, SideEffectClass } from "./types.js";
+/** Protocol-native contract introduced in 0.5. Product adapters must map into this vocabulary. */
+export type SkillKind = "knowledge" | "procedure" | "integration";
+export type DeclarationStatus = "specified" | "none" | "not_applicable";
+export type ExplicitDeclaration<T> = {
+    status: "specified";
+    items: T[];
+} | {
+    status: "none";
+    reason: string;
+} | {
+    status: "not_applicable";
+    reason: string;
+};
+export interface ContractTrigger {
+    id: string;
+    description: string;
+    examples?: string[];
+}
+export type InputApproval = "none" | "human_before_use";
+export interface ContractInput {
+    name: string;
+    description: string;
+    schema: JsonSchema;
+    required: boolean;
+    default?: unknown;
+    sensitivity: SensitivityLevel;
+    source: InputSource;
+    ask_when: AskWhen;
+    approval: InputApproval;
+}
+export interface ContractPrecondition {
+    id: string;
+    assertion: string;
+    check: "agent" | "capability" | "human";
+    on_failure: string;
+}
+export type ContractStepKind = "instruct" | "prompt" | "tool" | "transform" | "checkpoint" | "human_decision" | "verify" | "emit";
+export interface ContractStep {
+    id: string;
+    title: string;
+    kind: ContractStepKind;
+    instruction?: string;
+    capability?: string;
+    arguments?: Record<string, unknown>;
+    argument_bindings?: Record<string, string>;
+    result_as?: string;
+    output?: string;
+    from?: string;
+    assertions?: string[];
+    decision?: string;
+    next?: string;
+    on_failure?: string;
+    optional?: boolean;
+}
+export interface ContractBranch {
+    id: string;
+    after_step?: string;
+    condition: string;
+    then: string;
+    otherwise?: string;
+}
+export interface ContractHumanDecision {
+    id: string;
+    prompt: string;
+    choices?: string[];
+    required_before: string;
+    irreversible: boolean;
+    /** Declares an approval gate. It is never evidence that approval was granted. */
+    approval: "explicit_human";
+}
+export interface ContractCapability {
+    name: string;
+    description: string;
+    input_schema?: JsonSchema;
+    output_schema?: JsonSchema;
+    side_effect_class: SideEffectClass;
+    fallback: CapabilityFallback;
+    required: boolean;
+}
+export interface ContractPermission {
+    id: string;
+    side_effect_class: SideEffectClass;
+    description: string;
+    paths?: string[];
+    hosts?: string[];
+    consent: "none" | "explicit_human";
+}
+export interface ForbiddenAction {
+    id: string;
+    description: string;
+    enforcement: "runtime" | "host" | "review";
+}
+export interface ContractOutput {
+    name: string;
+    description: string;
+    schema: JsonSchema;
+    required: boolean;
+    media_type?: string;
+    assertions?: string[];
+}
+export interface RecoveryEdge {
+    id: string;
+    from_step: string;
+    condition: string;
+    action: string;
+    goto?: string;
+    terminal?: boolean;
+}
+export interface VerificationAssertion {
+    id: string;
+    assertion: string;
+    check: "runtime" | "capability" | "human";
+    evidence?: string[];
+    required: boolean;
+}
+export interface ContractCorrection {
+    id: string;
+    lesson: string;
+    applies_to?: string[];
+}
+export interface ContractEvidence {
+    id: string;
+    kind: "source" | "section" | "test" | "review" | "external";
+    ref: string;
+    digest?: string;
+    supports: string[];
+}
+export interface ContractProvenance {
+    evidence: ExplicitDeclaration<ContractEvidence>;
+    limitations: ExplicitDeclaration<string>;
+    human_review: {
+        status: "not_reviewed";
+    } | {
+        status: "reviewed";
+        actor: string;
+        at: string;
+        scope: string[];
+        digest?: string;
+    };
+}
+/**
+ * Complete transferable skill authoring contract.
+ *
+ * Every declaration is required on the wire. `none` and `not_applicable` are
+ * deliberate author statements; an absent field is an ambiguous omission.
+ */
+export interface SkillContract {
+    kind: "skill_contract";
+    contract_version: "0.5";
+    skill_kind: SkillKind;
+    title: string;
+    intent: string;
+    sensitivity: PackageSensitivity;
+    triggers: ExplicitDeclaration<ContractTrigger>;
+    inputs: ExplicitDeclaration<ContractInput>;
+    preconditions: ExplicitDeclaration<ContractPrecondition>;
+    steps: ExplicitDeclaration<ContractStep>;
+    branches: ExplicitDeclaration<ContractBranch>;
+    human_decisions: ExplicitDeclaration<ContractHumanDecision>;
+    capabilities: ExplicitDeclaration<ContractCapability>;
+    permissions: ExplicitDeclaration<ContractPermission>;
+    forbidden_actions: ExplicitDeclaration<ForbiddenAction>;
+    outputs: ExplicitDeclaration<ContractOutput>;
+    recovery: ExplicitDeclaration<RecoveryEdge>;
+    verification: ExplicitDeclaration<VerificationAssertion>;
+    corrections: ExplicitDeclaration<ContractCorrection>;
+    provenance: ContractProvenance;
+}
+export type ContractField = "contract" | "title" | "intent" | "skill_kind" | "sensitivity" | "triggers" | "inputs" | "preconditions" | "steps" | "branches" | "human_decisions" | "capabilities" | "permissions" | "forbidden_actions" | "outputs" | "recovery" | "verification" | "corrections" | "provenance.evidence" | "provenance.limitations" | "provenance.human_review";
+export interface ContractIssue {
+    field: ContractField;
+    code: "missing" | "empty" | "invalid" | "profile_required" | "approval_invalid";
+    message: string;
+    fix: string;
+}
+export interface ContractAssessment {
+    kind: "contract_assessment";
+    profile: "continuity" | "release";
+    complete: boolean;
+    release_eligible: boolean;
+    issues: ContractIssue[];
+}
+export interface SkillCandidate {
+    id: string;
+    title: string;
+    evidence_refs: string[];
+    assessment: ContractAssessment;
+    contract?: SkillContract;
+}

package/dist/contract.js

@@ -0,0 +1 @@
+export {};

package/dist/extract.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Multi-skill identification → scaffold extraction for agents.
+ *
+ * Segmentation is an agent/adapter responsibility. This module does not invent
+ * skills from free prose: the caller must supply candidate topics. It emits
+ * incomplete SkillContract / SkillSource scaffolds plus completeness reports
+ * so create flows stay coherent with SkillContract 0.5 and refuse incomplete
+ * release compiles.
+ */
+import type { SkillCandidate, SkillKind } from "./contract.js";
+import type { PackageSensitivity, SkillCompileProfile } from "./types.js";
+import { PROTOCOL_VERSION } from "./types.js";
+export type JourneyCandidateInput = {
+    id?: string;
+    title: string;
+    evidence_refs?: string[];
+    intent?: string;
+    skill_kind?: SkillKind;
+    notes?: string;
+};
+/** Redacted journey JSON accepted by `skill extract` / `segment`. */
+export type RedactedJourneyInput = {
+    kind?: "redacted_journey";
+    summary: string;
+    redacted?: boolean;
+    sensitivity?: PackageSensitivity;
+    /** Preferred: explicit skill candidates the agent identified. */
+    candidates?: JourneyCandidateInput[];
+    /** Convenience alias when only titles (or title objects) are known. */
+    topics?: Array<string | JourneyCandidateInput>;
+};
+export type ExtractionScaffold = {
+    candidate: SkillCandidate;
+    /** Incomplete contract scaffold; placeholders intentionally fail assessment. */
+    contract_scaffold: Record<string, unknown>;
+    /** Incomplete SkillSource scaffold for one skill (one workspace). */
+    source_scaffold: Record<string, unknown>;
+    /** Suggested workspace directory slug (relative). */
+    workspace_slug: string;
+    /** Machine-readable missing fields / fixes for this candidate. */
+    missing: Array<{
+        field: string;
+        message: string;
+        fix: string;
+    }>;
+    next_steps: string[];
+};
+export type ExtractionReport = {
+    kind: "skill_extraction";
+    protocol_version: typeof PROTOCOL_VERSION;
+    profile: SkillCompileProfile;
+    journey_summary: string;
+    redacted: boolean;
+    candidate_count: number;
+    scaffolds: ExtractionScaffold[];
+    protocol: {
+        one_workspace_per_skill: true;
+        refuse_release_if_incomplete: true;
+        rules: string[];
+        create_path: string[];
+    };
+};
+export type AgentGuide = {
+    kind: "skill_agent_guide";
+    protocol_version: typeof PROTOCOL_VERSION;
+    purpose: string;
+    rules: string[];
+    identify_multiple_skills: string[];
+    create_one_skill: string[];
+    ingest: string[];
+    cli: string[];
+    refuse: string[];
+};
+/**
+ * Emit incomplete SkillContract/SkillSource scaffolds for agent-identified candidates.
+ * Does not invent topics from free prose when candidates/topics are absent.
+ */
+export declare function extractSkillCandidates(raw: unknown, options?: {
+    profile?: SkillCompileProfile;
+    host?: string;
+}): ExtractionReport;
+/** Alias for adapters that prefer "segment" vocabulary. */
+export declare const segmentJourney: typeof extractSkillCandidates;
+/** Structured agent-facing create / multi-skill protocol (also printed by CLI). */
+export declare function agentCreateGuide(): AgentGuide;
+/** Human-readable text form of agentCreateGuide (for terminals / AGENT.md parity). */
+export declare function formatAgentGuide(guide?: AgentGuide): string;
+/** Type guard helper for partial SkillContract assessments on scaffolds. */
+export declare function assessExtractionScaffold(scaffold: ExtractionScaffold, profile?: SkillCompileProfile): SkillCandidate["assessment"];