skill-family-engineering-kit 0.23.0 → 0.24.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.24.1 locale=en baseline=sha256:60780ae0d34a8e8fcc016ebb188586876b9c31ceafb0c02a826db8e449e43729 -->
+## [0.24.1] - 2026-10-12
+
+Engineering Kit 0.24.1 advances only to keep the existing four-unit lockstep contract for the Foundation documentation patch. It adds no capability, API, Schema, protocol, or mechanism.
+
+### Changed
+
+- Update only the package coordinate and its managed version projections; existing capabilities, parameters, and failure boundaries remain unchanged.
+
+### Upgrade Notes
+
+Pin the three Foundation npm packages to the exact same version and keep the independent Plugin at that release version. Contracts specification 1.20.0 remains a separate coordinate from npm package versions. Use the actual published version's public interfaces and sources; this note does not replace post-publish verification.
+<!-- release-skill:changelog:end version=0.24.1 locale=en -->
+
+
+<!-- release-skill:changelog:start version=0.24.0 locale=en baseline=sha256:ab4ce0e2c0eb82f9d7b97bd2d48a040965596785dab29dd8898dbe5730acd303 -->
+## [0.24.0] - 2026-10-07
+
+Engineering Kit 0.24.0 adds explicit persistent-tool-lock registration within the existing check relock transaction. The four top-level commands remain scaffold, adopt-plan, projection, and check. This note records the local lockstep candidate, not completed remote publication or real-consumer adoption.
+
+### Changed
+
+- The API registrationClass accepts only handwritten or trackedToolLocks; the CLI uses --registration-class. The default remains handwritten, including its existing automatic discovery when the files list is absent or empty.
+- The trackedToolLocks mode requires an explicit non-empty files list, supplied with --files in the CLI. Every path must identify an existing ordinary file inside the target. It does not discover tool locks automatically or infer tool semantics from names or content.
+- The same transaction initializes entries when classes.trackedToolLocks is absent, then appends the explicit paths. An existing malformed class or non-array entries is refused before the first write. Other classes remain unchanged.
+- Only .foundation/file-registry.json and skill-family.managed-file-lock.json are updated. Tool-lock content is excluded from managed hashes, so a later provider update does not itself cause managed drift. Existing path, symlink, prior-registration, state-document, and managed-drift refusals remain. A mid-publication failure still exposes publicationState; no atomic rollback of both documents is promised.
+- The package moves to 0.24.0 with the other three units. Contracts stays specification 1.20.0, with no new contract object, Harness mechanism, or report kind. Historical 0.23.1 notes remain unchanged.
+
+### Upgrade Notes
+
+Pin all three Foundation npm packages to exactly 0.24.0. The new registration mode belongs to this candidate and is not a published 0.23.0 capability; adoption depends on the corresponding released public interface. Complete consumer, initialization, and release qualification remain to be verified.
+<!-- release-skill:changelog:end version=0.24.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.23.0 locale=en baseline=sha256:6220b2be13af0cfb071f46ab481b1ecec5d1f0ce176cbb8cb6cc28ea9d0a7e3d -->
 ## [0.23.0] - 2026-09-26
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,39 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.24.1 locale=zh-CN baseline=sha256:0d0b6cccd46c69014e89efa21677ef015ccd3085f0fd07e8021b364b1c1f47e6 -->
+## [0.24.1] - 2026-10-12
+
+Engineering Kit 0.24.1 仅随 Foundation 文档补丁按既有四单元合同锁步前移，没有新增能力、API、Schema、协议或机制。
+
+### 变更
+
+- 仅更新包版本和相应受管版本派生；现有能力、参数与失败边界保持不变。
+
+### 升级说明
+
+三个 Foundation npm 包须精确锁定同版，独立插件与三包保持相同发布版本。Contracts 规格仍为 1.20.0，与 npm 包版本分别处理；消费以实际发布版本的公开接口和来源为准，本说明不替代发布后验证。
+<!-- release-skill:changelog:end version=0.24.1 locale=zh-CN -->
+
+
+<!-- release-skill:changelog:start version=0.24.0 locale=zh-CN baseline=sha256:0ae5e1d34d13be6d56f72e4c77ab44e4d24e0e4d5f562ab424d104795db770eb -->
+## [0.24.0] - 2026-10-07
+
+Engineering Kit 0.24.0 在既有 `check relock` 事务中增加显式的持久工具锁登记能力，四个顶层命令仍为 `scaffold`、`adopt-plan`、`projection`、`check`。本说明记录本地锁步候选状态，不表示远端发布或真实消费者采用已完成。
+
+### 变更
+
+- `registrationClass` 为 API 参数，仅接受 `handwritten` 或 `trackedToolLocks`；CLI 对应参数为 `--registration-class`。默认值保持为 `handwritten`；在默认手写模式下，文件清单为空或缺省时，原自动发现行为维持不变。
+- 使用 `trackedToolLocks` 时必须提供非空显式 `files` 清单，CLI 通过 `--files` 指定。每个路径必须指向目标内已存在的普通文件，不支持自动发现工具锁，也不根据文件名或内容推断工具语义。
+- 若原事务中 `classes.trackedToolLocks` 缺省，则在首次写入前初始化其 `entries` 数组，并追加明确指定的路径；若已有类别非合法对象，或 `entries` 非数组类型，则在首写前拒绝操作。其他类别保持不变。
+- 仅更新 `.foundation/file-registry.json` 与 `skill-family.managed-file-lock.json` 两份状态文件。工具锁内容不进入受管摘要，后续由原工具刷新内容不会因此引发受管漂移；路径、符号链接、已登记路径、状态文档及既有受管漂移的拒绝规则继续有效。中途发布失败时仍暴露原始 `publicationState`，不承诺双文件原子回滚。
+- 包版本与其他三单元同步前移至 0.24.0。Contracts 规格仍为 1.20.0，未新增合同对象、Harness 机制或报告种类；0.23.1 中仅锁步前移的历史说明保持原样。
+
+### 升级说明
+
+三个 Foundation npm 包须精确锁定至 0.24.0 版本。新登记模式仅属本轮候选，非 0.23.0 已发布能力；实际采用以对应版本公开接口为准。完整消费者、初始化及发布资格仍待验证。
+<!-- release-skill:changelog:end version=0.24.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.23.0 locale=zh-CN baseline=sha256:4192d7adcff64a7411acab5ef402d9baa657bcb1db6f41c4ed3b33c2303e25bc -->
 ## [0.23.0] - 2026-09-26
 

