skill-family-engineering-kit 公共 API 参考¶

本页从真实导出（src/index.mjs 与各源模块、CLI 入口）核对，不手写无法证明新鲜度的全集。每个公共入口按 hand-off §4.3 说明：签名、输入与输出、是否纯函数、文件/进程/Git/网络副作用、稳定错误码与 details.kind、前置条件与信任锚、since 与 stability、源文件与正例/负例测试、调用方仍拥有的业务语义。

Kit 消费 Contracts 与 Harness，只拥有四个顶层命令与它们的只读/受控写边界。包级常量：TOP_LEVEL_COMMANDS（冻结 4 个：scaffold / adopt-plan / projection / check）、FORBIDDEN_SIDE_EFFECTS、COMMAND_SIDE_EFFECTS、KIT_EXIT_CODES（ok=0 / findings=1 / rejected=2）。Kit 永不执行 Git 写、发布、删除用户内容或触网。

外置 source authority 不增加 Kit API。调用方先用 Contracts parseSourceAuthorityReceipt(receipt, actualSubjects) 核对收据，再把成功结果中的 sourceRepository 与 sourceBaseCommit 传给既有 Quickstart builder。Kit 不读取私有发布 plan，不发现实际包，也不签发 receipt。

provider Profile descriptor 使用 Contracts 1.13.0 时，须把自身的 base.contractsVersion 字段更新为 1.13.0。 Kit 仍只有四个顶层命令；Quickstart Bundle 继续是 candidate 精确版本，并在同一 mechanisms CLI 中提供有序 validate-many-by-schema-id。

能力分组（与 docs/agents/capability-catalog.json 对应）：

scaffold → scaffoldTarget
adopt-plan → planAdoption / evaluateMigrationCompletion
projection → buildProjectionClosure / runProjection / loadProjectionManifest
check → runChecks / runCoreCheck
report → renderReportAction / checkReportAction
git-probe → probeGitState / probeGitFacts
host → describeHost / resolveHostId / probeHost / planHost / applyHostPlan …
licensing → loadLicensingProfile / generateLicenseContent …
identity-check → checkIdentityDrift / validateIdentityAgainstProfile
CLI → runCommand / cliMain

scaffold (foundation.kit.scaffold)¶

scaffoldTarget / describeSkeletonFiles / normalizeSkeletonInputs¶

签名：
scaffoldTarget({ root, projectId, projectName, profileId, licensingProfile, licensingVariant, licensingProfileData, profilesRoot, identityProjections } = {})（async）
describeSkeletonFiles(inputs)（async）
normalizeSkeletonInputs({ projectId, projectName, profileId, licensingProfile, licensingVariant, rootBasename })
输入：目标根、骨架选项（projectId 等）。
输出：精确集合的托管骨架文件（原子 + 路径收容）。含两个目标侧手写种子（handwritten 类，adopt 永不覆写）：SOURCE-OF-TRUTH.md（唯一声明点、真源清单与生成谱系、运行与证据目录约定）与 profile.json（foundation_profile / foundation_pin 采用字段加只收紧方向的 overrides 示例）；.gitignore / .projenrc.js / file-registry 三处同步携带根级唯一忽略基线 /site/、/.qoder/、/.artifacts/、/.runs/、/.evidence/（嵌套同名目录不被忽略）。
纯函数：normalizeSkeletonInputs 是；scaffoldTarget 落盘。
副作用：在受收容目标创建文件（原子 + 收容）；目标非空则拒绝、不覆盖。
稳定错误码与 details.kind：非法 kebab projectId / 非空目标抛 KitError（KIT_ERROR_KINDS 的 invalid-params / rejected）；非法参数 + INVALID_PARAMS（SFC2003）。
前置条件与信任锚：目标为可写空目录；Node >= 22.22.2；骨架集合与 scaffold-conformance fixture 一致（33 个计划文件）。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-engineering-kit/src/scaffold.mjs、skeleton.mjs。
正例/负例测试：packages/skill-family-engineering-kit/test/scaffold.test.mjs、skeleton-contract.test.mjs。
调用方仍拥有的业务语义：业务项目内容（存量仓改用 adopt-plan）。

