skill-family-engineering-kit 0.26.0 → 0.27.0

package/package.json

@@ -8,8 +8,8 @@
     "url": "https://github.com/ifoohoo/skill-family-engineering-kit/issues"
   },
   "dependencies": {
-    "skill-family-contracts": "0.26.0",
-    "skill-family-harness-node": "0.26.0",
+    "skill-family-contracts": "0.27.0",
+    "skill-family-harness-node": "0.27.0",
     "yaml": "2.9.0"
   },
   "description": "Build-time scaffold, adoption planning, projection, and checks.",
@@ -52,7 +52,7 @@
     "url": "https://github.com/ifoohoo/skill-family-engineering-kit.git"
   },
   "type": "module",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

package/release-notes/0.27.0.yaml

@@ -0,0 +1,21 @@
+version: 0.27.0
+date: 2026-10-21
+locales:
+  en:
+    summary: "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."
+    changes:
+      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."
+    upgradeNotes: "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."
+  zh-CN:
+    summary: "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` 仍要求已有合法登记。"
+    changes:
+      changed:
+        - "新增公共函数 `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 能力保持原样，本版本不重做。"
+    upgradeNotes: "三个 Foundation npm 包须精确锁定 0.27.0，独立插件与三包保持相同发布版本。Contracts 规格仍为 1.20.0，与 npm 包版本分别处理。消费以实际发布版本的公开接口和源码为准。首次非空登记不证明业务资格或初始化完成。本说明不替代发布后验证。"

package/src/adopt-plan.mjs

@@ -360,7 +360,7 @@ export function buildProfileDraft({ inputs, migrationManifest, writeSet, entries
     ready: incompleteFields.length === 0,
     binding: { targetSetDigest, foundationPlanDigest },
     policyNote:
-      "adoption-lock is deprecated (remediation handoff D-8): the kit no longer produces adoption-lock-form artifacts. The adoption proof is this project's adoption declaration, completed with real artifact paths and digests inside the profile write set and machine-verified by verifyProjectProfile (SPE1006 digest discipline, SPE1007 tightening-only overrides).",
+      "adoption-lock is deprecated (remediation handoff D-8): the kit no longer produces adoption-lock-form artifacts. The adoption proof is this project's adoption declaration, completed with real artifact paths and digests inside the profile write set and machine-verified by verifyProjectProfile (SPE1006 digest discipline, SPE1007 tightening-only overrides). profileDraft is a proposed draft only; an incomplete or empty draft does not invalidate a current valid profile.json.",
   };
 }
 

package/src/check.mjs

@@ -52,10 +52,12 @@ import { loadEngineeringDeclaration } from "./engineering-declaration.mjs";
  *               fail-closed semantics are unchanged: it remains a finding);
  *   closure   — harness resource closure over declared inputs/outputs;
  *   version   — declared contracts version vs the frozen contracts version,
- *               plus version single-source consistency (SG-13/14, VRG-001/002:
- *               package.json is the single version authority; no double-headed
- *               VERSION authority; every workspace package.json carries the
- *               same single-source version);
+ *               plus root-only version single-source facts when no
+ *               engineering.releaseUnits declaration is in force (SG-13/14,
+ *               VRG-001: package.json is the root version authority; no
+ *               double-headed VERSION authority). Nested package.json files
+ *               and historical snapshots are not current release units; actual
+ *               units are checked only through declared versionSource/versionMirrors;
  *   docs      — documentation facts (README presence, identity consistency);
  *   git       — read-only Git pre-state (never a git write);
  *   identity  — licensing and identity drift checks (FND-045);
@@ -552,22 +554,27 @@ async function checkClosure(rootAbs, findings) {
 }
 
 /**
- * Version single-source consistency (SG-13/14; audit VRG-001/VRG-002).
+ * Legacy version facts used when engineering.releaseUnits is absent.
  *
- * The version truth source of a release unit is the `version` field of its
- * package.json. Two mechanical facts follow:
- * - VRG-001: a VERSION file alongside package.json is a double-headed
- *   version authority; the authority must converge on package.json;
- * - VRG-002: the version value is declared once; every other occurrence is
- *   mechanically synchronized — here: every nested workspace package.json
- *   must carry exactly the root package.json version.
+ * Scope is the root package.json and an adjacent VERSION file only
+ * (VRG-001: no double-headed VERSION authority next to the root package).
+ * Nested package.json files, historical snapshots, and independent release
+ * units are not current version authorities; declare releaseUnits with
+ * versionSource/versionMirrors to check those objects. Invalid declarations
+ * never fall back to this path. Provider lockstep among Foundation's own
+ * four release units stays in the workspace check-structure gate.
  *
  * When no root package.json version exists there is no single source to
  * compare against and the sub-check reports nothing (never guesses).
- * Returns { rootVersion, versionFilePresent, drifted }.
+ * Returns { rootVersion, versionFilePresent, drifted, note }.
  */
 async function checkVersionSingleSource(rootAbs, findings) {
-  const facts = { rootVersion: null, versionFilePresent: false, drifted: [] };
+  const facts = {
+    rootVersion: null,
+    versionFilePresent: false,
+    drifted: [],
+    note: "legacy version class reads the root package.json and an adjacent VERSION file only; nested package.json files and historical snapshots are not current release units. Declare engineering.releaseUnits to check actual units.",
+  };
   const packageDocument = await loadDocument(rootAbs, "package.json");
   if (packageDocument.state !== "ok" || typeof packageDocument.value?.version !== "string") {
     return facts;
@@ -587,27 +594,6 @@ async function checkVersionSingleSource(rootAbs, findings) {
       ),
     );
   }
