skill-family-engineering-kit 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.4.0 locale=en baseline=sha256:b75bcca6a62cddc63d0a8d88faf268415aec803bcf00e04aacd797907d1ea6e8 -->
+## [0.4.0] - 2026-08-16
+
+This release adds the candidate adoption CLI and adoption mechanisms to the Engineering Kit while preserving the stable four-command surface and the 0.3.0 offline bundle.
+
+### Added
+
+- Adds the adoption-cli candidate, a stdin/stdout CLI that assesses adoption bindings, legacy exit lists, and legacy references through the migration manifest, and verifies managed-bundle identity and harness surface inventory.
+- Adds the adoption-mechanisms candidate module as the shared implementation behind the adoption CLI.
+
+### Changed
+
+- Keeps the stable scaffold, adopt-plan, projection, and check commands unchanged.
+- Carries forward the 0.3.0 Quickstart Profile v2 offline bundle (standalone validators selected by schema $id, full provenance recording) and the candidate plugin skill naming checker.
+
+### Upgrade Notes
+
+Version 0.4.0 is released on npm and the public mirror. The adoption CLI is a candidate entry point; invoke it through its explicit candidate subpath and pin the package to exactly 0.4.0.
+<!-- release-skill:changelog:end version=0.4.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.3.0 locale=en baseline=sha256:4c017d6121ff888f90ad9a4ef958b4fee3e25c8d1b69be61cc1ba1f79d527163 -->
 ## [0.3.0] - 2026-08-12
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,26 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.4.0 locale=zh-CN baseline=sha256:0305934fb2f833eff10b17014f551533bfca9e9e51d3820a5a1e62613a3edb6a -->
+## [0.4.0] - 2026-08-16
+
+本版为 Engineering Kit 新增候选 adoption CLI 与 adoption mechanisms，同时保持稳定四命令边界与 0.3.0 的离线 Bundle 不变。
+
+### 新增
+
+- 新增 adoption-cli 候选：基于 stdin/stdout 的 CLI，通过 migration manifest 评估 adoption 绑定、遗留 exit list 与遗留引用，并校验 managed-bundle 身份与 harness 表面清单。
+- 新增 adoption-mechanisms 候选模块，作为 adoption CLI 的共享实现。
+
+### 变更
+
+- 稳定四命令（scaffold、adopt-plan、projection、check）保持不变。
+- 延续 0.3.0 的 Quickstart Profile v2 离线 Bundle（按 schema $id 选择的 standalone validator、完整 provenance 记录）与候选插件技能命名检查器。
+
+### 升级说明
+
+0.4.0 已发布到 npm 与 public 镜像仓。adoption CLI 是候选入口，须经显式 candidate 子路径调用，并把包精确锁定为 0.4.0。
+<!-- release-skill:changelog:end version=0.4.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.3.0 locale=zh-CN baseline=sha256:ddb48e61ef87de545348880216ee283b5d0165305dd5dfd8e044929b93ec4673 -->
 ## [0.3.0] - 2026-08-12
 

package/README.md

@@ -4,29 +4,28 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.3.0 -->
+<!-- release-skill:release-version: 0.4.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.3.0** (2026-08-12)
+**0.4.0** (2026-08-16)
 
-This source candidate builds a deterministic Quickstart Profile v2 bundle that runs offline without Foundation packages, node_modules, or runtime Ajv.
+This release adds the candidate adoption CLI and adoption mechanisms to the Engineering Kit while preserving the stable four-command surface and the 0.3.0 offline bundle.
 
 **Added**
 
-- Accepts explicit consumer schema files and source identity, then generates standalone validators selected by schema $id.
-- Records complete source and payload provenance, package-manager identity, and the licenses for third-party code that enters the bundle.
-- Adds a candidate plugin skill naming checker (policy JSON plus build-time CLI) that scans a plugin skills root and reports per-rule PASS/FAIL for the prefixed-name, description-signal, and routing-scope rules.
+- Adds the adoption-cli candidate, a stdin/stdout CLI that assesses adoption bindings, legacy exit lists, and legacy references through the migration manifest, and verifies managed-bundle identity and harness surface inventory.
+- Adds the adoption-mechanisms candidate module as the shared implementation behind the adoption CLI.
 
 **Changed**
 
