skill-family-engineering-kit 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.27.0 locale=en baseline=sha256:788200e7009ed97f33b3b4d407854f84ca89240b9a9ee02043413898ba95a66c -->
+## [0.27.0] - 2026-10-21
+
+Engineering Kit 0.27.0 adds the public function `runRegisterExisting` and the CLI sub-action `skill-family-kit check register-existing` under the existing `check` command. The four top-level commands remain `scaffold`, `adopt-plan`, `projection`, and `check`. The sub-action is the only legal first write of `.foundation/file-registry.json`, `skill-family.project-manifest.json`, and `skill-family.managed-file-lock.json` into a nonempty root that already has a valid `profile.json`. Relock never seeds. Scaffold still refuses nonempty directories. Adopt-plan remains read-only. Projection still requires an existing legal registry.
+
+### Changed
+
+- Add the public function `runRegisterExisting` and the CLI `skill-family-kit check register-existing`. The API `root` must be an absolute project working directory; the CLI resolves the current directory or a relative path to an absolute path first. `--handwritten` is required and non-empty.
+- Missing all three closed-world documents yields exclusive create. All three present and byte-identical yields idempotent success with zero write. Any other combination, class overlap, or drifted bytes refuses with zero overwrite.
+- Relock still never seeds a missing registry. Scaffold still refuses nonempty directories. Adopt-plan remains strictly read-only. Projection and later relock still require an existing legal registry.
+- The package moves to 0.27.0 with the other three units. Contracts specification remains 1.20.0. Published 0.26.0 capabilities are unchanged and are not redone.
+
+### Upgrade Notes
+
+Pin the three Foundation npm packages to exactly 0.27.0 and keep the independent Plugin at that release version. Contracts specification 1.20.0 remains a separate coordinate from npm package versions. Consume the actual published version's public interfaces and sources. First nonempty registration does not prove business qualification or completed initialization. This note does not replace post-publish verification.
+<!-- release-skill:changelog:end version=0.27.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.26.0 locale=en baseline=sha256:f92651ad31301672d84ced913199520f2f7868c15881a51766064a9a2b11922c -->
 ## [0.26.0] - 2026-10-17
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,23 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.27.0 locale=zh-CN baseline=sha256:1a04833defa7c8007013debe70f397bb051a7cfc4d22a1eac0a11cfe0fe4fe63 -->
+## [0.27.0] - 2026-10-21
+
+Engineering Kit 0.27.0 在既有 `check` 下新增公共函数 `runRegisterExisting` 与 CLI 子动作 `skill-family-kit check register-existing`。四个顶层命令仍为 `scaffold`、`adopt-plan`、`projection`、`check`。该子动作是已有有效 `profile.json` 的非空根首次写入 `.foundation/file-registry.json`、`skill-family.project-manifest.json`、`skill-family.managed-file-lock.json` 的唯一合法入口。`relock` 不为缺锁工程播种。`scaffold` 仍拒绝非空目录。`adopt-plan` 仍只读。`projection` 仍要求已有合法登记。
+
+### 变更
+
+- 新增公共函数 `runRegisterExisting` 与 CLI `skill-family-kit check register-existing`。API 的 `root` 必须是绝对项目工作目录；CLI 会把当前目录或相对路径先解析成绝对路径。`--handwritten` 必填且非空。
+- 三份闭域文件均不存在时排他创建；三份均在且字节一致时幂等成功且零写入；任一其他组合、分类重叠或字节漂移均拒绝且零覆盖。
+- `relock` 仍不为缺锁工程播种。`scaffold` 仍拒绝非空目录。`adopt-plan` 仍严格只读。`projection` 与后续 `relock` 仍要求已有合法登记。
+- 包版本与其他三单元锁步到 0.27.0。Contracts 规格仍为 1.20.0。已发布的 0.26.0 能力保持原样，本版本不重做。
+
+### 升级说明
+
+三个 Foundation npm 包须精确锁定 0.27.0，独立插件与三包保持相同发布版本。Contracts 规格仍为 1.20.0，与 npm 包版本分别处理。消费以实际发布版本的公开接口和源码为准。首次非空登记不证明业务资格或初始化完成。本说明不替代发布后验证。
+<!-- release-skill:changelog:end version=0.27.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.26.0 locale=zh-CN baseline=sha256:3437859b22ecdad6bc0766dccf3d8b3ed7f1eb9240a9b898f1a2628a092f7143 -->
 ## [0.26.0] - 2026-10-17
 