-
-  const entries = await listTargetEntries(rootAbs);
-  for (const entry of entries) {
-    if (entry.kind !== "file" || entry.path === "package.json" || !entry.path.endsWith("package.json")) {
-      continue;
-    }
-    const nested = await loadDocument(rootAbs, entry.path);
-    if (nested.state !== "ok" || typeof nested.value?.version !== "string") continue;
-    if (nested.value.version !== facts.rootVersion) {
-      facts.drifted.push({ path: entry.path, version: nested.value.version });
-      findings.push(
-        finding(
-          "version",
-          KIT_ERROR_KINDS.VERSION_SINGLE_SOURCE_DRIFT,
-          "SFC2004",
-          `${entry.path} declares version ${nested.value.version}; the single version source is the root package.json version ${facts.rootVersion} (VRG-002)`,
-          { path: entry.path, declared: nested.value.version, expected: facts.rootVersion },
-        ),
-      );
-    }
-  }
   return facts;
 }
 

package/src/cli.mjs

@@ -8,6 +8,7 @@ import { bundledProfilesRoot } from "./licensing.mjs";
 import { checkEntriesAction } from "./entry-check.mjs";
 import { checkHostLoadingAction } from "./host-loading-check.mjs";
 import { relockAction } from "./relock.mjs";
