@dot-skill/protocol 0.4.2 → 0.5.0

package/dist/extract.js

@@ -0,0 +1,299 @@
+/**
+ * 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 { createHash } from "node:crypto";
+import { assessSkillContract, scaffoldSkillContract } from "./authoring.js";
+import { PROTOCOL_VERSION } from "./types.js";
+function slugify(title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+    return slug || "skill-candidate";
+}
+function candidateId(title, index) {
+    const digest = createHash("sha256")
+        .update(`${index}:${title}`)
+        .digest("hex")
+        .slice(0, 12);
+    return `cand_${digest}`;
+}
+function normalizeCandidates(input) {
+    const fromCandidates = input.candidates ?? [];
+    const fromTopics = (input.topics ?? []).map((topic) => typeof topic === "string" ? { title: topic } : topic);
+    const merged = [...fromCandidates, ...fromTopics];
+    const seen = new Set();
+    const out = [];
+    for (const item of merged) {
+        const title = typeof item.title === "string" ? item.title.trim() : "";
+        if (!title)
+            continue;
+        const key = title.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ ...item, title });
+    }
+    return out;
+}
+function parseJourney(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new Error('extract expects JSON object { summary, candidates|topics: [...] }. Run: skill agent-guide');
+    }
+    const obj = raw;
+    const summary = typeof obj.summary === "string"
+        ? obj.summary
+        : typeof obj.journey_summary === "string"
+            ? obj.journey_summary
+            : "";
+    if (!summary.trim()) {
+        throw new Error("extract requires a redacted journey summary string (summary or journey_summary).");
+    }
+    return {
+        kind: "redacted_journey",
+        summary: summary.trim(),
+        redacted: obj.redacted !== false,
+        sensitivity: obj.sensitivity === "private" ||
+            obj.sensitivity === "shareable_redacted" ||
+            obj.sensitivity === "public"
+            ? obj.sensitivity
+            : "shareable_redacted",
+        candidates: Array.isArray(obj.candidates)
+            ? obj.candidates
+            : undefined,
+        topics: Array.isArray(obj.topics)
+            ? obj.topics
+            : undefined,
+    };
+}
+function seedContract(title, intent, skillKind, sensitivity) {
+    const scaffold = scaffoldSkillContract();
+    scaffold.title = title;
+    scaffold.intent =
+        intent?.trim() ||
+            `__required__: state the transferable intent for “${title}” (what an agent must do).`;
+    if (skillKind)
+        scaffold.skill_kind = skillKind;
+    scaffold.sensitivity = sensitivity;
+    return scaffold;
+}
+function sourceScaffold(args) {
+    return {
+        kind: "skill_source",
+        id: args.id,
+        hash: `sha256:${"0".repeat(64)}`,
+        title: args.title,
+        summary: args.summary,
+        intent: args.contract.intent,
+        contract: args.contract,
+        candidates: undefined,
+        sections: [],
+        steering: [],
+        prompts: [],
+        code_refs: [],
+        parents: [],
+        agent: {
+            host: args.host,
+            deployment: "unknown",
+        },
+        journey: {
+            summary: args.summary,
+            redacted: true,
+            sensitivity: args.sensitivity,
+        },
+        inputs_declared: "inferred",
+        sensitivity: args.sensitivity,
+        created_at: new Date(0).toISOString(),
+        actor: { id: "agent" },
+        source_protocol_version: PROTOCOL_VERSION,
+        source_refs: args.evidenceRefs.map((ref, i) => ({
+            product: "extract",
+            kind: "evidence",
+            id: `ev_${i + 1}`,
+            hash: ref,
+        })),
+    };
+}
+const PROTOCOL_RULES = [
+    "Identify distinct transferable skills from the redacted journey; do not collapse unrelated topics into one skill.",
+    "One skill workspace per candidate (skill init in its own directory).",
+    "Fill a SkillContract 0.5 for each skill; section prose alone cannot satisfy release completeness.",
+    "Run skill status / skill contract-check; refuse release compile when incomplete.",
+    "Never invent filler declarations to force a mint; use continuity checkpoint for partial handoff.",
+    "Secrets stay as {{refs}} / env refs; journey text must stay redacted.",
+];
+const CREATE_PATH = [
+    "skill agent-guide",
+    "Identify N candidate skills → write redacted_journey.json with summary + candidates|topics",
+    "skill extract redacted_journey.json -o ./extraction",
+    "For each selected candidate: mkdir workspace && cd workspace && skill init --title \"…\"",
+    "Copy/adapt contract scaffold → complete every declaration (or explicit none/not_applicable)",
+    "skill journey --summary \"…\" && skill propose … (evidence sections)",
+    "skill contract-check .skill/… or contract.json --profile release",
+    "skill status → skill compile -m \"…\" --approve --mint  (or checkpoint if incomplete)",
+];
+/**
+ * Emit incomplete SkillContract/SkillSource scaffolds for agent-identified candidates.
+ * Does not invent topics from free prose when candidates/topics are absent.
+ */
+export function extractSkillCandidates(raw, options = {}) {
+    const journey = parseJourney(raw);
+    const profile = options.profile ?? "release";
+    const host = options.host ?? "__set_SKILL_HOST__";
+    const candidates = normalizeCandidates(journey);
+    if (candidates.length === 0) {
+        throw new Error("No skill candidates supplied. Identify distinct skills from the journey, then pass candidates:[{title,evidence_refs?}] or topics:[\"…\"]. See: skill agent-guide");
+    }
+    const scaffolds = candidates.map((item, index) => {
+        const id = item.id?.trim() || candidateId(item.title, index);
+        const evidence = item.evidence_refs?.filter((r) => typeof r === "string" && r.trim()) ??
+            [];
+        if (evidence.length === 0) {
+            evidence.push(`journey:${slugify(item.title)}`);
+        }
+        const contract = seedContract(item.title, item.intent, item.skill_kind, journey.sensitivity ?? "shareable_redacted");
+        const assessment = assessSkillContract(contract, profile);
+        const candidate = {
+            id,
+            title: item.title,
+            evidence_refs: evidence,
+            assessment,
+            // Incomplete scaffold is intentional; do not claim a complete contract.
+            contract: undefined,
+        };
+        const workspace_slug = slugify(item.title);
+        const missing = assessment.issues.map(({ field, message, fix }) => ({
+            field,
+            message,
+            fix,
+        }));
+        const source = sourceScaffold({
+            id: `src_${id.replace(/^cand_/, "")}`,
+            title: item.title,
+            summary: journey.summary,
+            contract,
+            evidenceRefs: evidence,
+            sensitivity: journey.sensitivity ?? "shareable_redacted",
+            host,
+        });
+        return {
+            candidate,
+            contract_scaffold: contract,
+            source_scaffold: source,
+            workspace_slug,
+            missing,
+            next_steps: [
+                `mkdir -p ${workspace_slug} && cd ${workspace_slug} && export SKILL_HOST=${host === "__set_SKILL_HOST__" ? "cursor" : host} && skill init --title ${JSON.stringify(item.title)}`,
+                "Complete contract_scaffold into a real SkillContract 0.5 (every declaration explicit).",
+                `skill contract-check contract.json --profile ${profile}`,
+                'skill journey --summary "…" && skill propose --json \'[…]\'',
+                "skill status — refuse release compile until complete; use skill checkpoint for handoff.",
+            ],
+        };
+    });
+    return {
+        kind: "skill_extraction",
+        protocol_version: PROTOCOL_VERSION,
+        profile,
+        journey_summary: journey.summary,
+        redacted: journey.redacted !== false,
+        candidate_count: scaffolds.length,
+        scaffolds,
+        protocol: {
+            one_workspace_per_skill: true,
+            refuse_release_if_incomplete: true,
+            rules: PROTOCOL_RULES,
+            create_path: CREATE_PATH,
+        },
+    };
+}
+/** Alias for adapters that prefer "segment" vocabulary. */
+export const segmentJourney = extractSkillCandidates;
+/** Structured agent-facing create / multi-skill protocol (also printed by CLI). */
+export function agentCreateGuide() {
+    return {
+        kind: "skill_agent_guide",
+        protocol_version: PROTOCOL_VERSION,
+        purpose: "Create portable .skill packages with SkillContract 0.5. Identify multiple skills from a conversation when warranted; enforce completeness; never fake a release.",
+        rules: PROTOCOL_RULES,
+        identify_multiple_skills: [
+            "Read the redacted journey / work summary. List distinct transferable skills (separate intents, triggers, or runtimes).",
+            "Do not invent a multi-skill auto-pipeline beyond this protocol. You identify; the CLI scaffolds.",
+            "Write JSON: { \"kind\":\"redacted_journey\", \"summary\":\"…\", \"redacted\":true, \"candidates\":[{ \"title\":\"…\", \"evidence_refs\":[\"…\"], \"intent\":\"…\", \"skill_kind\":\"procedure|knowledge|integration\" }] }",
+            "Run: skill extract journey.json -o ./extraction",
+            "Present candidates + missing[] reports to the human. Only proceed on selected skills.",
+            "One directory / one skill init per selected candidate. Never merge unrelated candidates into one workspace.",
+        ],
+        create_one_skill: [
+            "export SKILL_HOST=<your-host-id>",
+            "skill init --title \"…\"",
+            "skill journey --summary \"Redacted human+AI journey…\"",
+            "Complete SkillContract 0.5 (skill contract-template → edit → skill contract-check).",
+            "skill propose --json '[{\"title\":\"…\",\"body\":\"…\",\"type\":\"decision|integration|…\"}]' for evidence sections",
+            "skill status — inspect completeness / missing",
+            "Partial handoff: skill checkpoint -m \"WIP\"",
+            "Release only when complete: skill compile -m \"…\" --approve --mint",
+            "On compile_refused: list missing fields/fixes; do not pack a fake release.",
+        ],
+        ingest: [
+            "skill inspect ./file.skill",
+            "skill validate ./file.skill",
+            "skill verify-trust ./file.skill",
+            "skill load ./file.skill   # continuity resume",
+            "skill run ./file.skill   # dry-run by default",
+        ],
+        cli: [
+            "skill agent-guide [--json]",
+            "skill extract <journey.json> [-o dir] [--profile release|continuity]",
+            "skill segment …          # alias of extract",
+            "skill contract-template",
+            "skill contract-check <contract-or-source.json> [--profile release|continuity]",
+            "skill status",
+        ],
+        refuse: [
+            "Refuse release compile/mint when contract assessment is incomplete.",
+            "Refuse to invent filler skills or filler contract fields to satisfy gates.",
+            "Refuse to create multiple skills in one workspace.",
+            "Refuse to proceed without SKILL_HOST on create/mint paths.",
+        ],
+    };
+}
+/** Human-readable text form of agentCreateGuide (for terminals / AGENT.md parity). */
+export function formatAgentGuide(guide = agentCreateGuide()) {
+    const lines = [
+        `skill agent-guide — Open .skill Protocol v${guide.protocol_version}`,
+        "",
+        guide.purpose,
+        "",
+        "Rules:",
+        ...guide.rules.map((r) => `  - ${r}`),
+        "",
+        "Identify → propose multiple skills:",
+        ...guide.identify_multiple_skills.map((r, i) => `  ${i + 1}. ${r}`),
+        "",
+        "Create one skill (complete or refuse):",
+        ...guide.create_one_skill.map((r) => `  $ ${r}`),
+        "",
+        "Ingest / load / run:",
+        ...guide.ingest.map((r) => `  $ ${r}`),
+        "",
+        "CLI:",
+        ...guide.cli.map((r) => `  $ ${r}`),
+        "",
+        "Refuse when:",
+        ...guide.refuse.map((r) => `  - ${r}`),
+        "",
+    ];
+    return lines.join("\n");
+}
+/** Type guard helper for partial SkillContract assessments on scaffolds. */
+export function assessExtractionScaffold(scaffold, profile = "release") {
+    return assessSkillContract(scaffold.contract_scaffold, profile);
+}

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-/** Open .skill Protocol v0.4 — types, constants, and schemas. */
+/** Open .skill Protocol v0.5 — types, constants, authoring APIs, and schemas. */
 export { PROTOCOL_VERSION, CONTAINER_VERSION, WORKFLOW_DIALECT_VERSION, MEDIA_TYPE, MANIFEST_MEDIA_TYPE, DEFAULT_SKILL_POLICY, } from "./types.js";