-- Replaces the incompatible 0.2.1 dependency-closure bundle; consumers that still require v1 must remain pinned to exactly 0.2.1.
-- Projects the Contracts and Harness runtime mechanically while preserving the stable four-command Kit surface.
+- Keeps the stable scaffold, adopt-plan, projection, and check commands unchanged.
+- Carries forward the 0.3.0 Quickstart Profile v2 offline bundle (standalone validators selected by schema $id, full provenance recording) and the candidate plugin skill naming checker.
 
 **Upgrade Notes**
 
-Version 0.3.0 is a local, unpublished source candidate. Regenerate managed bundles from frozen inputs and pin the builder to exactly 0.3.0 when adopting v2.
+Version 0.4.0 is released on npm and the public mirror. The adoption CLI is a candidate entry point; invoke it through its explicit candidate subpath and pin the package to exactly 0.4.0.
 <!-- release-skill:managed:end id=latest-release -->
 
 | Command | Purpose | Side effects |
@@ -47,7 +46,7 @@ Kit is the "engineering stage" layer, depending on the Harness and Contracts. It
 ## Installation and Minimal Example
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.3.0
+npm install --save-dev skill-family-engineering-kit@0.4.0
 npm exec -- skill-family-kit --help
 npm exec -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
 npm exec -- skill-family-kit adopt-plan --root <repo>
@@ -55,7 +54,7 @@ npm exec -- skill-family-kit projection --root <repo>
 npm exec -- 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.3.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.4.0 -- skill-family-kit --help`.
 
 ### Report sub-action
 
@@ -79,7 +78,7 @@ import {
 
 The generated Bundle selects standalone validators by schema `$id` and runs offline without Foundation packages, `node_modules`, or runtime Ajv. Its provenance binds Foundation sources, consumer schemas, payload bytes, tool versions, and the licenses of code that actually enters the Bundle.
 
-Pass the returned `manifest` to the stable `runProjection` API; the helper does not write files or add a fifth top-level command. This subpath is public but **not stable**. Pin exactly `0.3.0` for v2; integrations that still require the v1 dependency-closure Bundle must stay pinned to exactly `0.2.1`.
+Pass the returned `manifest` to the stable `runProjection` API; the helper does not write files or add a fifth top-level command. This subpath is public but **not stable**. Pin exactly `0.4.0` for v2; integrations that still require the v1 dependency-closure Bundle must stay pinned to exactly `0.2.1`.
 
 ### Host sub-action
 

package/README.zh-CN.md

@@ -5,29 +5,28 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.3.0 -->
+<!-- release-skill:release-version: 0.4.0 -->
 
 开发与 CI 阶段使用的工程工具包。**恰好四个**顶层命令，没有第五个：
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.3.0** (2026-08-12)
+**0.4.0** (2026-08-16)
 
-本源码候选版构建确定性的 Quickstart Profile v2 Bundle，运行时不依赖 Foundation 包、node_modules 或 Ajv。
+本版为 Engineering Kit 新增候选 adoption CLI 与 adoption mechanisms，同时保持稳定四命令边界与 0.3.0 的离线 Bundle 不变。
 
 **新增**
 
-- 接收显式消费者 Schema 文件与来源身份，生成按 Schema $id 选择的 standalone validator。
-- 完整记录来源与 payload provenance、包管理器身份，以及实际进入 Bundle 的第三方代码许可证。
-- 新增候选插件技能命名检查器（policy JSON 加构建期 CLI）：扫描插件 skills 根目录，对前缀命名、description 领域信号与路由入口范围三条规则逐项输出 PASS/FAIL。
+- 新增 adoption-cli 候选：基于 stdin/stdout 的 CLI，通过 migration manifest 评估 adoption 绑定、遗留 exit list 与遗留引用，并校验 managed-bundle 身份与 harness 表面清单。
+- 新增 adoption-mechanisms 候选模块，作为 adoption CLI 的共享实现。
 
 **变更**
 
-- 替换与 0.2.1 不兼容的依赖闭包 Bundle；仍依赖 v1 的消费者必须继续精确锁定 0.2.1。
-- 机械投影 Contracts 与 Harness 运行代码，同时保持 Kit 稳定的四命令边界。
+- 稳定四命令（scaffold、adopt-plan、projection、check）保持不变。
+- 延续 0.3.0 的 Quickstart Profile v2 离线 Bundle（按 schema $id 选择的 standalone validator、完整 provenance 记录）与候选插件技能命名检查器。
 
 **升级说明**
 
-0.3.0 当前只是本地、未发布的源码候选。采用 v2 时，应从冻结输入重新生成受管 Bundle，并把 builder 精确锁定为 0.3.0。
+0.4.0 已发布到 npm 与 public 镜像仓。adoption CLI 是候选入口，须经显式 candidate 子路径调用，并把包精确锁定为 0.4.0。
 <!-- release-skill:managed:end id=latest-release -->
 
 | 命令 | 用途 | 副作用 |
@@ -48,7 +47,7 @@ Kit 是「工程阶段」层，依赖 Harness 与 Contracts。它只做四件事
 ## 安装和最小示例
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.3.0
+npm install --save-dev skill-family-engineering-kit@0.4.0
 npm exec -- skill-family-kit --help
 npm exec -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
 npm exec -- skill-family-kit adopt-plan --root <repo>
@@ -56,7 +55,7 @@ npm exec -- skill-family-kit projection --root <repo>
 npm exec -- skill-family-kit check --root <repo>
 ```
 