package/README.md

@@ -4,29 +4,25 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.26.0 -->
+<!-- release-skill:release-version: 0.27.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.26.0** (2026-10-17)
+**0.27.0** (2026-10-21)
 
-Version 0.26.0 extends shared read-only static loading checks to seven hosts through the existing runHostLoadingCheck function and skill-family-kit check host-loading CLI action. The four top-level commands scaffold, adopt-plan, projection, and check remain unchanged; no new top-level command or public API is added. Checks do not start hosts, models, hooks, or scripts, access the network, or write files.
+Engineering Kit 0.27.0 adds the public function `runRegisterExisting` and the CLI sub-action `skill-family-kit check register-existing` under the existing `check` command. The four top-level commands remain `scaffold`, `adopt-plan`, `projection`, and `check`. The sub-action is the only legal first write of `.foundation/file-registry.json`, `skill-family.project-manifest.json`, and `skill-family.managed-file-lock.json` into a nonempty root that already has a valid `profile.json`. Relock never seeds. Scaffold still refuses nonempty directories. Adopt-plan remains read-only. Projection still requires an existing legal registry.
 
 **Changed**
 
-- Add shared static loading checks for seven hosts. The exact host versions, categories, and project directories are listed in the authoritative [NATIVE_HOSTS table](src/host-loading-native.mjs); this internal table is not a package-root public export.
-- Retain Codex CLI 0.154.0 project .agents/skills support and its existing activationRules mechanism.
-- Apply each host’s own discovery, parsing, ignore, name-competition, and local-file flag rules. Report Cursor menu, completion, and model metadata separately.
-- Only modelMetadata.* for Cursor CLI 2026.09.10-fd3934a may use source-reviewed-unexecuted, labeled “源码核实、未作原生运行校准” (source reviewed; not calibrated through native execution). This is not native runtime calibration and does not mean the check starts the host.
-- Other native-observed markers mean the check uses previously calibrated native rules; they do not mean this check starts the host.
-- The API project root must be an absolute working directory; the CLI resolves relative input to an absolute path first. A missing or unbindable project root returns 2. A missing, non-directory, or empty skill container within an existing project returns 1. Proven local loading blockers return 1; specific uncovered behavior or unknown competition returns 2 and takes precedence over 1. A fully covered static scope without blockers returns 0; normal skills cannot mask blockers or uncovered behavior. Only Codex supports activationRules; the seven other hosts accept only omission or null, and any other value, including an empty array, returns 2.
-- Retain link-containment and read boundaries. Uncalibrated actual competition, uncalibrated WorkBuddy optional metadata or version-source forms and icon resolution, Cursor completion string false, and CodeBuddy block scalars without proven equivalence remain specifically uncovered. Do not guess success or return 2 permanently for all ordinary input.
-- Exit 0 proves only static-check success. It does not prove final activation, installation, update, session selection, real triggering, or business execution. Codex evidence cannot establish calibration for other hosts.
+- Add the public function `runRegisterExisting` and the CLI `skill-family-kit check register-existing`. The API `root` must be an absolute project working directory; the CLI resolves the current directory or a relative path to an absolute path first. `--handwritten` is required and non-empty.
+- Missing all three closed-world documents yields exclusive create. All three present and byte-identical yields idempotent success with zero write. Any other combination, class overlap, or drifted bytes refuses with zero overwrite.
+- Relock still never seeds a missing registry. Scaffold still refuses nonempty directories. Adopt-plan remains strictly read-only. Projection and later relock still require an existing legal registry.
+- The package moves to 0.27.0 with the other three units. Contracts specification remains 1.20.0. Published 0.26.0 capabilities are unchanged and are not redone.
 
 **Upgrade Notes**
 
