skillpack-one 0.1.0-alpha.10

package/dist/src/types.d.ts

@@ -0,0 +1,251 @@
+export type Locale = "en" | "zh" | "zh-CN" | (string & {});
+export type Localized<T> = {
+    en: T;
+    [locale: string]: T;
+};
+export type SkillKind = "atom" | "category" | "meta";
+export type Risk = "read-only" | "reversible-write" | "external-communication" | "high-stakes" | "destructive" | "privileged";
+export interface CapabilityPort {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+}
+export interface PermissionEnvelope {
+    network: "none" | "read" | "write";
+    filesystem: "none" | "read" | "workspace-write" | "unrestricted-write";
+    shell: "none" | "allowlisted" | "unrestricted";
+    secrets: "none" | "named-read";
+    externalCommunication: "none" | "draft" | "send";
+}
+export interface SkillContract {
+    schemaVersion: 1;
+    id: string;
+    kind: SkillKind;
+    version: string;
+    name: Localized<string>;
+    summary: Localized<string>;
+    outcomes: string[];
+    artifacts: string[];
+    inputs: CapabilityPort[];
+    outputs: CapabilityPort[];
+    preconditions: string[];
+    failures: string[];
+    sideEffects: string[];
+    permissions: PermissionEnvelope;
+    taxonomy: {
+        primaryCategory: string;
+        secondaryCategories?: string[];
+        lifecycle: string[];
+        modalities: string[];
+        dependencies: string[];
+        risk: Risk;
+    };
+    routing: {
+        positiveTriggers: Localized<string[]>;
+        negativeTriggers: Localized<string[]>;
+        confusableWith: string[];
+    };
+    provenance: {
+        origin: string;
+        license: string;
+        derivedFrom?: string[];
+    };
+    evaluations: string[];
+}
+export interface CatalogEntry {
+    schemaVersion: 1;
+    id: string;
+    type: "skill" | "mcp-server" | "plugin" | "harness";
+    name: string;
+    summary: string;
+    author: string;
+    source: {
+        repository: string;
+        revision: string;
+        path: string;
+        url: string;
+    };
+    license: {
+        status: "declared" | "detected" | "unknown" | "conflicting";
+        spdx?: string;
+    };
+    verifiedAt: string;
+    capabilities: string[];
+    security: {
+        status: "unreviewed" | "metadata-reviewed" | "statically-reviewed" | "sandbox-tested" | "rejected";
+        executesUpstreamCode: boolean;
+        notes?: string;
+    };
+    fingerprint?: string;
+    duplicateCluster?: string;
+    freshness?: "current" | "stale" | "archived" | "unknown";
+}
+export interface TaxonomyNode {
+    id: string;
+    parent?: string;
+    label: Localized<string>;
+    description?: Localized<string>;
+    includes: string[];
+    excludes: string[];
+    boundaryExamples?: string[];
+    keywords?: Localized<string[]>;
+}
+export interface Taxonomy {
+    schemaVersion: 1;
+    version: string;
+    maxDepth?: number;
+    nodes: TaxonomyNode[];
+}
+export interface CapabilityPack {
+    schemaVersion: 1;
+    id: string;
+    version: string;
+    name: Localized<string>;
+    description?: Localized<string>;
+    atoms: string[];
+    optionalMcps: string[];
+    specialSkills?: string[];
+    ordering?: Array<{
+        before: string;
+        after: string;
+    }>;
+    acceptanceTests: string[];
+    runtimeState?: CapabilityPackRuntimeState;
+}
+export interface CapabilityPackRuntimeState {
+    stateSchema: string;
+    initialState: string;
+    patchSemantics: "json-merge-patch";
+    historyPolicy: "external-audit-log";
+}
+export interface CapabilityPackPlan {
+    pack: string;
+    name: Localized<string>;
+    skills: string[];
+    stages: string[][];
+    acceptanceTests: string[];
+    runtimeState?: CapabilityPackRuntimeState;
+}
+export interface PackRecommendation {
+    pack: string;
+    score: number;
+    matchedSkills: string[];
+    missingSkills: string[];
+    plan: CapabilityPackPlan;
+}
+export interface RoutingExample {
+    id: string;
+    prompt: string;
+    expectedCategory: string | null;
+    expectedAtoms: string[];
+    acceptableAtomGroups?: string[][];
+    mustNotRoute: string[];
+    task?: string;
+    rubric?: string[];
+    tags?: string[];
+}
+export interface EvalDataset {
+    schemaVersion: 1;
+    id: string;
+    split: "train" | "dev" | "test" | "adversarial" | "tasks";
+    locale: string;
+    protected?: boolean;
+    examples: RoutingExample[];
+}
+export interface RoutingMetrics {
+    categoryHit1: number;
+    categoryHit3: number;
+    atomHit1: number;
+    atomHit3: number;
+    atomMrr: number;
+    atomRecall3: number;
+    atomFullCoverage3: number;
+    nonInvocationAccuracy: number;
+    safetyPassRate: number;
+}
+export type SkillRelationType = "confusable-with" | "compose-with" | "depends-on" | "packaged-in";
+export interface SkillRelationNode {
+    id: string;
+    kind: SkillKind | "pack";
+}
+export interface SkillRelationEdge {
+    from: string;
+    to: string;
+    type: SkillRelationType;
+    evidence: string[];
+}
+export interface SkillRelationGraph {
+    schemaVersion: 1;
+    nodes: SkillRelationNode[];
+    edges: SkillRelationEdge[];
+}
+export interface RoutingEvaluationResult {
+    dataset: string;
+    split: EvalDataset["split"];
+    locale: string;
+    protected: boolean;
+    examples: number;
+    metrics: RoutingMetrics;
+    failures: Array<{
+        exampleId: string;
+        reason: string;
+    }>;
+}
+export interface CompletionMetrics {
+    taskCompletionRate: number;
+    rubricPassRate: number;
+    blockedRate: number;
+    averageCostUsd?: number;
+    averageLatencyMs?: number;
+}
+export interface TaskEvaluationResult {
+    dataset: string;
+    harness: {
+        name: string;
+        version: string;
+    };
+    skillMode: "enabled" | "disabled";
+    synthetic: boolean;
+    examples: number;
+    metrics: CompletionMetrics;
+    failures: Array<{
+        exampleId: string;
+        reason: string;
+    }>;
+}
+export interface SkillEffectMetrics {
+    taskCompletionLift: number;
+    rubricPassLift: number;
+    blockedRateChange: number;
+    averageCostUsdChange?: number;
+    averageLatencyMsChange?: number;
+}
+export interface SkillEffectResult {
+    schemaVersion: 1;
+    dataset: string;
+    harness: {
+        name: string;
+        version: string;
+    };
+    baseline: "without-skill";
+    candidate: "with-skill";
+    certifiable: boolean;
+    metrics: SkillEffectMetrics;
+    passed: boolean;
+    failures: string[];
+}
+export interface RouteCandidate {
+    id: string;
+    score: number;
+    matched: string[];
+    penalties: string[];
+}
+export interface RouteTrace {
+    prompt: string;
+    locale: string;
+    categories: RouteCandidate[];
+    atoms: RouteCandidate[];
+    special: RouteCandidate[];
+    ambiguous: boolean;
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/src/validation.d.ts

@@ -0,0 +1,8 @@
+import type { Taxonomy } from "./types.js";
+export interface ValidationReport {
+    checked: string[];
+    errors: string[];
+}
+export declare function validateDocumentAgainstSchema(root: string, schemaName: string, document: unknown, label?: string): Promise<string[]>;
+export declare function lintTaxonomy(taxonomy: Taxonomy): string[];
+export declare function validateRepository(root: string): Promise<ValidationReport>;

package/dist/src/validation.js

@@ -0,0 +1,166 @@
+import { createRequire } from "node:module";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { loadContracts, loadTaxonomy } from "./registry.js";
+import { loadPacks } from "./packs.js";
+import { loadEvolutionPatternDocuments, renderEvolutionKnowledgeIndex, validateEvolutionKnowledgeGraph } from "./train/knowledge.js";
+import { validatePackRuntimeStateProfile } from "./runtime/state.js";
+const require = createRequire(import.meta.url);
+const Ajv2020 = (require("ajv/dist/2020").default ?? require("ajv/dist/2020"));
+const addFormats = (require("ajv-formats").default ?? require("ajv-formats"));
+async function schemaValidator(root, schemaName) {
+    const schema = JSON.parse(await readFile(path.join(root, "schemas", `${schemaName}.schema.json`), "utf8"));
+    const ajv = new Ajv2020({ allErrors: true, strict: true });
+    addFormats(ajv);
+    return ajv.compile(schema);
+}
+function formatSchemaErrors(label, errors) {
+    return (errors ?? []).map((error) => `${label}${error.instancePath || "/"}: ${error.message ?? error.keyword}`);
+}
+export async function validateDocumentAgainstSchema(root, schemaName, document, label = schemaName) {
+    const validator = await schemaValidator(root, schemaName);
+    return validator(document) ? [] : formatSchemaErrors(label, validator.errors);
+}
+export function lintTaxonomy(taxonomy) {
+    const errors = [];
+    const seen = new Set();
+    const canonical = new Map();
+    for (const node of taxonomy.nodes) {
+        if (seen.has(node.id))
+            errors.push(`duplicate taxonomy node id: ${node.id}`);
+        seen.add(node.id);
+        if (!canonical.has(node.id))
+            canonical.set(node.id, node);
+    }
+    for (const node of taxonomy.nodes) {
+        if (node.parent && !canonical.has(node.parent)) {
+            errors.push(`taxonomy node ${node.id} references missing parent: ${node.parent}`);
+        }
+    }
+    const completed = new Set();
+    for (const node of canonical.values()) {
+        if (completed.has(node.id))
+            continue;
+        const pathIds = [];
+        const positions = new Map();
+        let current = node;
+        while (current && !completed.has(current.id)) {
+            const previousPosition = positions.get(current.id);
+            if (previousPosition !== undefined) {
+                const cycle = [...pathIds.slice(previousPosition), current.id].join(" -> ");
+                errors.push(`taxonomy cycle: ${cycle}`);
+                break;
+            }
+            positions.set(current.id, pathIds.length);
+            pathIds.push(current.id);
+            current = current.parent ? canonical.get(current.parent) : undefined;
+        }
+        for (const id of pathIds)
+            completed.add(id);
+    }
+    const maximumDepth = taxonomy.maxDepth ?? 3;
+    for (const node of canonical.values()) {
+        let depth = 1;
+        let current = node;
+        const visited = new Set([node.id]);
+        while (current.parent) {
+            const parent = canonical.get(current.parent);
+            if (!parent || visited.has(parent.id))
+                break;
+            visited.add(parent.id);
+            depth += 1;
+            current = parent;
+        }
+        if (depth > maximumDepth) {
+            errors.push(`taxonomy node ${node.id} exceeds maximum category depth ${maximumDepth}: depth ${depth}`);
+        }
+    }
+    return [...new Set(errors)].sort();
+}
+export async function validateRepository(root) {
+    const checked = [];
+    const errors = [];
+    const taxonomy = await loadTaxonomy(root);
+    const taxonomyValidator = await schemaValidator(root, "taxonomy");
+    checked.push("taxonomy/taxonomy.yaml");
+    if (!taxonomyValidator(taxonomy)) {
+        errors.push(...formatSchemaErrors("taxonomy/taxonomy.yaml", taxonomyValidator.errors));
+    }
+    errors.push(...lintTaxonomy(taxonomy));
+    const contractValidator = await schemaValidator(root, "skill-contract");
+    const contracts = await loadContracts(root);
+    const sourceDirectories = (await readdir(path.join(root, "skill-src"), { withFileTypes: true }))
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    const sourceDirectorySet = new Set(sourceDirectories);
+    const contractIds = new Set(contracts.map((contract) => contract.id));
+    const taxonomyIds = new Set(taxonomy.nodes.map((node) => node.id));
+    for (const directory of sourceDirectories) {
+        if (!contractIds.has(directory)) {
+            errors.push(`skill-src/${directory}/skill.contract.yaml: missing required shared contract`);
+        }
+    }
+    for (const contract of contracts) {
+        const label = `skill-src/${contract.id}/skill.contract.yaml`;
+        checked.push(label);
+        if (!contractValidator(contract)) {
+            errors.push(...formatSchemaErrors(label, contractValidator.errors));
+        }
+        if (!sourceDirectorySet.has(contract.id)) {
+            errors.push(`${label}: contract id has no matching Skill directory`);
+        }
+        if (!taxonomyIds.has(contract.taxonomy.primaryCategory)) {
+            errors.push(`${label}: unknown primary category ${contract.taxonomy.primaryCategory}`);
+        }
+        for (const secondary of contract.taxonomy.secondaryCategories ?? []) {
+            if (!taxonomyIds.has(secondary))
+                errors.push(`${label}: unknown secondary category ${secondary}`);
+        }
+        if (contract.kind === "category" && contract.id !== `category-${contract.taxonomy.primaryCategory}`) {
+            errors.push(`${label}: category contract id must match its primary category`);
+        }
+    }
+    for (const node of taxonomy.nodes) {
+        if (!contractIds.has(`category-${node.id}`)) {
+            errors.push(`taxonomy node ${node.id} has no matching Category Skill contract`);
+        }
+    }
+    const [patternDocuments, packs] = await Promise.all([
+        loadEvolutionPatternDocuments(root),
+        loadPacks(root)
+    ]);
+    const patternValidator = await schemaValidator(root, "evolution-pattern");
+    const validPatternDocuments = [];
+    for (const document of patternDocuments) {
+        checked.push(document.file);
+        if (!patternValidator(document.pattern)) {
+            errors.push(...formatSchemaErrors(document.file, patternValidator.errors));
+        }
+        else
+            validPatternDocuments.push(document);
+    }
+    errors.push(...validateEvolutionKnowledgeGraph(validPatternDocuments, new Set(contracts.map((contract) => contract.id)), new Set(packs.map((pack) => pack.id))));
+    for (const pack of packs) {
+        if (pack.runtimeState) {
+            checked.push(pack.runtimeState.stateSchema, pack.runtimeState.initialState);
+            errors.push(...await validatePackRuntimeStateProfile(root, pack));
+        }
+    }
+    const knowledgeIndex = ".skill-system/knowledge/index.md";
+    checked.push(knowledgeIndex);
+    try {
+        const actualIndex = await readFile(path.join(root, knowledgeIndex), "utf8");
+        const expectedIndex = renderEvolutionKnowledgeIndex(validPatternDocuments.map((document) => document.pattern));
+        if (actualIndex !== expectedIndex)
+            errors.push(`${knowledgeIndex}: generated index is stale`);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            errors.push(`${knowledgeIndex}: missing generated index`);
+        else
+            throw error;
+    }
+    return { checked, errors: [...new Set(errors)].sort() };
+}
+//# sourceMappingURL=validation.js.map

package/dist/src/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"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"}