-export type { SkillCompileProfile, PackageSensitivity, ProvenanceMode, MintStatus, PermanenceAnchorKind, TrustProfile, InputSource, SensitivityLevel, AskWhen, SideEffectClass, CapabilityFallback, KnowledgeItemType, SteeringEffect, WorkflowStepKind, SkillRunStatus, RuntimeMode, CompletenessPart, GenerationUsage, JourneyProvenance, CompletenessReport, JsonSchema, ContentDigest, ProvenanceRef, InputSlot, OutputContract, CapabilityAdapterHint, CapabilityRequirement, SkillPermission, SkillPolicy, SkillDependency, MintRecord, CreationAttestation, PermanenceAnchor, SkillManifest, KnowledgeItem, SteeringConstraint, WorkflowStepBase, InstructStep, PromptStep, ToolStep, TransformStep, BranchStep, IterateStep, DelegateStep, CheckpointStep, HumanDecisionStep, VerifyStep, EmitStep, SubskillStep, WorkflowStep, Workflow, CompilationIssue, CompilationMapping, CompilationReport, SkillPackageFiles, SkillStepRecord, SkillRun, } from "./types.js";
-export { FORBIDDEN_AGENT_HOSTS, isValidAgentHost, } from "./source.js";
+export type { SkillCompileProfile, PackageSensitivity, ProvenanceMode, MintStatus, PermanenceAnchorKind, TrustProfile, TrustState, HostClaimBinding, IssuerClass, InputSource, SensitivityLevel, AskWhen, SideEffectClass, CapabilityFallback, KnowledgeItemType, SteeringEffect, WorkflowStepKind, SkillRunStatus, RuntimeMode, CompletenessPart, GenerationUsage, JourneyProvenance, CompletenessReport, JsonSchema, ContentDigest, ProvenanceRef, InputSlot, OutputContract, CapabilityAdapterHint, CapabilityRequirement, SkillPermission, SkillPolicy, SkillDependency, MintRecord, SealedManifestClaims, CreationAttestation, TrustView, PermanenceAnchor, SkillManifest, KnowledgeItem, SteeringConstraint, WorkflowStepBase, InstructStep, PromptStep, ToolStep, TransformStep, BranchStep, IterateStep, DelegateStep, CheckpointStep, HumanDecisionStep, VerifyStep, EmitStep, SubskillStep, WorkflowStep, Workflow, CompilationIssue, CompilationMapping, CompilationReport, SkillPackageFiles, SkillStepRecord, SkillRun, } from "./types.js";
+export { FORBIDDEN_AGENT_HOSTS, AGENT_RUNTIME_MARKER_ENVS, isValidAgentHost, detectAgentRuntimeMarkers, hasAgentRuntimeEvidence, } from "./source.js";
+export { assessSkillContract, scaffoldSkillContract, explainContractAssessment, } from "./authoring.js";
+export { extractSkillCandidates, segmentJourney, agentCreateGuide, formatAgentGuide, assessExtractionScaffold, } from "./extract.js";
+export type { JourneyCandidateInput, RedactedJourneyInput, ExtractionScaffold, ExtractionReport, AgentGuide, } from "./extract.js";
+export type { SkillKind, DeclarationStatus, ExplicitDeclaration, ContractTrigger, InputApproval, ContractInput, ContractPrecondition, ContractStepKind, ContractStep, ContractBranch, ContractHumanDecision, ContractCapability, ContractPermission, ForbiddenAction, ContractOutput, RecoveryEdge, VerificationAssertion, ContractCorrection, ContractEvidence, ContractProvenance, SkillContract, ContractField, ContractIssue, ContractAssessment, SkillCandidate, } from "./contract.js";
 export type { SectionType, SectionAuthor, CodeRef, Attachment, PersonRef, SkillSection, SteeringEvent, PromptVersion, AgentContext, SkillSource, SteeringVerb, CaptureFidelity, } from "./source.js";
 export { recipeToSkillSource } from "./recipe.js";
 export type { IngredientType, VisibilityIntent, RecipeIngredient, Recipe, Skill, } from "./recipe.js";