-Pin skill-family-engineering-kit, skill-family-contracts, skill-family-harness-node, and the independent Plugin to exactly 0.26.0 in lockstep. Contracts specification 1.20.0 remains separate from package versions and does not advance with Kit. Consume actual published public interfaces for the exact host version and category. Release notes do not replace post-publish verification or formal consumer acceptance. Exit 0 is not an upgrade-safety guarantee or evidence of production validation.
+Pin the three Foundation npm packages to exactly 0.27.0 and keep the independent Plugin at that release version. Contracts specification 1.20.0 remains a separate coordinate from npm package versions. Consume the actual published version's public interfaces and sources. First nonempty registration does not prove business qualification or completed initialization. This note does not replace post-publish verification.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Governance Check (0.22.0)
@@ -69,7 +65,7 @@ Kit is the "engineering stage" layer, depending on the Harness and Contracts. It
 
 ## Installation and Minimal Example
 
-This package version is 0.26.0; version 0.24.1 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:
+This package version is 0.27.0; version 0.24.1 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)"
@@ -77,21 +73,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.26.0.tgz" "$pack_dir/skill-family-harness-node-0.26.0.tgz" "$pack_dir/skill-family-engineering-kit-0.26.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.27.0.tgz" "$pack_dir/skill-family-harness-node-0.27.0.tgz" "$pack_dir/skill-family-engineering-kit-0.27.0.tgz")
 ```
 
-The registry installation below requires exact version 0.26.0 to be formally available:
+The registry installation below requires exact version 0.27.0 to be formally available:
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.26.0
-npm exec --package=skill-family-engineering-kit@0.26.0 -- skill-family-kit --help
-npm exec --package=skill-family-engineering-kit@0.26.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
-npm exec --package=skill-family-engineering-kit@0.26.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.26.0 -- skill-family-kit projection --root <repo>
-npm exec --package=skill-family-engineering-kit@0.26.0 -- skill-family-kit check --root <repo>
+npm install --save-dev skill-family-engineering-kit@0.27.0
+npm exec --package=skill-family-engineering-kit@0.27.0 -- skill-family-kit --help
+npm exec --package=skill-family-engineering-kit@0.27.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
+npm exec --package=skill-family-engineering-kit@0.27.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.27.0 -- skill-family-kit projection --root <repo>
+npm exec --package=skill-family-engineering-kit@0.27.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.26.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.27.0 -- skill-family-kit --help`.
 
 ### Engineering declarations (available since 0.24.0)
 

package/README.zh-CN.md

@@ -5,29 +5,25 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.26.0 -->
+<!-- release-skill:release-version: 0.27.0 -->
 
 开发与 CI 阶段使用的工程工具包。**恰好四个**顶层命令，没有第五个：
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.26.0** (2026-10-17)
+**0.27.0** (2026-10-21)
 
-0.26.0 版本通过既有公共函数 `runHostLoadingCheck` 与 CLI 子动作 `skill-family-kit check host-loading`，扩展对七宿主的共享只读静态加载检查能力。四顶层命令 `scaffold`、`adopt-plan`、`projection`、`check` 保持不变，未新增顶层命令或公共 API。检查不启动宿主、模型、hook 或脚本，不联网、不写文件。
+Engineering Kit 0.27.0 在既有 `check` 下新增公共函数 `runRegisterExisting` 与 CLI 子动作 `skill-family-kit check register-existing`。四个顶层命令仍为 `scaffold`、`adopt-plan`、`projection`、`check`。该子动作是已有有效 `profile.json` 的非空根首次写入 `.foundation/file-registry.json`、`skill-family.project-manifest.json`、`skill-family.managed-file-lock.json` 的唯一合法入口。`relock` 不为缺锁工程播种。`scaffold` 仍拒绝非空目录。`adopt-plan` 仍只读。`projection` 仍要求已有合法登记。
 
 **变更**
 