adopt-plan (foundation.kit.adopt-plan)¶

planAdoption / buildProfileDraft / evaluateMigrationCompletion / validateException / assessLegacyExitList / findNestedRepositories¶

签名（节选）：
planAdoption({ root, manifest, ... } = {})（async）
buildProfileDraft({ inputs, migrationManifest, writeSet, entries })
evaluateMigrationCompletion({ ... })
validateException(exception, index, nowMs)
assessLegacyExitList(root, legacyItems)（async）
findNestedRepositories(entries)
输入：目标根、迁移清单路径。
输出：采用分类（direct-adoption / compatibility-layer / keep-business / foundation-gap）、完成判定、profile 草稿（kind=skill-family.profile-draft：预填 D-8 最小采用声明 + 空 overrides 示例，仅输出，不落盘；adoption-lock 形态已废弃）。
纯函数：分类与评估函数为纯函数；planAdoption 含只读探测。
副作用：严格只读——不写文件（临时文件也不写）、不 Git 写、不 rename、不触网；可能触发只读 Git 探测。
稳定错误码与 details.kind：例外缺字段 / 未退出旧实现则完成判定 false；硬失败抛 KitError（CONTRACTS_VERSION 不一致等）。
前置条件与信任锚：目标仓存在且可只读访问；MIGRATION_MANIFEST_PATH / MIGRATION_MANIFEST_SCHEMA_ID 指向契约。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-engineering-kit/src/adopt-plan.mjs、migration.mjs。
正例/负例测试：packages/skill-family-engineering-kit/test/adopt-plan.test.mjs、migration.test.mjs。
调用方仍拥有的业务语义：存量业务代码的迁移决策（真正迁移执行由调用方负责）。

projection (foundation.kit.projection)¶

runProjection / loadProjectionManifest¶

签名：
runProjection({ root, manifest: manifestRelPath } = {})（async）
loadProjectionManifest(rootAbs, manifestRelPath)（async）
输入：投影清单、目标根。
输出：投影文件（仅在校验全部通过时写入）。
纯函数：loadProjectionManifest 是；runProjection 两阶段（全校验后才写，失败回滚）。
副作用：在受收容目标写投影文件；不覆盖 handwritten 文件；任一校验失败零写。
稳定错误码与 details.kind：未授权 / 手写冲突 / 越界 / 内容冲突抛 KitError（rejected / unauthorized 类 kind）。
前置条件与信任锚：投影清单已登记（PROJECTION_MANIFEST_PATH）。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-engineering-kit/src/projection.mjs。
正例/负例测试：packages/skill-family-engineering-kit/test/projection.test.mjs。
调用方仍拥有的业务语义：投影内容的业务含义（远端发布转 release-skill）。

buildProjectionClosure¶

签名：buildProjectionClosure(resources)
输入：资源数组，成员为 {path, sha256, mode}（显式 type: "file" 被容忍）。
输出：规范投影闭包 {digestAlgorithm: "sha256", digest, resourceCount, resources}（成员规范化为 {path, type: "file", sha256, mode}，按 path 确定性排序，digest = sha256(JSON.stringify(resources))），可原样作为 compileProjectionPlan() 的 previousOwnedClosure 或 externalCandidateClosure；空数组是合法空闭包。
纯函数：是（无文件读写、无网络、无子进程；入参不被改写）。
副作用：无。
稳定错误码与 details.kind：非数组输入、重复路径、可移植路径碰撞、非法 path/type/sha256/mode 在既有 projection plan input invalid 错误域内失败关闭（SFC2004，details.kind 为 invalid-manifest）。
边界：本函数构造的是投影/计划闭包，与 Harness computeResourceClosure() 的资源闭包（成员 {path, role, exists, sha256}、整体信封摘要）形状与用途不同，两者不可互换；与 normalizePlanClosure()、候选枚举闭包共享同一规范化与摘要事实源。
前置条件与信任锚：无；结果直接满足 compileProjectionPlan() 的闭包合同，不新增第二个编译入口。
since / stability：0.7.0 / stable。
源文件：packages/skill-family-engineering-kit/src/projection.mjs。
正例/负例测试：packages/skill-family-engineering-kit/test/projection-closure-builder.test.mjs。
调用方仍拥有的业务语义：投影内容的业务含义与资源字节的来源证明。

