skill-family-engineering-kit 0.1.3 → 0.2.0

package/docs/setup/index.html

@@ -840,9 +840,9 @@ pnpm check
 </code></pre>
 <ul>
 <li><code>pnpm synth</code> 再生成 projen 受管文件。受管文件只能通过修改 <code>.projenrc.js</code> 间接变更；手写源码、文档和 fixture 不会被 synth 覆盖。</li>
-<li><code>pnpm check</code> 是当前统一根门禁：10 个稳定门禁 ID 按固定顺序串联执行，任一步骤非 0 即整体失败；本仓没有任何 CI/CD workflow，全部门禁都在私有工作区内运行。下方区块由根 <code>package.json</code> 的 <code>scripts.check</code> 机械投影（<code>node scripts/docs/fact-check.mjs</code> 逐字核对，禁止手写清单再次滞后）：</li>
+<li><code>pnpm check</code> 是当前统一根门禁：11 个稳定门禁 ID 按固定顺序串联执行，任一步骤非 0 即整体失败；本仓没有任何 CI/CD workflow，全部门禁都在私有工作区内运行。下方区块由根 <code>package.json</code> 的 <code>scripts.check</code> 机械投影（<code>node scripts/docs/fact-check.mjs</code> 逐字核对，禁止手写清单再次滞后）：</li>
 </ul>
-<!-- BEGIN SKILL-FAMILY-GATE-STAGES v2 (10 stable gate IDs; derived from package.json scripts.check; verified by fact-check) -->
+<!-- BEGIN SKILL-FAMILY-GATE-STAGES v2 (11 stable gate IDs; derived from package.json scripts.check; verified by fact-check) -->
 <ol>
 <li>pnpm run check:structure</li>
 <li>pnpm run check:packages</li>
@@ -854,6 +854,7 @@ pnpm check
 <li>pnpm run check:release-artifacts</li>
 <li>pnpm run check:projen</li>
 <li>pnpm run check:integration</li>
+<li>pnpm run check:artifacts</li>
 </ol>
 <!-- END SKILL-FAMILY-GATE-STAGES -->
 

package/package.json

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

package/src/cli.mjs

@@ -2,7 +2,9 @@
 import { realpathSync } from "node:fs";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { readFileContained, resolveContained } from "skill-family-harness-node";
 import { bundledProfilesRoot } from "./licensing.mjs";