-- 新增七宿主共享静态加载检查；精确宿主版本、类别与项目目录见权威 [NATIVE_HOSTS 表](src/host-loading-native.mjs)。该内部表不是包根公共导出。
-- **兼容性保留**：Codex CLI 0.154.0 的 `.agents/skills` 项目结构继续支持，其 `activationRules` 机制保持可用。
-- **检查逻辑**：各宿主独立执行发现、解析、忽略、名称竞争与局部文件标志判断。Cursor 的菜单、补全与模型元数据三类行为分别报告。
-- **证据例外**：仅当 `modelMetadata.*` 字段来自 Cursor CLI 2026.09.10-fd3934a 版本时，允许标注 `source-reviewed-unexecuted`，文字为“源码核实、未作原生运行校准”。该标记不表示原生运行已校准，也不代表本次检查启动宿主。
-- **标记语义**：其余 `native-observed` 标记仅表示采用已有原生校准规则，不表示本次检查启动宿主。
-- **边界与退出码**： 项目 root 必须为绝对工作目录，CLI 先将相对输入解析为绝对路径。 项目根不存在或不可绑定 → 退出码 2。 项目存在但技能容器缺失、非目录或为空 → 退出码 1。 已证明本地加载阻断 → 退出码 1。 具体未覆盖或未知竞争 → 退出码 2，且优先于 1。 普通完整静态范围无阻断 → 退出码 0；已有正常技能不能掩盖阻断或未覆盖。 Codex 支持原有 `activationRules`；其余七宿主仅接受省略或 `null`，其他值（包括空数组）返回 2。
-- **数据边界**：保留链接收容与读取边界。未校准的实际竞争、WorkBuddy 尚未校准的可选元信息或版本来源形态及图标解析、Cursor 补全字符串 `false`、CodeBuddy 未证明等价的块标量等，均按具体未覆盖处理，不猜测成功，也不将所有普通输入永久返回 2。
-- **静态通过不等于业务成功**：退出码 0 仅表示静态检查通过，不证明最终启用、安装、更新、会话选择、真实触发或业务执行成功。不得复用 Codex 证据宣称其他宿主已校准。
+- 新增公共函数 `runRegisterExisting` 与 CLI `skill-family-kit check register-existing`。API 的 `root` 必须是绝对项目工作目录；CLI 会把当前目录或相对路径先解析成绝对路径。`--handwritten` 必填且非空。
+- 三份闭域文件均不存在时排他创建；三份均在且字节一致时幂等成功且零写入；任一其他组合、分类重叠或字节漂移均拒绝且零覆盖。
+- `relock` 仍不为缺锁工程播种。`scaffold` 仍拒绝非空目录。`adopt-plan` 仍严格只读。`projection` 与后续 `relock` 仍要求已有合法登记。
+- 包版本与其他三单元锁步到 0.27.0。Contracts 规格仍为 1.20.0。已发布的 0.26.0 能力保持原样，本版本不重做。
 
 **升级说明**
 
-三个 Foundation npm 包（`skill-family-engineering-kit`、`skill-family-contracts`、`skill-family-harness-node`）及独立 Plugin 均需精确锁定至 0.26.0 版本，实现四单元锁步。 Contracts 规格保持 1.20.0，与包版本为独立坐标，不随 Kit 升级。 消费方应按精确宿主版本与类别，使用实际已发布的公共接口。 发布说明不替代发布后验证或正式消费者验收。 退出码 0 不构成升级安全保证，不等同于可安全升级或已通过生产验证。
+三个 Foundation npm 包须精确锁定 0.27.0，独立插件与三包保持相同发布版本。Contracts 规格仍为 1.20.0，与 npm 包版本分别处理。消费以实际发布版本的公开接口和源码为准。首次非空登记不证明业务资格或初始化完成。本说明不替代发布后验证。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 治理检查（0.22.0）
@@ -68,7 +64,7 @@ Kit 是「工程阶段」层，依赖 Harness 与 Contracts。它只做四件事
 
 ## 安装和最小示例
 
-本包版本为 0.26.0；0.24.1 已正式发布。验证尚未正式发布的工作树时，先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
+本包版本为 0.27.0；0.24.1 已正式发布。验证尚未正式发布的工作树时，先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -76,21 +72,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.26.0.tgz" "$pack_dir/skill-family-harness-node-0.26.0.tgz" "$pack_dir/skill-family-engineering-kit-0.26.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.27.0.tgz" "$pack_dir/skill-family-harness-node-0.27.0.tgz" "$pack_dir/skill-family-engineering-kit-0.27.0.tgz")
 ```
 
-以下 registry 安装方式以精确版本 0.26.0 已正式可用为前提：
+以下 registry 安装方式以精确版本 0.27.0 已正式可用为前提：
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.26.0
-npm exec --package=skill-family-engineering-kit@0.26.0 -- skill-family-kit --help
-npm exec --package=skill-family-engineering-kit@0.26.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
-npm exec --package=skill-family-engineering-kit@0.26.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.26.0 -- skill-family-kit projection --root <repo>
-npm exec --package=skill-family-engineering-kit@0.26.0 -- skill-family-kit check --root <repo>
+npm install --save-dev skill-family-engineering-kit@0.27.0
+npm exec --package=skill-family-engineering-kit@0.27.0 -- skill-family-kit --help
+npm exec --package=skill-family-engineering-kit@0.27.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
+npm exec --package=skill-family-engineering-kit@0.27.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.27.0 -- skill-family-kit projection --root <repo>
+npm exec --package=skill-family-engineering-kit@0.27.0 -- skill-family-kit check --root <repo>
 ```
 
