skill-family-engineering-kit 0.3.0 → 0.4.0

package/package.json

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

package/release-notes/0.4.0.yaml

@@ -0,0 +1,23 @@
+version: 0.4.0
+date: 2026-08-16
+locales:
+  en:
+    summary: 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.
+    changes:
+      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.
+    upgradeNotes: 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.
+  zh-CN:
+    summary: 本版为 Engineering Kit 新增候选 adoption CLI 与 adoption mechanisms，同时保持稳定四命令边界与 0.3.0 的离线 Bundle 不变。
+    changes:
+      added:
+        - 新增 adoption-cli 候选：基于 stdin/stdout 的 CLI，通过 migration manifest 评估 adoption 绑定、遗留 exit list 与遗留引用，并校验 managed-bundle 身份与 harness 表面清单。
+        - 新增 adoption-mechanisms 候选模块，作为 adoption CLI 的共享实现。
+      changed:
+        - 稳定四命令（scaffold、adopt-plan、projection、check）保持不变。
+        - 延续 0.3.0 的 Quickstart Profile v2 离线 Bundle（按 schema $id 选择的 standalone validator、完整 provenance 记录）与候选插件技能命名检查器。
+    upgradeNotes: 0.4.0 已发布到 npm 与 public 镜像仓。adoption CLI 是候选入口，须经显式 candidate 子路径调用，并把包精确锁定为 0.4.0。

package/src/adopt-plan.mjs