check (foundation.kit.check)¶

runChecks / runCoreCheck / isContainedDeclaration¶

签名：
runChecks({ root, allowGitSpawn = true, only, profilesRoot } = {})（async）
runCoreCheck({ root, allowGitSpawn = true, profilesRoot } = {})（async）
isContainedDeclaration(rel)
输入：--only 取值 contracts|drift|closure|version|docs|git|identity|boundary|platform。
输出：发现清单；退出码 findings=1（有发现）、mechanism=2（某类检查无法完成）、ok=0。
纯函数：否（读取目标文件与只读 Git 状态）；但只诊断、不修复、不写。
副作用：无文件写入；只读 Git 探测（至多一次冻结 status 查询）。
稳定错误码与 details.kind：CHECK_CLASSES 为九类闭集，不扩张（审计整改 C2 依裁决 SG-13/14、SG-17、SFA-PLAT-002 增设 boundary、platform 两类，并为 version 类加装版本单源一致性事实；扩类经治理批准，此后仍不扩张）；机制失败抛 KitError（mechanism 类）。
前置条件与信任锚：GIT_READ_ONLY_ALLOWLIST 限定可调用子命令。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-engineering-kit/src/check.mjs、core-check.mjs。
正例/负例测试：packages/skill-family-engineering-kit/test/check.test.mjs、core-check.test.mjs、check-equivalence.test.mjs。
调用方仍拥有的业务语义：发现项的业务处置（自动修复执行由调用方负责）。

report (foundation.kit.report)¶

renderReportAction / checkReportAction¶

签名：
renderReportAction(options = {})（async）
checkReportAction(options = {})（async）
输入：report-model、--out / --binding 选项。
输出：Markdown 文本；显式 --out / --binding 才落盘，否则只写 stdout。
纯函数：否（默认只写 stdout；显式选项才写受收容文件）。
副作用：默认无文件写入；显式 --out / --binding 才写受收容文件。
稳定错误码与 details.kind：硬失败计为发现；非法参数 reject（invalid-params）。
前置条件与信任锚：已存在 Harness report-model；报告由机器结果确定性渲染。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-engineering-kit/src/report.mjs。
正例/负例测试：packages/skill-family-engineering-kit/test/report.test.mjs。
调用方仍拥有的业务语义：报告结论解读（机制在 Harness report）。

git-probe (foundation.kit.git-probe)¶

probeGitState / probeGitFacts¶

签名：
probeGitState(root, { allowSpawn = true } = {})（async）
probeGitFacts(root, candidatePaths, { allowSpawn = true } = {})（async）
输入：目标根。
输出：Git 状态与事实（只读）。
纯函数：否（调用 git 只读子命令）；不含任何写操作。
副作用：只读调用 git status / ls-files / check-ignore；参数向量冻结于 GIT_STATUS_ARGS / GIT_LS_FILES_ARGS / GIT_CHECK_IGNORE_ARGS，不在白名单即拒绝。
稳定错误码与 details.kind：非白名单参数向量抛 KitError（unauthorized-git 类）。
前置条件与信任锚：GIT_READ_ONLY_ALLOWLIST 限定可调用子命令。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-engineering-kit/src/gitprobe.mjs。
正例/负例测试：packages/skill-family-engineering-kit/test/git-probe.test.mjs。
调用方仍拥有的业务语义：Git 写操作授权（Git 写归 Git 生命周期指南，Foundation 不拥有）。