-以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.26.0 -- skill-family-kit --help`。
+以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.27.0 -- skill-family-kit --help`。
 
 ### 工程声明调用（自 0.24.0 提供）
 

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

@@ -1507,6 +1507,57 @@
     "Foundation entry contract: check entries"
    ]
   },
+  {
+   "id": "foundation.kit.register-existing",
+   "intent": "Seed the three official closed-world documents for a nonempty project that already has a valid profile.json and does not yet have a legal registry",
+   "useWhen": [
+    "Need the only legal first write of .foundation/file-registry.json, skill-family.project-manifest.json, and skill-family.managed-file-lock.json into a nonempty root",
+    "Need an official first-nonempty registration that is exclusive-create, idempotent on identical bytes, and refuse-with-zero-overwrite otherwise"
+   ],
+   "doNotUseWhen": [
+    "The target is empty (use scaffold)",
+    "The three official documents already exist and a later handwritten file must be admitted (use check relock)",
+    "Need a read-only inventory of an existing project (use adopt-plan)",
+    "Need to overwrite drifted closed-world bytes"
+   ],
+   "prerequisites": [
+    "Caller supplies an absolute project working directory",
+    "profile.json exists at the target root and is contract-valid, including profile.adoption.foundation_profile.id",
+    "handwritten classification list is non-empty"
+   ],
+   "inputs": [
+    "Absolute project working directory root",
+    "Non-empty handwritten globs or relative paths",
+    "Optional engineering JSON, trackedToolLocks paths, and gitignore-style artifacts patterns"
+   ],
+   "outputs": [
+    "register-existing report (kind skill-family.register-existing-report)",
+    "On first create: exclusive publication of the three closed-world documents; on identical bytes: idempotent success with zero write; otherwise refuse with zero overwrite"
+   ],
+   "sideEffects": [
+    "Writes at most the three closed-world documents; never overwrites mismatched existing bytes; does not scaffold, apply adopt-plan, or seed via relock"
+   ],
+   "failureSemantics": [
+    "Missing or invalid profile.json refuses",
+    "Empty handwritten list refuses",
+    "Class overlap among handwritten, artifacts, and trackedToolLocks refuses",
+    "Any incomplete or drifted combination of the three documents refuses with zero overwrite"
+   ],
+   "invariants": [
+    "Adds no fifth top-level command; it runs as the check register-existing sub-action",
+    "Relock never seeds; this sub-action is the only legal first write of the three documents into a nonempty root",
+    "Scaffold still refuses nonempty directories; adopt-plan remains read-only"
+   ],
+   "ownedByCaller": [
+    "Choosing handwritten, artifacts, and trackedToolLocks classifications",
+    "Remediation after a refuse-with-zero-overwrite result"
+   ],
+   "routeElsewhere": [
+    "Empty target: scaffold",
+    "Existing legal registry plus new handwritten files: check relock",
+    "Read-only nonempty inventory: adopt-plan"
+   ]
+  },
   {
    "id": "foundation.kit.relock",
    "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.",

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

@@ -996,6 +996,32 @@
     "packages/skill-family-engineering-kit/test/cli.test.mjs"
    ]
   },
