skill-family-engineering-kit 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.22.0 locale=en baseline=sha256:5eeae7aaee659b91fd9d412ff5a0651d49e90fbcb020ffdb335d25845d590ef3 -->
+## [0.22.0] - 2026-09-18
+
+Engineering Kit 0.22.0 keeps the four top-level commands and adds declared engineering-declaration checking plus explicit professional-conclusion output inside the existing `check` command.
+
+### Added
+
+- Adds declared engineering-declaration checking with a declaration version and an entry branch, reading only the version source and physical entry a project explicitly registers and never executing the target.
+- Adds optional professional-conclusion output that only `runCommand('check')` and the entry action may exclusively create, and only when the caller supplies an existing output root and a contained relative path.
+
+### Changed
+
+- The default `check` diagnosis and the pure `runChecks`/`runEntryContractCheck` functions remain read-only; a missing output root or an existing conclusion entry is rejected instead of created or overwritten.
+- Publishes the 0.22.0 capability catalog with the new `foundation.harness.file-set-recovery` entry projected from Contracts 1.20.0.
+
+### Upgrade Notes
+
+Pin all three Foundation packages to exactly 0.22.0. Declarative checking proves only that a registered version source and entry agree structurally; it does not prove the target executed, and business interpretation of a conclusion remains outside Foundation.
+<!-- release-skill:changelog:end version=0.22.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.21.0 locale=en baseline=sha256:308114b76ba97466f58479dd0d5e4251ea8efba6ad291afc65236f26170229c5 -->
 ## [0.21.0] - 2026-09-11
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,26 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.22.0 locale=zh-CN baseline=sha256:1926982b72cf2756963b204c22c9bfdf2969d690d3b336cf9bdc098fe4d256a0 -->
+## [0.22.0] - 2026-09-18
+
+Engineering Kit 0.22.0 保持四个顶层命令不变，在既有 `check` 命令内增加声明式工程检查与显式的专业结论输出。
+
+### 新增
+
+- 增加不含价格的声明式工程检查，带声明版本与入口分支；只读取项目明确登记的版本来源与物理入口，不执行目标。
+- 增加可选的专业结论输出。只有 `runCommand('check')` 和入口动作可以独占创建，且必须由调用方提供已存在的输出根与受收容的相对路径。
+
+### 变更
+
+- 默认 `check` 诊断与纯函数 `runChecks`/`runEntryContractCheck` 仍然只读；输出根不存在或结论条目已存在时拒绝，不创建、不覆盖。
+- 随 0.22.0 发布新的能力目录，按 Contracts 1.20.0 投影新增 `foundation.harness.file-set-recovery` 条目。
+
+### 升级说明
+
+三个 Foundation 包须一起精确锁定到 0.22.0。声明式检查只证明已登记的版本来源与入口在结构上一致，不证明目标已执行；结论的业务解释不属于 Foundation。
+<!-- release-skill:changelog:end version=0.22.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.21.0 locale=zh-CN baseline=sha256:1f50ac51db5691c5c9dbe1014d0ab43e6cfa4eab1d60eb37a9ca74d30bc75890 -->
 ## [0.21.0] - 2026-09-11
 

package/README.md

@@ -4,29 +4,43 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.21.0 -->
+<!-- release-skill:release-version: 0.22.0 -->
 
 An engineering toolkit used in development and CI. There are **exactly four** top-level commands, and no fifth:
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.21.0** (2026-09-11)
+**0.22.0** (2026-09-18)
 
-Engineering Kit 0.21.0 adds `prepareHostVerification` for preparing one bounded Cursor invocation and reading its digest-bound private output through the existing host-verification path.
+Engineering Kit 0.22.0 keeps the four top-level commands and adds declared engineering-declaration checking plus explicit professional-conclusion output inside the existing `check` command.
 
 **Added**
 
-- Adds `prepareHostVerification`, which derives the fixed driver request, contained invocation directories, frozen snapshots, and private bindings from caller-owned candidate, workload, Skill, workspace, fixture, prompt, executable, and state-root inputs.
-- Adds `readInvocationStream` to the frozen preparation object so callers can read stdout or stderr only after the result, request, evidence-root binding, stream digest, and byte count match.
+- Adds declared engineering-declaration checking with a declaration version and an entry branch, reading only the version source and physical entry a project explicitly registers and never executing the target.
+- Adds optional professional-conclusion output that only `runCommand('check')` and the entry action may exclusively create, and only when the caller supplies an existing output root and a contained relative path.
 
 **Changed**
 
-- Rechecks bindings and source snapshots before process spawn, then compares the installed Skill closure digest before session creation or probing; drift and post-install digest mismatches fail closed.
+- The default `check` diagnosis and the pure `runChecks`/`runEntryContractCheck` functions remain read-only; a missing output root or an existing conclusion entry is rejected instead of created or overwritten.
+- Publishes the 0.22.0 capability catalog with the new `foundation.harness.file-set-recovery` entry projected from Contracts 1.20.0.
 
 **Upgrade Notes**
 