host (foundation.kit.host)¶

bundledHostProfilesRoot / describeHost / resolveHostId / loadHostRegistry / probeHost / buildHostAdapter / verifyHostPeers / runHostVerification / verifyHostVerificationBindings / materializeHostBuild / planHost / assertPlanConsistency / applyHostPlan / probeTrustedVersionDriver¶

签名（节选；bundledHostProfilesRoot 与 assertPlanConsistency 为同步函数，其余入口按下列 async 合同执行）：
bundledHostProfilesRoot()：返回 Engineering Kit 安装包内宿主 Profile 闭包的规范绝对路径。
describeHost({ hostId, hostsRoot, registry } = {})
resolveHostId({ hostId, hostsRoot, registry } = {})（async）：读取已登记的有限 Profile 集合，解析 canonical hostId 与 sourceAliases；不读取或写入全局别名表。
loadHostRegistry({ hostsRoot, registry } = {})
probeHost({ hostId, hostsRoot, registry, executable, allowSpawn = false, timeoutMs = 5000, runner } = {})
buildHostAdapter({ hostId, pathCategoryId, input, hostsRoot, registry } = {})
verifyHostPeers({ request, peerRoots, hostsRoot, registry } = {})（async）：hostsRoot 为必需的 Profile 证明根，registry 可选；npm 消费者可以显式传 bundledHostProfilesRoot()，薄包装 Harness 的同级适配器只读验证，不写入目录。
runHostVerification({ request, bindings, hostsRoot } = {})（async）：按已登记的封闭内置 driver 表（kimi-code-print-v1、workbuddy-codebuddy-print-v1、claude-code-print-v1、codex-exec-v1、qodercli-print-v1，均绑定 existing-user-state + host-managed）执行一次受约束调用。请求、候选、fixture、workspace、现有用户状态根和临时根均由调用方绑定；公共结果只返回脱敏的逐宿主事实。
verifyHostVerificationBindings({ results, expectedCommon, expectedRequestDigestByHost } = {})：只组合已验证的 observed 结果，要求共同字段和逐宿主 request digest 精确匹配；不同宿主的 driver、安装、Prompt 和可执行文件事实保持独立。
materializeHostBuild(options)
planHost({ hostId, pathCategoryId, buildManifest, probeFacts, operation = "install", previousMembers = [], hostsRoot, registry } = {})
assertPlanConsistency(planInput)
applyHostPlan({ plan, build, targetRoot, authorizationRef } = {})：复用 Harness 的身份绑定读取、严格不替换发布和原子替换；卸载始终返回 manual-recovery-required，不删除文件。
probeTrustedVersionDriver({ hostId, driverId, capabilities = CAPABILITIES, executable, allowSpawn = false, timeoutMs = 5000, runner } = {})
输入：宿主标识、有限 Profile、probe/plan 选项；更新和卸载计划必须携带已拥有成员的摘要。
输出：宿主描述、canonical 身份、逐项独立的九类 probe fact、构建产物、plan 或本地操作结果。runHostVerification() 直接返回 Contracts 校验后的逐宿主四态 result；verifyHostVerificationBindings() 成功时严格返回 { status: "bound" }。
纯函数：只有 assertPlanConsistency 是；resolveHostId 通过受收容的只读 I/O 读取 Profile，不能当作纯函数。其余入口按职责含落盘或进程调用。
副作用：resolveHostId / verifyHostPeers 只读；build / materialize 在受收容目标写产物；probe 默认 allowSpawn=false，不取 PATH。真实宿主验证只在调用方提供的 fresh 私有根内写原始证据；公共 result 不落盘为 Foundation receipt。
稳定错误码与 details.kind：缺 probe facts 抛 KitError（missing-probe-facts）；写入失败按 Harness 的 publicationState 返回 partially_applied 或 indeterminate。HOST_DRIVER_IDS 仅两个受信版本 driver（claude-version-v1 / codex-version-v1）；manual 宿主（含 Qoder）由 probeHost 生成九项 driver-limited 事实、由 planHost 返回 manual 计划，不授予生命周期能力。
前置条件与信任锚：宿主 Profile 已在 profiles/hosts 登记，并由 synth 投影进 Kit 的 data/hosts；别名必须来自该有限集合；受信 driver 限定；applyHostPlan 要求显式 authorizationRef、已验证 build 与目标根。真实宿主验证还要求显式 hostsRoot、受 Descriptor 约束的封闭内置 driver 表（五个固定组合，均绑定 existing-user-state + host-managed）、canonical 的 existingUserStateRoot（只读根可位于其下；不得等于或位于 output、temporary、private evidence、安装目标、WorkBuddy config root 或 Qoder fresh workspace 内部），以及互不重叠的 fresh 根与最小发现布局预检（每个 driver 的 <skills-root> materialize 前为空；WorkBuddy 的 <config>/skills、Codex 的 <workspace>/.codex/skills 与 Qoder 的 <fresh-ws>/.qoder/skills 布局在 spawn 前预检；Codex 另要求 repositoryRoot/.git 存在，不使用 --skip-git-repo-check，不执行任何 git 命令）。宿主入口不设置默认 hostsRoot。
可执行文件身份边界：executableSha256 只绑定启动前严格读取到的字节，是点时观察；实际进程仍按 pathname 启动，不证明进程映像。调用方必须在 probe 与正式调用期间独占可执行文件的命名空间。
临时目录生命周期：Foundation 保留本次调用的 session-* 目录，不按路径自动删除。调用方完成检查后，统一清理其独占的外层 temporaryRoot。
since / stability：既有宿主能力自 0.10.0 提供；bundledHostProfilesRoot 与真实宿主验证自 0.11.0 提供；0.12.0 把封闭 driver 表扩展到五个（Kimi 与 WorkBuddy 保持回归基线，Claude Code、Codex、Qoder 为新增）。真实宿主验证仍为 candidate：真实发布门（五平台现有登录态复用）未关闭前不得发布。
源文件：packages/skill-family-engineering-kit/src/host.mjs、host-profiles.mjs、host-drivers.mjs、host-verification.mjs、host-verification-drivers.mjs。
正例/负例测试：packages/skill-family-engineering-kit/test/host.test.mjs、host-verification.test.mjs。
调用方仍拥有的业务语义：宿主能力是否可用、手动事实的解释与生命周期授权；Foundation 不声明消费者 smoke 或远端发布成功，也不宣称认证状态隔离、凭证未变化、模型身份固定或宿主工具能力已关闭。