package/README.md

@@ -4,28 +4,22 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.23.0 -->
+<!-- release-skill:release-version: 0.24.1 -->
 
 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.23.0** (2026-09-26)
+**0.24.1** (2026-10-12)
 
-Engineering Kit 0.23.0 keeps the four top-level commands and adds family proof creation and proof reading for a complete static professional review. This note records the local lockstep candidate only; it does not claim remote publication or real-host acceptance.
-
-**Added**
-
-- Adds `check proof-create`, which projects one caller-supplied static review result into a single exclusive Foundation conclusion. It checks the review structure and writes the family result; it does not scan the target again, authenticate authorship, or overwrite an existing conclusion.
-- Adds `check proof`, which reads one existing Foundation-family proof and explains its public code. It does not scan the target, follow paths inside `details`, or authenticate authorship.
-- Records `FOUNDATION_STATIC_CLEAR` only when every applicable selected static item passes, `FOUNDATION_STATIC_FINDINGS` when a real finding is present, and `FOUNDATION_STATIC_INCOMPLETE` when coverage is unfinished, evidence is insufficient, or every selected item is not applicable. Existing `ENGINEERING_*` codes stay limited to the previous declaration branches.
+Engineering Kit 0.24.1 advances only to keep the existing four-unit lockstep contract for the Foundation documentation patch. It adds no capability, API, Schema, protocol, or mechanism.
 
 **Changed**
 
-- Moves the package coordinate to 0.23.0 together with Contracts, Harness, and the adoption Plugin. The Contracts specification remains 1.20.0, and this package adds no new contract object or Harness mechanism.
+- Update only the package coordinate and its managed version projections; existing capabilities, parameters, and failure boundaries remain unchanged.
 
 **Upgrade Notes**
 
-Pin all three Foundation packages to exactly 0.23.0. The Kit projects and reads the family result; the engineering judgment stays with `foundation-engineering-check`. Remote publication and real-host verification are outside this note.
+Pin the three Foundation npm packages to the exact same version and keep the independent Plugin at that release version. Contracts specification 1.20.0 remains a separate coordinate from npm package versions. Use the actual published version's public interfaces and sources; this note does not replace post-publish verification.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Governance Check (0.22.0)
@@ -68,7 +62,7 @@ Kit is the "engineering stage" layer, depending on the Harness and Contracts. It
 
 ## Installation and Minimal Example
 
-Version 0.23.0 is the local source candidate and is not yet formally published. Version 0.22.0 remains the published package. Build all three tarballs into one temporary directory and install those exact files for a candidate check:
+This package version is 0.24.1; version 0.24.0 has been formally published. To verify a working tree before formal publication, build all three tarballs into one temporary directory and install those exact files:
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -76,21 +70,62 @@ 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.23.0.tgz" "$pack_dir/skill-family-harness-node-0.23.0.tgz" "$pack_dir/skill-family-engineering-kit-0.23.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.24.1.tgz" "$pack_dir/skill-family-harness-node-0.24.1.tgz" "$pack_dir/skill-family-engineering-kit-0.24.1.tgz")
 ```
 
-After 0.23.0 is formally published, use the registry coordinate:
+The registry installation below requires exact version 0.24.1 to be formally available:
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.23.0
-npm exec --package=skill-family-engineering-kit@0.23.0 -- skill-family-kit --help
-npm exec --package=skill-family-engineering-kit@0.23.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
-npm exec --package=skill-family-engineering-kit@0.23.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.23.0 -- skill-family-kit projection --root <repo>
-npm exec --package=skill-family-engineering-kit@0.23.0 -- skill-family-kit check --root <repo>
+npm install --save-dev skill-family-engineering-kit@0.24.1
+npm exec --package=skill-family-engineering-kit@0.24.1 -- skill-family-kit --help
+npm exec --package=skill-family-engineering-kit@0.24.1 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
+npm exec --package=skill-family-engineering-kit@0.24.1 -- 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.24.1 -- skill-family-kit projection --root <repo>
+npm exec --package=skill-family-engineering-kit@0.24.1 -- 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.24.1 -- skill-family-kit --help`.
+
+### Engineering declarations (available since 0.24.0)
+
+The optional `engineering` input has been available since `0.24.0`; `0.23.0` does not support it. Use the already selected SDK only after confirming its actual public interfaces and exact lockstep source for all three Foundation packages; candidate verification and post-release adoption are separate facts. Omitting the input preserves existing bytes and paths. `null`, `{}`, unknown fields, and invalid references are rejected.
+
+Construct `engineering` from the project's actual business entries and release units. Each `entries` member has `name`, `form`, and `physicalRef`; `form` is either `skill_md` or `file`, and `skill_md` must point to `SKILL.md`. Each `releaseUnits` member has `id` and `versionSource`, with optional `versionMirrors`. A text version reference has `path` and `format: "text"`; a JSON reference has `path`, `format: "json"`, and a non-empty `jsonPointer`. Use actual business version sources, not the private skeleton example package, SDK version, or Profile version. The presence of `package.json` does not establish npm distribution. No separate declaration input file is required.
+
+The variables below are supplied by the caller; `engineering` is the complete confirmed declaration, rather than a default example answer:
+
+```js
+import { describeSkeletonFiles, scaffoldTarget, planAdoption, runProjection } from "skill-family-engineering-kit";
+
+const skeleton = await describeSkeletonFiles({ ...inputs, engineering });
+const generated = await scaffoldTarget({ ...options, engineering });
+const plan = await planAdoption({ ...options, engineering, allowGitSpawn: false });
+const updated = await runProjection({ root: targetRoot, engineering });
 ```
 