+import { registerExistingAction } from "./register-existing.mjs";
 import { checkReportAction, renderReportAction } from "./report.mjs";
 import {
   COMMAND_SIDE_EFFECTS,
@@ -77,6 +78,10 @@ const HELP_TEXT = `skill-family-engineering-kit —— 构建期工程工具包
                把新手写文件登记进 .foundation/file-registry.json，并以当前字节
                重算 skill-family.managed-file-lock.json（单次 fail-closed 事务；
                只写这两个收容状态文档，任何拒绝都零写入）。
+               首次非空登记子动作: check register-existing 为已有非空工程生成
+               三份闭世界登记（file-registry / project-manifest / managed-file-lock）。
+               消费已确认的 profile 身份与调用方分类/engineering；重复执行幂等，
+               冲突拒绝且零覆盖。不走 scaffold，也不把 adopt-plan 写成 apply。
                显式资格子动作: check qualification 仅在显式提供
                capability/request/bindings/native 后适配目录声明的能力特定入口，
                可在预检后调用能力特定的原生宿主。
@@ -158,6 +163,12 @@ function commandHelp(command) {
       "  --registration-class <handwritten|trackedToolLocks>  登记类别，默认 handwritten",
       "  trackedToolLocks 必须提供非空 --files 清单，只登记路径，不锁定工具锁内容。",
       "",
+      "首次非空登记: skill-family-kit check register-existing --root <dir> --handwritten <globs>",
+      "  --engineering <json>  可选，现有 project-manifest.engineering 对象",
+      "  --tracked-tool-locks <paths>  可选，已存在的持久工具锁路径",
+      "  --artifacts <patterns>  可选，额外忽略模式；不得把已跟踪生成物列为忽略运行目录",
+      "  目标必须已有合法 profile.json；三份登记全部缺失则独占创建，全部匹配则幂等，其它情况拒绝零覆盖。",
+      "",
       "选项:",
       "  --root <dir>          目标工作区（默认当前目录）",
       "  --only <class>        只运行一个诊断类: contracts|drift|closure|version|docs|git|identity|boundary|platform",
@@ -347,6 +358,16 @@ const COMMAND_SPECS = {
       "--registration-class": { key: "registrationClass", value: true },
     },
   },
+  "check register-existing": {
+    rejectDuplicates: true,
+    flags: {
+      "--root": { key: "root", value: true },
+      "--handwritten": { key: "handwritten", value: true },
+      "--engineering": { key: "engineeringJson", value: true },
+      "--tracked-tool-locks": { key: "trackedToolLocks", value: true },
+      "--artifacts": { key: "artifacts", value: true },
+    },
+  },
   "check qualification": {
     rejectDuplicates: true,
     flags: {
@@ -615,6 +636,37 @@ async function runRelockSubAction(rest) {
   }
 }
 
+async function runRegisterExistingSubAction(rest) {
+  const specName = "check register-existing";
+  try {
+    const options = parseOptions(rest, { command: specName, flags: COMMAND_SPECS[specName].flags, rejectDuplicates: true });
+    if (options.help) {
+      process.stdout.write(`${commandHelp("check")}\n`);
+      return KIT_EXIT_CODES.ok;
+    }
+    let engineering;
+    if (options.engineeringJson !== undefined) {
+      try {
+        engineering = JSON.parse(options.engineeringJson);
+      } catch {
+        throw invalidParamsError("--engineering must be a JSON engineering object", { flag: "--engineering" });
+      }
+    }
+    const { status, output } = await registerExistingAction({
+      root: options.root,
+      handwritten: options.handwritten,
+      engineering,
+      trackedToolLocks: options.trackedToolLocks,
+      artifacts: options.artifacts,
+    });
+    process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    return status === "ok" ? KIT_EXIT_CODES.ok : KIT_EXIT_CODES.rejected;
+  } catch (error) {
+    printError(error);
+    return KIT_EXIT_CODES.rejected;
+  }
+}
+
 function requireJsonFlag(options, specName) {
   if (options.json !== true) {
     throw invalidParamsError(`${specName} requires --json`, { reason: "missing-option-value", flag: "--json" });
@@ -788,6 +840,9 @@ export async function cliMain(argv) {
   if (command === "check" && argv[1] === "relock") {
     return runRelockSubAction(argv.slice(2));
   }
+  if (command === "check" && argv[1] === "register-existing") {
+    return runRegisterExistingSubAction(argv.slice(2));
+  }
   if (command === "check" && argv[1] === "qualification") {
     return runQualificationSubAction(argv.slice(2));
   }

package/src/errors.mjs

@@ -92,6 +92,8 @@ export const KIT_ERROR_KINDS = Object.freeze({
   // controlled relock channel (SG-36; audit friction F5): `check relock`
   RELOCK_REGISTRATION_REFUSED: "relock-registration-refused",
   RELOCK_LOCK_DRIFT: "relock-lock-drift",
+  // first nonempty closed-world seed (check register-existing)
+  REGISTER_EXISTING_REFUSED: "register-existing-refused",
   // read-only host integration slice
   HOST_CONTRACT_INVALID: "host-contract-invalid",
   HOST_PROBE_FAILED: "host-probe-failed",

package/src/index.mjs

@@ -24,6 +24,11 @@ import {
   relockAction,
   runRelock,
 } from "./relock.mjs";
+import {
+  REGISTER_EXISTING_REPORT_KIND,
+  registerExistingAction,
+  runRegisterExisting,
+} from "./register-existing.mjs";
 import {
   invalidParamsError,
   KitError,
@@ -164,7 +169,7 @@ export const COMMAND_SIDE_EFFECTS = Object.freeze({
   check: Object.freeze({
     summary: "契约/漂移/闭包/版本/文档事实/Git 前置状态诊断。",
     sideEffect:
-      "none for default diagnosis and the pure runChecks/runEntryContractCheck functions — they never write or auto-fix, and git is probed read-only (one frozen status query at most); with policy declared, only the runCommand('check') and checkEntriesAction wrappers may exclusively create one conclusion when callers explicitly provide an existing output root plus a contained relative path, never creating parent directories or overwriting an existing entry; check proof is read-only proof interpretation and never writes; check proof-create exclusively creates one conclusion from a Skill review-input under the same exclusive-write rules; check host-loading is a strictly read-only sub-action that never writes, spawns, or contacts a network; relock remains a separately explicit controlled write transaction; qualification remains separately explicit and may invoke the capability-specific native host only after its preflight. Foundation itself does not issue network requests, but a bound executable may access the network; sandbox and egress controls remain with callers and the execution environment",
+      "none for default diagnosis and the pure runChecks/runEntryContractCheck functions — they never write or auto-fix, and git is probed read-only (one frozen status query at most); with policy declared, only the runCommand('check') and checkEntriesAction wrappers may exclusively create one conclusion when callers explicitly provide an existing output root plus a contained relative path, never creating parent directories or overwriting an existing entry; check proof is read-only proof interpretation and never writes; check proof-create exclusively creates one conclusion from a Skill review-input under the same exclusive-write rules; check host-loading is a strictly read-only sub-action that never writes, spawns, or contacts a network; relock remains a separately explicit controlled write transaction; check register-existing remains a separately explicit first-nonempty registration write of the three closed-world documents and never overwrites mismatched bytes; qualification remains separately explicit and may invoke the capability-specific native host only after its preflight. Foundation itself does not issue network requests, but a bound executable may access the network; sandbox and egress controls remain with callers and the execution environment",
     exitCodes: "0 无发现；1 有发现；2 拒绝/用法/机制错误",
   }),
 });
@@ -262,6 +267,9 @@ export {
   relockAction,
   RELOCK_LOCK_PATH_PATTERN,
   RELOCK_REPORT_KIND,
+  runRegisterExisting,
+  registerExistingAction,
+  REGISTER_EXISTING_REPORT_KIND,
   runChecks,
   CHECK_CLASSES,
   DOCUMENT_STATES,