licensing (foundation.kit.licensing)¶

loadLicensingProfile / listLicensingProfiles / validateLicensingProfile / generateLicenseContent / generateNoticeContent / generateIdentityRecord / bundledProfilesRoot¶

签名（节选）：
loadLicensingProfile({ profilesRoot, profileId, variant } = {})（async）
listLicensingProfiles(profilesRoot)
validateLicensingProfile(profile)
generateLicenseContent(profile) / generateNoticeContent(profile, { projectName }) / generateIdentityRecord(profile, { projectId, projectName, projections } = {})
bundledProfilesRoot()
输入：Profile 标识、变体选择。
输出：许可证 / 声明 / 身份记录文本。
纯函数：validateLicensingProfile 与各 generate* 是；load* 含只读读取 Profile 数据。
副作用：无（纯函数生成 + 只读读取）。
稳定错误码与 details.kind：多变体未指定 / 非法 Profile 抛 KitError（invalid-licensing-profile）。
前置条件与信任锚：profiles/licensing/registry.json + schema.json 存在；默认取 registry 第一变体，多变体须显式选择；所有商业载荷当前关闭。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-engineering-kit/src/licensing.mjs、profiles/licensing/registry.json、profiles/licensing/schema.json。
正例/负例测试：packages/skill-family-engineering-kit/test/licensing.test.mjs。
调用方仍拥有的业务语义：授权业务语义（授权执行决策由调用方负责）。