-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.23.0 -- skill-family-kit --help`.
+These operations are independent; they do not form a sequence to run on one target. Use `scaffoldTarget` for an empty target. It generates the declaration and its manifest hash using the same skeleton generator and existing managed lock. It validates the contract and contained path shape but does not verify that referenced files exist or write domain content. References may point to files the business author will create later. Use `planAdoption` to analyze an existing non-empty project without modifying it. It predicts the same declaration bytes as `scaffold`, remains strictly read-only, and creates no temporary files. `allowGitSpawn: false` disables the existing read-only Git probe. `writeSet`, `conflicts`, and `complete` do not authorize execution or establish business qualification.
+
+Use `runProjection({ root: targetRoot, engineering })` only for an already managed project. It replaces the entire `engineering` object without deep-merging. Include all still-needed existing `entries` and `releaseUnits` in the complete confirmed object. It cannot be combined with `manifest`, `candidateRoot`, or `preparedProjection`. The target must be an ordinary existing root with valid ordinary registry, project manifest, and managed lock; manifest and lock must already be declared managed by both registry and `managedFiles`, and the manifest lock entry must be owned by Engineering Kit. All other managed files must match their original lock, with no missing coverage, duplicate entries, or unowned lock entries. Every business entry and version reference must point to an existing ordinary file inside the root. Missing prerequisites make this update unavailable; they do not trigger automatic takeover of an arbitrary non-empty project.
+
+A valid update writes only `skill-family.project-manifest.json` and `skill-family.managed-file-lock.json`. It preserves non-`engineering` fields, registry and other file bytes, other lock entries, generator identity, versions, `lockVersion`, and file modes. The existing generator derives the manifest hash, and identical content is idempotent. The result remains a `skill-family.projection-receipt` with `schemaVersion: 2`; its in-memory `candidate.root` and `manifest.location` are `null`. Existing v1/v2 and prepared-projection protection remain in place; do not hand-write a manifest or lock candidate to hide drift.
+
+The three existing CLI commands accept `--engineering <JSON>`:
+
+```text
+skill-family-kit scaffold --root <target> --project-id <id> --profile generic --licensing-profile <licensing-id> --engineering <JSON>
+skill-family-kit adopt-plan --root <target> --project-id <id> --profile <profile-id> --licensing-profile <licensing-id> --no-git-spawn --engineering <JSON>
+skill-family-kit projection --root <target> --engineering <JSON>
+```
+
+`<JSON>` is a JSON object string, not a file path; quote it as one shell argument. `--engineering` is separate from `--engineering-baseline`, which still requires `--compare-skeleton`. Capability catalog queries cannot include engineering declarations. The existing four-command boundary remains.
+
+If facts are incomplete, report the missing facts. A declaration may contain only `entries` or only `releaseUnits`, but the absent declared-check branch remains `incomplete`. Once the real business and version files exist, use the official managed update and the existing core, declared version, and declared entry checks. Generation, a read-only plan, static checks, formal host discovery, real business execution, independent semantic review, and overall qualification remain separate facts. Omission preserves old behavior; it does not mean declarations are complete.
+
+Since 0.24.0, `runCoreCheck` selects the applicable version-check path from the target declarations: when a target explicitly declares `engineering.releaseUnits`, the core reuses the existing declared reader for `versionSource` and `versionMirrors` (text or JSON), applying the same validation logic. A private `package.json` within the engineering scope is not treated as an implicit source or mirror for that business unit. It is checked for that unit only when explicitly declared. Targets with no version declaration, or only valid `entries`, continue to use the legacy version check. Invalid or duplicate declarations cannot fall back to success. Missing or unreadable declared sources or mirrors fail visibly.
+
+The nine-class loop and report assembly are preserved, maintaining Contracts specification-version compatibility and the integrity of the other eight classes. Declared sources, mirrors, and their ancestral paths are included in the preflight check via the original tree enumeration and `lstat` safety validation, including paths inside opaque tooling directories. Only declared paths are probed; no new directory walker is introduced. Symlinks, FIFOs, and unsafe ancestor paths remain rejected under the original rules, including in-root symlinks. Completion status, mechanism failures, and exit codes 0/1/2 are propagated accurately.
+
+Public `runChecks` defaults to `policy: "legacy"`. Its original findings and full/only equivalence remain unchanged. Explicit `policy: "declared"` still requires `only: "version"` and preserves its report structure, zero-target execution semantics, and zero-Git boundary. No new public policy value, API, CLI option, Schema definition, or package-root export is added. No checker is copied into the generated target shim. Local verification does not establish publication readiness, business qualification, or complete initialization. This update reflects only a narrow, targeted change in core behavior for targets with declared versions; standalone `runChecks` retains its documented behavior.
 
 ### Three adoption journeys
 
@@ -229,8 +264,10 @@ The caller owns workload semantics, candidate-to-payload binding, domain asserti
 - `scaffold`'s target must be an **empty directory** (any entry including dotfiles counts as non-empty), or a non-existent path whose parent directory exists (only the last level is created). All writes go through the harness's atomic contained write (`writeFileAtomic`), leaving no half-written artifact on failure, and paths cannot escape the target root.
 - `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.