+  {
+   "id": "foundation.kit.register-existing",
+   "package": "skill-family-engineering-kit",
+   "layer": "engineering-kit",
+   "since": "0.27.0",
+   "stability": "candidate",
+   "migration": "none",
+   "promotionPolicy": "consumer-transparent",
+   "adoptionScopes": ["engineering-kit"],
+   "entrypoints": [
+    "runRegisterExisting (packages/skill-family-engineering-kit/src/register-existing.mjs)",
+    "registerExistingAction (packages/skill-family-engineering-kit/src/register-existing.mjs)",
+    "REGISTER_EXISTING_REPORT_KIND (packages/skill-family-engineering-kit/src/register-existing.mjs)"
+   ],
+   "sourceRefs": [
+    "packages/skill-family-engineering-kit/src/register-existing.mjs",
+    "packages/skill-family-engineering-kit/src/cli.mjs",
+    "packages/skill-family-engineering-kit/src/index.mjs"
+   ],
+   "positiveTestRefs": [
+    "packages/skill-family-engineering-kit/test/register-existing.test.mjs"
+   ],
+   "negativeTestRefs": [
+    "packages/skill-family-engineering-kit/test/register-existing.test.mjs"
+   ]
+  },
   {
    "id": "foundation.kit.relock",
    "package": "skill-family-engineering-kit",

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

@@ -1506,6 +1506,57 @@
     "Foundation 入口契约：check entries"
    ]
   },
+  {
+   "id": "foundation.kit.register-existing",
+   "intent": "为已有有效 profile.json、尚未具备合法登记的非空工程，播种三份官方闭域文件",
+   "useWhen": [
+    "需要把 .foundation/file-registry.json、skill-family.project-manifest.json、skill-family.managed-file-lock.json 合法地首次写入非空根",
+    "需要官方首次非空登记：三份皆无则排他创建，字节一致则幂等零写入，其余情况拒绝且零覆盖"
+   ],
+   "doNotUseWhen": [
+    "目标为空（走 scaffold）",
+    "三份官方文件已存在、只需纳入后来的手写文件（走 check relock）",
+    "只需只读盘点既有工程（走 adopt-plan）",
+    "需要覆盖已漂移的闭域字节"
+   ],
+   "prerequisites": [
+    "调用方给出绝对项目工作目录",
+    "目标根已有合同有效的 profile.json，且含 profile.adoption.foundation_profile.id",
+    "手写分类清单非空"
+   ],
+   "inputs": [
+    "绝对项目工作目录 root",
+    "非空手写 glob 或相对路径",
+    "可选 engineering JSON、trackedToolLocks 路径，以及 gitignore 风格的 artifacts 模式"
+   ],
+   "outputs": [
+    "register-existing 报告（kind skill-family.register-existing-report）",
+    "首次创建时排他写入三份闭域文件；字节一致时幂等成功且零写入；否则拒绝且零覆盖"
+   ],
+   "sideEffects": [
+    "最多写入三份闭域文件；从不覆盖不匹配的既有字节；不 scaffold、不 apply adopt-plan、不经 relock 播种"
+   ],
+   "failureSemantics": [
+    "缺少或无效的 profile.json 拒绝",
+    "空手写清单拒绝",
+    "handwritten、artifacts、trackedToolLocks 分类重叠拒绝",
+    "三份文件任一不完整或字节漂移时拒绝且零覆盖"
+   ],
+   "invariants": [
+    "不新增第五个顶层命令，落在 check register-existing 子动作",
+    "relock 不为缺锁工程播种；本子动作是非空根首次写入三份文件的唯一合法入口",
+    "scaffold 仍拒绝非空目录；adopt-plan 仍只读"
+   ],
+   "ownedByCaller": [
+    "选择 handwritten、artifacts、trackedToolLocks 分类",
+    "拒绝且零覆盖之后的整改"
+   ],
+   "routeElsewhere": [
+    "空目标：scaffold",
+    "已有合法登记且需纳入新手写文件：check relock",
+    "非空只读盘点：adopt-plan"
+   ]
+  },
   {
    "id": "foundation.kit.relock",
    "intent": "运行受控 relock 事务：默认登记新增手写文件；显式选择 trackedToolLocks 时登记持久工具锁路径，并在原事务中同步 registry 与受管文件锁。工具锁内容不纳入受管摘要。",

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

@@ -1507,6 +1507,57 @@
     "Foundation entry contract: check entries"
    ]
   },