@@ -6,6 +6,7 @@ import { probeGitFacts, probeGitState } from "./gitprobe.mjs";
 import {
   assessAdoptionBinding,
   assessLegacyExitList,
+  assessLegacyReferences,
   assessVerificationEvidence,
   evaluateMigrationCompletion,
   findNestedRepositories,
@@ -89,6 +90,7 @@ export function buildHandoffDraft({
   conflicts,
   risks,
   legacyExitList,
+  legacyReferenceExitList,
   verificationFacts,
   migrationState,
   entries,
@@ -137,8 +139,17 @@ export function buildHandoffDraft({
   });
 
   // 5. The validator/builder/docs-pipeline/git-preflight slated for exit.
+  //    Includes both whole-file exits (legacyInfra) and reference-level
+  //    exits (legacyReferences) for retained files.
   push(5, HANDOFF_FIELDS[4], "derived", {
     exits: legacyExitList.map((item) => ({ path: item.path, replacedBy: item.replacedBy, status: item.status })),
+    referenceExits: (legacyReferenceExitList ?? []).map((ref) => ({
+      path: ref.path,
+      text: ref.text,
+      replacedBy: ref.replacedBy,
+      status: ref.status,
+      occurrenceCount: ref.occurrenceCount,
+    })),
   });
 
   // 6. Business logic that must be kept: never derivable from repo facts.
@@ -420,6 +431,17 @@ export async function planAdoption({
       });
     }
   }
+  const legacyReferenceExitList = await assessLegacyReferences(rootAbs, migrationManifest?.legacyReferences ?? []);
+  for (const ref of legacyReferenceExitList) {
+    if (ref.status === "invalid") {
+      conflicts.push({
+        path: MIGRATION_MANIFEST_PATH,
+        kind: "legacy-path-containment",
+        code: "SFC2004",
+        detail: `legacy reference path rejected by harness containment, fail-closed: ${ref.path ?? "<malformed>"} (${ref.invalidKind ?? "unknown"}); user paths are only ever read inside the target root`,
+      });
+    }
+  }
   const exceptionFindings = [];
   const declaredExceptions = Array.isArray(migrationManifest?.exceptions) ? migrationManifest.exceptions : [];
   for (const [index, exception] of declaredExceptions.entries()) {
@@ -481,6 +503,7 @@ export async function planAdoption({
   const completion = evaluateMigrationCompletion({
     manifestDeclared,
     legacyExitList,
+    legacyReferenceExitList,
     exceptionFindings,
     conflicts,
     binding,
@@ -512,6 +535,7 @@ export async function planAdoption({
     conflicts,
     risks,
     legacyExitList,
+    legacyReferenceExitList,
     verificationFacts,
     migrationState: completion.state,
     entries,
@@ -555,6 +579,7 @@ export async function planAdoption({
       manifestStatus: manifestState.status,
       manifestPath: MIGRATION_MANIFEST_PATH,
       legacyExitList,
+      legacyReferenceExitList,
       exceptions: { declared: declaredExceptions.length, findings: exceptionFindings },
       binding,
       adoptionProof,
@@ -589,6 +614,6 @@ export async function planAdoption({
       },
     ],
     policy:
-      "strictly read-only: this plan changes nothing in the target (no files, no temp files, no git); every listed byte is computed from describeSkeletonFiles, the same source scaffold consumes; the kit never renames repositories or directories and never touches remotes — infrastructure adoption and repository renaming are separate decisions; migration completion additionally requires every legacy implementation to have exited (dual-track wiring alone is not completion)",
+      "strictly read-only: this plan changes nothing in the target (no files, no temp files, no git); every listed byte is computed from describeSkeletonFiles, the same source scaffold consumes; the kit never renames repositories or directories and never touches remotes — infrastructure adoption and repository renaming are separate decisions; migration completion additionally requires every legacy implementation to have exited and every declared legacy reference to be absent from its retained file (dual-track wiring alone is not completion)",
   };
 }

package/src/index.mjs

@@ -22,6 +22,7 @@ import {
 import {
   assessAdoptionBinding,
   assessLegacyExitList,
+  assessLegacyReferences,
   assessVerificationEvidence,
   evaluateMigrationCompletion,
   EXCEPTION_REQUIRED_FIELDS,
@@ -50,7 +51,7 @@ import {
   listLicensingProfiles,
   loadLicensingProfile,
 } from "./licensing.mjs";
-import { runProjection, loadProjectionManifest } from "./projection.mjs";
+import { compileProjectionPlan, runProjection, loadProjectionManifest } from "./projection.mjs";
 import { checkReportAction, renderReportAction } from "./report.mjs";
 import { scaffoldTarget } from "./scaffold.mjs";
 import {
@@ -119,7 +120,7 @@ export const COMMAND_SIDE_EFFECTS = Object.freeze({
   projection: Object.freeze({
     summary: "投影受管生成物。",
     sideEffect:
-      "writes only manifest-authorized managed artifacts; the report sub-action (projection report) writes only the explicitly named --out/--binding paths contained in --root (Markdown goes to stdout when no --out is given); unauthorized, handwritten, escaping, or conflicting paths are refused with zero writes",
+      "writes or deletes only explicitly owned, manifest-authorized managed artifacts; the report sub-action (projection report) writes only the explicitly named --out/--binding paths contained in --root (Markdown goes to stdout when no --out is given); unauthorized, handwritten, escaping, or conflicting paths are refused before mutation",
     exitCodes: "0 成功；2 拒绝/用法/机制错误",
   }),
   check: Object.freeze({
@@ -191,6 +192,7 @@ export {
   planAdoption,
   buildHandoffDraft,
   HANDOFF_FIELDS,
+  compileProjectionPlan,
   runProjection,
   loadProjectionManifest,
   renderReportAction,
@@ -259,5 +261,6 @@ export {
   assessAdoptionBinding,
   assessVerificationEvidence,
   assessLegacyExitList,
+  assessLegacyReferences,
   evaluateMigrationCompletion,
 };

package/src/migration.mjs

@@ -1,8 +1,11 @@
-import { lstat } from "node:fs/promises";
+import { lstat, readFile } from "node:fs/promises";
+import { TextDecoder } from "node:util";
 import { findSchemaByObject } from "skill-family-contracts";
 import { HarnessError, readFileContained, resolveContained, validateContractDocument } from "skill-family-harness-node";
 import { normalizeRelPath, readOptionalJson } from "./workspace.mjs";
 
+const UTF8_STRICT_DECODER = new TextDecoder("utf-8", { fatal: true });
+
 /**
  * Migration closure facts for adopt-plan (FND-070, formalized by the
  * migration manifest contract).
@@ -189,6 +192,112 @@ export async function assessLegacyExitList(root, legacyItems) {
   return list;
 }
 
+/**
+ * Assesses the legacy reference exit list: for each declared reference,
+ * checks whether the exact literal `text` still appears in the retained file.
+ *
+ * Returns one entry per declared reference with:
+ *   status: "absent"   — the literal text is not found (0 occurrences); file
+ *                        missing also counts as absent (the text is gone);
+ *   status: "present"  — the literal text appears one or more times;
+ *   status: "invalid"  — path rejected by containment, file contains
+ *                        invalid UTF-8 bytes, unreadable, or is a directory.
+ *
+ * UTF-8 decoding is strict: any invalid byte sequence fails closed with
+ * `invalidKind: "invalid-utf8"` instead of silently replacing bad bytes
+ * with U+FFFD. This prevents false "absent" verdicts when the file
+ * contains corrupted text that would otherwise mask the literal search.
+ *
+ * The `occurrenceCount` field is reported for "present" and "absent" entries
+ * without leaking file contents. Paths are resolved through harness
+ * containment (fail-closed on escape).
+ */
+export async function assessLegacyReferences(root, legacyRefs) {
+  const list = [];
+  if (!Array.isArray(legacyRefs)) return list;
+  for (const ref of legacyRefs) {
+    if (!ref || typeof ref.path !== "string" || ref.path.trim() === "") {
+      list.push({ path: null, text: null, replacedBy: null, status: "invalid", invalidKind: "malformed-entry", occurrenceCount: 0 });
+      continue;
+    }
+    const rel = normalizeRelPath(ref.path);
+    const text = typeof ref.text === "string" ? ref.text : null;
+    if (text === null || text === "") {
+      list.push({ path: rel, text: null, replacedBy: null, status: "invalid", invalidKind: "empty-text", occurrenceCount: 0 });
+      continue;
+    }
+    const replacedBy = typeof ref.replacedBy === "string" && ref.replacedBy.trim() !== "" ? ref.replacedBy : null;
+    if (replacedBy === null) {
+      list.push({ path: rel, text, replacedBy: null, status: "invalid", invalidKind: "empty-replaced-by", occurrenceCount: 0 });
+      continue;
+    }
+    let resolved;
+    try {
+      resolved = await resolveContained(root, rel);
+    } catch (cause) {
+      list.push({
+        path: rel,
+        text,
+        replacedBy,
+        status: "invalid",
+        invalidKind: cause instanceof HarnessError && cause.details?.kind ? cause.details.kind : "containment-rejected",
+        occurrenceCount: 0,
+      });
+      continue;
+    }
+    let bytes;
+    try {
+      bytes = await readFile(resolved);
+    } catch (cause) {
+      if (cause && cause.code === "ENOENT") {
+        // File missing: the old text is absent by definition.
+        list.push({ path: rel, text, replacedBy, status: "absent", occurrenceCount: 0 });
+        continue;
+      }
+      // Directory, unreadable, or other failure: fail-closed as invalid.
+      list.push({
+        path: rel,
+        text,
+        replacedBy,
+        status: "invalid",
+        invalidKind: cause && cause.code === "EISDIR" ? "is-directory" : "unreadable",
+        occurrenceCount: 0,
+      });
+      continue;
+    }
+    // Strict UTF-8 decode: reject any invalid byte sequences instead of
+    // replacing them with U+FFFD. This prevents silent data corruption
+    // when assessing whether legacy text has truly exited a file.
+    let content;
+    try {
+      content = UTF8_STRICT_DECODER.decode(bytes);
+    } catch {
+      list.push({
+        path: rel,
+        text,
+        replacedBy,
+        status: "invalid",
+        invalidKind: "invalid-utf8",
+        occurrenceCount: 0,
+      });
+      continue;
+    }
+    // Strict UTF-8 decode succeeded. Exact literal match: count
+    // non-overlapping occurrences.
+    let count = 0;
+    let fromIndex = 0;
+    while (true) {
+      const idx = content.indexOf(text, fromIndex);
+      if (idx === -1) break;
+      count++;
+      fromIndex = idx + text.length;
+    }
+    const status = count === 0 ? "absent" : "present";
+    list.push({ path: rel, text, replacedBy, status, occurrenceCount: count });
+  }
+  return list;
+}
+
 /**
  * Migration state machine. States advance monotonically as facts
  * are proven; completion is the final state only. No tool ever advances a
@@ -317,6 +426,9 @@ export async function assessVerificationEvidence(rootAbs, verification, plannedP
  * - every legacy implementation removed or provably absent — an invalid
  *   (containment-rejected or malformed) entry fails closed like a present
  *   one; dual-track wiring alone is not completion;
+ * - every declared legacy reference absent from its retained file — an
+ *   invalid (containment-rejected, unreadable, malformed) entry fails
+ *   closed like a present one;
  * - no incomplete/invalid/expired temporary exceptions;
  * - no unresolved adoption conflicts;
  * - all four verification evidence documents proven with matching identity.
@@ -329,6 +441,7 @@ export async function assessVerificationEvidence(rootAbs, verification, plannedP
 export function evaluateMigrationCompletion({
   manifestDeclared,
   legacyExitList,
+  legacyReferenceExitList,
   exceptionFindings,
   conflicts,
   binding,
@@ -385,6 +498,13 @@ export function evaluateMigrationCompletion({
       adoptionBlockers.push(`legacy entry cannot be verified (fail-closed): ${item.path ?? "<malformed>"} (${item.invalidKind ?? "unknown"})`);
     }
   }
+  for (const ref of legacyReferenceExitList ?? []) {
+    if (ref.status === "present") {
+      adoptionBlockers.push(`legacy reference still present in ${ref.path}: ${ref.occurrenceCount} occurrence(s)`);
+    } else if (ref.status === "invalid") {
+      adoptionBlockers.push(`legacy reference cannot be verified (fail-closed): ${ref.path ?? "<malformed>"} (${ref.invalidKind ?? "unknown"})`);
+    }
+  }
   for (const finding of exceptionFindings ?? []) {
     if (finding.kind === "exception-incomplete") {
       adoptionBlockers.push(`exception #${finding.index} missing required fields: ${finding.missing.join(", ")}`);