package/dist/index.js

@@ -1,4 +1,6 @@
-/** Open .skill Protocol v0.4 — types, constants, and schemas. */
+/** Open .skill Protocol v0.5 — types, constants, authoring APIs, and schemas. */
 export { PROTOCOL_VERSION, CONTAINER_VERSION, WORKFLOW_DIALECT_VERSION, MEDIA_TYPE, MANIFEST_MEDIA_TYPE, DEFAULT_SKILL_POLICY, } from "./types.js";
-export { FORBIDDEN_AGENT_HOSTS, isValidAgentHost, } from "./source.js";
+export { FORBIDDEN_AGENT_HOSTS, AGENT_RUNTIME_MARKER_ENVS, isValidAgentHost, detectAgentRuntimeMarkers, hasAgentRuntimeEvidence, } from "./source.js";
+export { assessSkillContract, scaffoldSkillContract, explainContractAssessment, } from "./authoring.js";
+export { extractSkillCandidates, segmentJourney, agentCreateGuide, formatAgentGuide, assessExtractionScaffold, } from "./extract.js";
 export { recipeToSkillSource } from "./recipe.js";

package/dist/recipe.d.ts

@@ -5,6 +5,7 @@
  * Skillerr (and similar products) map recipe/ingredient/bake → SkillSource/compile.
  */
 import type { GenerationUsage, JourneyProvenance } from "./types.js";
