简体中文

Recipe: Deterministic Human Report¶

1. Scenario and Non-Scenario¶

Applicable: you need to deterministically render machine results into a human-readable report (Markdown + digest binding + graded checks), writing the paired dual outputs as a group and refusing path aliases and input overwrites.

Not applicable: needs to freely author a report from open business outputs (forbidden); needs model invocation or business orchestration.

2. Architecture Choice and Capability ID¶

Preferred capabilities: foundation.harness.report (validate → render → bind → check, pure functions) and foundation.kit.report (CLI sub-action orchestrating rendering and grading).

3. Preconditions and Trust Boundary¶

A Contracts-validated report-model and operation-result already exist.
Trust boundary: deterministic Markdown escaping; a three-digest binding of model/result/report; the caller must first construct a valid model, and Kit does not derive facts from business outputs.

4. Minimal Code¶

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); // graded check findings

The code above shows the four-step order of model validation, rendering, binding, and graded check.

5. Expected Output and Evidence¶

renderReportMarkdown returns deterministic Markdown; buildBinding produces the three-digest binding; checkReport returns graded check findings. Evidence: packages/skill-family-harness-node/test/report.test.mjs and packages/skill-family-engineering-kit/test/report.test.mjs.

6. Safety / Failure Negative Case¶

// Negative case: report bytes deviate from deterministic re-render -> SFC3003 (REPORT_FACT_DRIFT)
// after manually editing markdown then bind/check, the digest mismatch fails
checkReport(model, result, tamperedMarkdown, binding);
// throws HarnessError, errorCode = "SFC3003"

SFC3001 (digest mismatch) and SFC3002 (missing mandatory element) are likewise hard failures.

7. Copy-Paste Verification Command¶

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

8. Business Logic the Caller Continues to Own¶

Interpretation of the report's business conclusions.
The caller must first construct a valid report-model (Kit does not derive facts from business outputs).

9. Upgrade and Rollback Notes¶

The report is deterministically rendered from machine results, not freely authored; upgrade follows the skill-family-harness-node and skill-family-engineering-kit versions.
The paired dual outputs are written as a group, refusing path aliases and input overwrites; rollback restores from the expect.sha256 pre-state written before the write.