-以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.3.0 -- skill-family-kit --help`。
+以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.4.0 -- skill-family-kit --help`。
 
 ### 报告子动作
 
@@ -80,7 +79,7 @@ import {
 
 生成的 Bundle 按 Schema `$id` 选择 standalone validator，离线运行时不依赖 Foundation 包、`node_modules` 或 Ajv。provenance 绑定 Foundation 来源、消费者 Schema、payload 字节、工具版本，以及实际进入 Bundle 的代码许可证。
 
-以上辅助函数不写文件，也不增加第五个顶层命令。调用方需要把返回的 `manifest` 交给稳定的 `runProjection` API。该子路径公开但**不稳定**；使用 v2 时应精确锁定 `0.3.0`，仍依赖 v1 依赖闭包 Bundle 的接入必须继续精确锁定 `0.2.1`。
+以上辅助函数不写文件，也不增加第五个顶层命令。调用方需要把返回的 `manifest` 交给稳定的 `runProjection` API。该子路径公开但**不稳定**；使用 v2 时应精确锁定 `0.4.0`，仍依赖 v1 依赖闭包 Bundle 的接入必须继续精确锁定 `0.2.1`。
 
 ### 宿主子动作
 

package/candidate/adoption-cli.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { stdin, stdout, stderr } from "node:process";
+import { fileURLToPath } from "node:url";
+import {
+  invokeFoundationAdoption,
+  verifyManagedBundleIdentity,
+} from "./adoption-mechanisms.mjs";
+
+const CLI_NAME = "adoption-cli.mjs";
+
+async function readRequest(input) {
+  const chunks = [];
+  for await (const chunk of input) chunks.push(Buffer.from(chunk));
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+  return JSON.parse(text);
+}
+
+function errorResponse(cause) {
+  return {
+    ok: false,
+    error: {
+      name: typeof cause?.name === "string" ? cause.name : "Error",
+      message: cause?.message ?? String(cause),
+    },
+  };
+}
+
+/** One-request/one-response transport for the fixed adoption operation set. */
+export async function runAdoptionCli({
+  input = stdin,
+  output = stdout,
+  error = stderr,
+  invoke = invokeFoundationAdoption,
+} = {}) {
+  try {
+    const request = await readRequest(input);
+    const result = request?.operation === "self-check"
+      ? await runSelfCheck(request)
+      : await invoke(request);
+    output.write(`${JSON.stringify(result)}\n`);
+    return 0;
+  } catch (cause) {
+    error.write(`${JSON.stringify(errorResponse(cause))}\n`);
+    return 2;
+  }
+}
+
+async function runSelfCheck(request) {
+  if (
+    request === null ||
+    typeof request !== "object" ||
+    Array.isArray(request) ||
+    Object.keys(request).sort().join(",") !== "operation,params" ||
+    request.params === null ||
+    typeof request.params !== "object" ||
+    Array.isArray(request.params) ||
+    Object.keys(request.params).length !== 0
+  ) {
+    throw new TypeError("adoption CLI self-check requires exactly operation and empty params");
+  }
+  return verifyManagedBundleIdentity({ cliUrl: import.meta.url, cliName: CLI_NAME });
+}
+
+if (process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+  process.exitCode = await runAdoptionCli();
+}

package/candidate/adoption-mechanisms.mjs

@@ -0,0 +1,69 @@
+import {
+  assessAdoptionBinding,
+  assessLegacyExitList,
+  assessLegacyReferences,
+  loadMigrationManifestState,
+} from "../src/migration.mjs";
+import {
+  verifyHarnessSurfaceInventory,
+  verifyManagedBundleIdentity,
+} from "skill-family-harness-node/candidate/quickstart-profile";
+
+export { verifyManagedBundleIdentity };
+
+const ADOPTION_OPERATIONS = Object.freeze([
+  "load-migration-manifest-state",
+  "assess-adoption-binding",
+  "assess-legacy-exit-list",
+  "assess-legacy-references",
+  "verify-harness-surface-inventory",
+]);
+
+const FORBIDDEN_ROUTING_KEYS = new Set(["entry", "module", "export", "pathToFileURL"]);
+
+function assertNoRoutingKeys(value, path = "params") {
+  if (value === null || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoRoutingKeys(item, `${path}/${index}`));
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (FORBIDDEN_ROUTING_KEYS.has(key)) {
+      throw new TypeError(`invokeFoundationAdoption: caller routing key is forbidden at ${path}/${key}`);
+    }
+    assertNoRoutingKeys(child, `${path}/${key}`);
+  }
+}
+
+/** Fixed, read-only adoption bridge; callers cannot select code or exports. */
+export async function invokeFoundationAdoption(request) {
+  if (request === null || typeof request !== "object" || Array.isArray(request)) {
+    throw new TypeError("invokeFoundationAdoption: request must be an object");
+  }
+  const requestKeys = Object.keys(request).sort();
+  if (requestKeys.length !== 2 || requestKeys[0] !== "operation" || requestKeys[1] !== "params") {
+    throw new TypeError("invokeFoundationAdoption: request must contain exactly operation and params");
+  }
+  const { operation, params } = request;
+  if (!ADOPTION_OPERATIONS.includes(operation)) {
+    throw new TypeError(`invokeFoundationAdoption: unknown operation: ${String(operation)}`);
+  }
+  if (params === null || typeof params !== "object" || Array.isArray(params)) {
+    throw new TypeError("invokeFoundationAdoption: params must be an object");
+  }
+  assertNoRoutingKeys(params);
+  switch (operation) {
+    case "load-migration-manifest-state":
+      return loadMigrationManifestState(params.root);
+    case "assess-adoption-binding":
+      return assessAdoptionBinding(params.manifest, params.profileId);
+    case "assess-legacy-exit-list":
+      return assessLegacyExitList(params.root, params.legacyItems);
+    case "assess-legacy-references":
+      return assessLegacyReferences(params.root, params.legacyReferences);
+    case "verify-harness-surface-inventory":
+      return verifyHarnessSurfaceInventory(params);
+    default:
+      throw new TypeError("invokeFoundationAdoption: unreachable operation");
+  }
+}

package/candidate/index.mjs

@@ -1,4 +1,7 @@
 export {
   buildQuickstartProfileProjection,
+  buildQuickstartProfileProjectionFromInventory,
   QUICKSTART_PROFILE_TARGET_PREFIX,
 } from "./profile-bundle.mjs";
+export { invokeFoundationAdoption } from "./adoption-mechanisms.mjs";
+export { runAdoptionCli } from "./adoption-cli.mjs";