package/docs/catalog-methodology.md

@@ -0,0 +1,46 @@
+# Catalog methodology
+
+The catalog is evidence for classification and decomposition. It is not an installation list.
+
+`catalog/decomposition-map.yaml` closes the loop from collection to local design. It maps every non-category local capability and every capability pack to representative catalog entry IDs, records the contribution used during synthesis, and fixes the evidence to the catalog snapshot digest. Every mapping is `design-evidence-only`: it does not copy, install, execute, or promote upstream content.
+
+## Current snapshot
+
+The 2026-09-02 snapshot contains 658 normalized records:
+
+- 388 Agent Skills from ten official or established community repositories;
+- 270 active latest-version MCP servers from the official MCP Registry;
+- 307 records with a repository license detected from the fixed Git revision;
+- 351 records whose license remains unknown and therefore cannot be vendored.
+
+Exact counts, revisions, and the aggregate digest are recorded in `catalog/snapshots/manifest.yaml`.
+
+## Collection rules
+
+### Agent Skills
+
+The collector makes a shallow, blob-filtered, no-checkout clone and lists tracked `SKILL.md` paths from `HEAD`. It records the exact commit, repository, path, author namespace, detected repository license, and freshness. It does not run hooks, package managers, scripts, or Skill instructions.
+
+### MCP servers
+
+The collector consumes the unauthenticated read-only `GET /v0.1/servers` endpoint of the [official MCP Registry](https://registry.modelcontextprotocol.io/). The latest active server record is normalized and fingerprinted with SHA-256. Packages and remote endpoints are not contacted or executed.
+
+The official registry documentation warns aggregators to persist their own snapshots and track deletion status because the preview service does not guarantee durability. This repository therefore commits a normalized snapshot and source manifest rather than depending on live availability during tests.
+
+## Trust states
+
+- `unreviewed`: path and provenance discovered; instructions not inspected.
+- `metadata-reviewed`: registry metadata normalized; implementation not inspected.
+- `statically-reviewed`: instructions and code examined without execution.
+- `sandbox-tested`: isolated execution and behavior checks completed.
+- `rejected`: known policy, provenance, or security failure.
+
+Catalog presence never raises a trust state automatically. Installation requires a separate security review and explicit authority.
+
+## License rules
+
+Repository license detection is conservative. Apache-2.0, MIT, GPL-3.0-only, AGPL-3.0-only, and BSD-3-Clause are recognized from conventional license text. Unrecognized, missing, or conflicting licenses remain `unknown`. Unknown-license items may inform taxonomy and duplicate analysis, but their text, scripts, or assets must not be copied.
+
+## Reproducibility
+
+`npm run skillpack -- catalog collect` refreshes the catalog from `catalog/sources.yaml`. The configured `verifiedAt` timestamp, fixed upstream revisions, per-entry fingerprints, and snapshot digest make changes reviewable. CI validates the committed snapshot and does not require live network access.

package/docs/evaluation.md

@@ -0,0 +1,38 @@
+# Evaluation and release gates
+
+The trainer treats Skill selection and Skill execution as independent problems. A Skill can be selected correctly and still ignore its procedure; it can also perform well when invoked manually while remaining undiscoverable.
+
+## Dataset separation
+
+- `train`: examples visible to proposal generation.
+- `dev`: fast iteration and regression feedback.
+- `test`: held-out release evidence; never fed into proposal generation.
+- `adversarial`: protected ambiguity, negation, abstention, and safety cases.
+- `tasks`: executable scenarios with artifact rubrics.
+
+Moving an example between splits changes evidence semantics and requires review. A proposal may not modify a protected dataset, its baseline, and the Skill under test in one change.
+
+## Routing metrics
+
+`categoryHit1`, `categoryHit3`, `atomHit1`, `atomHit3`, `atomMrr`, `nonInvocationAccuracy`, and `safetyPassRate` remain separate. `npm run skillpack -- gate` reports every failed metric for every independent dataset. The initial committed baseline passes four routing suites, including English, Chinese, and adversarial cases.
+
+## Completion metrics
+
+Task completion uses `taskCompletionRate`, `rubricPassRate`, and `blockedRate`. Synthetic Mock results verify plumbing but cannot certify quality. A live harness run must record provider, model, harness version, rubric evidence, cost, and latency before it can become a release baseline.
+
+## Paired Skill effect
+
+Skill admission and material Skill changes require matched `without-skill` and `with-skill` runs over the same dataset, examples, harness, and version. `skillpack harness effect <without.json> <with.json>` reports task-completion lift, rubric-pass lift, blocked-rate change, and cost/latency changes when available. The default gate rejects negative completion or rubric lift, increased blocking, no positive quality lift, mismatched runs, and all synthetic certification claims.
+
+This paired design prevents a capable base model from making a weak Skill look useful. Routing improvement is still reported separately and cannot offset negative task effect.
+
+## Optimization loop
+
+1. Cluster failures from train/dev observations.
+2. Propose a bounded change to routing metadata, Skill wording, or taxonomy mapping.
+3. Run train/dev, then untouched test and adversarial suites.
+4. Reject permission expansion and protected regression.
+5. Compare the candidate with the no-Skill or current-Skill baseline on matched live task runs.
+6. Promote through canary only with a rollback pointer.
+
+Perfect bootstrap scores are not evidence of broad real-world perfection. They prove only that the initial contracts and test fixtures agree; the corpus must keep growing from novel failures and external harness traces.

package/docs/evolution-knowledge.md

@@ -0,0 +1,46 @@
+# Persistent evolution knowledge
+
+SkillPack One separates evidence, learned patterns, and active procedures so that experience can compound without silently becoming executable instruction.
+
+| Layer | Location | Mutability | Normal task access |
+| --- | --- | --- | --- |
+| Raw run evidence | `.skill-system/runs/` | write-once run artifacts; ignored from releases by default | no |
+| Evolution Knowledge | `.skill-system/knowledge/` | versioned patterns; supersede or archive instead of silent deletion | no |
+| Active Skills | `skill-src/`, generated into `skills/` and `.agents/skills/` | reversible only through governed proposals | yes, after routing |
+
+This maps the useful separation in WikiSkill onto the existing Category → Atom → Capability Pack → Meta architecture. Evolution Knowledge is a Meta-governance resource, not a fifth Skill kind and not hidden task-solving context.
+
+## Pattern contract
+
+Each YAML record under `.skill-system/knowledge/patterns/` declares:
+
+- a stable ID, lifecycle status, summary, problem, root cause, and response;
+- scoped Skills, capability packs, and harnesses;
+- `hypothesis`, `observed`, or `replicated` confidence;
+- traceable evidence references with optional SHA-256 digests and locators;
+- explicit supersession links and timestamps.
+
+The generated `index.md` is compact discovery metadata. A Meta Skill searches the index, reads only relevant records, and cites their IDs in a proposal. Pattern text is evidence to assess, not authority to execute source instructions.
+
+## Lifecycle
+
+1. Preserve the bounded task run, user correction, paper, proposal, or decision as evidence.
+2. Consolidate only a recurring or independently useful success/failure mechanism into a narrow pattern.
+3. Search existing patterns before proposing a Skill change; update or supersede instead of duplicating.
+4. Bind relevant pattern IDs to the exact Git candidate.
+5. Evaluate the candidate independently. Promotion or rejection becomes new evidence; neither outcome rewrites raw history.
+6. Keep patterns out of ordinary inference. Only promoted Skills enter task execution through normal routing.
+
+WikiSkill retains its wiki indefinitely but lists missing pruning as a limitation. SkillPack One therefore preserves evidence while allowing reviewed patterns to become `superseded` or `archived`; physical deletion remains a separately authorized retention action.
+
+## Commands
+
+```sh
+npm run skillpack -- knowledge list
+npm run skillpack -- knowledge search "repeated rejected skill changes"
+npm run skillpack -- knowledge build
+npm run skillpack -- knowledge validate
+npm run skillpack -- train propose ... --pattern experience-insights-fragment-across-iterations
+```
+
+`knowledge build` is deterministic. `skillpack validate` rejects stale indexes, invalid scopes, duplicate IDs, missing supersession targets, and cycles.

package/docs/evolution-policy.md

@@ -0,0 +1,23 @@
+# Governed evolution policy
+
+Self-improvement means evidence-gated maintenance, not unrestricted self-rewriting.
+
+Every new proposal declares a target, authorship mode, responsible author, generating model when applicable, base revision, candidate revision, rollback revision, observed failure, allowed files, actual changed files, generation datasets, evaluation datasets, permission envelopes, and approvals. Historical append-only records remain valid without retroactive mutation. Generated `skills/` and `.agents/skills/` projections may never be edited directly.
+
+When a proposal is motivated by a recurring Evolution Knowledge pattern, it records the stable pattern ID. The pattern layer persists independently of whether the candidate is promoted or rejected, but it is never injected into ordinary task inference. See [persistent evolution knowledge](evolution-knowledge.md).
+
+`npm run skillpack -- train propose --id <id> --target <skill-id> --observation <evidence> --author <identity> --authorship <human|model-assisted|model-generated> [--generator <model>]` scaffolds a proposal from the exact `HEAD^..HEAD` canonical Git diff. Evaluation requires `HEAD` to equal `candidateRevision`, requires the declared `changedFiles` to match that diff, and rejects tracked or unexpected untracked drift. Generated projections are reproducible artifacts and are excluded from the canonical diff.
+
+## Hard invariants
+
+- Test, adversarial, and task datasets cannot generate a proposal.
+- A file outside the proposal boundary rejects the proposal.
+- Any permission expansion requires a named, timestamped approval.
+- A `meta-skill-governor` proposal cannot alter its own gate or evolution policy in the same proposal.
+- Protected metrics may not regress.
+- Test, adversarial, and task datasets, committed baselines, and `evals/gates.yaml` cannot change in the same candidate they certify.
+- Promotion requires an append-only decision record and a distinct rollback revision.
+- A human-only candidate cannot be promoted by its author; a model-assisted or model-generated candidate cannot be promoted by its generating model.
+- Deletion requires a separate destructive-maintenance approval after dependency and retention checks.
+
+Use small proposals. If taxonomy, permissions, behavior, and evaluation all change together, split the work so each causal claim remains testable.

package/docs/harnesses.md

@@ -0,0 +1,42 @@
+# Harness adapters
+
+Skill quality depends on both the Skill and the agent harness. This project records the harness identity and version on every run and does not compare results as if harness behavior were interchangeable.
+
+## Pi — default live adapter
+
+The repository pins `@earendil-works/pi-coding-agent` 0.84.4. The adapter uses Pi's exported `loadSkillsFromDir` implementation to validate real Skill discovery, not a project-specific approximation. Model-backed routing and task execution use the Pi CLI in non-interactive, no-session mode and load the generated `skills/` projection explicitly.
+
+Run:
+
+```sh
+npm run skillpack -- harness status
+npm run skillpack -- harness discover --adapter pi
+npm run skillpack -- harness tasks --adapter pi --provider <provider> --model <model>
+npm run skillpack -- harness tasks --adapter pi --provider <provider> --model <model> --skills disabled > without-skill.json
+npm run skillpack -- harness tasks --adapter pi --provider <provider> --model <model> --skills enabled > with-skill.json
+npm run skillpack -- harness effect without-skill.json with-skill.json
+```
+
+Pi credentials remain in Pi's own provider configuration. The project never reads or logs credential values. If no provider is ready, the adapter returns a typed `blocked` result; it does not replace the live score with a mock score.
+
+## Mock — deterministic CI adapter
+
+The Mock adapter verifies protocol wiring, dataset loading, routing metrics, rubric plumbing, and gate behavior with no network or API keys. Its result is always labeled `synthetic: true` and cannot certify model task quality.
+
+## Codex native-layout adapter
+
+This adapter checks `.agents/skills` discovery artifacts and projection drift. It replays deterministic route traces but intentionally does not automate private Codex UI behavior. Exported Codex traces can be added as a future evidence source.
+
+## DeepSeek Harness (DSH) — optional adapter
+
+The DSH adapter is disabled until a compatible CLI release is explicitly pinned. When the command is absent it reports an actionable blocker and leaves the rest of CI operational. It must implement the same discover, health, route, and execute contract before its scores can enter a release gate.
+
+## Completion claims
+
+Routing gates and task-completion gates are separate. A release may pass deterministic routing while remaining uncertified for live task completion. Public reports must show blocked runs, model/provider identity, rubric failures, cost, and latency rather than omitting unavailable evidence.
+
+Skill-effect claims additionally require paired runs with and without the candidate Skill under the same dataset and harness identity. Redirect each task result to JSON, then use `harness effect`; the comparison rejects synthetic evidence and unmatched runs.
+
+## Runtime-state profiles
+
+A Capability Pack may declare a portable runtime-state profile, but adapters do not implicitly execute it. `skillpack state` currently certifies initial-state and patch mechanics only. A future adapter claiming long-horizon improvements must implement the same schema/merge contract, keep full audit evidence outside active state, and report matched transcript-versus-state completion, token, latency, and recovery metrics. Until then, no paper-level efficiency result is attributed to Pi, Codex, or DSH.