+
+  Engineering mode retains the originally verified reference snapshots and rechecks them before each actual mutation and after completion; repeated reads cannot replace the baseline. A rejection before the first write performs no restoration writes, and foreign bytes on an output never attempted by this mode are preserved. If an actual output write is attempted and fails, the existing error, verification, and best-effort rollback path restores only outputs this mode actually attempted. This does not promise a transaction for the whole initialization, hostile concurrency, or ABA safety; the existing v2 complete-closure rollback contract remains unchanged.
 - 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.
+- In the 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
 

package/README.zh-CN.md

@@ -5,33 +5,27 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.23.0 -->
+<!-- release-skill:release-version: 0.24.1 -->
 
 开发与 CI 阶段使用的工程工具包。**恰好四个**顶层命令，没有第五个：
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.23.0** (2026-09-26)
+**0.24.1** (2026-10-12)
 
-Engineering Kit 0.23.0 保持四个顶层命令，并增加完整静态专业审阅所需的本族证明出证和读取。本说明只记录本地锁步候选，不表示已经远端发布，也不表示真实宿主已经接受。
-
-**新增**
-
-- 增加 `check proof-create`。它把调用方提供的一份静态审阅结果投影成一份排他的 Foundation 结论，只检查审阅结构并写入本族结果；不再次扫描目标，不鉴定作者，也不覆盖已有结论。
-- 增加 `check proof`。它读取一份已有的本族证明并解释公开领域码；不扫描目标，不追随 `details` 里的路径，不鉴定作者。
-- 全部适用且选中的静态项通过时记录 `FOUNDATION_STATIC_CLEAR`；存在真实发现时记录 `FOUNDATION_STATIC_FINDINGS`；覆盖未完成、证据不足，或选中项全部不适用时记录 `FOUNDATION_STATIC_INCOMPLETE`。既有 `ENGINEERING_*` 仍只表示原来的局部声明检查。
+Engineering Kit 0.24.1 仅随 Foundation 文档补丁按既有四单元合同锁步前移，没有新增能力、API、Schema、协议或机制。
 
 **变更**
 
-- 包坐标与 Contracts、Harness 和采用 Plugin 一起前移到 0.23.0。Contracts 规格仍是 1.20.0。本包不新增合同对象，也不新增 Harness 机制。
+- 仅更新包版本和相应受管版本派生；现有能力、参数与失败边界保持不变。
 
 **升级说明**
 
-三个 Foundation 包须一起精确锁定到 0.23.0。Kit 负责投影和读取本族结果；工程判断仍由 `foundation-engineering-check` 作出。远端发布和真实宿主验证不在本说明范围内。
+三个 Foundation npm 包须精确锁定同版，独立插件与三包保持相同发布版本。Contracts 规格仍为 1.20.0，与 npm 包版本分别处理；消费以实际发布版本的公开接口和来源为准，本说明不替代发布后验证。
 <!-- release-skill:managed:end id=latest-release -->
 
-## 本地未发布治理检查
+## 治理检查（0.22.0）
 
-当前工作树在既有 `check` 命令下增加显式 `declared` 政策。版本检查只读取
+0.22.0 在既有 `check` 命令下增加显式 `declared` 政策。版本检查只读取
 `skill-family.project-manifest.json` 声明的发行单元及其文本或 JSON 版本引用；入口检查只读取
 声明的物理文件。两个分支都不运行目标脚本、Skill、hook、模型，也不先跑未选择的 legacy 检查。
 
@@ -67,7 +61,7 @@ Kit 是「工程阶段」层，依赖 Harness 与 Contracts。它只做四件事
 
 ## 安装和最小示例
 