+import { checkReportAction, renderReportAction } from "./report.mjs";
 import {
   COMMAND_SIDE_EFFECTS,
   KIT_EXIT_CODES,
@@ -12,14 +14,23 @@ import {
   unknownCommandError,
   invalidParamsError,
   mutationModeError,
+  describeHost,
+  probeHost,
+  buildHostAdapter,
+  materializeHostBuild,
+  planHost,
+  refuseHostApply,
 } from "./index.mjs";
 
 /**
  * skill-family-engineering-kit CLI.
  *
- * Exactly four top-level commands exist; there is no fifth. Exit codes are
- * stable: 0 = ok/clean, 1 = findings (check), 2 = rejected/usage/mechanism
- * error. Every refusal prints its registered SFC code and stable kind.
+ * Exactly four top-level commands exist; there is no fifth. The report layer
+ * (FND-ADR-005) hangs under two of them as positional sub-actions —
+ * `projection report` (render) and `check report` (graded diagnosis) — not as
+ * a fifth command. Exit codes are stable: 0 = ok/clean, 1 = findings (check),
+ * 2 = rejected/usage/mechanism error. Every refusal prints its registered
+ * SFC code and stable kind.
  */
 
 const HELP_TEXT = `skill-family-engineering-kit —— 构建期工程工具包（恰好四个顶层命令）
@@ -37,15 +48,22 @@ const HELP_TEXT = `skill-family-engineering-kit —— 构建期工程工具包
   projection   投影受管生成物。
                副作用: 只写 manifest 授权且被目标声明为受管的路径；
                未授权路径、手写文件与越界路径一律拒绝（拒绝时零写入）。
+               报告子动作: projection report 将调用方提交的 report-model 确定性渲染为
+               中立 Markdown（FND-ADR-005）；默认只写 stdout，给定 --out/
+               --binding 时只写这两个显式且被 --root 收容的路径（原子写）。
   check        契约/漂移/闭包/版本/文档事实/Git 前置状态诊断。
                副作用: 无 —— 只诊断、绝不自动修复，git 仅只读探测。
+               报告子动作: check report 对一份已渲染报告做分级诊断：
+               硬失败（SFC3001/3002/3003）计为发现（退出码 1）；
+               风格告警只报告、绝不阻塞机器正确的报告。
 
 全局选项:
   --root <dir>  目标工作区根目录（默认当前目录）
   --help, -h    显示本帮助或单个命令的帮助
 
 退出码: 0 成功/无发现；1 check 有发现；2 拒绝/用法/机制错误。
-错误码复用 contracts 的 SFC* 体系（SFC2002/SFC2003/SFC2004 + 稳定 details.kind）。
+错误码复用 contracts 的 SFC* 体系（SFC2002/SFC2003/SFC2004 + 稳定 details.kind；
+报告层硬失败使用 SFC3001/SFC3002/SFC3003）。
 禁止项: git init/commit/push/tag、发布、删除、远端写入；不存在第五个顶层命令。
 `;
 
@@ -61,6 +79,10 @@ function commandHelp(command) {
       "  --licensing-profile <id> 许可证 Profile id（默认 registry 第一个变体）",
       "  --licensing-variant <id> 多变体 Profile 的必选变体 id",
       "  --profiles-root <dir> 许可证 Profile 根目录",
+      "",
+      "宿主构建: skill-family-kit scaffold host-build --root <workspace> --host <id>",
+      "  --path-category <id> --input <relpath> --out <relpath> [--hosts-root <dir>]",
+      "  将完整 source closure 逐字节写入 sibling staging，验证后一次 rename；目标必须不存在。",
     ],
     "adopt-plan": [
       "选项:",
@@ -72,6 +94,11 @@ function commandHelp(command) {
       "  --profiles-root <dir> 许可证 Profile 根目录",
       "  --no-git-spawn        禁用只读 git status 探测，仅用文件系统事实",
       "",
+      "只读宿主子动作: host-describe | host-probe | host-plan | host-apply",
+      "  host-probe 默认不执行进程；仅 --allow-host-spawn + --host-executable <绝对路径> 可启用受审计版本向量；",
+      "  host-plan 必须显式提供 --build-manifest/--probe-facts，绝不隐式探测；",
+      "  host-apply 在本阶段稳定拒绝，且不会产生占位文件或临时目录。",
+      "",
       "  迁移闭环（FND-070）: 只读读取目标仓 skill-family.migration.json",
       "  （旧实现退出清单 + 临时例外）；例外缺 owner/reason/deadline/",
       "  migrationTarget 任一字段即计为冲突；到期例外不自动续期；",
@@ -81,6 +108,13 @@ function commandHelp(command) {
       "选项:",
       "  --root <dir>          目标工作区（默认当前目录）",
       "  --manifest <relpath>  投影 manifest 相对路径（默认 skill-family.projection.json）",
+      "",
+      "报告子动作: skill-family-kit projection report [options]",
+      "  --model <relpath>     经 Contracts 验证的 report-model JSON（必填）",
+      "  --result <relpath>    机器结果 JSON（必填，仅用于摘要和错误绑定核对）",
+      "  --out <relpath>       报告 Markdown 输出路径；缺省时 Markdown 只写 stdout",
+      "  --binding <relpath>   同时写出 report-binding JSON（model/result/report 三摘要）",
+      "  确定性: 同一 report-model 反复渲染字节一致；Harness 不推导状态、不补造事实。",
     ],
     check: [
       "选项:",
@@ -88,6 +122,14 @@ function commandHelp(command) {
       "  --only <class>        只运行一个诊断类: contracts|drift|closure|version|docs|git|identity",
       "  --profiles-root <dir> 许可证 Profile 根目录",
       "  --no-git-spawn        禁用只读 git status 探测，仅用文件系统事实",
+      "",
+      "报告子动作: skill-family-kit check report [options]",
+      "  --report <relpath>    已渲染报告 Markdown（必填，只读）",
+      "  --model <relpath>     对应 report-model JSON（必填，只读）",
+      "  --result <relpath>    对应机器结果 JSON（必填，只读；核对 digest/errors）",
+      "  --binding <relpath>   可选 report-binding JSON；摘要过期即 SFC3001",
+      "  分级: 硬失败（SFC3001/3002/3003）计为发现，退出码 1；",
+      "  风格告警（超长句/重复段/翻译腔/未解释术语）只报告、绝不改变判定。",
     ],
   };
   return [
@@ -172,8 +214,134 @@ const COMMAND_SPECS = {
       "--no-git-spawn": { key: "noGitSpawn", value: false },
     },
   },
+  "projection report": {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--model": { key: "model", value: true },
+      "--result": { key: "result", value: true },
+      "--out": { key: "out", value: true },
+      "--binding": { key: "binding", value: true },
+    },
+  },
+  "check report": {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--report": { key: "report", value: true },
+      "--model": { key: "model", value: true },
+      "--result": { key: "result", value: true },
+      "--binding": { key: "binding", value: true },
+    },
+  },
+  "scaffold host-build": {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--host": { key: "hostId", value: true },
+      "--path-category": { key: "pathCategoryId", value: true },
+      "--input": { key: "input", value: true },
+      "--out": { key: "out", value: true },
+      "--hosts-root": { key: "hostsRoot", value: true },
+    },
+  },
+  "adopt-plan host-describe": {
+    flags: { "--host": { key: "hostId", value: true }, "--hosts-root": { key: "hostsRoot", value: true } },
+  },
+  "adopt-plan host-probe": {
+    flags: {
+      "--host": { key: "hostId", value: true },
+      "--hosts-root": { key: "hostsRoot", value: true },
+      "--allow-host-spawn": { key: "allowHostSpawn", value: false },
+      "--host-executable": { key: "hostExecutable", value: true },
+    },
+  },
+  "adopt-plan host-plan": {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--host": { key: "hostId", value: true },
+      "--path-category": { key: "pathCategoryId", value: true },
+      "--build-manifest": { key: "buildManifest", value: true },
+      "--probe-facts": { key: "probeFacts", value: true },
+      "--hosts-root": { key: "hostsRoot", value: true },
+    },
+  },
+  "adopt-plan host-apply": { flags: {} },
 };
 
+async function readJson(root, relPath, label) {
+  if (!relPath) throw invalidParamsError(`${label} is required`);
+  try {
+    return JSON.parse((await readFileContained(root, relPath)).toString("utf8"));
+  } catch (cause) {
+    if (cause?.code?.startsWith?.("SFC")) throw cause;
+    throw invalidParamsError(`${label} must name valid JSON contained in --root`);
+  }
+}
+
+async function runHostSubAction(command, action, rest) {
+  const specName = `${command} ${action}`;
+  try {
+    if (action === "host-apply") refuseHostApply();
+    const spec = COMMAND_SPECS[specName];
+    const options = parseOptions(rest, { command: specName, flags: spec.flags });
+    const hostsRoot = options.hostsRoot;
+    let output;
+    if (action === "host-describe") {
+      output = await describeHost({ hostId: options.hostId, hostsRoot });
+    } else if (action === "host-probe") {
+      output = await probeHost({ hostId: options.hostId, hostsRoot, allowSpawn: options.allowHostSpawn === true, executable: options.hostExecutable });
+    } else if (action === "host-build") {
+      const root = options.root ?? ".";
+      const input = await readJson(root, options.input, "--input");
+      const build = await buildHostAdapter({ hostId: options.hostId, pathCategoryId: options.pathCategoryId, input, hostsRoot });
+      if (build.status === "built") {
+        if (!options.out) throw invalidParamsError("--out is required");
+        const targetRoot = await resolveContained(root, options.out);
+        await materializeHostBuild({ targetRoot, build });
+      }
+      output = build.status === "built" ? { status: "built", manifest: build.manifest, outputRoot: options.out } : build;
+    } else if (action === "host-plan") {
+      const root = options.root ?? ".";
+      const buildManifest = await readJson(root, options.buildManifest, "--build-manifest");
+      const probeDocument = await readJson(root, options.probeFacts, "--probe-facts");
+      const probeFacts = Array.isArray(probeDocument) ? probeDocument : probeDocument.facts;
+      output = await planHost({ hostId: options.hostId, pathCategoryId: options.pathCategoryId, buildManifest, probeFacts, hostsRoot });
+    }
+    process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    return KIT_EXIT_CODES.ok;
+  } catch (error) {
+    printError(error);
+    return KIT_EXIT_CODES.rejected;
+  }
+}
+
+async function runReportSubAction(command, rest) {
+  const specName = `${command} report`;
+  try {
+    const options = parseOptions(rest, { command: specName, flags: COMMAND_SPECS[specName].flags });
+    if (options.help) {
+      process.stdout.write(`${commandHelp(command)}\n`);
+      return KIT_EXIT_CODES.ok;
+    }
+    const action = command === "projection" ? renderReportAction : checkReportAction;
+    const { status, output } = await action({
+      root: options.root,
+      model: options.model,
+      result: options.result,
+      report: options.report,
+      out: options.out,
+      binding: options.binding,
+    });
+    if (output !== undefined) {
+      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;
+  }
+}
+
 export async function cliMain(argv) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     process.stdout.write(HELP_TEXT);
@@ -185,6 +353,19 @@ export async function cliMain(argv) {
     return KIT_EXIT_CODES.rejected;
   }
 
+  // Positional report sub-actions (FND-ADR-005): `projection report` renders,
+  // `check report` diagnoses. They hang under existing commands; the
+  // four-command vocabulary and runCommand stay untouched.
+  if ((command === "projection" || command === "check") && argv[1] === "report") {
+    return runReportSubAction(command, argv.slice(2));
+  }
+  if (command === "scaffold" && argv[1] === "host-build") {
+    return runHostSubAction(command, "host-build", argv.slice(2));
+  }
+  if (command === "adopt-plan" && ["host-describe", "host-probe", "host-plan", "host-apply"].includes(argv[1])) {
+    return runHostSubAction(command, argv[1], argv.slice(2));
+  }
+
   try {
     const options = parseOptions(argv.slice(1), { command, flags: COMMAND_SPECS[command].flags });
     if (options.help) {

package/src/errors.mjs

@@ -67,6 +67,14 @@ export const KIT_ERROR_KINDS = Object.freeze({
   SYMLINK_ENTRY: "symlink-entry",
   SPECIAL_ENTRY: "special-entry",
   UNCONTAINED_DECLARATION: "uncontained-declaration",
+  // 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",
+  // read-only host integration slice
+  HOST_CONTRACT_INVALID: "host-contract-invalid",
+  HOST_PROBE_FAILED: "host-probe-failed",
+  HOST_BUILD_FAILED: "host-build-failed",
 });
 
 /** Error carrying one frozen SFC code plus a stable kit kind in details. */

package/src/host-drivers.mjs

@@ -0,0 +1,24 @@
+import path from "node:path";
+import { probeVersionVector } from "skill-family-harness-node";
+
+const CAPABILITIES = Object.freeze(["cli", "version", "payload", "registry", "discover", "enabled", "reload", "smoke", "uninstall"]);
+const DRIVERS = Object.freeze({
+  "claude-version-v1": Object.freeze({ executableBasename: "claude", argv: Object.freeze(["--version"]) }),
+  "codex-version-v1": Object.freeze({ executableBasename: "codex", argv: Object.freeze(["--version"]) }),
+});
+
+/**
+ * Selects one audited host-specific driver vector. The generic process and
+ * four-state classification mechanism lives in Harness.
+ */
+export async function probeTrustedVersionDriver({ hostId, driverId, capabilities = CAPABILITIES, executable, allowSpawn = false, timeoutMs = 5000, runner } = {}) {
+  const driver = DRIVERS[driverId];
+  if (!driver) throw new TypeError(`unknown frozen host driver: ${String(driverId)}`);
+  if (allowSpawn && path.basename(executable ?? "") !== driver.executableBasename) {
+    throw new TypeError(`driver ${driverId} requires an explicit ${driver.executableBasename} executable`);
+  }
+  return probeVersionVector({ hostId, capabilities, executable, argv: driver.argv, allowSpawn, timeoutMs, runner });
+}
+
+export const HOST_CAPABILITIES = CAPABILITIES;
+export const HOST_DRIVER_IDS = Object.freeze(Object.keys(DRIVERS));

package/src/host-profiles.mjs

@@ -0,0 +1,51 @@
+import { validateDocument } from "skill-family-contracts";
+import { readFileContained } from "skill-family-harness-node";
+import { invalidParamsError, kitError, KIT_ERROR_KINDS } from "./errors.mjs";
+
+const HOST_DESCRIPTOR_SCHEMA_ID = "https://contracts.skill-family.example/v1/host-descriptor.json";
+const HOST_REGISTRY_SCHEMA_ID = "https://contracts.skill-family.example/v1/host-registry.json";
+const HOST_ID_PATTERN = /^[a-z][a-z0-9-]{1,63}$/;
+
+function validateRegistered(document, schemaId, message) {
+  const result = validateDocument(document, { schemaId, dialect: "2020-12", policy: "strict" });
+  if (!result.valid) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, message, { errors: result.errors });
+  return result.data;
+}
+
+function assertRegistrySemantics(registry) {
+  return registry;
+}
+
+export async function loadHostRegistry({ hostsRoot, registry } = {}) {
+  if (registry !== undefined) return Object.freeze(structuredClone(assertRegistrySemantics(validateRegistered(registry, HOST_REGISTRY_SCHEMA_ID, "host registry fails its registered contract"))));
+  if (!hostsRoot) throw invalidParamsError("loadHostRegistry requires an explicit hostsRoot or injected registry");
+  let document;
+  try {
+    document = JSON.parse((await readFileContained(hostsRoot, "registry.json")).toString("utf8"));
+  } catch (cause) {
+    if (cause?.code?.startsWith?.("SFC")) throw cause;
+    throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "host registry cannot be read or parsed", { causeKind: cause?.details?.kind ?? "unknown" });
+  }
+  return Object.freeze(structuredClone(assertRegistrySemantics(validateRegistered(document, HOST_REGISTRY_SCHEMA_ID, "host registry fails its registered contract"))));
+}
+
+export async function describeHost({ hostId, hostsRoot, registry } = {}) {
+  if (!HOST_ID_PATTERN.test(hostId ?? "")) throw invalidParamsError("describeHost requires a valid hostId");
+  const loaded = await loadHostRegistry({ hostsRoot, registry });
+  if (!loaded.hosts.includes(hostId)) throw invalidParamsError(`unknown host: ${hostId}`, { hostId });
+  if (!hostsRoot) throw invalidParamsError("host descriptor resolution requires an explicit hostsRoot");
+  let document;
+  try {
+    document = JSON.parse((await readFileContained(hostsRoot, `${hostId}/host-descriptor.json`)).toString("utf8"));
+  } catch (cause) {
+    if (cause?.code?.startsWith?.("SFC")) throw cause;
+    throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "host descriptor cannot be read or parsed", { hostId, causeKind: cause?.details?.kind ?? "unknown" });
+  }
+  const descriptor = validateRegistered(document, HOST_DESCRIPTOR_SCHEMA_ID, "host descriptor fails its registered contract");
+  if (descriptor.hostId !== hostId) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "host descriptor hostId does not match its registry entry", { hostId });
+  const categoryIds = descriptor.pathCategories.map((category) => category.id);
+  if (new Set(categoryIds).size !== categoryIds.length) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "host descriptor has duplicate path category ids", { hostId });
+  return Object.freeze(structuredClone(descriptor));
+}
+
+export { HOST_DESCRIPTOR_SCHEMA_ID, HOST_REGISTRY_SCHEMA_ID };

package/src/host.mjs

@@ -0,0 +1,108 @@
+import path from "node:path";
+import { canonicalJson, digestDocument, validateDocument } from "skill-family-contracts";
+import {
+  buildAdapterClosure,
+  materializeAdapterBuild,
+  verifyAdapterBuildManifest,
+} from "skill-family-harness-node";
+import { invalidParamsError, kitError, KIT_ERROR_KINDS } from "./errors.mjs";
+import { HOST_CAPABILITIES, probeTrustedVersionDriver } from "./host-drivers.mjs";
+import { describeHost } from "./host-profiles.mjs";
+
+const FACT_SCHEMA_ID = "https://contracts.skill-family.example/v1/host-capability-fact.json";
+const PROBE_RESULT_SCHEMA_ID = "https://contracts.skill-family.example/v1/host-probe-result.json";
+const PLAN_SCHEMA_ID = "https://contracts.skill-family.example/v1/host-operation-plan.json";
+
+function validateContract(document, schemaId, message) {
+  const result = validateDocument(document, { schemaId, dialect: "2020-12", policy: "strict" });
+  if (!result.valid) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, message, { errors: result.errors });
+  return result.data;
+}
+
+function selectCategory(descriptor, pathCategoryId) {
+  const category = descriptor.pathCategories.find((candidate) => candidate.id === pathCategoryId);
+  if (!category) throw invalidParamsError(`host ${descriptor.hostId} does not declare path category ${String(pathCategoryId)}`);
+  return { id: category.id, scope: category.scope, anchor: category.anchor, relPath: category.relPath };
+}
+
+export async function probeHost({ hostId, hostsRoot, registry, executable, allowSpawn = false, timeoutMs = 5000, runner } = {}) {
+  const descriptor = await describeHost({ hostId, hostsRoot, registry });
+  if (descriptor.support === "unsupported") {
+    return validateContract({ schemaVersion: 1, kind: "skill-family.host-probe-result", hostId, support: "unsupported", reason: descriptor.unsupportedReason, facts: [] }, PROBE_RESULT_SCHEMA_ID, "unsupported probe result fails its contract");
+  }
+  const facts = await probeTrustedVersionDriver({
+    hostId,
+    driverId: descriptor.driverId,
+    capabilities: descriptor.probeCapabilities,
+    executable,
+    allowSpawn,
+    timeoutMs,
+    runner,
+  });
+  for (const fact of facts) validateContract(fact, FACT_SCHEMA_ID, "host driver emitted an invalid capability fact");
+  const names = facts.map((fact) => fact.capability);
+  if (new Set(names).size !== HOST_CAPABILITIES.length || !HOST_CAPABILITIES.every((name) => names.includes(name))) {
+    throw kitError(KIT_ERROR_KINDS.HOST_PROBE_FAILED, "host driver did not emit the exact capability fact set");
+  }
+  return validateContract({ schemaVersion: 1, kind: "skill-family.host-probe-result", hostId, support: "supported", facts }, PROBE_RESULT_SCHEMA_ID, "host probe result fails its contract");
+}
+
+export async function buildHostAdapter({ hostId, pathCategoryId, input, hostsRoot, registry } = {}) {
+  const descriptor = await describeHost({ hostId, hostsRoot, registry });
+  if (descriptor.support !== "supported") return { status: "unsupported", reason: descriptor.unsupportedReason };
+  return buildAdapterClosure({ hostId, pathCategory: selectCategory(descriptor, pathCategoryId), input });
+}
+
+export async function materializeHostBuild(options) {
+  return materializeAdapterBuild(options);
+}
+
+function validateFactSet(hostId, facts) {
+  if (!Array.isArray(facts) || facts.length !== HOST_CAPABILITIES.length) throw invalidParamsError(`planHost requires exactly ${HOST_CAPABILITIES.length} explicit probe facts`);
+  for (const fact of facts) {
+    validateContract(fact, FACT_SCHEMA_ID, "planHost received an invalid probe fact");
+    if (fact.hostId !== hostId) throw invalidParamsError("probe fact hostId does not match the planned host");
+  }
+  const names = facts.map((fact) => fact.capability);
+  if (new Set(names).size !== names.length || !HOST_CAPABILITIES.every((name) => names.includes(name))) throw invalidParamsError("probe facts must cover each capability exactly once");
+  return [...facts].sort((left, right) => HOST_CAPABILITIES.indexOf(left.capability) - HOST_CAPABILITIES.indexOf(right.capability));
+}
+
+export async function planHost({ hostId, pathCategoryId, buildManifest, probeFacts, hostsRoot, registry } = {}) {
+  const descriptor = await describeHost({ hostId, hostsRoot, registry });
+  if (descriptor.support !== "supported") {
+    const base = { schemaVersion: 1, kind: "skill-family.host-operation-plan", hostId, status: "unsupported", unsupportedReason: descriptor.unsupportedReason, probeFacts: [], actions: [], writeSet: [] };
+    return validateContract({ ...base, digest: digestDocument(base) }, PLAN_SCHEMA_ID, "unsupported host plan fails its contract");
+  }
+  const category = selectCategory(descriptor, pathCategoryId);
+  const facts = validateFactSet(hostId, probeFacts);
+  const manifest = verifyAdapterBuildManifest(buildManifest, { hostId, pathCategory: category });
+  const actions = manifest.members.map((member, index) => ({ sequence: index + 1, kind: "install-file", categoryId: category.id, scope: category.scope, anchor: category.anchor, target: member.target, expect: "absent", sourceSha256: member.sha256 }));
+  const writeSet = actions.map(({ categoryId, scope, anchor, target, sourceSha256 }) => ({ categoryId, scope, anchor, target, sourceSha256 }));
+  const base = { schemaVersion: 1, kind: "skill-family.host-operation-plan", hostId, status: "planned", pathCategory: category, probeFacts: facts, actions, writeSet };
+  const plan = validateContract({ ...base, digest: digestDocument(base) }, PLAN_SCHEMA_ID, "host operation plan fails its contract");
+  assertPlanConsistency(plan);
+  return plan;
+}
+
+export function assertPlanConsistency(planInput) {
+  const plan = validateContract(planInput, PLAN_SCHEMA_ID, "host operation plan fails its registered contract");
+  const { digest, ...base } = plan;
+  if (digestDocument(base) !== digest) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "plan digest does not match its content");
+  if (plan.status === "unsupported") return true;
+  if (plan.actions.length !== plan.writeSet.length) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "plan actions/writeSet lengths differ");
+  for (let index = 0; index < plan.actions.length; index += 1) {
+    const action = plan.actions[index];
+    const write = plan.writeSet[index];
+    const normalized = path.posix.normalize(action.target);
+    if (normalized !== action.target || normalized.startsWith("../") || path.isAbsolute(action.target)) throw invalidParamsError("plan target must be a normalized contained path");
+    if (action.sequence !== index + 1 || action.categoryId !== plan.pathCategory.id || action.scope !== plan.pathCategory.scope || action.anchor !== plan.pathCategory.anchor || !action.target.startsWith(`${plan.pathCategory.relPath}/`) || canonicalJson(write) !== canonicalJson({ categoryId: action.categoryId, scope: action.scope, anchor: action.anchor, target: action.target, sourceSha256: action.sourceSha256 })) {
+      throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "plan action, target, writeSet, category and anchor are inconsistent");
+    }
+  }
+  return true;
+}
+
+export function refuseHostApply() {
+  throw invalidParamsError("host apply is not implemented in the read-only Phase D slice", { action: "apply", stableRefusal: true });
+}

package/src/index.mjs

@@ -51,7 +51,17 @@ import {
   loadLicensingProfile,
 } from "./licensing.mjs";
 import { runProjection, loadProjectionManifest } from "./projection.mjs";
+import { checkReportAction, renderReportAction } from "./report.mjs";
 import { scaffoldTarget } from "./scaffold.mjs";
+import {
+  assertPlanConsistency,
+  buildHostAdapter,
+  materializeHostBuild,
+  planHost,
+  probeHost,
+  refuseHostApply,
+} from "./host.mjs";
+import { describeHost, loadHostRegistry } from "./host-profiles.mjs";
 import {
   describeSkeletonFiles,
   IDENTITY_RECORD_PATH,
@@ -109,13 +119,13 @@ export const COMMAND_SIDE_EFFECTS = Object.freeze({
   projection: Object.freeze({
     summary: "投影受管生成物。",
     sideEffect:
-      "writes only manifest-authorized managed artifacts; unauthorized, handwritten, escaping, or conflicting paths are refused with zero writes",
+      "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",
     exitCodes: "0 成功；2 拒绝/用法/机制错误",
   }),
   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)",
+      "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",
     exitCodes: "0 无发现；1 有发现；2 拒绝/用法/机制错误",
   }),
 });
@@ -183,6 +193,8 @@ export {
   HANDOFF_FIELDS,
   runProjection,
   loadProjectionManifest,
+  renderReportAction,
+  checkReportAction,
   runChecks,
   CHECK_CLASSES,
   DOCUMENT_STATES,
@@ -204,6 +216,14 @@ export {
   PROJECTION_MANIFEST_PATH,
   IDENTITY_RECORD_PATH,
   matchAnyGlob,
+  describeHost,
+  loadHostRegistry,
+  probeHost,
+  buildHostAdapter,
+  materializeHostBuild,
+  planHost,
+  assertPlanConsistency,
+  refuseHostApply,
 };
 export { ContractsError };