+import type { SkillContract } from "./contract.js";
 import type { AgentContext, Attachment, CodeRef, PersonRef, PromptVersion, SectionType, SkillSource, SteeringEvent } from "./source.js";
 /** @deprecated Prefer SectionType from source.ts — kept for Skillerr adapters. */
 export type IngredientType = SectionType;
@@ -48,6 +49,8 @@ export interface Recipe {
     source_protocol_version: string;
     generation_usage?: GenerationUsage;
     journey_summary?: string;
+    /** Optional 0.5 protocol-native semantics carried through this lossy product adapter. */
+    contract?: SkillContract;
 }
 /** @deprecated Legacy flat markdown skill export. Prefer SkillManifest / `.skill`. */
 export interface Skill {

package/dist/recipe.js

@@ -45,6 +45,7 @@ export function recipeToSkillSource(recipe, overrides = {}) {
         title: recipe.title,
         summary: recipe.summary,
         intent: recipe.summary ?? recipe.title,
+        contract: recipe.contract ? structuredClone(recipe.contract) : undefined,
         sections,
         steering: recipe.steering,
         prompts: recipe.prompts,

package/dist/source.d.ts

@@ -4,6 +4,7 @@
  * Products (Skillerr, etc.) may use their own words (ingredient, recipe, bake).
  * Adapters map those into SkillSource / SkillSection before compile.
  */
+import type { SkillContract, SkillCandidate } from "./contract.js";
 import type { GenerationUsage, JourneyProvenance, PackageSensitivity } from "./types.js";
 export type SectionType = "prompt" | "decision" | "architecture" | "diagram" | "integration" | "resource" | "reference" | "lesson" | "requirement" | "tradeoff" | "risk" | "question" | "implementation_note" | "config" | "correction_note" | "doc" | "message" | "handoff" | "code" | "intent" | "workflow_note";
 export type SectionAuthor = "agent" | "human_via_agent";
@@ -89,6 +90,13 @@ export interface SkillSource {
     title: string;
     summary?: string;
     intent?: string;
+    /**
+     * 0.5 source of truth for transferable semantics. A missing contract marks
+     * a 0.4-compatible text source and is release-lossy.
+     */
+    contract?: SkillContract;
+    /** Optional extraction candidates. Segmentation belongs to an adapter/AI, not the compiler. */
+    candidates?: SkillCandidate[];
     sections: SkillSection[];
     steering: SteeringEvent[];
     prompts: PromptVersion[];
@@ -111,6 +119,20 @@ export interface SkillSource {
         hash?: string;
     }>;
 }
-/** Hosts that are not valid AI agent runtimes for skill creation. */
+/**
+ * Hosts that are not valid AI agent runtimes for skill creation / mint.
+ * Humans exporting SKILL_HOST=cli|shell|manual must never mint as an agent.
+ */
 export declare const FORBIDDEN_AGENT_HOSTS: Set<string>;
 export declare function isValidAgentHost(host: string | undefined | null): boolean;
+/**
+ * Process / mint markers that indicate an agent runtime path (not a bare human shell).
+ * These are still spoofable by a determined local process — residual risk remains —
+ * but a human who only exports SKILL_HOST=cursor without any agent context fails this check.
+ */
+export declare const AGENT_RUNTIME_MARKER_ENVS: readonly ["CURSOR_AGENT", "CURSOR_TRACE_ID", "COMPOSER_SESSION_ID", "SKILL_AGENT_INVOCATION", "SKILL_SESSION_ID", "CLAUDE_CODE_ENTRYPOINT", "AIDER_ACTIVE"];
+export declare function detectAgentRuntimeMarkers(env?: Record<string, string | undefined>): string[];
+export declare function hasAgentRuntimeEvidence(evidence?: {
+    markers?: string[];
+    session_id?: string;
+} | null, env?: Record<string, string | undefined>): boolean;

package/dist/source.js

@@ -4,7 +4,10 @@
  * Products (Skillerr, etc.) may use their own words (ingredient, recipe, bake).
  * Adapters map those into SkillSource / SkillSection before compile.
  */
-/** Hosts that are not valid AI agent runtimes for skill creation. */
+/**
+ * Hosts that are not valid AI agent runtimes for skill creation / mint.
+ * Humans exporting SKILL_HOST=cli|shell|manual must never mint as an agent.
+ */
 export const FORBIDDEN_AGENT_HOSTS = new Set([
     "",
     "human",
@@ -12,9 +15,55 @@ export const FORBIDDEN_AGENT_HOSTS = new Set([
     "none",
     "cli",
     "user",
+    "shell",
+    "bash",
+    "zsh",
+    "sh",
+    "fish",
+    "powershell",
+    "pwsh",
+    "cmd",
+    "terminal",
+    "console",
+    "tty",
+    "stdin",
+    "keyboard",
+    "local-shell",
+    "human-cli",
+    "operator",
 ]);
 export function isValidAgentHost(host) {
     if (!host)
         return false;
     return !FORBIDDEN_AGENT_HOSTS.has(host.trim().toLowerCase());
 }
+/**
+ * Process / mint markers that indicate an agent runtime path (not a bare human shell).
+ * These are still spoofable by a determined local process — residual risk remains —
+ * but a human who only exports SKILL_HOST=cursor without any agent context fails this check.
+ */
+export const AGENT_RUNTIME_MARKER_ENVS = [
+    "CURSOR_AGENT",
+    "CURSOR_TRACE_ID",
+    "COMPOSER_SESSION_ID",
+    "SKILL_AGENT_INVOCATION",
+    "SKILL_SESSION_ID",
+    "CLAUDE_CODE_ENTRYPOINT",
+    "AIDER_ACTIVE",
+];
+export function detectAgentRuntimeMarkers(env = process.env) {
+    const found = [];
+    for (const key of AGENT_RUNTIME_MARKER_ENVS) {
+        const v = env[key];
+        if (v !== undefined && String(v).trim() !== "")
+            found.push(key);
+    }
+    return found;
+}
+export function hasAgentRuntimeEvidence(evidence, env = process.env) {
+    if (evidence?.session_id && evidence.session_id.trim())
+        return true;
+    if (evidence?.markers?.some((m) => m.trim()))
+        return true;
+    return detectAgentRuntimeMarkers(env).length > 0;
+}

package/dist/types.d.ts

@@ -1,7 +1,8 @@
-/** Open .skill Protocol v0.4 — semantic types for portable `.skill` packages. */
-export declare const PROTOCOL_VERSION = "0.4.0";
+/** Open .skill Protocol v0.5 — semantic types for portable `.skill` packages. */
+import type { ContractBranch, ContractHumanDecision, InputApproval, ContractPrecondition, ContractTrigger, ExplicitDeclaration, RecoveryEdge, SkillContract, VerificationAssertion } from "./contract.js";
+export declare const PROTOCOL_VERSION = "0.5.0";
 export declare const CONTAINER_VERSION = "1.0";
-export declare const WORKFLOW_DIALECT_VERSION = "1.0";
+export declare const WORKFLOW_DIALECT_VERSION = "1.1";
 /** Media type for a packaged `.skill` archive (zip). */
 export declare const MEDIA_TYPE = "application/vnd.dot-skill+zip";
 /** Media type for the manifest JSON document inside a `.skill` archive. */
@@ -18,6 +19,21 @@ export type ProvenanceMode = "full" | "redacted" | "proof_only";
 export type MintStatus = "draft" | "minted";
 export type PermanenceAnchorKind = "registry" | "transparency_log" | "ledger" | "content_addressed_store" | "other";
 export type TrustProfile = "open" | "minted" | "anchored" | `issuer:${string}`;
+/**
+ * Human-readable trust decision for TrustView / inspect --trust.
+ * - untrusted: unsigned, open, or failed verification
+ * - development: public-dev HMAC verified structurally — never production trust
+ * - self_reported: signed, but host/model claims are env/self-asserted (not issuer-verified)
+ * - verified_issuer: configured non-public issuer key bound the sealed claims
+ */
+export type TrustState = "untrusted" | "development" | "self_reported" | "verified_issuer";
+/** How the host/model claim was bound into the seal. */
+export type HostClaimBinding = "self_reported" | "verified_issuer";
+/**
+ * Class of mint issuer key material.
+ * public_dev_hmac MUST NOT be treated as production trust.
+ */
+export type IssuerClass = "public_dev_hmac" | "configured_hmac" | "verified_issuer";
 export type InputSource = "human" | "environment" | "secret" | "artifact" | "derived";
 export type SensitivityLevel = "public" | "private" | "secret";
 export type AskWhen = "always" | "if_missing" | "never";
@@ -29,7 +45,7 @@ export type WorkflowStepKind = "instruct" | "prompt" | "tool" | "transform" | "b
 export type SkillRunStatus = "pending" | "running" | "paused" | "succeeded" | "failed" | "cancelled";
 export type RuntimeMode = "inspect" | "explain" | "dry_run" | "execute" | "resume";
 /** Parts the compiler checks before producing a package. */
-export type CompletenessPart = "agent_context" | "intent" | "sections" | "workflow" | "knowledge_or_prompts" | "inputs_declared" | "journey" | "generation_usage" | "human_approvals";
+export type CompletenessPart = "agent_context" | "intent" | "sections" | "workflow" | "knowledge_or_prompts" | "inputs_declared" | "journey" | "generation_usage" | "human_approvals" | "semantic_contract" | "triggers" | "inputs" | "preconditions" | "steps" | "branches" | "human_decisions" | "capabilities" | "permissions" | "forbidden_actions" | "outputs" | "recovery" | "verification" | "corrections" | "provenance";
 export interface GenerationUsage {
     input_tokens?: number;
     output_tokens?: number;
@@ -79,6 +95,7 @@ export interface InputSlot {
     default?: unknown;
     sensitivity: SensitivityLevel;
     ask_when: AskWhen;
+    approval?: InputApproval;
     examples?: unknown[];
     provenance?: ProvenanceRef[];
     generalization_reason?: string;
@@ -139,9 +156,60 @@ export interface MintRecord {
     mint_issuer?: string;
     content_id?: string;
 }
+/**
+ * Claims bound by the creation seal (identity + safety + content digests).
+ * Digest of this object is `sealed_manifest_digest`.
+ */
+export interface SealedManifestClaims {
+    id: string;
+    version: string;
+    title: string;
+    intent?: string;
+    description: string;
+    package_digest: string;
+    permissions: Array<{
+        side_effect_class: SideEffectClass;
+        description: string;
+        paths?: string[];
+        hosts?: string[];
+        requires_consent: boolean;
+    }>;
+    policy: {
+        require_signatures: boolean;
+        require_minted?: boolean;
+        require_anchor?: boolean;
+        allow_network: boolean;
+        filesystem_roots?: string[];
+        consent_for: SideEffectClass[];
+        trust_profile?: TrustProfile;
+        max_tool_calls: number;
+        max_runtime_ms: number;
+        fail_on_unsupported_step: boolean;
+    };
+    capabilities: Array<{
+        name: string;
+        side_effect_class: SideEffectClass;
+        required: boolean;
+    }>;
+    inputs: Array<{
+        name: string;
+        sensitivity: SensitivityLevel;
+        required: boolean;
+        source: InputSource;
+    }>;
+    content: ContentDigest[];
+    contract?: {
+        title: string;
+        intent: string;
+        skill_kind: string;
+        sensitivity: string;
+    };
+}
 export interface CreationAttestation {
     kind: "creation_attestation";
     package_digest: string;
+    /** Digest over identity + permissions/policy/capabilities + content index. */
+    sealed_manifest_digest: string;
     skill_id: string;
     skill_version: string;
     minted_at: string;
@@ -155,6 +223,12 @@ export interface CreationAttestation {
     model?: string;
     deployment?: "local" | "hosted" | "hybrid" | "unknown";
     endpoint?: string;
+    /** Whether host/model claims are self-asserted or issuer-verified. */
+    host_claim_binding: HostClaimBinding;
+    /** Issuer key class — public_dev_hmac is never production trust. */
+    issuer_class: IssuerClass;
+    /** Agent-runtime markers observed at mint (inspectable; still spoofable locally). */
+    agent_runtime_markers?: string[];
     journey: {
         /** @deprecated Prefer source_id — Skillerr recipe id when adapted. */
         recipe_id?: string;
@@ -172,6 +246,35 @@ export interface CreationAttestation {
     };
     policy_profile?: TrustProfile;
 }
+/** Seal / trust summary readable without compile or model body ingest. */
+export interface TrustView {
+    trust_state: TrustState;
+    mint_status: MintStatus;
+    signed: boolean;
+    issuer?: string;
+    issuer_class?: IssuerClass;
+    host_claim_binding?: HostClaimBinding;
+    agent?: {
+        host?: string;
+        provider?: string;
+        model?: string;
+        runtime?: string;
+        version?: string;
+        key_id?: string;
+        deployment?: string;
+        markers?: string[];
+    };
+    package_digest: string;
+    sealed_manifest_digest?: string;
+    attestation_digest?: string;
+    label: string;
+    warnings: string[];
+    issues: Array<{
+        severity: "error" | "warning";
+        code: string;
+        message: string;
+    }>;
+}
 export interface PermanenceAnchor {
     kind: PermanenceAnchorKind;
     package_digest: string;
@@ -192,7 +295,16 @@ export interface SkillManifest {
     title: string;
     description: string;
     intent?: string;
-    triggers?: string[];
+    /** Authoritative 0.5 semantic contract. Absent only on legacy/draft adapters. */
+    contract?: SkillContract;
+    triggers?: ContractTrigger[];
+    preconditions?: ExplicitDeclaration<ContractPrecondition>;
+    branches?: ExplicitDeclaration<ContractBranch>;
+    human_decisions?: ExplicitDeclaration<ContractHumanDecision>;
+    forbidden_actions?: SkillContract["forbidden_actions"];
+    recovery?: ExplicitDeclaration<RecoveryEdge>;
+    verification?: ExplicitDeclaration<VerificationAssertion>;
+    corrections?: SkillContract["corrections"];
     authors?: Array<{
         id: string;
         display_name?: string;
@@ -217,6 +329,8 @@ export interface SkillManifest {
     package_sensitivity?: PackageSensitivity;
     mint?: MintRecord;
     attestation_digest?: string;
+    /** Present on minted packages — binds identity/policy/content claims in the seal. */
+    sealed_manifest_digest?: string;
     anchors?: PermanenceAnchor[];
     legacy?: boolean;
     needs_human_review?: boolean;
@@ -331,6 +445,11 @@ export interface Workflow {
     entrypoint: string;
     steps: WorkflowStep[];
     constraints?: SteeringConstraint[];
+    preconditions?: ExplicitDeclaration<ContractPrecondition>;
+    branches?: ExplicitDeclaration<ContractBranch>;
+    human_decisions?: ExplicitDeclaration<ContractHumanDecision>;
+    recovery?: ExplicitDeclaration<RecoveryEdge>;
+    verification?: ExplicitDeclaration<VerificationAssertion>;
 }
 export interface CompilationIssue {
     severity: "error" | "warning" | "info";
@@ -360,6 +479,8 @@ export interface CompilationReport {
     pending_approvals: string[];
     approved: boolean;
     completeness: CompletenessReport;
+    semantic_contract: "native_0.5" | "legacy_lossy";
+    losses?: string[];
 }
 export interface SkillPackageFiles {
     manifest: SkillManifest;