+  {
+   "id": "foundation.kit.register-existing",
+   "intent": "Seed the three official closed-world documents for a nonempty project that already has a valid profile.json and does not yet have a legal registry",
+   "useWhen": [
+    "Need the only legal first write of .foundation/file-registry.json, skill-family.project-manifest.json, and skill-family.managed-file-lock.json into a nonempty root",
+    "Need an official first-nonempty registration that is exclusive-create, idempotent on identical bytes, and refuse-with-zero-overwrite otherwise"
+   ],
+   "doNotUseWhen": [
+    "The target is empty (use scaffold)",
+    "The three official documents already exist and a later handwritten file must be admitted (use check relock)",
+    "Need a read-only inventory of an existing project (use adopt-plan)",
+    "Need to overwrite drifted closed-world bytes"
+   ],
+   "prerequisites": [
+    "Caller supplies an absolute project working directory",
+    "profile.json exists at the target root and is contract-valid, including profile.adoption.foundation_profile.id",
+    "handwritten classification list is non-empty"
+   ],
+   "inputs": [
+    "Absolute project working directory root",
+    "Non-empty handwritten globs or relative paths",
+    "Optional engineering JSON, trackedToolLocks paths, and gitignore-style artifacts patterns"
+   ],
+   "outputs": [
+    "register-existing report (kind skill-family.register-existing-report)",
+    "On first create: exclusive publication of the three closed-world documents; on identical bytes: idempotent success with zero write; otherwise refuse with zero overwrite"
+   ],
+   "sideEffects": [
+    "Writes at most the three closed-world documents; never overwrites mismatched existing bytes; does not scaffold, apply adopt-plan, or seed via relock"
+   ],
+   "failureSemantics": [
+    "Missing or invalid profile.json refuses",
+    "Empty handwritten list refuses",
+    "Class overlap among handwritten, artifacts, and trackedToolLocks refuses",
+    "Any incomplete or drifted combination of the three documents refuses with zero overwrite"
+   ],
+   "invariants": [
+    "Adds no fifth top-level command; it runs as the check register-existing sub-action",
+    "Relock never seeds; this sub-action is the only legal first write of the three documents into a nonempty root",
+    "Scaffold still refuses nonempty directories; adopt-plan remains read-only"
+   ],
+   "ownedByCaller": [
+    "Choosing handwritten, artifacts, and trackedToolLocks classifications",
+    "Remediation after a refuse-with-zero-overwrite result"
+   ],
+   "routeElsewhere": [
+    "Empty target: scaffold",
+    "Existing legal registry plus new handwritten files: check relock",
+    "Read-only nonempty inventory: adopt-plan"
+   ]
+  },
   {
    "id": "foundation.kit.relock",
    "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.",

package/docs/agents/capability-catalog.json

@@ -996,6 +996,32 @@
     "packages/skill-family-engineering-kit/test/cli.test.mjs"
    ]
   },
+  {
+   "id": "foundation.kit.register-existing",
+   "package": "skill-family-engineering-kit",
+   "layer": "engineering-kit",
+   "since": "0.27.0",
+   "stability": "candidate",
+   "migration": "none",
+   "promotionPolicy": "consumer-transparent",
+   "adoptionScopes": ["engineering-kit"],
+   "entrypoints": [
+    "runRegisterExisting (packages/skill-family-engineering-kit/src/register-existing.mjs)",
+    "registerExistingAction (packages/skill-family-engineering-kit/src/register-existing.mjs)",
+    "REGISTER_EXISTING_REPORT_KIND (packages/skill-family-engineering-kit/src/register-existing.mjs)"
+   ],
+   "sourceRefs": [
+    "packages/skill-family-engineering-kit/src/register-existing.mjs",
+    "packages/skill-family-engineering-kit/src/cli.mjs",
+    "packages/skill-family-engineering-kit/src/index.mjs"
+   ],
+   "positiveTestRefs": [
+    "packages/skill-family-engineering-kit/test/register-existing.test.mjs"
+   ],
+   "negativeTestRefs": [
+    "packages/skill-family-engineering-kit/test/register-existing.test.mjs"
+   ]
+  },
   {
    "id": "foundation.kit.relock",
    "package": "skill-family-engineering-kit",

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

@@ -1506,6 +1506,57 @@
     "Foundation 入口契约：check entries"
    ]
   },