-0.23.0 是尚未正式发布的本地源码候选；0.22.0 是已发布包。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
+本包版本为 0.24.1；0.24.0 已正式发布。验证尚未正式发布的工作树时，先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -75,21 +69,62 @@ 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.23.0.tgz" "$pack_dir/skill-family-harness-node-0.23.0.tgz" "$pack_dir/skill-family-engineering-kit-0.23.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.24.1.tgz" "$pack_dir/skill-family-harness-node-0.24.1.tgz" "$pack_dir/skill-family-engineering-kit-0.24.1.tgz")
 ```
 
-0.23.0 正式发布后，再使用对应的 registry 坐标：
+以下 registry 安装方式以精确版本 0.24.1 已正式可用为前提：
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.23.0
-npm exec --package=skill-family-engineering-kit@0.23.0 -- skill-family-kit --help
-npm exec --package=skill-family-engineering-kit@0.23.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
-npm exec --package=skill-family-engineering-kit@0.23.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.23.0 -- skill-family-kit projection --root <repo>
-npm exec --package=skill-family-engineering-kit@0.23.0 -- skill-family-kit check --root <repo>
+npm install --save-dev skill-family-engineering-kit@0.24.1
+npm exec --package=skill-family-engineering-kit@0.24.1 -- skill-family-kit --help
+npm exec --package=skill-family-engineering-kit@0.24.1 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
+npm exec --package=skill-family-engineering-kit@0.24.1 -- 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.24.1 -- skill-family-kit projection --root <repo>
+npm exec --package=skill-family-engineering-kit@0.24.1 -- skill-family-kit check --root <repo>
+```
+
+以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.24.1 -- skill-family-kit --help`。
+
+### 工程声明调用（自 0.24.0 提供）
+
+可选 `engineering` 参数自 `0.24.0` 提供，`0.23.0` 不支持。使用已选 SDK 前，核对其实际公共接口与三个 Foundation 包的精确锁步来源；候选验证与正式发布后采用分别报告。省略参数保持既有字节和路径；`null`、`{}`、未知字段和非法引用拒绝。无需另建声明输入文件。
+
+`engineering` 由调用方依据真实业务入口和发行单元构造。`entries` 每项包含 `name`、`form`、`physicalRef`；`form` 仅为 `skill_md` 或 `file`，前者必须指向 `SKILL.md`。`releaseUnits` 每项包含 `id`、`versionSource`，可选 `versionMirrors`。`versionSource` 为文本或 JSON 引用对象，`versionMirrors` 为引用数组。文本版本引用使用 `path` 和 `format: "text"`；JSON 引用使用 `path`、`format: "json"` 与非空 `jsonPointer`。版本取自真实业务版本源，不取私有骨架示例包、SDK 或 Profile 版本，不因 `package.json` 存在推导 npm 分发。
+
+下例变量由调用方提供；`engineering` 是完整已确认的声明，不是默认示例答案：
+
+```js
+import { describeSkeletonFiles, scaffoldTarget, planAdoption, runProjection } from "skill-family-engineering-kit";
+
+const skeleton = await describeSkeletonFiles({ ...inputs, engineering });
+const generated = await scaffoldTarget({ ...options, engineering });
+const plan = await planAdoption({ ...options, engineering, allowGitSpawn: false });
+const updated = await runProjection({ root: targetRoot, engineering });
 ```
 
-以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.23.0 -- skill-family-kit --help`。
+这些调用用于不同目标状态，不能按示例次序对同一目标全跑。空目标由 `scaffoldTarget` 通过同一骨架生成器和原受管锁派生声明与清单摘要；只检查合同和根内路径形态，可引用业务作者稍后创建的文件，不确认文件已存在，也不代写领域内容。非空目标由 `planAdoption` 预测与 `scaffold` 相同的声明字节，保持严格只读，连临时文件也不写；`allowGitSpawn: false` 关闭原只读 Git 探测。`writeSet`、`conflicts` 和 `complete` 不授权执行，也不证明业务资格。
+
+现有受管项目使用 `runProjection({ root: targetRoot, engineering })` 完整替换整个 `engineering`，不做深合并。完整已确认对象须保留仍需使用的旧 `entries` 和 `releaseUnits`。不能与 `manifest`、`candidateRoot` 或 `preparedProjection` 同传。目标须为现有普通根，具备有效普通 registry、项目清单和受管锁；清单与锁已由 registry 及 `managedFiles` 声明受管，清单锁条目由 Engineering Kit 拥有。其他受管文件须匹配原锁，没有缺覆盖、重复或未拥有的锁条目。每个业务入口与版本引用须指向根内现存普通文件。前提缺失只表示本更新不可执行，不自动接管任意非空项目。
+
+合法更新只写 `skill-family.project-manifest.json` 和 `skill-family.managed-file-lock.json`，保留非 `engineering` 字段、registry 与其他文件字节、其他锁条目、生成器身份、版本、`lockVersion` 和文件 mode。清单摘要由原生成器派生，同内容幂等。结果沿用 `schemaVersion: 2` 的 `skill-family.projection-receipt`；内存候选的 `candidate.root` 与 `manifest.location` 为 `null`。原 v1/v2 和 prepared 投影保护保留，不手写清单或锁候选掩盖漂移。
+
+三个原 CLI 命令接受 `--engineering <JSON>`：
+
+```text
+skill-family-kit scaffold --root <target> --project-id <id> --profile generic --licensing-profile <licensing-id> --engineering <JSON>
+skill-family-kit adopt-plan --root <target> --project-id <id> --profile <profile-id> --licensing-profile <licensing-id> --no-git-spawn --engineering <JSON>
+skill-family-kit projection --root <target> --engineering <JSON>
+```
+
+`<JSON>` 是工程对象的 JSON 字符串，不是文件路径，须以 shell 引号作为一个参数传入。`--engineering` 与 `--engineering-baseline` 独立，后者仍须与 `--compare-skeleton` 成对；能力目录查询不能混入工程声明。四个顶层命令边界保留。
+
+事实未齐时具体报告缺项。可以只声明 `entries` 或只声明 `releaseUnits`，但未声明的另一检查分支仍为 `incomplete`。待真实业务和版本文件存在后，使用官方受管更新及既有 core、declared 版本、declared 入口检查。生成、只读计划、静态检查、正式宿主发现、真实业务、独立语义审阅与整体资格分别报告；省略参数保留旧行为，不表示声明已完成。
+
+自 0.24.0 起，公开 `runCoreCheck` 的版本检查按目标声明选择适用路径：目标真实声明 `engineering.releaseUnits` 时，版本类复用已有声明式版本读取逻辑，依据 `versionSource` 与 `versionMirrors` 检查文本或 JSON 格式的版本信息；私有工程的 `package.json` 不自动成为该业务单元的版本源或镜像，仅当被显式声明时方可参与版本认定。对于真正未声明版本、或仅包含合法 `entries` 的目标，仍沿用原有 legacy 版本检查路径。非法或重复的声明不回退为通过；声明的版本源或镜像缺失、不可读时如实失败。
+
+核心调度机制保持不变，共用原九类循环与报告流程，保留 Contracts 规格版本一致性检查及其他八类校验。声明的来源、镜像及各祖先路径均需先通过原树枚举与 `lstat` 安全预检，包括原不展开的工具目录；仅探查声明所涉路径，不引入新的目录遍历器。符号链接、FIFO 及其他不安全读集仍按原规则拒绝访问，禁止穿过根内符号链接目录；`completed`、`mechanism` 与 0/1/2 退出码如实传播。
+
+该调整仅涉及公开 core 对已声明版本目标的检查：公共 `runChecks` 缺省行为仍等同于显式 `policy: "legacy"`，涵盖原版本发现及 `full`/`only` 等价逻辑；显式 `policy: "declared"` 仍仅允许 `only: "version"`，维持原报告形式、不执行目标代码、不调用 Git 的边界。未新增任何公共 policy 值、API、CLI 参数、Schema 定义或包根导出，亦不在目标生成 shim 中复制检查逻辑。局部验证不构成正式发布、业务资格或整体初始化完成的证明。
 
 ### 三条采用旅程
 