-Pin all three Foundation packages to exactly 0.21.0. The new preparation API supports only one declared Cursor Skill with the packaged `cursor-agent-print-v1` driver; workload meaning, domain assertions, release freshness, and cleanup remain caller responsibilities.
+Pin all three Foundation packages to exactly 0.22.0. Declarative checking proves only that a registered version source and entry agree structurally; it does not prove the target executed, and business interpretation of a conclusion remains outside Foundation.
 <!-- release-skill:managed:end id=latest-release -->
 
+## Governance Check (0.22.0)
+
+Version 0.22.0 adds an explicit `declared` policy under the existing `check` command. Version
+checking reads only the release units and text or JSON version references listed in
+`skill-family.project-manifest.json`; entry checking reads only the listed physical files. Neither branch
+runs target scripts, Skills, hooks, models, or unselected legacy checks.
+
+`runChecks` and `runEntryContractCheck` remain read-only. Only the existing `runCommand("check")` and
+`checkEntriesAction` wrappers may create one `professional-conclusion` file, and only when the caller
+provides both an existing output root and a contained relative path. The write is exclusive: parent
+directories are not created and existing entries are not overwritten. This implementation ships with the
+0.22.0 artifact; the earlier published 0.21.0 artifact does not contain it.
+
 ### Foundation 0.15.0 candidate qualification entries
 
 The candidate adds two fixed qualification entries: `foundation.kit.plugin-verification` accepts the Qoder and WorkBuddy native-lifecycle branches, and `foundation.kit.skill-family-directory-verification` accepts the Kimi branch. Qoder and WorkBuddy each use a dedicated production driver with its own argv plan and the same twelve ordered semantic stages; executable identity is re-observed before every spawn. Contracts validates only the closed stage structure, order, and stop propagation.
@@ -54,7 +68,7 @@ Kit is the "engineering stage" layer, depending on the Harness and Contracts. It
 
 ## Installation and Minimal Example
 
-Version 0.21.0 is the local source candidate. Build all three tarballs into one temporary directory and install those exact files for a candidate check:
+Version 0.22.0 is the local source candidate. Build all three tarballs into one temporary directory and install those exact files for a candidate check:
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -62,21 +76,21 @@ pack_dir="$(mktemp -d)"
 (cd packages/skill-family-harness-node && pnpm pack --pack-destination "$pack_dir")
 (cd packages/skill-family-engineering-kit && pnpm pack --pack-destination "$pack_dir")
 mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