identity-check (foundation.kit.identity-check)¶

loadIdentityRecord / checkIdentityDrift / validateIdentityAgainstProfile¶

签名：
loadIdentityRecord(rootAbs)（async）
checkIdentityDrift({ rootAbs, identityRecord } = {})（async）
validateIdentityAgainstProfile(record, profilesRoot)（async）
输入：目标根、Profile 标识。
输出：漂移发现、校验结论。
纯函数：validateIdentityAgainstProfile 是；load* / check* 含只读读取目标文件。
副作用：只读读取目标文件；不修改。
稳定错误码与 details.kind：漂移或校验失败产出 findings（不抛错，由 check 退出码 1 表达）。
前置条件与信任锚：IDENTITY_RECORD_PATH 指向身份记录。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-engineering-kit/src/identity-check.mjs。
正例/负例测试：packages/skill-family-engineering-kit/test/identity-check.test.mjs。
调用方仍拥有的业务语义：漂移业务处置（自动修复由调用方负责）。

CLI (foundation.kit.cli)¶

runCommand / cliMain / 拒绝变更旗标¶

签名：
runCommand(command, options = {})（async）—— 按 TOP_LEVEL_COMMANDS 分派，返回 { exitCode, output }
cliMain(argv)（async）—— CLI 入口
输入：argv。
输出：命令结果；退出码 ok=0 / findings=1 / rejected=2。
纯函数：否（依命令产生受收容文件写入或只读探测）。
副作用：依命令而定（scaffold/projection 受收容写；adopt-plan/check 只读）；REFUSED_MUTATION_FLAGS（如 --apply）在 parseOptions 入口即拒。
稳定错误码与 details.kind：未知命令 / 拒绝旗标退出码 2（unknown-command / refused-mutation）。
前置条件与信任锚：Node >= 22.22.2；TOP_LEVEL_COMMANDS 固定 4 个，第 5 个命令禁止新增；REFUSED_MUTATION_FLAGS 在解析入口即拒。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-engineering-kit/src/index.mjs、cli.mjs。
正例/负例测试：packages/skill-family-engineering-kit/test/cli.test.mjs、boundary.test.mjs。
调用方仍拥有的业务语义：命令的业务目标（命令集合不扩张）。

Kit 错误类型：KitError extends ContractsError（构造未登记码立即抛 TypeError）；KIT_ERROR_KINDS 为稳定 kind 枚举；kitError / invalidParamsError / unknownCommandError / mutationModeError / refusalError 为构造辅助。REFUSED_MUTATION_FLAGS 列出入口即拒的变更旗标（如 --apply）。

Profile SPI 公共投影¶

skill-family-engineering-kit/profile-spi 是 Profile SPI v2 的公共数据入口。它由 Profiles 源实现投影生成，包内同时携带三个 SPI JSON 资源与 Contracts 的 profile-descriptor.schema.json；投影脚本只替换两个公共包导入和一个本地 Schema URL，资源字节保持绑定。

公共入口¶

loadSpiDefinition()：读取 extension-spi.json，返回开放扩展点、核心所有权和 entrypoint 规则。
loadExtendedDescriptorSchema()：读取 profile-descriptor.schema.json，返回扩展 Profile descriptor Schema。
loadRuleBaselineCatalog()：读取 rule-baseline-catalog.json，返回 overrides-policy 的基线目录。
verifyProfile({ profileRoot, descriptorRelPath = "profile.json" } = {})（async）：只读校验 Profile descriptor、资源收容、核心反向依赖、采用 pin 与 overrides；返回 SPE0000 或 SPE1001–SPE1007 结果码，不执行 Profile entrypoint。
verifyAdoptionDigests({ profileRoot, adoption }) 与 assessOverridesPolicy(overrides)：分别校验采用 pin 摘要和只收紧的 overrides。