@@ -230,8 +265,10 @@ const stdout = result.streams
 - `scaffold` 的目标必须是**空目录**（任何条目含点文件都算非空），或其父目录已存在的不存在路径（只创建最后一级）。全部写入经 harness 的原子收容写（`writeFileAtomic`），失败不留半成品，路径不能越出目标根。
 - `adopt-plan` 结构性只读：实现中不存在任何写调用，连临时文件都不产生；计划字节与 `scaffold` 同源（`describeSkeletonFiles` 单一事实源），因此「计划即动作」。默认可能启动一条冻结参数的只读 Git status 探测；CLI 的 `--no-git-spawn`（或 API 的 `allowGitSpawn: false`）可关闭该探测。dirty 仓运行前后字节级零变化。
 - `projection` 采用两阶段执行：先对每个条目做路径分类、收容预检、自投影检查、manifest 授权检查、手写保护与冲突守卫；任一条目违规则整体拒绝、零写入。覆盖既有文件必须声明精确的 `expect.sha256` 前置状态；内容相同的既有文件是幂等 no-op。写入失败时尽力还原已覆盖文件的前置字节。
+
+  工程模式保留原始已核引用快照，在每次实际修改前和完成后重验；重复读取不能替换基线。首写前若发生拒绝，则不执行恢复写入，未尝试输出的外来字节保留。实际尝试写入失败时沿用既有错误、验证与尽力回滚，仅恢复本模式实际尝试的输出路径。不承诺整次初始化事务、恶意并发或 ABA 安全；原 v2 完整闭包回滚合同不变。
 - 普通 `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。只有调用方显式要求结论时，两个既有包装入口才通过独占创建产生本轮唯一新增持久副作用。
+- declared 分支中的两个纯检查函数保持只读，也不探测 Git。只有调用方显式要求结论时，两个既有包装入口才通过独占创建产生本轮唯一新增持久副作用。
 
 ## 错误码与退出码
 

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

@@ -1461,10 +1461,11 @@
   },
   {
    "id": "foundation.kit.relock",
-   "intent": "Run the controlled relock transaction: register newly handwritten files into .foundation/file-registry.json and recompute skill-family.managed-file-lock.json from the current bytes in one fail-closed operation.",
+   "intent": "Run the controlled relock transaction: register new handwritten files by default, or persistent tool-lock paths with explicit trackedToolLocks selection; update the registry and managed-file lock in the existing transaction without hashing tool-lock contents.",
    "useWhen": [
     "Need to admit a newly handwritten file into the closed world without hand-editing the registry",
-    "Need to recompute the managed-file lock from current bytes after registration"
+    "Need to recompute the managed-file lock from current bytes after registration",
+    "Explicitly register provider-generated persistent lock paths in the existing trackedToolLocks category without locking their contents"
    ],
    "doNotUseWhen": [
     "Need to legitimize drifted managed bytes (relock refuses drift)",
@@ -1472,7 +1473,8 @@
    ],
    "prerequisites": [],
    "inputs": [
-    "Project root carrying .foundation/file-registry.json and skill-family.managed-file-lock.json"
+    "Project root carrying .foundation/file-registry.json and skill-family.managed-file-lock.json",
+    "registrationClass defaults to handwritten and accepts only handwritten or trackedToolLocks; CLI: --registration-class. trackedToolLocks requires an explicit non-empty files array (CLI --files: comma-separated paths)"
    ],
    "outputs": [
     "Relock report (kind skill-family.relock-report)"
@@ -1481,12 +1483,13 @@
     "Writes exactly two contained state documents: the registry and the managed-file lock"
    ],
    "failureSemantics": [
-    "Every refusal leaves the target untouched (zero writes)",
+    "Pre-write parameter, path, registration and drift validation refusals leave the target unchanged",
     "A half-updated state is never presented as success"
    ],
    "invariants": [
     "Adds no fifth top-level command; it runs as the check relock sub-action",
-    "The new lock binds the new registry bytes before either document is committed"
+    "The new lock binds the new registry bytes before either document is committed",
+    "Initialize entries within the same transaction when trackedToolLocks is absent; reject an existing non-object category or non-array entries without replacing malformed fields"
    ],
    "ownedByCaller": [
     "Reconciliation of drifted managed bytes before relocking"

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

@@ -1460,10 +1460,11 @@
   },
   {
    "id": "foundation.kit.relock",
-   "intent": "运行受控 relock 事务：将新手写文件登记进 .foundation/file-registry.json，并以当前字节重算 skill-family.managed-file-lock.json，单次 fail-closed 操作",
+   "intent": "运行受控 relock 事务：默认登记新增手写文件；显式选择 trackedToolLocks 时登记持久工具锁路径，并在原事务中同步 registry 与受管文件锁。工具锁内容不纳入受管摘要。",
    "useWhen": [
     "需要把新手写文件纳入闭域而不手改 registry",
-    "需要在登记后以当前字节重算受管文件锁"
+    "需要在登记后以当前字节重算受管文件锁",
+    "需要将原工具生成的持久锁显式登记到既有 trackedToolLocks 类别，且不锁定其内容"
    ],
    "doNotUseWhen": [
     "需要合法化已漂移的受管字节（relock 拒绝漂移）",
@@ -1471,7 +1472,8 @@
    ],
    "prerequisites": [],
    "inputs": [
-    "携带 .foundation/file-registry.json 与 skill-family.managed-file-lock.json 的项目根"
+    "携带 .foundation/file-registry.json 与 skill-family.managed-file-lock.json 的项目根",
+    "registrationClass 默认为 handwritten；仅可选 handwritten 或 trackedToolLocks，CLI 对应 --registration-class。trackedToolLocks 必须传非空 files 显式清单（CLI --files 为逗号分隔路径）"
    ],
    "outputs": [
     "relock 报告（kind skill-family.relock-report）"
@@ -1480,12 +1482,13 @@
     "只写两个受收容状态文档：registry 与受管文件锁"
    ],
    "failureSemantics": [
-    "每次拒绝都零写入，目标不被触碰",
+    "写入前的参数、路径、登记与漂移检查拒绝时零写入",
     "半更新状态绝不呈现为成功"
    ],
    "invariants": [
     "不新增第五个顶层命令，落在 check relock 子动作",
-    "新锁先绑定新 registry 字节，再提交任一文档"
+    "新锁先绑定新 registry 字节，再提交任一文档",
+    "trackedToolLocks 缺省时在同一事务初始化 entries 数组；已有类别不是对象或 entries 不是数组时拒绝，不替换异常字段"
    ],
    "ownedByCaller": [
     "relock 前对已漂移受管字节的对账"

package/docs/agents/capability-catalog.en.json

@@ -1461,10 +1461,11 @@
   },
   {
    "id": "foundation.kit.relock",
-   "intent": "Run the controlled relock transaction: register newly handwritten files into .foundation/file-registry.json and recompute skill-family.managed-file-lock.json from the current bytes in one fail-closed operation.",
+   "intent": "Run the controlled relock transaction: register new handwritten files by default, or persistent tool-lock paths with explicit trackedToolLocks selection; update the registry and managed-file lock in the existing transaction without hashing tool-lock contents.",
    "useWhen": [
     "Need to admit a newly handwritten file into the closed world without hand-editing the registry",
-    "Need to recompute the managed-file lock from current bytes after registration"
+    "Need to recompute the managed-file lock from current bytes after registration",
+    "Explicitly register provider-generated persistent lock paths in the existing trackedToolLocks category without locking their contents"
    ],
    "doNotUseWhen": [
     "Need to legitimize drifted managed bytes (relock refuses drift)",
@@ -1472,7 +1473,8 @@
    ],
    "prerequisites": [],
    "inputs": [
-    "Project root carrying .foundation/file-registry.json and skill-family.managed-file-lock.json"
+    "Project root carrying .foundation/file-registry.json and skill-family.managed-file-lock.json",
+    "registrationClass defaults to handwritten and accepts only handwritten or trackedToolLocks; CLI: --registration-class. trackedToolLocks requires an explicit non-empty files array (CLI --files: comma-separated paths)"
    ],
    "outputs": [
     "Relock report (kind skill-family.relock-report)"
@@ -1481,12 +1483,13 @@
     "Writes exactly two contained state documents: the registry and the managed-file lock"
    ],
    "failureSemantics": [
-    "Every refusal leaves the target untouched (zero writes)",
+    "Pre-write parameter, path, registration and drift validation refusals leave the target unchanged",
     "A half-updated state is never presented as success"
    ],
    "invariants": [
     "Adds no fifth top-level command; it runs as the check relock sub-action",
-    "The new lock binds the new registry bytes before either document is committed"
+    "The new lock binds the new registry bytes before either document is committed",
+    "Initialize entries within the same transaction when trackedToolLocks is absent; reject an existing non-object category or non-array entries without replacing malformed fields"
    ],
    "ownedByCaller": [
     "Reconciliation of drifted managed bytes before relocking"

package/docs/agents/capability-catalog.zh-CN.json

@@ -1460,10 +1460,11 @@
   },
   {
    "id": "foundation.kit.relock",
-   "intent": "运行受控 relock 事务：将新手写文件登记进 .foundation/file-registry.json，并以当前字节重算 skill-family.managed-file-lock.json，单次 fail-closed 操作",
+   "intent": "运行受控 relock 事务：默认登记新增手写文件；显式选择 trackedToolLocks 时登记持久工具锁路径，并在原事务中同步 registry 与受管文件锁。工具锁内容不纳入受管摘要。",
    "useWhen": [
     "需要把新手写文件纳入闭域而不手改 registry",
-    "需要在登记后以当前字节重算受管文件锁"
+    "需要在登记后以当前字节重算受管文件锁",
+    "需要将原工具生成的持久锁显式登记到既有 trackedToolLocks 类别，且不锁定其内容"
    ],
    "doNotUseWhen": [
     "需要合法化已漂移的受管字节（relock 拒绝漂移）",
@@ -1471,7 +1472,8 @@
    ],
    "prerequisites": [],
    "inputs": [
-    "携带 .foundation/file-registry.json 与 skill-family.managed-file-lock.json 的项目根"
+    "携带 .foundation/file-registry.json 与 skill-family.managed-file-lock.json 的项目根",
+    "registrationClass 默认为 handwritten；仅可选 handwritten 或 trackedToolLocks，CLI 对应 --registration-class。trackedToolLocks 必须传非空 files 显式清单（CLI --files 为逗号分隔路径）"
    ],
    "outputs": [
     "relock 报告（kind skill-family.relock-report）"
@@ -1480,12 +1482,13 @@
     "只写两个受收容状态文档：registry 与受管文件锁"
    ],
    "failureSemantics": [
-    "每次拒绝都零写入，目标不被触碰",
+    "写入前的参数、路径、登记与漂移检查拒绝时零写入",
     "半更新状态绝不呈现为成功"
    ],
    "invariants": [
     "不新增第五个顶层命令，落在 check relock 子动作",
-    "新锁先绑定新 registry 字节，再提交任一文档"
+    "新锁先绑定新 registry 字节，再提交任一文档",
+    "trackedToolLocks 缺省时在同一事务初始化 entries 数组；已有类别不是对象或 entries 不是数组时拒绝，不替换异常字段"
    ],
    "ownedByCaller": [
     "relock 前对已漂移受管字节的对账"

package/docs/architecture/index.html

@@ -2155,6 +2155,9 @@ operation。后续晋升 stable 只提高兼容承诺，不再触发消费者源
 版本来源及镜像；入口分支只静态读取声明的普通文件，均不运行目标脚本、Skill、hook 或模型。
 纯读取 API 与缺省命令不写文件。只有 <code>runCommand("check")</code> 与 <code>checkEntriesAction</code> 在调用方同时
 给出已存在输出根和根内相对路径时，才独占创建一份公共结论；不自动建目录，也不覆盖现有文件。</p>
+<p>本地 0.24.0 候选对公开 <code>runCoreCheck</code> 作一项窄行为修复：目标真实声明 <code>engineering.releaseUnits</code> 时，版本类复用已有声明式版本读取逻辑，依据 <code>versionSource</code> 与 <code>versionMirrors</code> 检查文本或 JSON 格式的版本信息；私有工程的 <code>package.json</code> 不自动成为该业务单元的版本源或镜像，仅当被显式声明时方可参与版本认定。对于真正未声明版本、或仅包含合法 <code>entries</code> 的目标，仍沿用原有 legacy 版本检查路径。非法或重复的声明不回退为通过；声明的版本源或镜像缺失、不可读时如实失败。</p>
+<p>核心调度机制保持不变，共用原九类循环与报告流程，保留 Contracts 规格版本一致性检查及其他八类校验。声明的来源、镜像及各祖先路径均需先通过原树枚举与 <code>lstat</code> 安全预检，包括原不展开的工具目录；仅探查声明所涉路径，不引入新的目录遍历器。符号链接、FIFO 及其他不安全读集仍按原规则拒绝访问，禁止穿过根内符号链接目录；<code>completed</code>、<code>mechanism</code> 与 0/1/2 退出码如实传播。</p>
+<p>本次变更仅限于公开 core 在已声明版本目标上的适用性调整：公共 <code>runChecks</code> 缺省行为仍等同于显式 <code>policy: "legacy"</code>，涵盖原版本发现及 <code>full</code>/<code>only</code> 等价逻辑；显式 <code>policy: "declared"</code> 仍仅允许 <code>only: "version"</code>，维持原报告形式、不执行目标代码、不调用 Git 的边界。未新增任何公共 policy 值、API、CLI 参数、Schema 定义或包根导出，亦不在目标生成 shim 中复制检查逻辑。候选实现与局部验证不构成正式发布、业务资格或整体初始化完成的证明。</p>
 <p>这组源码不是已发布 <code>0.21.0</code> 的组成部分。已发布 <code>0.21.0</code> 仍对应 Contracts <code>1.18.0</code> 与 46 类
 对象；新协议的发布、跨方正式采用，以及跨操作类别的权限交集均不在本地实现完成结论内。</p>
 <h2 id="下一阶段能力线架构-hand-off">下一阶段能力线（架构 hand-off）<a class="headerlink" href="#下一阶段能力线架构-hand-off" title="Permanent link">&para;</a></h2>