-(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.21.0.tgz" "$pack_dir/skill-family-harness-node-0.21.0.tgz" "$pack_dir/skill-family-engineering-kit-0.21.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.22.0.tgz" "$pack_dir/skill-family-harness-node-0.22.0.tgz" "$pack_dir/skill-family-engineering-kit-0.22.0.tgz")
 ```
 
 After publication, use the registry coordinate:
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.21.0
-npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit --help
-npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
-npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit adopt-plan --root <repo> --list-capabilities --all --scope all --locale en --uses ./uses.json
-npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit projection --root <repo>
-npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit check --root <repo>
+npm install --save-dev skill-family-engineering-kit@0.22.0
+npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit --help
+npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
+npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit adopt-plan --root <repo> --list-capabilities --all --scope all --locale en --uses ./uses.json
+npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit projection --root <repo>
+npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit check --root <repo>
 ```
 
-The four commands above cover skeleton generation, read-only inventory, managed projection, and diagnostics respectively; a zero-install form is available via `npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit --help`.
+The four commands above cover skeleton generation, read-only inventory, managed projection, and diagnostics respectively; a zero-install form is available via `npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit --help`.
 
 ### Three adoption journeys
 
@@ -172,7 +186,7 @@ The API keeps consumer workload, domain output checks, domain PASS/FAIL, release
 
 #### 0.21.0 candidate: prepare a Cursor invocation
 
-`prepareHostVerification` is a 0.21.0 candidate public API and has not yet been published remotely. The published 0.20.0 package does not contain this API. It prepares one declared Skill for `cursor`, using the packaged Descriptor and fixed `cursor-agent-print-v1` driver. It accepts no custom driver, arguments, model override, credential handling, or domain validator. The existing seven-driver `runHostVerification` entrypoint remains compatible.
+`prepareHostVerification` was published with 0.21.0 and remains available in 0.22.0. It prepares one declared Skill for `cursor`, using the packaged Descriptor and fixed `cursor-agent-print-v1` driver. It accepts no custom driver, arguments, model override, credential handling, or domain validator. The existing seven-driver `runHostVerification` entrypoint remains compatible.
 
 The caller supplies the following values; document and fixture content is an opaque UTF-8 string or Buffer. `skillMembers` must include `SKILL.md`; only declared members are installed. All roots must already exist as canonical absolute paths. `sessionRoot` must be empty and exclusively owned, and the workspace must be inside `repositoryRoot` (equality is allowed). The caller authorizes use of the existing user-state root and exclusively controls the executable namespace.
 
@@ -208,6 +222,7 @@ The caller owns workload semantics, candidate-to-payload binding, domain asserti
 - Existing-repo adoption inventory: `adopt-plan` (strictly read-only, no file writes, no auto-migration).
 - Managed projection: `projection` + Profile (does not overwrite handwritten files).
 - Engineering diagnostics: ordinary `check` is read-only; `check relock` is an explicit controlled write transaction, and `check qualification` may spawn a bound executable after preflight.
+- Declared governance diagnostics: select `policy: "declared"` with version-only checking, or use the declared entry sub-action. The target is inspected statically; an optional conclusion file requires explicit output authorization.
 
 ## Boundary Mechanisms
 
@@ -215,6 +230,7 @@ The caller owns workload semantics, candidate-to-payload binding, domain asserti
 - `adopt-plan` is structurally read-only: there is no write call in the implementation, not even a temp file; the plan bytes share the same source as `scaffold` (single source of truth `describeSkeletonFiles`), hence "the plan is the action". By default it may spawn one frozen read-only Git status probe; the CLI `--no-git-spawn` (or API `allowGitSpawn: false`) disables that probe. A dirty repo has zero byte-level change before and after running.
 - `projection` uses two-phase execution: first, for each entry, it performs path classification, containment pre-check, self-projection check, manifest authorization check, hand-written protection, and conflict guard; if any entry violates, the whole is rejected with zero writes. Overwriting an existing file must declare the precise `expect.sha256` precondition; an existing file with identical content is an idempotent no-op. On write failure it best-effort restores the pre-write bytes of already-overwritten files.
 - Ordinary `check` is read-only and has no write calls or `--fix/--apply/--repair` modes (such flags are rejected at the entry point). By default it may spawn one frozen read-only Git status probe; the CLI `--no-git-spawn` (or API `allowGitSpawn: false`) disables that probe. `check relock` is the explicit controlled write transaction; `check qualification` may spawn a bound executable after preflight. Git precondition state uses only filesystem facts plus at most one read-only `git status --porcelain=2` with a frozen parameter vector (`--no-optional-locks` + `GIT_OPTIONAL_LOCKS=0`, no index refresh).
+- In the unreleased declared branch, the two pure check functions remain read-only and do not probe Git. An explicitly requested conclusion is the only added persistent effect and is performed by the two existing wrappers through exclusive creation.
 
 ## Error Codes and Exit Codes
 
@@ -327,4 +343,4 @@ The candidate `runPluginVerification({ request, bindings, hostsRoot })` preserve
 
 The separate `runSkillFamilyDirectoryVerification({ request, bindings })` entry fixes the Kimi production argv and narrow environment and rejects caller observation. Its raw parser is exercised through the production process path, but no controlled fixture event is promoted to `observed`; without an official typed mapping, the public result remains `indeterminate` and a manual candidate.
 
-Version 0.21.0 is the local source candidate. Remote availability must be established by the corresponding release-skill post-release evidence. Consume the three locally verified tarballs for candidate checks; a version marker, unit test, or successful install is not complete contract integration, migration completion, or real-host qualification.
+The declared governance branch and conclusion output ship with the 0.22.0 artifact; the earlier published 0.21.0 artifact does not contain them. Remote availability must be established by the corresponding release-skill post-release evidence. Local tests or working-tree tarballs do not prove contract integration, migration completion, or real-host qualification.

package/README.zh-CN.md

@@ -5,29 +5,41 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.21.0 -->
+<!-- release-skill:release-version: 0.22.0 -->
 
 开发与 CI 阶段使用的工程工具包。**恰好四个**顶层命令，没有第五个：
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.21.0** (2026-09-11)
+**0.22.0** (2026-09-18)
 
-Engineering Kit 0.21.0 增加 `prepareHostVerification`，在既有宿主验证路径上准备一次受约束的 Cursor 调用，并读取经过摘要绑定的私有输出。
+Engineering Kit 0.22.0 保持四个顶层命令不变，在既有 `check` 命令内增加声明式工程检查与显式的专业结论输出。
 
 **新增**
 
-- 增加 `prepareHostVerification`。它从调用方持有的候选、工作负载、Skill、工作区、夹具、提示词、可执行文件和状态根输入派生固定驱动请求、受收容调用目录、冻结快照与私有绑定。
-- 冻结的准备对象增加 `readInvocationStream`。只有结果、请求、证据根绑定、流摘要和字节数一致时，调用方才能读取 stdout 或 stderr。
+- 增加不含价格的声明式工程检查，带声明版本与入口分支；只读取项目明确登记的版本来源与物理入口，不执行目标。
+- 增加可选的专业结论输出。只有 `runCommand('check')` 和入口动作可以独占创建，且必须由调用方提供已存在的输出根与受收容的相对路径。
 
 **变更**
 
-- 启动进程前重新校验绑定与来源快照；创建会话或探测前比较安装后的 Skill 闭包摘要。发现漂移或摘要不匹配时失败关闭。
+- 默认 `check` 诊断与纯函数 `runChecks`/`runEntryContractCheck` 仍然只读；输出根不存在或结论条目已存在时拒绝，不创建、不覆盖。
+- 随 0.22.0 发布新的能力目录，按 Contracts 1.20.0 投影新增 `foundation.harness.file-set-recovery` 条目。
 
 **升级说明**
 
-三个 Foundation 包须一起精确锁定到 0.21.0。新准备接口只支持一个已声明的 Cursor Skill，并固定使用随包 `cursor-agent-print-v1` 驱动；工作负载含义、领域断言、发布新鲜度和清理由调用方负责。
+三个 Foundation 包须一起精确锁定到 0.22.0。声明式检查只证明已登记的版本来源与入口在结构上一致，不证明目标已执行；结论的业务解释不属于 Foundation。
 <!-- release-skill:managed:end id=latest-release -->
 
+## 本地未发布治理检查
+
+当前工作树在既有 `check` 命令下增加显式 `declared` 政策。版本检查只读取
+`skill-family.project-manifest.json` 声明的发行单元及其文本或 JSON 版本引用；入口检查只读取
+声明的物理文件。两个分支都不运行目标脚本、Skill、hook、模型，也不先跑未选择的 legacy 检查。
+
+`runChecks` 与 `runEntryContractCheck` 仍然只读。只有既有 `runCommand("check")` 和
+`checkEntriesAction` 包装入口可以创建一份 `professional-conclusion` 文件，而且调用方必须同时
+给出已存在输出根与根内相对路径。写入采用独占创建，不建父目录、不覆盖现有条目。这组实现随
+0.22.0 制品发布；此前已发布的 0.21.0 制品不包含它。
+
 ### Foundation 0.15.0 candidate 资格入口
 
 本候选版本增加两个固定资格入口：`foundation.kit.plugin-verification` 接入 Qoder 与 WorkBuddy 的 native-lifecycle 分支，`foundation.kit.skill-family-directory-verification` 接入 Kimi 目录分支。Qoder 与 WorkBuddy 各有一个生产 driver，各自确定 argv 计划，共用十二个有序语义阶段；每次 spawn 前重新观察可执行文件身份。Contracts 只校验闭合阶段结构、顺序与停止传播。
@@ -55,7 +67,7 @@ Kit 是「工程阶段」层，依赖 Harness 与 Contracts。它只做四件事
 
 ## 安装和最小示例
 
-0.21.0 是本地源码候选。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
+0.22.0 是本地源码候选。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -63,21 +75,21 @@ pack_dir="$(mktemp -d)"
 (cd packages/skill-family-harness-node && pnpm pack --pack-destination "$pack_dir")
 (cd packages/skill-family-engineering-kit && pnpm pack --pack-destination "$pack_dir")
 mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
-(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.21.0.tgz" "$pack_dir/skill-family-harness-node-0.21.0.tgz" "$pack_dir/skill-family-engineering-kit-0.21.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.22.0.tgz" "$pack_dir/skill-family-harness-node-0.22.0.tgz" "$pack_dir/skill-family-engineering-kit-0.22.0.tgz")
 ```
 
 发布后再使用 registry 坐标：
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.21.0
-npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit --help
-npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
-npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit adopt-plan --root <repo> --list-capabilities --all --scope all --locale zh-CN --uses ./uses.json
-npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit projection --root <repo>
-npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit check --root <repo>
+npm install --save-dev skill-family-engineering-kit@0.22.0
+npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit --help
+npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
+npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit adopt-plan --root <repo> --list-capabilities --all --scope all --locale zh-CN --uses ./uses.json
+npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit projection --root <repo>
+npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit check --root <repo>
 ```
 
-以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.21.0 -- skill-family-kit --help`。
+以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.22.0 -- skill-family-kit --help`。
 
 ### 三条采用旅程
 
@@ -173,7 +185,7 @@ Profile 必须显式提供，Kit 不默认绑定具体宿主。规范宿主 ID
 
 #### 0.21.0 候选：准备 Cursor 调用
 
-`prepareHostVerification` 是 0.21.0 候选公开 API，尚未发布到远端；已发布的 0.20.0 包不包含该接口。它只为 `cursor` 准备单个已声明 Skill，使用随包 Descriptor（宿主描述符）和固定 `cursor-agent-print-v1` 驱动，不接受自定义驱动、参数、模型覆盖、凭据处理或领域验证器。原有七驱动的 `runHostVerification` 入口保持兼容。
+`prepareHostVerification` 已随 0.21.0 发布，并在 0.22.0 中继续可用。它只为 `cursor` 准备单个已声明 Skill，使用随包 Descriptor（宿主描述符）和固定 `cursor-agent-print-v1` 驱动，不接受自定义驱动、参数、模型覆盖、凭据处理或领域验证器。原有七驱动的 `runHostVerification` 入口保持兼容。
 
 下例变量由调用方提供，文档和夹具内容为不透明的 UTF-8 字符串或 Buffer。`skillMembers` 必须包含 `SKILL.md`，安装只覆盖声明成员。各根目录须已存在，并使用规范绝对路径；`sessionRoot` 必须为空且由调用方独占，工作区必须位于 `repositoryRoot` 内，也允许两者相等。调用方授权使用现有用户状态根，并独占可执行文件命名空间。
 
@@ -211,6 +223,7 @@ const stdout = result.streams
 - 存量采用盘点：`adopt-plan`（严格只读，不写文件、不自动迁移）。
 - 受管投影：`projection` + Profile（不覆盖 handwritten 文件）。
 - 工程诊断：普通 `check` 只读；`check relock` 执行显式受控写事务，`check qualification` 预检通过后可能启动绑定的 executable。
+- 声明式治理诊断：版本检查显式选择 `policy: "declared"`，入口检查走 declared 子动作。目标只被静态读取；可选结论文件须由调用方明确授权输出位置。
 
 ## 边界机制
 
@@ -218,6 +231,7 @@ const stdout = result.streams
 - `adopt-plan` 结构性只读：实现中不存在任何写调用，连临时文件都不产生；计划字节与 `scaffold` 同源（`describeSkeletonFiles` 单一事实源），因此「计划即动作」。默认可能启动一条冻结参数的只读 Git status 探测；CLI 的 `--no-git-spawn`（或 API 的 `allowGitSpawn: false`）可关闭该探测。dirty 仓运行前后字节级零变化。
 - `projection` 采用两阶段执行：先对每个条目做路径分类、收容预检、自投影检查、manifest 授权检查、手写保护与冲突守卫；任一条目违规则整体拒绝、零写入。覆盖既有文件必须声明精确的 `expect.sha256` 前置状态；内容相同的既有文件是幂等 no-op。写入失败时尽力还原已覆盖文件的前置字节。
 - 普通 `check` 只读且无写调用，也没有 `--fix/--apply/--repair` 模式（此类标志在入口处被拒绝）。默认可能启动一条冻结参数的只读 Git status 探测；CLI 的 `--no-git-spawn`（或 API 的 `allowGitSpawn: false`）可关闭该探测。`check relock` 执行显式受控写事务；`check qualification` 预检通过后可能启动绑定的 executable。Git 前置状态仅用文件系统事实加至多一次冻结参数矢量的只读 `git status --porcelain=2`（`--no-optional-locks` + `GIT_OPTIONAL_LOCKS=0`，不刷新索引）。
+- 未发布的 declared 分支中，两个纯检查函数仍只读，也不探测 Git。只有调用方显式要求结论时，两个既有包装入口才通过独占创建产生本轮唯一新增持久副作用。
 
 ## 错误码与退出码
 
@@ -330,4 +344,4 @@ Foundation 本身不发起网络请求，但绑定的 executable 仍可能联网
 
 独立入口 `runSkillFamilyDirectoryVerification({ request, bindings })` 固定 Kimi 生产 argv 与窄环境，并拒绝调用方 observation。原始 parser 通过生产进程路径验证，但受控 fixture 事件不会被提升为 `observed`；缺少官方 typed mapping 时，公共结果保持 `indeterminate` 和 manual candidate。
 
-0.21.0 是本地源码候选，远端可用性须由对应的 release-skill 发布后证据证明。候选检查使用本地已验证的三包 tarball；版本标记、单元测试或安装成功都不等于契约接入完成、迁移完成或真实宿主资格。
+声明式治理分支与结论输出随 0.22.0 制品发布；此前已发布的 0.21.0 制品不包含它们。远端可用性须由对应的 release-skill 发布后证据证明。本地测试或工作树 tarball 不等于契约接入完成、迁移完成或真实宿主资格。

package/data/capability-catalog/capability-catalog.en.json

@@ -20,9 +20,9 @@
  "capabilities": [
   {
    "id": "foundation.contracts.object-validation",
-   "intent": "Compile and validate all 45 registered top-level Foundation contract object documents under both the draft-07 and 2020-12 dialects using Ajv 8.20.0 (exact pin).",
+      "intent": "Compile and validate all 53 top-level objects registered in the current local Foundation contract source under both the draft-07 and 2020-12 dialects using Ajv 8.20.0 (exact pin).",
    "useWhen": [
-    "Need to validate registered contract objects such as project-manifest, profile-descriptor, report-model",
+        "Need to validate registered contract objects such as project-manifest, professional-conclusion, profile-descriptor, or report-model",
     "Need to detect the document dialect and select the strict or tolerant validation policy"
    ],
    "doNotUseWhen": [
@@ -1184,10 +1184,11 @@
   },
   {
    "id": "foundation.kit.check",
-   "intent": "Diagnose only, do not fix: run the nine check classes contracts/drift/closure/version/docs/git/identity/boundary/platform and output findings.",
+      "intent": "Diagnose only, do not fix: retain the nine legacy check classes and add an explicit declared version branch that reads only project-listed release units.",
    "useWhen": [
     "Need to surface engineering inconsistencies without auto-modifying",
-    "Need to narrow the check scope via --only"
+        "Need to narrow a legacy check via --only",
+        "Need to compare declared text or JSON version sources and mirrors without scanning undeclared units"
    ],
    "doNotUseWhen": [
     "Need auto-fix (forbidden; check writes no fixes)",
@@ -1195,19 +1196,23 @@
    ],
    "prerequisites": [],
    "inputs": [
-    "--only values: contracts|drift|closure|version|docs|git|identity|boundary|platform"
+        "Legacy --only values: contracts|drift|closure|version|docs|git|identity|boundary|platform",
+        "Declared version input: policy declared, only version, and project-manifest engineering.releaseUnits"
    ],
    "outputs": [
-    "Findings list; exit code findings=1, mechanism=2"
+        "Findings list; exit code findings=1, mechanism=2",
+        "Optional professional-conclusion path from the runCommand check wrapper when an explicit output root and relative path are provided"
    ],
    "sideEffects": [
-    "No file writes (read-only diagnosis)"
+        "runChecks is read-only; the declared branch does not spawn, probe Git, or execute target content",
+        "Only the runCommand check wrapper may exclusively create one conclusion under an explicitly supplied existing output root; it creates no parent and overwrites nothing"
    ],
    "failureSemantics": [
     "findings exit code 1; mechanism rejection exit code 2"
    ],
    "invariants": [
-    "CHECK_CLASSES is a closed set of nine classes, not expanded"
+        "CHECK_CLASSES is a closed set of nine legacy classes, not expanded",
+        "Declared checking reads only named units and preserves partial versus not-performed completion"
    ],
    "ownedByCaller": [
     "Business disposition of each finding"
@@ -1411,30 +1416,34 @@
   },
   {
    "id": "foundation.kit.entry-check",
-   "intent": "Read the entry-contract declaration and run five checks per entry: physical existence, logical-name consistency, human-entry registration, side-effect class, and token budget.",
+      "intent": "Retain the legacy entry-contract checks and provide an explicit declared branch that statically reads only physical entries listed by project-manifest.",
    "useWhen": [
     "Need to verify the entry-contract declaration against the physical SKILL.md",
-    "Need to check entry logical names, side-effect classes, and token budgets"
+        "Need to check entry logical names, side-effect classes, and token budgets",
+        "Need to verify declared physical files without executing a Skill, script, hook, or model"
    ],
    "doNotUseWhen": [
     "Need to fix the declaration or entries (check only diagnoses, it does not fix)"
    ],
    "prerequisites": [],
    "inputs": [
-    "Project root (carrying skill-family.entry-contract.json and package.json)"
+        "Legacy project root (carrying skill-family.entry-contract.json and package.json)",
+        "Declared project root (carrying project-manifest engineering.entries)"
    ],
    "outputs": [
-    "Entry-check report (kind skill-family.entry-check-report) and findings"
+        "Entry-check report (kind skill-family.entry-check-report) and findings",
+        "Optional professional-conclusion path from checkEntriesAction when explicit conclusion output is authorized"
    ],
    "sideEffects": [
-    "Read-only read of the declaration, package.json, and entry files"
+        "runEntryContractCheck only reads declarations and entry files; it never executes target content",
+        "Only checkEntriesAction may exclusively create one conclusion under an explicitly supplied existing output root; it creates no parent and overwrites nothing"
    ],
    "failureSemantics": [
     "A missing declaration is data, never a finding",
     "Each failed check produces a finding of a distinct kind"
    ],
    "invariants": [
-    "Does not modify any file",
+        "The pure check function does not modify any file",
     "Adds no fifth top-level command; it runs as the check entries sub-action"
    ],
    "ownedByCaller": [
@@ -2370,6 +2379,66 @@
    "routeElsewhere": [
     "An observed conclusion requires a separately approved official Kimi typed observation mapping; hostile concurrency or new output facts return to Foundation"
    ]
+  },
+  {
+   "id": "foundation.harness.file-set-recovery",
+   "intent": "Apply ordered create, replace, and delete operations for scattered ordinary files under one project root through a single public entry point, and, after a caught failure or a forced process termination, restore the original bytes and modes from durable recovery materials or report per-path conflicts and unknowns",
+   "useWhen": [
+    "A set of scattered ordinary files must be created, replaced, or deleted in fixed order under one real project root, with whole-group preflight and per-path intent facts",
+    "Writer interleaving must be prevented under a cooperative-exclusion precondition the caller has already established, rather than relying on instantaneous multi-file visibility",
+    "An uncommitted operation must be recoverable through an explicit public entry point after a process restart, and recovery must stay re-entrant when it is itself interrupted",
+    "Recovery materials should be retained by default and only the materials of a specified terminal operation should be cleaned"
+   ],
+   "doNotUseWhen": [
+    "Instantaneous multi-file visibility, cross-file transactional snapshots, or directory-level operations are needed",
+    "Protection against uncooperative concurrent writers or same-privilege hostile processes is needed (this capability offers only a cooperative-exclusion precondition)",
+    "Symbolic links, hard links, cross-device targets, or mechanism-reserved paths must be handled",
+    "Foundation must define domain validation semantics, business retry policy, or the final destination of recovery materials"
+   ],
+   "prerequisites": [
+    "The caller has approved a canonical absolute real root with createFilesystemRootBinding and passes the fixed recoveryRelPath and allowAdjacentStaging explicitly in the apply and recover requests",
+    "environment declares filesystem as apfs or ext4 and cooperativeWriters as true; the business root and the recovery materials share one device and parent directories already exist",
+    "apply requires a read-only validate function; recover requires an externally established exclusive maintenance interval and the complete observation of that interval; prune takes the normal writer when nothing is left over and requires the same maintenance observation only when a fault takeover is needed",
+    "Targets belong to the executing user, the owner-read bit is set, and no bit of the original or new mode is masked by the process umask"
+   ],
+   "inputs": [
+    "file-set-apply-request: operationId, root, rootBinding, recoveryRelPath, allowAdjacentStaging, environment, validationTimeoutMs, and up to 1024 ordered operations (path/action/expected/next, with bytes only in the JS call arguments)",
+    "file-set-recovery-request: the same root binding and environment plus allowAdjacentStaging and the maintenance observation; file-set-prune-request: the same root binding and environment, with an explicit maintenance observation required only for a fault takeover",
+    "The caller-supplied validate({root, operationId, signal}), synchronous or asynchronous, returning the closed object {passed}"
+   ],
+   "outputs": [
+    "file-set-result: operation, outcome, preflight, businessWrite, validation, recovery, paths, errors, and materials",
+    "paths in original request order, each with apply, restore, current, and errorKinds, separating historical intent, the restore action, and the last safe observation",
+    "materials with the recovery-material relative path, none/retained/partial/pruned, durable, and adjacentStaging facts"
+   ],
+   "sideEffects": [
+    "Writes journal and operations/<id>/{before,after}/<index> recovery materials under the fixed .foundation-file-apply directory inside the root, and performs strict single-file publication or atomic replacement writes on business paths",
+    "Retains recovery materials by default; only an explicit prune removes the exact materials of a terminal operation, and the journal is kept",
+    "Issues no network requests, starts no subprocesses, performs no Git writes, and never changes the process umask"
+   ],
+   "failureSemantics": [
+    "Catchable mechanism failures return a file-set-result instead of only throwing; the outer code stays SFC2004 and details carries the closed kind and phase enumerations, which are the branching inputs rather than the message",
+    "Whole-group preflight failure, unsupported environment, capacity breach, and path or precondition mismatch leave zero business writes and report the specific precondition failure",
+    "Domain validation that returns false, throws, times out, returns an invalid result, or completes late triggers automatic recovery without committing, and validation state is reported separately from recovery state",
+    "Recovery keeps external content for conflicting paths and continues with the remaining safe paths, while global exclusivity or root-identity problems stop the whole group",
+    "A valid commit event is never rolled back; when target re-verification or durability is unconfirmed the result is commit-unconfirmed and the materials are retained"
+   ],
+   "invariants": [
+    "No business path is touched before a durable apply-intent fact exists for that path, and a committed operation is never rolled back by recovery",
+    "The whole group uses one cooperative single writer and the existing event chain; no second log, lock, sequence, or digest chain is added and no state-store internal file is cleaned",
+    "Per-path result fields separate historical and current observations instead of collapsing into one boolean, and a completed restore never rewrites businessWrite back to none",
+    "Instantaneous multi-file visibility is not promised, nor is protection against uncooperative or same-privilege hostile concurrent writers"
+   ],
+   "ownedByCaller": [
+    "Freezing the business plan, the original state, and the new bytes, plus the final destination of recovery materials",
+    "The domain judgment inside validate, its exception details, the read-only precondition, and the chosen timeout value",
+    "Establishing the maintenance interval, confirming that old participants and old recoverers have stopped, and operational decisions when the commit is unconfirmed",
+    "The exact pin, adoption qualification, and domain acceptance judgment"
+   ],
+   "routeElsewhere": [
+    "Directory operations, symbolic links, cross-device writes, or complete metadata backup stay on the consumer path, or return to Foundation as a new minimal capability contract",
+    "Business state machines and orchestration go to loop-agent; distribution and release state go to release-skill"
+   ]
   }
  ]
 }

package/data/capability-catalog/capability-catalog.json

@@ -25,13 +25,16 @@
    "since": "0.2.0",
    "stability": "stable",
    "adoptionScopes": ["contracts"],
-   "entrypoints": [
-    "validateDocument (packages/skill-family-contracts/src/validator.mjs)",
-    "compileSchema (packages/skill-family-contracts/src/validator.mjs)",
-    "detectDialect (packages/skill-family-contracts/src/validator.mjs)"
-   ],
-   "sourceRefs": [
-    "packages/skill-family-contracts/src/validator.mjs"
+      "entrypoints": [
+        "validateDocument (packages/skill-family-contracts/src/validator.mjs)",
+        "compileSchema (packages/skill-family-contracts/src/validator.mjs)",
+        "detectDialect (packages/skill-family-contracts/src/validator.mjs)",
+        "professional-conclusion Schema (packages/skill-family-contracts/src/schemas/professional-conclusion.schema.json)"
+      ],
+      "sourceRefs": [
+        "packages/skill-family-contracts/src/validator.mjs",
+        "packages/skill-family-contracts/src/schemas/professional-conclusion.schema.json",
+        "packages/skill-family-contracts/src/schemas/project-manifest.schema.json"
    ],
    "positiveTestRefs": [
     "packages/skill-family-contracts/test/validator.test.mjs",
@@ -779,14 +782,17 @@
    "since": "0.2.0",
    "stability": "stable",
    "adoptionScopes": ["engineering-kit"],
-   "entrypoints": [
-    "runChecks (packages/skill-family-engineering-kit/src/check.mjs)",
-    "runCoreCheck (packages/skill-family-engineering-kit/src/core-check.mjs)",
-    "isContainedDeclaration (packages/skill-family-engineering-kit/src/core-check.mjs)"
-   ],
-   "sourceRefs": [
-    "packages/skill-family-engineering-kit/src/check.mjs",
-    "packages/skill-family-engineering-kit/src/core-check.mjs"
+      "entrypoints": [
+        "runChecks (packages/skill-family-engineering-kit/src/check.mjs)",
+        "runCommand check wrapper (packages/skill-family-engineering-kit/src/index.mjs)",
+        "runCoreCheck (packages/skill-family-engineering-kit/src/core-check.mjs)",
+        "isContainedDeclaration (packages/skill-family-engineering-kit/src/core-check.mjs)"
+      ],
+      "sourceRefs": [
+        "packages/skill-family-engineering-kit/src/check.mjs",
+        "packages/skill-family-engineering-kit/src/core-check.mjs",
+        "packages/skill-family-engineering-kit/src/engineering-declaration.mjs",
+        "packages/skill-family-engineering-kit/src/professional-conclusion.mjs"
    ],
    "positiveTestRefs": [
     "packages/skill-family-engineering-kit/test/check.test.mjs",
@@ -939,14 +945,16 @@
    "since": "0.6.0",
    "stability": "stable",
    "adoptionScopes": ["engineering-kit"],
-   "entrypoints": [
-    "runEntryContractCheck (packages/skill-family-engineering-kit/src/entry-check.mjs)",
-    "checkEntriesAction (packages/skill-family-engineering-kit/src/entry-check.mjs)",
+      "entrypoints": [
+        "runEntryContractCheck (packages/skill-family-engineering-kit/src/entry-check.mjs)",
+        "checkEntriesAction (packages/skill-family-engineering-kit/src/entry-check.mjs)",
     "ENTRY_CONTRACT_DECLARATION_PATH (packages/skill-family-engineering-kit/src/entry-check.mjs)",
     "ENTRY_CONTRACT_DECLARATION_KIND (packages/skill-family-engineering-kit/src/entry-check.mjs)"
    ],
-   "sourceRefs": [
-    "packages/skill-family-engineering-kit/src/entry-check.mjs"
+      "sourceRefs": [
+        "packages/skill-family-engineering-kit/src/entry-check.mjs",
+        "packages/skill-family-engineering-kit/src/engineering-declaration.mjs",
+        "packages/skill-family-engineering-kit/src/professional-conclusion.mjs"
    ],
    "positiveTestRefs": [
     "packages/skill-family-engineering-kit/test/entry-check.test.mjs"
@@ -1564,6 +1572,41 @@
    },
    "migration": "none",
    "promotionPolicy": "consumer-transparent"
+  },
+  {
+   "id": "foundation.harness.file-set-recovery",
+   "package": "skill-family-harness-node",
+   "layer": "harness",
+   "since": "0.22.0",
+   "stability": "candidate",
+   "adoptionScopes": ["harness"],
+   "entrypoints": [
+    "applyFileSet (packages/skill-family-harness-node/src/file-set-recovery.mjs)",
+    "recoverFileSet (packages/skill-family-harness-node/src/file-set-recovery.mjs)",
+    "pruneFileSetRecovery (packages/skill-family-harness-node/src/file-set-recovery.mjs)"
+   ],
+   "sourceRefs": [
+    "packages/skill-family-harness-node/src/file-set-recovery.mjs",
+    "packages/skill-family-harness-node/src/index.mjs",
+    "packages/skill-family-contracts/src/schemas/file-set-apply-request.schema.json",
+    "packages/skill-family-contracts/src/schemas/file-set-recovery-request.schema.json",
+    "packages/skill-family-contracts/src/schemas/file-set-prune-request.schema.json",
+    "packages/skill-family-contracts/src/schemas/file-set-result.schema.json",
+    "packages/skill-family-contracts/src/schemas/file-set-event-payload.schema.json",
+    "packages/skill-family-contracts/src/schemas/state-store-recovery-observation.schema.json"
+   ],
+   "positiveTestRefs": [
+    "packages/skill-family-harness-node/test/file-set-recovery.test.mjs",
+    "packages/skill-family-harness-node/test/file-set-recovery-crash.test.mjs",
+    "packages/skill-family-contracts/test/file-set-contract.test.mjs"
+   ],
+   "negativeTestRefs": [
+    "packages/skill-family-harness-node/test/file-set-recovery.test.mjs",
+    "packages/skill-family-harness-node/test/file-set-recovery-crash.test.mjs",
+    "packages/skill-family-contracts/test/file-set-contract.test.mjs"
+   ],
+   "migration": "none",
+   "promotionPolicy": "consumer-transparent"
   }
  ]
 }