+  {
+   "id": "foundation.kit.register-existing",
+   "intent": "为已有有效 profile.json、尚未具备合法登记的非空工程，播种三份官方闭域文件",
+   "useWhen": [
+    "需要把 .foundation/file-registry.json、skill-family.project-manifest.json、skill-family.managed-file-lock.json 合法地首次写入非空根",
+    "需要官方首次非空登记：三份皆无则排他创建，字节一致则幂等零写入，其余情况拒绝且零覆盖"
+   ],
+   "doNotUseWhen": [
+    "目标为空（走 scaffold）",
+    "三份官方文件已存在、只需纳入后来的手写文件（走 check relock）",
+    "只需只读盘点既有工程（走 adopt-plan）",
+    "需要覆盖已漂移的闭域字节"
+   ],
+   "prerequisites": [
+    "调用方给出绝对项目工作目录",
+    "目标根已有合同有效的 profile.json，且含 profile.adoption.foundation_profile.id",
+    "手写分类清单非空"
+   ],
+   "inputs": [
+    "绝对项目工作目录 root",
+    "非空手写 glob 或相对路径",
+    "可选 engineering JSON、trackedToolLocks 路径，以及 gitignore 风格的 artifacts 模式"
+   ],
+   "outputs": [
+    "register-existing 报告（kind skill-family.register-existing-report）",
+    "首次创建时排他写入三份闭域文件；字节一致时幂等成功且零写入；否则拒绝且零覆盖"
+   ],
+   "sideEffects": [
+    "最多写入三份闭域文件；从不覆盖不匹配的既有字节；不 scaffold、不 apply adopt-plan、不经 relock 播种"
+   ],
+   "failureSemantics": [
+    "缺少或无效的 profile.json 拒绝",
+    "空手写清单拒绝",
+    "handwritten、artifacts、trackedToolLocks 分类重叠拒绝",
+    "三份文件任一不完整或字节漂移时拒绝且零覆盖"
+   ],
+   "invariants": [
+    "不新增第五个顶层命令，落在 check register-existing 子动作",
+    "relock 不为缺锁工程播种；本子动作是非空根首次写入三份文件的唯一合法入口",
+    "scaffold 仍拒绝非空目录；adopt-plan 仍只读"
+   ],
+   "ownedByCaller": [
+    "选择 handwritten、artifacts、trackedToolLocks 分类",
+    "拒绝且零覆盖之后的整改"
+   ],
+   "routeElsewhere": [
+    "空目标：scaffold",
+    "已有合法登记且需纳入新手写文件：check relock",
+    "非空只读盘点：adopt-plan"
+   ]
+  },
   {
    "id": "foundation.kit.relock",
    "intent": "运行受控 relock 事务：默认登记新增手写文件；显式选择 trackedToolLocks 时登记持久工具锁路径，并在原事务中同步 registry 与受管文件锁。工具锁内容不纳入受管摘要。",

package/docs/public/status/index.html

@@ -1814,24 +1814,24 @@
 <tbody>
 <tr>
 <td><code>skill-family-contracts</code></td>
-<td>0.26.0</td>
+<td>0.27.0</td>
 <td><a href="https://github.com/ifoohoo/skill-family-contracts">ifoohoo/skill-family-contracts</a></td>
 </tr>
 <tr>
 <td><code>skill-family-harness-node</code></td>
-<td>0.26.0</td>
+<td>0.27.0</td>
 <td><a href="https://github.com/ifoohoo/skill-family-harness-node">ifoohoo/skill-family-harness-node</a></td>
 </tr>
 <tr>
 <td><code>skill-family-engineering-kit</code></td>
-<td>0.26.0</td>
+<td>0.27.0</td>
 <td><a href="https://github.com/ifoohoo/skill-family-engineering-kit">ifoohoo/skill-family-engineering-kit</a></td>
 </tr>
 </tbody>
 </table>
 <h2 id="独立-Plugin">独立 Plugin<a class="headerlink" href="#独立-Plugin" title="Permanent link">&para;</a></h2>
 <ul>
-<li><code>foundation-adoption-review</code>：0.26.0，公开镜像 <a href="https://github.com/ifoohoo/foundation-adoption-review">ifoohoo/foundation-adoption-review</a></li>
+<li><code>foundation-adoption-review</code>：0.27.0，公开镜像 <a href="https://github.com/ifoohoo/foundation-adoption-review">ifoohoo/foundation-adoption-review</a></li>
 <li><code>foundation-adoption-review</code>：只读采用诊断</li>
 <li><code>foundation-engineering-check</code>：只读静态工程审阅与证明读取</li>
 <li><code>foundation-initialize</code>：在明确授权下初始化目标工程，保留业务和人工判断</li>