English

Recipe：确定性人类报告¶

1. 场景与非场景¶

适用：需要从机器结果确定性渲染成人类可读报告（Markdown + digest 绑定 + 分级检查），双输出成组写入并拒绝路径别名与输入覆盖。

不适用：需要从开放业务 outputs 自由编报告（禁止）；需要模型调用或业务编排。

2. 架构选择及能力 ID¶

首选能力：foundation.harness.report（validate → render → bind → check，纯函数）与 foundation.kit.report（CLI 子动作编排渲染与分级）。

3. 前置条件与信任边界¶

已存在经 Contracts 校验的 report-model 与 operation-result。
信任边界：Markdown 确定性转义；model/result/report 三摘要绑定；调用方必须先构造合法 model，Kit 不从业务 outputs 推导事实。

4. 最小代码¶

import {
  validateReportModel,
  renderReportMarkdown,
  buildBinding,
  checkReport,
} from "skill-family-harness-node";

validateReportModel(model);
const markdown = renderReportMarkdown(model, { locale: "zh-CN" });
const binding = buildBinding(model, result, markdown);
const graded = checkReport(model, result, markdown, binding); // 分级检查发现

以上代码展示了模型校验、渲染、绑定与分级检查的四步顺序。

5. 预期输出与证据¶

renderReportMarkdown 返回确定性 Markdown；buildBinding 产出三摘要绑定；checkReport 返回分级检查发现。证据：packages/skill-family-harness-node/test/report.test.mjs 与 packages/skill-family-engineering-kit/test/report.test.mjs。

6. 安全/失败负例¶

// 负例：报告字节偏离确定性重渲染 -> SFC3003 (REPORT_FACT_DRIFT)
// 手工改了 markdown 再 bind/check，摘要对不上即失败
checkReport(model, result, tamperedMarkdown, binding);
// 抛 HarnessError，errorCode = "SFC3003"

SFC3001（摘要不一致）、SFC3002（缺强制元素）同样为硬失败。

7. 可复制验证命令¶

node --test packages/skill-family-harness-node/test/report.test.mjs \
           packages/skill-family-engineering-kit/test/report.test.mjs

8. 调用方继续拥有的业务逻辑¶

报告业务结论的解读。
调用方必须先构造合法 report-model（Kit 不从业务 outputs 推导事实）。

9. 升级与回滚注意事项¶

报告由机器结果确定性渲染，不自由撰写；升级跟随 skill-family-harness-node 与 skill-family-engineering-kit 版本。
双输出成组写入，拒绝路径别名与输入覆盖，回滚以写入前的 expect.sha256 前置状态还原。