简体中文

Compatibility and Support Matrix

This page records the current source versions, runtime support, and the one-time migration rule for historical candidate entrypoints. Package manifests, the Contracts registry, and the capability catalog are the machine authorities.

Current Versions

Package	Current source version	Role
skill-family-contracts	0.13.0	Contracts 1.13.0 machine contracts
skill-family-harness-node	0.13.0	Node implementation of Contracts mechanisms
skill-family-engineering-kit	0.13.0	Four engineering commands and build-time projection
Private parent workspace	0.13.0	Sole development source of truth

The three leaf packages release in lockstep and must not be mixed. The Contracts specification and npm packages use separate version lines.

Two-Generation Maturity Rule

Historical candidate APIs migrate once to canonical entrypoints. Legacy entrypoints continue to resolve to the same module during the compatibility window. Removing one requires a published deprecation, zero references in known real consumers, at least one release cycle, and a separate major-version decision.

APIs introduced from 0.10.0 onward use their final canonical identity from the first candidate release. An active candidate upgrade can still require adaptation. Candidate-to-stable promotion, however, may change only the provider's compatibility promise. It cannot change the entrypoint, capability ID, Schema $id, operation, request, result, or error semantics. A consumer must still update all three exact package pins to obtain the newly published stable promise. Existing package-identity, source-digest, and provenance bindings determine whether a Bundle rebuild is required; the maturity label adds no separate rebuild condition. FND-ADR-016 and CANDIDATE_PROMOTION_POLICY define the machine rule.

Historical Candidate Migration Matrix

Historical coordinate or capability	0.10.0 migration target	Current treatment
skill-family-contracts/candidate/quickstart-profile	skill-family-contracts/quickstart-profile	Same source module; migrate once
skill-family-harness-node/candidate/quickstart-profile	skill-family-harness-node/quickstart-profile	Same source module; operations unchanged
skill-family-harness-node/candidate/rename-directory-no-replace	skill-family-harness-node/rename-directory-no-replace	Same source module; distinct from high-level fixed-set publication
skill-family-engineering-kit/candidate/quickstart-profile	skill-family-engineering-kit/quickstart-profile	One-time Quickstart builder migration
Adoption from the old Quickstart namespace	skill-family-engineering-kit/adoption	Responsibility-specific canonical entrypoint backed by the same source
Package-local or projected skill-naming candidate	skill-family-engineering-kit/skill-naming	Canonical package entrypoint; no fifth Kit command
0.4.0 fixed-set candidate schemas and primitive	0.9.0 stable Schema $id values and skill-family-harness-node/fixed-set-publication	Legacy schemas remain packaged while consumers migrate to the high-level API
0.9.0 validate-many-by-schema-id candidate schemas	/foundation-mechanisms/v1/schema-validation-batch-{request,result}.json	One canonical Schema copy; legacy and canonical IDs dispatch to the same compiled validator, with no operation or echoed-result change

The six Quickstart v2 identities for Resource, Task, Result, consumer inventory, and Harness surface inventory/detectors also migrate once from /candidate/quickstart-profile/v2/ to /quickstart-profile/v2/. Contracts loaders return only canonical $id values. During the compatibility window, Bundles accept both old and new IDs without a second Schema set or a general alias registry.

Quickstart v1 had already been replaced by v2 before 0.3.0. Consumers that still require v1 must remain pinned to 0.2.1. Version 0.10.0 neither rewrites historical artifacts nor repackages v1.

R05 and legacy platform-manifest migration

The R05 request/result Schemas are the sole structural owners of logicalMappings. A consumer keeps only fields that belong to its own domain, then removes duplicated closure, digest, and file-list structures after real-directory verification. It does not maintain permanent dual writes.

Legacy field	Migration decision
familyId	Map to skillFamilyId.
platformId	Map to canonical hostId only after a registered Descriptor proves the identity. A request declaration is not proof.
version	Keep as the consumer package version.
sourceDigest	Map to commonSourceClosure.digest.
projectionDigest	No automatic equivalence; manifest.digest must not stand in for it.
fileCount / files	Derive from the standard manifest. The peer root's skills/ does not include a legacy manifest in its parent directory; remove the old list after migration.
logicalMappings	Owned only by request/result.
lifecycleStatus / blocked / blockingReasons / advisories	Remain in the consumer domain.
verified	Does not derive product, Audit, or release state.

Node and Toolchain

• Node: >=22.22.2 <23; .node-version fixes the exact floor at 22.22.2.
• pnpm: 10.30.0.
• projen: 0.101.23, the sole generator for managed engineering files.
• Schema validator: Ajv 8.20.0, supporting draft-07 and 2020-12.

Results from Node below the floor or above the locked major cannot replace authoritative gate results.

Contracts and Engineering Boundaries

• The Contracts registry contains 42 top-level object classes and is the sole authority for that set.
• The stable kernel protocol is skill-family.kernel.operation; the Contracts specification is 1.13.0, while the kernel document remains byte-pinned at its 1.8.0 lifecycle coordinate.
• Error codes are append-only and are never reassigned.
• Kit top-level commands remain scaffold, adopt-plan, projection, and check.
• Host apply, install/update/uninstall, a full Qoder driver, remote publication, business state machines, model orchestration, and domain-audit semantics are outside the stable support surface. Local install/update remain within the 0.10.0 unstable plan-API boundary; an unsupported host receives no automatic lifecycle capability and no remote-publication guarantee.

Current host support comes from the capability catalog, Profile descriptors, and real drivers. A directory convention or CLI identity alone does not establish a supported lifecycle.