skill-family-engineering-kit 0.5.0 → 0.6.0

package/src/cli.mjs

@@ -4,6 +4,8 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { readFileContained, resolveContained } from "skill-family-harness-node";
 import { bundledProfilesRoot } from "./licensing.mjs";
+import { checkEntriesAction } from "./entry-check.mjs";
+import { relockAction } from "./relock.mjs";
 import { checkReportAction, renderReportAction } from "./report.mjs";
 import {
   COMMAND_SIDE_EFFECTS,
@@ -56,6 +58,13 @@ const HELP_TEXT = `skill-family-engineering-kit —— 构建期工程工具包
                报告子动作: check report 对一份已渲染报告做分级诊断：
                硬失败（SFC3001/3002/3003）计为发现（退出码 1）；
                风格告警只报告、绝不阻塞机器正确的报告。
+               入口契约子动作: check entries 运行共享入口契约门禁
+               （SFA-ENTRY-003/004/005/007 + SFA-CONTEXT-001/002），
+               读取 skill-family.entry-contract.json 声明；声明缺失是数据、不是发现。
+               受控重锁子动作: check relock 运行受控 relock 事务（SG-36）：
+               把新手写文件登记进 .foundation/file-registry.json，并以当前字节
+               重算 skill-family.managed-file-lock.json（单次 fail-closed 事务；
+               只写这两个收容状态文档，任何拒绝都零写入）。
 
 全局选项:
   --root <dir>  目标工作区根目录（默认当前目录）
@@ -119,7 +128,7 @@ function commandHelp(command) {
     check: [
       "选项:",
       "  --root <dir>          目标工作区（默认当前目录）",
-      "  --only <class>        只运行一个诊断类: contracts|drift|closure|version|docs|git|identity",
+      "  --only <class>        只运行一个诊断类: contracts|drift|closure|version|docs|git|identity|boundary|platform",
       "  --profiles-root <dir> 许可证 Profile 根目录",
       "  --no-git-spawn        禁用只读 git status 探测，仅用文件系统事实",
       "",
@@ -232,6 +241,17 @@ const COMMAND_SPECS = {
       "--binding": { key: "binding", value: true },
     },
   },
+  "check entries": {
+    flags: {
+      "--root": { key: "root", value: true },
+    },
+  },
+  "check relock": {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--files": { key: "files", value: true },
+    },
+  },
   "scaffold host-build": {
     flags: {
       "--root": { key: "root", value: true },
@@ -342,6 +362,53 @@ async function runReportSubAction(command, rest) {
   }
 }
 
+async function runEntriesSubAction(rest) {
+  const specName = "check entries";
+  try {
+    const options = parseOptions(rest, { command: specName, flags: COMMAND_SPECS[specName].flags });
+    if (options.help) {
+      process.stdout.write(`${commandHelp("check")}\n`);
+      return KIT_EXIT_CODES.ok;
+    }
+    const { status, output } = await checkEntriesAction({ root: options.root });
+    process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    if (status === "ok") return KIT_EXIT_CODES.ok;
+    if (status === "findings") return KIT_EXIT_CODES.findings;
+    return KIT_EXIT_CODES.rejected;
+  } catch (error) {
+    printError(error);
+    return KIT_EXIT_CODES.rejected;
+  }
+}
+
+async function runRelockSubAction(rest) {
+  const specName = "check relock";
+  try {
+    const options = parseOptions(rest, { command: specName, flags: COMMAND_SPECS[specName].flags });
+    if (options.help) {
+      process.stdout.write(`${commandHelp("check")}\n`);
+      return KIT_EXIT_CODES.ok;
+    }
+    // --files is one comma-separated relative-path list; absent means the
+    // auto-discovery mode of the closed-world stage (mirrors runRelock).
+    const files =
+      options.files === undefined
+        ? null
+        : options.files
+            .split(",")
+            .map((rel) => rel.trim())
+            .filter((rel) => rel.length > 0);
+    const { status, output } = await relockAction({ root: options.root, files });
+    process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    // Relock has no findings state: it either commits the whole transaction
+    // or throws (exit 2). Any status other than "ok" is a mechanism error.
+    return status === "ok" ? KIT_EXIT_CODES.ok : KIT_EXIT_CODES.rejected;
+  } catch (error) {
+    printError(error);
+    return KIT_EXIT_CODES.rejected;
+  }
+}
+
 export async function cliMain(argv) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     process.stdout.write(HELP_TEXT);
@@ -359,6 +426,18 @@ export async function cliMain(argv) {
   if ((command === "projection" || command === "check") && argv[1] === "report") {
     return runReportSubAction(command, argv.slice(2));
   }
+  // Positional entry-contract sub-action (SG-34): `check entries` runs the
+  // shared entry contract gate (SFA-ENTRY-003/004/005/007 + SFA-CONTEXT-001/002).
+  // It hangs under the existing check command; no fifth command is created.
+  if (command === "check" && argv[1] === "entries") {
+    return runEntriesSubAction(argv.slice(2));
+  }
+  // Positional controlled-relock sub-action (SG-36): `check relock` runs the
+  // fail-closed registration + lock-recompute transaction. It hangs under the
+  // existing check command, parallel to `check entries`; no fifth command.
+  if (command === "check" && argv[1] === "relock") {
+    return runRelockSubAction(argv.slice(2));
+  }
   if (command === "scaffold" && argv[1] === "host-build") {
     return runHostSubAction(command, "host-build", argv.slice(2));
   }

package/src/core-check.mjs

@@ -5,7 +5,9 @@ import { CHECK_CLASSES, runChecks } from "./check.mjs";
 import {
   IDENTITY_RECORD_PATH,
   MANAGED_LOCK_PATH,
+  PLATFORM_SUBSET_DECLARATION_PATH,
   PROJECT_MANIFEST_PATH,
+  PUBLIC_BOUNDARY_DECLARATION_PATH,
 } from "./skeleton.mjs";
 import {
   listTargetEntries,
@@ -23,7 +25,7 @@ import {
  * ONLY import this function: safe file-tree enumeration, lstat/symlink/FIFO
  * and special-entry rejection, file-registry classification (managed /
  * handwritten / artifact closed world), declaration path containment, the
- * seven check classes, and the stable finding/exit mapping all live here and
+ * nine check classes, and the stable finding/exit mapping all live here and
  * nowhere else. No generated string may re-derive a recursive walk, an lstat
  * classification, a glob match, or a local closed-world algorithm.
  *
@@ -35,7 +37,7 @@ import {
  *   3. tree enumeration — every symlink and special entry fails closed;
  *      every regular file must belong to the registered closed world
  *      (managed, handwritten, artifact, or a tracked tool lock);
- *   4. the seven check classes through runChecks — skipped whenever an
+ *   4. the nine check classes through runChecks — skipped whenever an
  *      unsafe path (symlink/special at a managed or class-read path) would
  *      be opened by them: FIFOs must never be read (they block), symlinks
  *      must never be followed.
@@ -68,7 +70,7 @@ export const CORE_CHECK_SECURITY_KINDS = Object.freeze([
 const CORE_CLASS = "core";
 
 /**
- * Paths the seven check classes open by name. They take part in the unsafe
+ * Paths the nine check classes open by name. They take part in the unsafe
  * read-set even when they are not declared managed (README.md is handwritten
  * in the skeleton), so a symlink/FIFO there can never hang or escape a read.
  */
@@ -79,6 +81,8 @@ const CLASS_READ_PATHS = Object.freeze([
   MANAGED_LOCK_PATH,
   IDENTITY_RECORD_PATH,
   "identity-record.json",
+  PUBLIC_BOUNDARY_DECLARATION_PATH,
+  PLATFORM_SUBSET_DECLARATION_PATH,
 ]);
 
 /** Lexical containment of a managed declaration; never touches the fs. */
@@ -189,7 +193,7 @@ export async function runCoreCheck({ root, allowGitSpawn = true, profilesRoot }
     );
   }
 
-  // ---- Stage 4: the seven check classes through the shared entry ---------
+  // ---- Stage 4: the nine check classes through the shared entry ---------
   let classReport = null;
   if (unsafeReadPaths.size === 0) {
     classReport = await runChecks({ root: rootAbs, allowGitSpawn, profilesRoot });

package/src/entry-check.mjs

@@ -0,0 +1,384 @@
+import {
+  readFileContained,
+  estimateTokens,
+  TOKEN_ESTIMATOR_ID,
+  TOKEN_ESTIMATOR_VERSION,
+  TOKEN_ESTIMATION_ALGORITHM,
+} from "skill-family-harness-node";
+import {
+  consumeTokenEstimateStrict,
+  TOKEN_ESTIMATE_CONSUMPTION,
+} from "skill-family-contracts";
+import { KIT_ERROR_KINDS } from "./errors.mjs";
+import { KIT_TOOL_NAME, KIT_VERSION } from "./skeleton.mjs";
+import { readOptionalJson, resolveTargetRoot } from "./workspace.mjs";
+
+/**
+ * runEntryContractCheck — the shared entry contract gate (SG-34; audit
+ * friction F2, satisfaction carrier of PGM-001(c)).
+ *
+ * Before this sub-action existed, every project hand-wrote roughly 150 lines
+ * of equivalent entry-gate logic and owned its correctness alone. The five
+ * frozen checks implement exactly the semantics the audit rules define:
+ *
+ *   1. SFA-ENTRY-003 — every declared entry exists physically in its
+ *      declared form (v1 freezes the single form skill_md: the physicalRef
+ *      must be a readable regular file named SKILL.md);
+ *   2. SFA-ENTRY-004 — the outward logical name of every entry is the
+ *      qualified name `<project>:<name>` and logical names are unique;
+ *   3. SFA-ENTRY-005 — entries declared as human entries never appear in
+ *      the method-registration boundary (registeredMethods);
+ *   4. SFA-ENTRY-007 — entries flagged readOnlyRequired declare the
+ *      read_only side-effect class (controlled vocabulary: read_only or
+ *      transactional);
+ *   5. SFA-CONTEXT-001/002 — every entry's SKILL.md token budget is
+ *      measured with the authoritative deterministic estimator and consumed
+ *      through the frozen token estimate consumption contract (SG-33):
+ *      tokens >= hardLimitTokens is a hard-line finding (SFA-CONTEXT-002),
+ *      tokens >= warnLimitTokens a warn-line finding (SFA-CONTEXT-001).
+ *      The estimate is never coerced: consumption failure is a mechanism
+ *      error (fail closed), and degradation never relaxes the thresholds —
+ *      inside the kit the authoritative estimator is a hard dependency, so
+ *      no degraded path exists here.
+ *
+ * The input is one kit-owned declaration document
+ * (skill-family.entry-contract.json, kind
+ * skill-family.entry-contract-declaration). Absence of the declaration is
+ * data, never a finding — whether a project owes an entry contract depends
+ * on its entry surface. The gate is diagnosis only: it reads, estimates and
+ * reports; it never writes.
+ *
+ * Report shape: kind skill-family.entry-check-report; exit mapping
+ * 0 clean / 1 findings / 2 mechanism (thrown by the caller).
+ */
+
+export const ENTRY_CONTRACT_DECLARATION_PATH = "skill-family.entry-contract.json";
+export const ENTRY_CONTRACT_DECLARATION_KIND = "skill-family.entry-contract-declaration";
+export const ENTRY_FORMS = Object.freeze(["skill_md"]);
+export const ENTRY_SIDE_EFFECT_CLASSES = Object.freeze(["read_only", "transactional"]);
+
+const SEMVER_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+const LOCAL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+function finding(kind, code, message, extra) {
+  return { class: "entries", kind, code, message, ...(extra ?? {}) };
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Runs the five entry contract checks over one target.
+ * Options: { root }.
+ * Returns the entry-check report document. Never writes anywhere.
+ * Throws only for unusable inputs (an unreadable target root) and for
+ * fail-closed token consumption failures (mechanism errors, exit 2).
+ */
+export async function runEntryContractCheck({ root } = {}) {
+  const rootAbs = await resolveTargetRoot(root ?? ".");
+  const findings = [];
+  const data = {
+    declared: false,
+    documentState: "missing",
+    project: null,
+    declaredVersion: null,
+    entries: [],
+    estimator: {
+      source: "foundation-token-estimator",
+      id: TOKEN_ESTIMATOR_ID,
+      version: TOKEN_ESTIMATOR_VERSION,
+      algorithm: TOKEN_ESTIMATION_ALGORITHM,
+      consumptionContract: TOKEN_ESTIMATE_CONSUMPTION.kind,
+      numericField: TOKEN_ESTIMATE_CONSUMPTION.numericField,
+    },
+  };
+
+  const loaded = await readOptionalJson(rootAbs, ENTRY_CONTRACT_DECLARATION_PATH);
+  if (loaded.reason === "missing") {
+    return entryReport(data, findings);
+  }
+  data.declared = true;
+  if (!loaded.ok) {
+    data.documentState = "parse-failed";
+    findings.push(
+      finding(
+        KIT_ERROR_KINDS.CONTRACT_PARSE_FAILED,
+        "SFC2004",
+        `${ENTRY_CONTRACT_DECLARATION_PATH} is not valid JSON`,
+        { path: ENTRY_CONTRACT_DECLARATION_PATH, documentState: data.documentState },
+      ),
+    );
+    return entryReport(data, findings);
+  }
+
+  const declaration = loaded.value;
+  const invalid = (message, extra) =>
+    findings.push(
+      finding(KIT_ERROR_KINDS.ENTRY_CONTRACT_INVALID, "SFC2004", message, {
+        path: ENTRY_CONTRACT_DECLARATION_PATH,
+        ...(extra ?? {}),
+      }),
+    );
+
+  // ---- template shape -----------------------------------------------------
+  data.documentState = "ok";
+  if (!isPlainObject(declaration)) {
+    invalid("the declaration must be a JSON object");
+    return entryReport(data, findings);
+  }
+  if (declaration.schemaVersion !== 1) {
+    invalid(`schemaVersion must be exactly 1 (got ${JSON.stringify(declaration.schemaVersion ?? null)})`, {
+      field: "schemaVersion",
+    });
+  }
+  if (declaration.kind !== ENTRY_CONTRACT_DECLARATION_KIND) {
+    invalid(`kind must be "${ENTRY_CONTRACT_DECLARATION_KIND}" (got ${JSON.stringify(declaration.kind ?? null)})`, {
+      field: "kind",
+    });
+  }
+  if (typeof declaration.project !== "string" || !LOCAL_NAME_PATTERN.test(declaration.project)) {
+    invalid("project must be a kebab-case project id", { field: "project" });
+  } else {
+    data.project = declaration.project;
+  }
+  if (typeof declaration.declaredVersion !== "string" || !SEMVER_PATTERN.test(declaration.declaredVersion)) {
+    invalid("declaredVersion must be a semantic version string X.Y.Z", { field: "declaredVersion" });
+  } else {
+    data.declaredVersion = declaration.declaredVersion;
+    const packageDocument = await readOptionalJson(rootAbs, "package.json");
+    if (
+      packageDocument.ok &&
+      typeof packageDocument.value?.version === "string" &&
+      packageDocument.value.version !== declaration.declaredVersion
+    ) {
+      findings.push(
+        finding(
+          KIT_ERROR_KINDS.ENTRY_CONTRACT_VERSION_DRIFT,
+          "SFC2004",
+          `entry contract declaration declares version ${declaration.declaredVersion}; the single version source (package.json) is ${packageDocument.value.version}`,
+          {
+            path: ENTRY_CONTRACT_DECLARATION_PATH,
+            declared: declaration.declaredVersion,
+            expected: packageDocument.value.version,
+          },
+        ),
+      );
+    }
+  }
+
+  const entries = Array.isArray(declaration.entries) ? declaration.entries : null;
+  if (entries === null) {
+    invalid("entries must be an array of entry declarations", { field: "entries" });
+    return entryReport(data, findings);
+  }
+  const registeredMethods = Array.isArray(declaration.registeredMethods)
+    ? declaration.registeredMethods.filter((item) => typeof item === "string")
+    : [];
+  if (!Array.isArray(declaration.registeredMethods)) {
+    invalid("registeredMethods must be an array of registered method logical names", {
+      field: "registeredMethods",
+    });
+  }
+
+  const tokenBudget = isPlainObject(declaration.tokenBudget) ? declaration.tokenBudget : null;
+  const warnLimitTokens = tokenBudget?.warnLimitTokens;
+  const hardLimitTokens = tokenBudget?.hardLimitTokens;
+  const budgetUsable =
+    Number.isInteger(warnLimitTokens) &&
+    warnLimitTokens > 0 &&
+    Number.isInteger(hardLimitTokens) &&
+    hardLimitTokens > 0;
+  if (!budgetUsable) {
+    invalid("tokenBudget.warnLimitTokens and tokenBudget.hardLimitTokens must be positive integers", {
+      field: "tokenBudget",
+    });
+  } else if (warnLimitTokens >= hardLimitTokens) {
+    invalid("tokenBudget.warnLimitTokens must be strictly below hardLimitTokens", { field: "tokenBudget" });
+  }
+
+  // ---- per-entry checks ----------------------------------------------------
+  const seenLogicalNames = new Set();
+  for (const [index, entry] of entries.entries()) {
+    const at = `entries[${index}]`;
+    if (!isPlainObject(entry)) {
+      invalid(`${at} must be an object`, { field: at });
+      continue;
+    }
+    const name = typeof entry.name === "string" ? entry.name : null;
+    if (name === null || !LOCAL_NAME_PATTERN.test(name)) {
+      invalid(`${at}.name must be a kebab-case local entry name`, { field: `${at}.name` });
+      continue;
+    }
+    const expectedLogicalName = data.project ? `${data.project}:${name}` : null;
+
+    // Check 2 (SFA-ENTRY-004): qualified logical name consistency + uniqueness.
+    if (typeof entry.logicalName !== "string" || entry.logicalName.length === 0) {
+      invalid(`${at}.logicalName must be a non-empty string`, { field: `${at}.logicalName` });
+    } else {
+      if (expectedLogicalName !== null && entry.logicalName !== expectedLogicalName) {
+        findings.push(
+          finding(
+            KIT_ERROR_KINDS.ENTRY_NAME_INCONSISTENT,
+            "SFC2004",
+            `entry '${name}' logical name is ${entry.logicalName}; the qualified name must be ${expectedLogicalName} (SFA-ENTRY-004)`,
+            { entry: name, declared: entry.logicalName, expected: expectedLogicalName },
+          ),
+        );
+      }
+      if (seenLogicalNames.has(entry.logicalName)) {
+        findings.push(
+          finding(
+            KIT_ERROR_KINDS.ENTRY_NAME_INCONSISTENT,
+            "SFC2004",
+            `logical name ${entry.logicalName} is declared more than once (SFA-ENTRY-004)`,
+            { entry: name, declared: entry.logicalName },
+          ),
+        );
+      }
+      seenLogicalNames.add(entry.logicalName);
+    }
+
+    const form = entry.form;
+    if (!ENTRY_FORMS.includes(form)) {
+      invalid(`${at}.form must be one of: ${ENTRY_FORMS.join(", ")} (got ${JSON.stringify(form ?? null)})`, {
+        field: `${at}.form`,
+      });
+      continue;
+    }
+    const physicalRef = typeof entry.physicalRef === "string" ? entry.physicalRef : null;
+    if (physicalRef === null || physicalRef.length === 0 || physicalRef.startsWith("/") || physicalRef.split("/").includes("..")) {
+      invalid(`${at}.physicalRef must be a contained relative path`, { field: `${at}.physicalRef` });
+      continue;
+    }
+    if (!physicalRef.endsWith("/SKILL.md") && physicalRef !== "SKILL.md") {
+      invalid(`${at}.physicalRef must name a SKILL.md file for form skill_md`, { field: `${at}.physicalRef` });
+      continue;
+    }
+
+    // Check 1 (SFA-ENTRY-003): physical presence in the declared form.
+    let text = null;
+    try {
+      text = await readFileContained(rootAbs, physicalRef, { encoding: "utf8" });
+    } catch (cause) {
+      const kind = cause && cause.details ? cause.details.kind : null;
+      if (kind === "missing-resource") {
+        findings.push(
+          finding(
+            KIT_ERROR_KINDS.ENTRY_PHYSICAL_MISSING,
+            "SFC2004",
+            `entry '${name}' physical SKILL.md is absent: ${physicalRef} (SFA-ENTRY-003)`,
+            { entry: name, path: physicalRef },
+          ),
+        );
+      } else {
+        // Escaping or unsafe references are target-supplied data: report, never follow.
+        findings.push(
+          finding(
+            KIT_ERROR_KINDS.ENTRY_PHYSICAL_MISSING,
+            "SFC2004",
+            `entry '${name}' physicalRef is not safely readable inside the target: ${physicalRef} (kind: ${kind ?? "unknown"})`,
+            { entry: name, path: physicalRef, causeKind: kind ?? "unknown" },
+          ),
+        );
+      }
+      continue;
+    }
+
+    // Check 3 (SFA-ENTRY-005): human entries stay outside method registration.
+    if (entry.humanEntry === true && entry.logicalName && registeredMethods.includes(entry.logicalName)) {
+      findings.push(
+        finding(
+          KIT_ERROR_KINDS.ENTRY_HUMAN_REGISTERED,
+          "SFC2004",
+          `human entry '${name}' appears in the method-registration boundary: ${entry.logicalName} (SFA-ENTRY-005)`,
+          { entry: name, logicalName: entry.logicalName },
+        ),
+      );
+    }
+
+    // Check 4 (SFA-ENTRY-007): read-only obligation vs declared side-effect class.
+    if (!ENTRY_SIDE_EFFECT_CLASSES.includes(entry.sideEffectClass)) {
+      invalid(
+        `${at}.sideEffectClass must be one of: ${ENTRY_SIDE_EFFECT_CLASSES.join(", ")} (got ${JSON.stringify(entry.sideEffectClass ?? null)})`,
+        { field: `${at}.sideEffectClass` },
+      );
+    } else if (entry.readOnlyRequired === true && entry.sideEffectClass !== "read_only") {
+      findings.push(
+        finding(
+          KIT_ERROR_KINDS.ENTRY_SIDE_EFFECT_VIOLATION,
+          "SFC2004",
+          `entry '${name}' is obligated read-only but declares side-effect class ${entry.sideEffectClass} (SFA-ENTRY-007)`,
+          { entry: name, declared: entry.sideEffectClass, expected: "read_only" },
+        ),
+      );
+    }
+
+    // Check 5 (SFA-CONTEXT-001/002): token budget via the frozen consumption
+    // contract. consumeTokenEstimateStrict throws fail-closed on a
+    // non-consumable estimate; the throw propagates as a mechanism error.
+    let tokens = null;
+    if (budgetUsable && warnLimitTokens < hardLimitTokens) {
+      const record = estimateTokens(text);
+      tokens = consumeTokenEstimateStrict(record);
+      if (tokens >= hardLimitTokens) {
+        findings.push(
+          finding(
+            KIT_ERROR_KINDS.ENTRY_TOKEN_BUDGET_EXCEEDED,
+            "SFC2004",
+            `entry '${name}' SKILL.md reaches the hard token line (${tokens} >= ${hardLimitTokens}, SFA-CONTEXT-002)`,
+            { entry: name, path: physicalRef, tokens, limit: hardLimitTokens, rule: "SFA-CONTEXT-002" },
+          ),
+        );
+      } else if (tokens >= warnLimitTokens) {
+        findings.push(
+          finding(
+            KIT_ERROR_KINDS.ENTRY_TOKEN_BUDGET_EXCEEDED,
+            "SFC2004",
+            `entry '${name}' SKILL.md reaches the warn token line (${tokens} >= ${warnLimitTokens}, SFA-CONTEXT-001)`,
+            { entry: name, path: physicalRef, tokens, limit: warnLimitTokens, rule: "SFA-CONTEXT-001" },
+          ),
+        );
+      }
+    }
+
+    data.entries.push({
+      name,
+      logicalName: typeof entry.logicalName === "string" ? entry.logicalName : null,
+      physicalRef,
+      humanEntry: entry.humanEntry === true,
+      sideEffectClass: entry.sideEffectClass ?? null,
+      tokens,
+    });
+  }
+
+  return entryReport(data, findings);
+}
+
+function entryReport(data, findings) {
+  return {
+    kind: "skill-family.entry-check-report",
+    schemaVersion: 1,
+    generatedBy: { tool: KIT_TOOL_NAME, version: KIT_VERSION },
+    target: { root: "." },
+    declared: data.declared,
+    documentState: data.documentState,
+    ok: findings.length === 0,
+    exitCode: findings.length === 0 ? 0 : 1,
+    findings,
+    data,
+    policy:
+      "entry contract gate is diagnosis only: it reads declarations and SKILL.md bytes, estimates tokens through the authoritative estimator and the frozen consumption contract, and never writes",
+  };
+}
+
+/**
+ * CLI sub-action wrapper (positioned as `check entries`, parallel to
+ * `check report`). Returns { status, output } where status maps to the
+ * stable kit exit codes: ok -> 0, findings -> 1; mechanism failures throw
+ * and the CLI maps them to 2.
+ */
+export async function checkEntriesAction({ root } = {}) {
+  const output = await runEntryContractCheck({ root });
+  return { status: output.ok ? "ok" : "findings", output };
+}

package/src/errors.mjs

@@ -52,6 +52,10 @@ export const KIT_ERROR_KINDS = Object.freeze({
   CHECK_CLASS_FAILED: "check-class-failed",
   MANAGED_FILE_MISSING: "managed-file-missing",
   MANAGED_FILE_DRIFT: "managed-file-drift",
+  // never-built distinction (SG-37): every well-formed managed entry declared
+  // in the lock is absent on disk — the build outputs were never produced.
+  // Distinguished from content drift; carries build-first guidance.
+  NEVER_BUILT: "never-built",
   SYMLINK_AT_MANAGED_PATH: "symlink-at-managed-path",
   NOT_A_REGULAR_FILE: "not-a-regular-file",
   CLOSURE_INPUT_MISSING: "closure-input-missing",
@@ -67,10 +71,27 @@ export const KIT_ERROR_KINDS = Object.freeze({
   SYMLINK_ENTRY: "symlink-entry",
   SPECIAL_ENTRY: "special-entry",
   UNCONTAINED_DECLARATION: "uncontained-declaration",
+  // check extensions (audit remediation C2: SG-13/14, SG-17, SFA-PLAT-002)
+  VERSION_AUTHORITY_DUAL: "version-authority-dual",
+  VERSION_SINGLE_SOURCE_DRIFT: "version-single-source-drift",
+  PUBLIC_BOUNDARY_VIOLATION: "public-boundary-violation",
+  PLATFORM_SUBSET_INVALID: "platform-subset-declaration-invalid",
+  PLATFORM_SUBSET_VERSION_DRIFT: "platform-subset-version-drift",
+  // entry contract gate sub-action (SG-34: SFA-ENTRY-003/004/005/007 + SFA-CONTEXT-001/002)
+  ENTRY_CONTRACT_INVALID: "entry-contract-declaration-invalid",
+  ENTRY_CONTRACT_VERSION_DRIFT: "entry-contract-version-drift",
+  ENTRY_PHYSICAL_MISSING: "entry-physical-missing",
+  ENTRY_NAME_INCONSISTENT: "entry-name-inconsistent",
+  ENTRY_HUMAN_REGISTERED: "entry-human-registered",
+  ENTRY_SIDE_EFFECT_VIOLATION: "entry-side-effect-violation",
+  ENTRY_TOKEN_BUDGET_EXCEEDED: "entry-token-budget-exceeded",
   // report sub-actions (projection report / check report, FND-ADR-005)
   REPORT_INPUT_MISSING: "report-input-missing",
   REPORT_PATH_CONFLICT: "report-path-conflict",
   REPORT_WRITE_FAILED: "report-write-failed",
+  // controlled relock channel (SG-36; audit friction F5): `check relock`
+  RELOCK_REGISTRATION_REFUSED: "relock-registration-refused",
+  RELOCK_LOCK_DRIFT: "relock-lock-drift",
   // read-only host integration slice
   HOST_CONTRACT_INVALID: "host-contract-invalid",
   HOST_PROBE_FAILED: "host-probe-failed",

package/src/index.mjs

@@ -1,7 +1,21 @@
 import { ContractsError } from "skill-family-contracts";
-import { buildHandoffDraft, HANDOFF_FIELDS, planAdoption } from "./adopt-plan.mjs";
-import { CHECK_CLASSES, DOCUMENT_STATES, runChecks } from "./check.mjs";
+import { buildProfileDraft, planAdoption } from "./adopt-plan.mjs";
+import { CHECK_CLASSES, DOCUMENT_STATES, PLATFORM_SUBSET_DECLARATION_KIND, runChecks } from "./check.mjs";
 import { CORE_CHECK_SECURITY_KINDS, isContainedDeclaration, runCoreCheck } from "./core-check.mjs";
+import {
+  checkEntriesAction,
+  ENTRY_CONTRACT_DECLARATION_KIND,
+  ENTRY_CONTRACT_DECLARATION_PATH,
+  ENTRY_FORMS,
+  ENTRY_SIDE_EFFECT_CLASSES,
+  runEntryContractCheck,
+} from "./entry-check.mjs";
+import {
+  RELOCK_LOCK_PATH_PATTERN,
+  RELOCK_REPORT_KIND,
+  relockAction,
+  runRelock,
+} from "./relock.mjs";
 import {
   invalidParamsError,
   KitError,
@@ -51,7 +65,7 @@ import {
   listLicensingProfiles,
   loadLicensingProfile,
 } from "./licensing.mjs";
-import { compileProjectionPlan, runProjection, loadProjectionManifest } from "./projection.mjs";
+import { compileProjectionPlan, PROJECTION_AUTHORITY_BINDING_KINDS, runProjection, loadProjectionManifest } from "./projection.mjs";
 import { checkReportAction, renderReportAction } from "./report.mjs";
 import { scaffoldTarget } from "./scaffold.mjs";
 import {
@@ -70,8 +84,10 @@ import {
   KIT_VERSION,
   MANAGED_LOCK_PATH,
   normalizeSkeletonInputs,
+  PLATFORM_SUBSET_DECLARATION_PATH,
   PROJECT_MANIFEST_PATH,
   PROJECTION_MANIFEST_PATH,
+  PUBLIC_BOUNDARY_DECLARATION_PATH,
 } from "./skeleton.mjs";
 import { matchAnyGlob } from "./workspace.mjs";
 
@@ -126,7 +142,7 @@ export const COMMAND_SIDE_EFFECTS = Object.freeze({
   check: Object.freeze({
     summary: "契约/漂移/闭包/版本/文档事实/Git 前置状态诊断。",
     sideEffect:
-      "none — diagnosis only: never writes, never auto-fixes; git is probed read-only (one frozen status query at most); the report sub-action (check report) grades one rendered report against its bound machine result and writes nothing",
+      "none — diagnosis only: never writes, never auto-fixes; git is probed read-only (one frozen status query at most); the report sub-action (check report) grades one rendered report against its bound machine result and writes nothing; the entries sub-action (check entries) runs the shared entry contract gate (SFA-ENTRY-003/004/005/007 + SFA-CONTEXT-001/002) over skill-family.entry-contract.json and SKILL.md bytes and writes nothing; the relock sub-action (check relock) is the one controlled exception: one fail-closed transaction writing exactly the two contained state documents (.foundation/file-registry.json and skill-family.managed-file-lock.json), with drift validation before the first write and zero writes on any refusal",
     exitCodes: "0 无发现；1 有发现；2 拒绝/用法/机制错误",
   }),
 });
@@ -190,16 +206,27 @@ export {
 export {
   scaffoldTarget,
   planAdoption,
-  buildHandoffDraft,
-  HANDOFF_FIELDS,
+  buildProfileDraft,
   compileProjectionPlan,
+  PROJECTION_AUTHORITY_BINDING_KINDS,
   runProjection,
   loadProjectionManifest,
   renderReportAction,
   checkReportAction,
+  runEntryContractCheck,
+  checkEntriesAction,
+  ENTRY_CONTRACT_DECLARATION_PATH,
+  ENTRY_CONTRACT_DECLARATION_KIND,
+  ENTRY_FORMS,
+  ENTRY_SIDE_EFFECT_CLASSES,
+  runRelock,
+  relockAction,
+  RELOCK_LOCK_PATH_PATTERN,
+  RELOCK_REPORT_KIND,
   runChecks,
   CHECK_CLASSES,
   DOCUMENT_STATES,
+  PLATFORM_SUBSET_DECLARATION_KIND,
   runCoreCheck,
   CORE_CHECK_SECURITY_KINDS,
   isContainedDeclaration,
@@ -217,6 +244,8 @@ export {
   MANAGED_LOCK_PATH,
   PROJECTION_MANIFEST_PATH,
   IDENTITY_RECORD_PATH,
+  PUBLIC_BOUNDARY_DECLARATION_PATH,
+  PLATFORM_SUBSET_DECLARATION_PATH,
   matchAnyGlob,
   describeHost,
   loadHostRegistry,