公共投影入口没有文件写入、Git、网络或进程副作用。profileRoot 必须是可读取目录，资源 entrypoint 必须留在该目录内且为 JSON 数据文件；符号链接和路径逃逸均失败关闭。Profile 的领域语义仍由调用方拥有。

profiles/spi 是唯一手写真源；packages/skill-family-engineering-kit/profile-spi 由 projen 机械生成，不得直接编辑投影文件。

Quickstart Profile v2 candidate¶

规范入口 skill-family-engineering-kit/quickstart-profile 导出 buildQuickstartProfileProjection、 buildQuickstartProfileProjectionFromInventory 与 QUICKSTART_PROFILE_TARGET_PREFIX。builder 接收显式消费者 Schema 路径与冻结来源身份，生成按 Schema $id 查询的 standalone validator、机械投影的 Contracts/Harness runtime、许可证和完整 provenance。历史 skill-family-engineering-kit/candidate/quickstart-profile 在弃用窗口内解析同一模块。

Bundle 离线运行时不需要 Foundation 包、node_modules 或 Ajv。builder 只返回稳定 projection manifest，不写目标文件，也不增加第五个 Kit 顶层命令；调用方仍需把 manifest 交给 runProjection 完成授权写入。0.3.0 的 v2 与 0.2.1 的依赖闭包 Bundle 不兼容，必须精确锁定版本。

历史 Quickstart 命名空间还导出 adoption 机制；0.10.0 的规范入口是 skill-family-engineering-kit/adoption。 skill naming 使用 skill-family-engineering-kit/skill-naming。两个入口都不增加 Kit 顶层命令；历史消费者迁移一次后，以后只改变成熟度标签时不再迁移合同身份。消费者采用新 Foundation 版本仍需更新精确 pin，Bundle 是否重建按既有 package identity、来源摘要与 provenance 绑定合同判断。

与机器事实层的互链¶

能力稳定 ID 见 docs/agents/capability-catalog.json（foundation.kit.*、foundation.unsupported.*）。
机械校验：scripts/docs/capability-catalog-check.mjs 解析 src/index.mjs 与 cli.mjs，拒绝引用不存在的入口，并校验 TOP_LEVEL_COMMANDS 未扩张为超 4 个。

完整插件验证 (foundation.kit.plugin-verification)¶

runPluginVerification¶

签名：runPluginVerification({ request, bindings, hostsRoot })（async）。
输入：注册的 plugin-verification-request、私有路径绑定及显式宿主 Profile 根。请求区分 install-only 与 install-and-invoke；来源区分 local-staged 与有限 public-channel。
输出：注册的 plugin-verification-result。输入、安装、原生发现和调用事实分别报告；未执行的阶段不填造事实。完整安装观察和原始输出保存于私有证据根。
副作用：创建新鲜安装、会话和证据目录；公共渠道命令可能访问网络，调用模式启动受限宿主。仅安装模式不运行模型。不覆盖已有安装，不自动重试、回滚或清理不确定现场。
失败语义：rejected 表示前提拒绝，failed 表示确定失败，indeterminate 表示边界终态无法证明。payloadMatches 记录比较事实，完整观察成功不替代消费者接受政策。
前提：三包精确锁步；调用方提供冻结源、授权和现有宿主登录态。每个真实宿主与来源组合必须另有资格证据，入口存在不等于全部组合获准。
since / stability：0.13.0 / candidate。永久入口身份不因成熟度标签变化而迁移；现有单 Skill 入口及合同保留。
源文件与正反例：packages/skill-family-engineering-kit/src/plugin-verification.mjs、test/plugin-verification.test.mjs。
调用方责任：源接受、领域结果、发布新鲜度和状态、消费者迁移及机制退出证明。