skill-family-doc-render 0.4.5 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 变更日志
 
+## 0.5.0 - 2026-09-28
+
+### 新增
+
+- `--check-project` 可以附带 `--conclusion-output <绝对路径>`。机械检查结束后，CLI 排他创建一份共同证明，不覆盖已有文件，也不改站点。
+- 新增 `--read-proof --proof-root <root> --proof <相对路径>`。它读取一份本族旧证明并打印 JSON，不重新扫描目标，也不要求网站配置。该模式与 `--check-project` 互斥。
+
+### 变更
+
+- 渲染器、文档插件和公开站点的本地源版本对齐为 0.5.0，作为计划中的联合发布目标。安装或 `npx` 前，先在官方 npm 确认 `skill-family-doc-render@0.5.0` 可用。
+- 已发布的 0.4.5 没有 `--conclusion-output` 和 `--read-proof`。本版出证和读证示例使用精确的 `npx skill-family-doc-render@0.5.0`。
+
+### 说明
+
+- 当前源码的出证和读证已在本地候选上验证。可引用的记录仍是当时的直接 CLI 与四场 Codex 代表场景，覆盖限制保持原记录。负向场景只说明当时如实停止。
+- 旧证明只记录原目标当时的结论。机械检查通过只说明机械范围，链接通过不代替中文语义审阅。记载未通过、未完成或未能开展检查的证明，结论保持为未通过。
+- 0.5.0 的发布、Hub 登记和四个宿主的新回复验收，以各自的官方记录为准。历史五类宿主的入口调用仍限于当时范围。
+
 ## 0.4.5 - 2026-09-10
 
 ### 变更

package/README.md

@@ -16,64 +16,99 @@ publication APIs. A failure before commit removes staging and leaves the existin
 untouched. After commit, or when publication is indeterminate, staging or displaced data may
 remain for diagnosis; the renderer does not guess or roll back.
 
-> **Version boundary:** this source tree is version `0.4.5`. Verify that exact version in the
-> official npm registry before treating it as installable. Version 0.4.5 preserves the
-> `markdown-v1`, `editorial`, and `--check-project` behavior introduced in 0.4.0 and aligns the
-> renderer, documentation plugin, and public site at 0.4.5 for the joint release.
+> **Version boundary:** this source tree is version `0.5.0`. That is the local version and the
+> intended joint target for the renderer, documentation plugin, and public site. Confirm this
+> exact version in the official npm registry before `npm install` or `npx`. Published `0.4.5`
+> preserves the `markdown-v1`, `editorial`, and `--check-project` behavior introduced in 0.4.0
+> and has no `--conclusion-output` or `--read-proof`. Those two commands belong to this 0.5.0
+> CLI. The examples give the command shape for that version. They leave publication, Skill
+> Family Hub registration, and new host-reply acceptance to the official records for `0.5.0`.
 
 ## Install
 
-After confirming availability, install this release with an exact version:
+After confirming `skill-family-doc-render@0.5.0` in the official npm registry, install that exact version:
 
 ```sh
-npm install --save-exact skill-family-doc-render@0.4.5
+npm install --save-exact skill-family-doc-render@0.5.0
 ```
 
 Requires Node.js `>=22.22.2 <23` (aligned with the skill-family foundation packages).
 
-Version 0.4.5 has exact runtime dependencies on `marked@18.0.11`,
-`skill-family-contracts@0.19.3`, and `skill-family-harness-node@0.19.3`. `marked` supplies the
+This checkout currently pins exact runtime dependencies on `marked@18.0.11`,
+`skill-family-contracts@0.22.0`, and `skill-family-harness-node@0.22.0`. `marked` supplies the
 Markdown lexer; the renderer applies its own restricted-format validation before passing semantic
 content to the template. The workspace profile check separately uses
-`skill-family-engineering-kit@0.19.3`.
+`skill-family-engineering-kit@0.22.0`. These pins describe the local source and installed
+packages; they do not republish `0.5.0`.
 The 0.2.0 baseline format and exit-code changes are breaking changes; existing 0.1.x users
 must re-render their baseline before using `--check`. See the changelog for the full migration
 notes.
 
 ## CLI
 
-Use the exact 0.4.5 CLI for rendering, checks, coverage maintenance, and the Git index assertion:
+Use the exact 0.5.0 CLI for rendering, checks, coverage maintenance, the Git index assertion, and the proof commands. Confirm `skill-family-doc-render@0.5.0` in the official npm registry before running them. Published 0.4.5 can run the commands that omit `--conclusion-output` and `--read-proof`.
 
 ```sh
 # render all repos with a site field (writes to disk)
-npx skill-family-doc-render@0.4.5
+npx skill-family-doc-render@0.5.0
 
 # drift check only: compare in-memory render against the on-disk site-baseline.json, write nothing
-npx skill-family-doc-render@0.4.5 --check
+npx skill-family-doc-render@0.5.0 --check
 
 # render / check a single repo by name
-npx skill-family-doc-render@0.4.5 --repo <name>
+npx skill-family-doc-render@0.5.0 --repo <name>
 
 # assert every rendered file is tracked in the Git index, then render
-npx skill-family-doc-render@0.4.5 --assert-git
+npx skill-family-doc-render@0.5.0 --assert-git
 
 # run both the drift and Git index tracking checks without writing
-npx skill-family-doc-render@0.4.5 --check --assert-git
+npx skill-family-doc-render@0.5.0 --check --assert-git
 
 # inspect or refresh the reviewed product-input snapshot
-npx skill-family-doc-render@0.4.5 --status --repo <name>
-npx skill-family-doc-render@0.4.5 --refresh-coverage --repo <name>
-npx skill-family-doc-render@0.4.5 --check-project --repo <name>
+npx skill-family-doc-render@0.5.0 --status --repo <name>
+npx skill-family-doc-render@0.5.0 --refresh-coverage --repo <name>
+npx skill-family-doc-render@0.5.0 --check-project --repo <name>
+
+# after the mechanical check, exclusive-create one proof; do not overwrite
+npx skill-family-doc-render@0.5.0 --check-project --repo <name> --conclusion-output /absolute/path/conclusion.json
+
+# read one existing proof from any working directory; write nothing
+npx skill-family-doc-render@0.5.0 --read-proof --proof-root /absolute/proof-root --proof relative/conclusion.json
 ```
 
-The current directory must be the workspace that owns `public-release.json`. From this package's
-source checkout, `node bin/skill-family-doc-render.mjs` is the equivalent local CLI entry.
+`--check-project` still requires the current directory to own `public-release.json`.
+`--read-proof` does not read that file and does not require a site configuration.
 
 `--check-project` requires exactly one `--repo <name>`. It cannot be combined with `--check`,
-`--status`, `--refresh-coverage`, `--assert-git`, or `--help`. It checks input and public-content
-safety, the mechanical Markdown contract, coverage freshness, the in-memory render and baseline,
-then internal links and resources. It writes nothing. A failure identifies the repo,
-`public-release.json`, the reason, and a copyable `skill-family-docs-render-site` recovery prompt.
+`--status`, `--refresh-coverage`, `--assert-git`, `--help`, or `--read-proof`. It checks input and
+public-content safety, the mechanical Markdown contract, coverage freshness, the in-memory render
+and baseline, then internal links and resources. It does not re-render to make the check pass, and
+it does not run target scripts or hooks. Without `--conclusion-output` it writes nothing. A failure
+identifies the repo, `public-release.json`, the reason, and a copyable
+`skill-family-docs-render-site` recovery prompt.
+
+`--conclusion-output` is optional and only valid with `--check-project`. The path must be
+absolute. When present, the renderer exclusive-writes one Foundation
+`professional-conclusion` file after the mechanical check. It does not replace an existing file.
+The conclusion records only checks that actually ran. Domain codes are `DOCS_CLEAR`,
+`DOCS_FINDINGS`, `DOCS_CHECK_INCOMPLETE`, and `DOCS_CHECK_UNAVAILABLE`. The renderer conclusion is
+mechanical only; a passing link check is not a Chinese semantic review. A stored proof records
+the original target's conclusion at that time.
+
+`--read-proof` is mutually exclusive with `--check-project`. It reads one proof from
+`--proof-root` + `--proof`, validates the common structure, and prints a JSON result with
+`status` (`pass`, `not_pass`, or `unavailable`), `reason`, `provider`, and `conclusion`.
+It does not rescan the project, follow paths inside the proof, or execute the target.
+Same-version `DOCS_CLEAR` maps to `pass` only when `completion` is `complete`;
+`DOCS_FINDINGS`, `DOCS_CHECK_INCOMPLETE`, and `DOCS_CHECK_UNAVAILABLE` map to `not_pass`.
+That status keeps the proof's recorded non-pass. A missing file, damaged JSON, a different
+provider, or an unknown same-version domain code is `unavailable` (exit `2`). Earlier
+local-candidate runs exercised proof output and proof reading; those runs keep their original
+scene limits. Publication, Hub registration, and new host replies for `0.5.0` stay with the
+official records. These proof commands consume the Foundation
+`professional-conclusion` contract from `skill-family-contracts@0.22.0`. Refreshing a proof
+means running `--check-project` again to a new output path. Remediation, site creation, and
+render writes stay on their original authorized commands.
 
 Exit codes: `0` success; `1` drift/status class — `--check` drift, leak-scan hit, `--assert-git`
 untracked rendered files, missing/corrupt render baseline, or missing/stale coverage snapshot; `2`
@@ -283,9 +318,11 @@ Foundation packages below, it uses exact `marked@18.0.11` for Markdown tokenizat
 Apache-2.0
 
 <!-- release-skill:capability:safe-first-command -->
-> **Start here:** run `npx skill-family-doc-render@0.4.5 --check-project --repo <name>` after
-> confirming that exact release in the official registry. From a local checkout, use
-> `node bin/skill-family-doc-render.mjs --check-project --repo <name>`. The check is read-only:
+> **Start here:** run `npx skill-family-doc-render@0.5.0 --check-project --repo <name>` after
+> confirming that exact version in the official registry. From a local checkout, stay in the
+> directory that owns `public-release.json` and call
+> `node /absolute/path/to/skill-family-doc-render/bin/skill-family-doc-render.mjs --check-project --repo <name>`,
+> replacing the placeholder with the real source path. The check is read-only:
 > it renders in memory, compares against the on-disk `site-baseline.json`, writes
 > nothing and touches no network or credentials. The CLI performs no Git writes; only an
 > explicit `--assert-git` performs a read-only query of the Git index.
@@ -294,7 +331,9 @@ Apache-2.0
 > **External write boundary:** rendering writes the declared target and a controlled sibling
 > staging directory, both within the target's canonical parent, with contained path checks. An
 > explicit `--refresh-coverage` writes only the declared coverage lock through an atomic file
-> replacement. `--status`, `--check`, and `--check-project` write nothing.
+> replacement. `--status`, `--check`, and `--check-project` write nothing unless
+> `--check-project` is given an explicit `--conclusion-output`, which exclusive-creates that
+> proof file and never overwrites it. `--read-proof` writes nothing.
 > Render, scan, baseline and `--assert-git` preflight failures happen before target changes.
 > Staging is removed after success or a clearly pre-commit failure; post-commit or
 > indeterminate failures may retain it to preserve diagnosable state.
@@ -307,6 +346,6 @@ Apache-2.0
 Display help and run a read-only project check:
 
 ```sh
-npx skill-family-doc-render@0.4.5 --help
-npx skill-family-doc-render@0.4.5 --check-project --repo <name>
+npx skill-family-doc-render@0.5.0 --help
+npx skill-family-doc-render@0.5.0 --check-project --repo <name>
 ```

package/bin/skill-family-doc-render.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: Apache-2.0
-// CLI 入口：全部 argv 原样委托给 main()，闭集解析与 --help/-h 呈现统一由 main() 裁决。
+// CLI 入口：全部 argv 原样委托给 main()。闭集解析、--help/-h、
+// --check-project / --read-proof 互斥路由均由 main() 裁决。
 import { main, RenderError } from '../scripts/render-public-site.mjs';
 
 main(process.argv.slice(2), { cwd: process.cwd() })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-family-doc-render",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Config-driven GitHub Pages knowledge-site renderer for skill-family projects (multi-repo capable).",
   "author": "广州市风荷科技有限公司",
   "license": "Apache-2.0",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "marked": "18.0.11",
-    "skill-family-contracts": "0.19.3",
-    "skill-family-harness-node": "0.19.3"
+    "skill-family-contracts": "0.22.0",
+    "skill-family-harness-node": "0.22.0"
   }
 }

package/scripts/professional-conclusion.mjs

@@ -0,0 +1,360 @@
+// SPDX-License-Identifier: Apache-2.0
+// 文档族共同证明：把机械 --check-project 结果投影为 professional-conclusion，
+// 并读取本族证明。结构校验与文件读写使用 Foundation 公共入口；本模块只保留
+// DOCS 领域码、实际检查范围和原因转换。
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { findSchemaByObject, validateDocument } from 'skill-family-contracts';
+import {
+  HARNESS_ERROR_KINDS,
+  publishFileExclusive,
+  readFileStrict,
+  resolveContained,
+} from 'skill-family-harness-node';
+import { RenderedLinksError } from './lib/rendered-links.mjs';
+
+export const PROVIDER_ID = 'skill-family-doc-render';
+
+export const DOCS_CODES = Object.freeze({
+  CLEAR: 'DOCS_CLEAR',
+  FINDINGS: 'DOCS_FINDINGS',
+  INCOMPLETE: 'DOCS_CHECK_INCOMPLETE',
+  UNAVAILABLE: 'DOCS_CHECK_UNAVAILABLE',
+});
+
+export const CHECK_STAGE_IDS = Object.freeze([
+  'input-and-public-safety',
+  'coverage-freshness',
+  'in-memory-render-and-baseline',
+  'internal-links-and-resources',
+]);
+
+const MECHANICAL_LIMITATION = '本证明只覆盖渲染器机械检查，不含中文语义审阅。';
+
+const PROVIDER_VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
+
+export class ProofError extends Error {
+  constructor(message, exitCode = 2, cause) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.exitCode = exitCode;
+  }
+}
+
+export function providerInfo(entry) {
+  return { id: PROVIDER_ID, version: PROVIDER_VERSION, entry };
+}
+
+function professionalSchemaRegistration() {
+  return findSchemaByObject('professional-conclusion');
+}
+
+export function requireProfessionalSchemaId() {
+  const registration = professionalSchemaRegistration();
+  if (!registration?.$id || !registration.dialect) {
+    throw new ProofError(
+      '[skill-family-doc-render] 缺少 Foundation professional-conclusion Schema，需要精确安装 skill-family-contracts@0.22.0',
+      2,
+    );
+  }
+  return registration;
+}
+
+export function validateProfessionalConclusion(document) {
+  const registration = requireProfessionalSchemaId();
+  return validateDocument(document, {
+    schemaId: registration.$id,
+    dialect: registration.dialect,
+    policy: 'strict',
+  });
+}
+
+function uniqueLimitations(items) {
+  const seen = new Set();
+  const result = [];
+  for (const item of items) {
+    if (typeof item !== 'string' || !item || seen.has(item)) continue;
+    seen.add(item);
+    result.push(item);
+  }
+  return result;
+}
+
+export function buildDocsConclusion({
+  entry,
+  subjectRef,
+  subjectRevision,
+  checked,
+  limitations,
+  completion,
+  code,
+  summary,
+  details,
+}) {
+  const conclusion = {
+    schemaVersion: 1,
+    kind: 'skill-family.professional-conclusion',
+    provider: providerInfo(entry),
+    subject: subjectRevision
+      ? { ref: subjectRef, revision: subjectRevision }
+      : { ref: subjectRef },
+    scope: {
+      checked: [...checked],
+      limitations: uniqueLimitations([MECHANICAL_LIMITATION, ...limitations]),
+    },
+    outcome: { completion, code, summary },
+  };
+  if (details !== undefined) conclusion.details = details;
+  const validation = validateProfessionalConclusion(conclusion);
+  if (!validation.valid) {
+    const detail = (validation.errors || []).map((error) => error.message).join('; ');
+    throw new ProofError(
+      `[skill-family-doc-render] 共同证明结构校验失败: ${validation.errorCode || 'invalid'}${detail ? `: ${detail}` : ''}`,
+      2,
+    );
+  }
+  return validation.data;
+}
+
+function harnessKind(error) {
+  return error?.details?.kind;
+}
+
+function errorCauseChain(error) {
+  const seen = new Set();
+  const chain = [];
+  let current = error;
+  while (current && typeof current === 'object' && !seen.has(current)) {
+    seen.add(current);
+    chain.push(current);
+    current = current.cause;
+  }
+  return chain;
+}
+
+function hasRenderedLinkFailures(error) {
+  return errorCauseChain(error).some(
+    (item) => item instanceof RenderedLinksError && Array.isArray(item.failures) && item.failures.length > 0,
+  );
+}
+
+function hasMissingResourceKind(error) {
+  return errorCauseChain(error).some(
+    (item) => harnessKind(item) === HARNESS_ERROR_KINDS.MISSING_RESOURCE,
+  );
+}
+
+function isDomainFinding(exitCode, cause) {
+  if (exitCode !== 1) return false;
+  if (hasRenderedLinkFailures(cause)) return true;
+  return !hasMissingResourceKind(cause);
+}
+
+export function mapScanToOutcome({
+  ok,
+  exitCode,
+  finished = [],
+  attempted = null,
+  notReached = [],
+  repoSelected = true,
+  cause = null,
+}) {
+  if (ok) {
+    return {
+      completion: 'complete',
+      code: DOCS_CODES.CLEAR,
+      summary: '机械项目检查完成，未发现覆盖、渲染、链接或公开安全问题。',
+      checked: [...CHECK_STAGE_IDS],
+      limitations: [],
+    };
+  }
+  const started = Boolean(repoSelected && (finished.length || attempted));
+  if (!started) {
+    const remaining = attempted ? [attempted, ...notReached] : [...notReached];
+    return {
+      completion: 'not-performed',
+      code: DOCS_CODES.UNAVAILABLE,
+      summary: '未能开展机械项目检查。',
+      checked: [],
+      limitations: remaining.length ? remaining.map((id) => `未执行检查: ${id}`) : ['机械项目检查未开始。'],
+    };
+  }
+  const findings = isDomainFinding(exitCode, cause);
+  const checked = findings && attempted ? [...finished, attempted] : [...finished];
+  const limitations = [];
+  if (!findings && attempted) limitations.push(`未完成检查: ${attempted}`);
+  for (const id of notReached) limitations.push(`未执行检查: ${id}`);
+  if (findings) {
+    return {
+      completion: limitations.length ? 'partial' : 'complete',
+      code: DOCS_CODES.FINDINGS,
+      summary: '机械项目检查发现覆盖、渲染、链接或公开安全问题。',
+      checked,
+      limitations,
+    };
+  }
+  return {
+    completion: checked.length ? 'partial' : 'not-performed',
+    code: DOCS_CODES.INCOMPLETE,
+    summary: '机械项目检查未完成所声明范围。',
+    checked,
+    limitations: limitations.length ? limitations : ['所需项目输入不足。'],
+  };
+}
+
+function identifiableProvider(value) {
+  if (!value || typeof value !== 'object') return null;
+  const id = typeof value.id === 'string' && value.id ? value.id : null;
+  const version = typeof value.version === 'string' && value.version ? value.version : null;
+  const entry = typeof value.entry === 'string' && value.entry ? value.entry : null;
+  if (!id && !version && !entry) return null;
+  return {
+    ...(id ? { id } : {}),
+    ...(version ? { version } : {}),
+    ...(entry ? { entry } : {}),
+  };
+}
+
+function readResult(status, reason, provider, conclusion) {
+  return {
+    status,
+    reason,
+    provider: provider || providerInfo('skill-family-doc-render --read-proof'),
+    conclusion,
+  };
+}
+
+export function interpretDocsProof(document) {
+  const provider = identifiableProvider(document?.provider);
+  if (!document || typeof document !== 'object' || Array.isArray(document)) {
+    return readResult('unavailable', '证明不是 JSON 对象。', provider, null);
+  }
+  let validation;
+  try {
+    validation = validateProfessionalConclusion(document);
+  } catch (cause) {
+    if (cause instanceof ProofError) {
+      return readResult('unavailable', cause.message, provider, null);
+    }
+    throw cause;
+  }
+  if (!validation.valid) {
+    return readResult(
+      'unavailable',
+      `证明不符合 professional-conclusion 结构: ${validation.errorCode || 'invalid'}`,
+      provider,
+      null,
+    );
+  }
+  const conclusion = validation.data;
+  const recorded = conclusion.provider;
+  if (recorded.id !== PROVIDER_ID) {
+    return readResult(
+      'unavailable',
+      `证明提供方不是 ${PROVIDER_ID}`,
+      recorded,
+      null,
+    );
+  }
+  const code = conclusion.outcome.code;
+  const known = new Set(Object.values(DOCS_CODES));
+  if (!known.has(code)) {
+    return readResult(
+      'unavailable',
+      `未知同版本领域码: ${code}`,
+      recorded,
+      conclusion,
+    );
+  }
+  if (code === DOCS_CODES.CLEAR && conclusion.outcome.completion === 'complete') {
+    return readResult('pass', conclusion.outcome.summary, recorded, conclusion);
+  }
+  return readResult('not_pass', conclusion.outcome.summary, recorded, conclusion);
+}
+
+export function readProofExitCode(status) {
+  if (status === 'pass') return 0;
+  if (status === 'not_pass') return 1;
+  return 2;
+}
+
+export async function readProfessionalProof({ proofRoot, proofPath }) {
+  const root = resolve(proofRoot);
+  const entry = 'skill-family-doc-render --read-proof';
+  let relative;
+  try {
+    await resolveContained(root, proofPath);
+    relative = proofPath;
+  } catch (cause) {
+    return readResult(
+      'unavailable',
+      `证明路径未收容于 proof-root: ${cause.message}`,
+      providerInfo(entry),
+      null,
+    );
+  }
+  let receipt;
+  try {
+    receipt = await readFileStrict(root, relative, { encoding: 'utf8' });
+  } catch (cause) {
+    const kind = harnessKind(cause);
+    let reason = `无法读取证明: ${cause.message}`;
+    if (kind === HARNESS_ERROR_KINDS.MISSING_RESOURCE) reason = `证明文件不存在: ${relative}`;
+    if (kind === HARNESS_ERROR_KINDS.PATH_TRAVERSAL || kind === HARNESS_ERROR_KINDS.ABSOLUTE_PATH) {
+      reason = `证明路径未收容于 proof-root: ${cause.message}`;
+    }
+    return readResult('unavailable', reason, providerInfo(entry), null);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(receipt.content);
+  } catch (cause) {
+    return readResult(
+      'unavailable',
+      `证明 JSON 损坏: ${cause.message}`,
+      providerInfo(entry),
+      null,
+    );
+  }
+  return interpretDocsProof(parsed);
+}
+
+function splitAbsoluteOutput(absolutePath) {
+  const target = resolve(absolutePath);
+  if (!isAbsolute(target)) {
+    throw new ProofError('[skill-family-doc-render] --conclusion-output 必须是绝对路径', 2);
+  }
+  let directory = dirname(target);
+  const segments = [basename(target)];
+  while (!existsSync(directory)) {
+    const parent = dirname(directory);
+    if (parent === directory) {
+      throw new ProofError(`[skill-family-doc-render] 无法定位证明输出根目录: ${target}`, 2);
+    }
+    segments.unshift(basename(directory));
+    directory = parent;
+  }
+  return { root: directory, relPath: join(...segments), target };
+}
+
+export async function writeProfessionalConclusion(absolutePath, conclusion) {
+  const { root, relPath, target } = splitAbsoluteOutput(absolutePath);
+  const body = `${JSON.stringify(conclusion, null, 2)}\n`;
+  try {
+    const receipt = await publishFileExclusive(root, relPath, body, { createParents: true });
+    return { path: receipt.path || target, sha256: receipt.sha256 };
+  } catch (cause) {
+    if (harnessKind(cause) === HARNESS_ERROR_KINDS.EXCLUSIVE_PUBLISH_CONFLICT) {
+      throw new ProofError(`[skill-family-doc-render] 证明输出已存在，拒绝覆盖: ${target}`, 2, cause);
+    }
+    if (cause instanceof ProofError) throw cause;
+    throw new ProofError(`[skill-family-doc-render] 证明输出失败: ${cause.message}`, 2, cause);
+  }
+}
+
+export function conclusionEntryForRepo(repoName) {
+  return `skill-family-doc-render --check-project --repo ${repoName}`;
+}
+
+export { MECHANICAL_LIMITATION };

package/scripts/render-public-site.mjs

@@ -27,7 +27,7 @@
 //   可预期失败统一封装为 RenderError 携带 exitCode。
 import { existsSync, readFileSync } from 'node:fs';
 import { readFile, readdir, rm, mkdtemp, realpath, stat, glob } from 'node:fs/promises';
-import { resolve, relative, extname, join, dirname, basename, posix } from 'node:path';
+import { resolve, relative, extname, join, dirname, basename, posix, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import {
@@ -47,6 +47,16 @@ import { compileMarkdownV1, replaceMarkdownTokens } from './lib/markdown-v1.mjs'
 import { assertSafeSvg } from './lib/svg-safety.mjs';
 import { checkRenderedLinks } from './lib/rendered-links.mjs';
 import { renderEditorialSite } from '../templates/editorial/index.mjs';
+import {
+  CHECK_STAGE_IDS,
+  ProofError,
+  buildDocsConclusion,
+  conclusionEntryForRepo,
+  mapScanToOutcome,
+  readProfessionalProof,
+  readProofExitCode,
+  writeProfessionalConclusion,
+} from './professional-conclusion.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -284,9 +294,22 @@ async function computeCoverageSnapshot(sourceRoot, repo) {
   return { snapshot, versionSources };
 }
 
+function gitReadEnv(extra = {}) {
+  return { ...process.env, GIT_OPTIONAL_LOCKS: '0', ...extra };
+}
+
+function gitReadArgv(args) {
+  return ['--no-optional-locks', '-c', 'core.fsmonitor=false', ...args];
+}
+
 function git(root, args, repoName) {
   try {
-    return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    return execFileSync('git', gitReadArgv(args), {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: gitReadEnv(),
+    }).trim();
   } catch (cause) {
     const detail = String(cause.stderr || cause.message).trim();
     throw configError(repoName, `Git 命令失败: git ${args.join(' ')}${detail ? `: ${detail}` : ''}`, cause);
@@ -519,7 +542,11 @@ function assertGitTracked(root, repo, targetRel, files) {
   let missing = 0;
   for (const f of expected) {
     try {
-      execFileSync('git', ['ls-files', '--error-unmatch', f], { cwd: root, stdio: 'pipe' });
+      execFileSync('git', gitReadArgv(['ls-files', '--error-unmatch', f]), {
+        cwd: root,
+        stdio: 'pipe',
+        env: gitReadEnv(),
+      });
     } catch (cause) {
       if (cause?.status === 1) {
         console.error(`[assert-git] ${repo.name}: 未被 Git 索引跟踪（请先 git add）: ${f}`);
@@ -771,26 +798,164 @@ function projectCheckError(repoName, cause, fallbackExitCode = 1) {
   );
 }
 
+function attachDocsCheck(error, finished, attempted, notReached) {
+  error.docsCheck = { finished, attempted, notReached };
+  return error;
+}
+
 async function checkProject(root, repo, release, leakLiterals) {
+  const finished = [];
+  const stages = [
+    {
+      id: CHECK_STAGE_IDS[0],
+      run: async () => {
+        await renderRepo(root, repo, release, leakLiterals, { check: false, assertGit: false, inputOnly: true });
+        console.log(`[render-public-site --check-project] ${repo.name}: 输入、公开安全与正文机械合同通过`);
+      },
+    },
+    {
+      id: CHECK_STAGE_IDS[1],
+      run: async () => {
+        await reportCoverageStatus(root, repo);
+      },
+    },
+    {
+      id: CHECK_STAGE_IDS[2],
+      run: async () => {
+        await renderRepo(root, repo, release, leakLiterals, { check: true, assertGit: false });
+      },
+    },
+    {
+      id: CHECK_STAGE_IDS[3],
+      run: async () => {
+        const sourceRoot = await repoSourceRoot(root, repo);
+        const targetDir = await containedOrConfig(sourceRoot, repo.site.target, repo.name, 'site.target');
+        const pagesDoc = await readJsonContained(sourceRoot, join(repo.site.dir, repo.site.pages), 'pages.json', repo.name);
+        await checkRenderedLinks({ targetRoot: targetDir, pageIds: pagesDoc.pages.map((page) => page.id) });
+        console.log(`[render-public-site --check-project] ${repo.name}: 内部链接与资源通过`);
+        console.log(`[render-public-site --check-project] ${repo.name}: public-release.json 只读项目检查通过`);
+      },
+    },
+  ];
   try {
-    await renderRepo(root, repo, release, leakLiterals, { check: false, assertGit: false, inputOnly: true });
-    console.log(`[render-public-site --check-project] ${repo.name}: 输入、公开安全与正文机械合同通过`);
-    await reportCoverageStatus(root, repo);
-    await renderRepo(root, repo, release, leakLiterals, { check: true, assertGit: false });
-    const sourceRoot = await repoSourceRoot(root, repo);
-    const targetDir = await containedOrConfig(sourceRoot, repo.site.target, repo.name, 'site.target');
-    const pagesDoc = await readJsonContained(sourceRoot, join(repo.site.dir, repo.site.pages), 'pages.json', repo.name);
-    await checkRenderedLinks({ targetRoot: targetDir, pageIds: pagesDoc.pages.map((page) => page.id) });
-    console.log(`[render-public-site --check-project] ${repo.name}: 内部链接与资源通过`);
-    console.log(`[render-public-site --check-project] ${repo.name}: public-release.json 只读项目检查通过`);
+    for (const stage of stages) {
+      await stage.run();
+      finished.push(stage.id);
+    }
   } catch (cause) {
-    throw projectCheckError(repo.name, cause);
+    const remaining = stages.map((stage) => stage.id).filter((id) => !finished.includes(id));
+    throw attachDocsCheck(
+      projectCheckError(repo.name, cause),
+      finished,
+      remaining[0] ?? null,
+      remaining.slice(1),
+    );
   }
 }
 
+function subjectRevision(root) {
+  try {
+    return execFileSync('git', gitReadArgv(['rev-parse', 'HEAD']), {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: gitReadEnv(),
+    }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+function asRenderError(error) {
+  if (error instanceof RenderError) return error;
+  if (error instanceof ProofError) return new RenderError(error.message, error.exitCode, error);
+  return error;
+}
+
+async function emitProjectConclusion({
+  outputPath,
+  root,
+  repoName,
+  ok,
+  exitCode,
+  message,
+  cause = null,
+  docsCheck,
+  repoSelected = true,
+}) {
+  const outcome = mapScanToOutcome({
+    ok,
+    exitCode,
+    finished: docsCheck?.finished || [],
+    attempted: docsCheck?.attempted || null,
+    notReached: docsCheck?.notReached || (ok ? [] : [...CHECK_STAGE_IDS]),
+    repoSelected,
+    cause,
+  });
+  const conclusion = buildDocsConclusion({
+    entry: conclusionEntryForRepo(repoName),
+    subjectRef: `${root}::${repoName}`,
+    subjectRevision: subjectRevision(root),
+    checked: outcome.checked,
+    limitations: outcome.limitations,
+    completion: outcome.completion,
+    code: outcome.code,
+    summary: outcome.summary,
+    details: {
+      mechanical: true,
+      repo: repoName,
+      exitCode,
+      findings: ok ? [] : [message],
+    },
+  });
+  const receipt = await writeProfessionalConclusion(outputPath, conclusion);
+  console.log(`[render-public-site --check-project] ${repoName}: professional conclusion written to ${receipt.path}`);
+  return receipt;
+}
+
+async function emitProjectConclusionOrThrow(args, primaryError) {
+  try {
+    await emitProjectConclusion(args);
+  } catch (cause) {
+    const writeError = asRenderError(cause);
+    if (primaryError) {
+      throw new RenderError(`${primaryError.message}\n${writeError.message}`, 2, writeError);
+    }
+    throw writeError;
+  }
+  if (primaryError) throw primaryError;
+}
+
+function takeValue(argv, i, flag, flags, key) {
+  if (flags[key] !== null) {
+    throw new RenderError(`[render-public-site] 参数错误: ${flag} 重复出现，取值语义不明确`, 2);
+  }
+  const value = argv[i + 1];
+  if (value === undefined || value === '' || value.startsWith('-')) {
+    throw new RenderError(`[render-public-site] ${flag} 后必须跟一个有效取值（不能缺省，且值不能是另一个选项）`, 2);
+  }
+  flags[key] = value;
+  return i + 1;
+}
+
+function projectModeError(flags, message) {
+  const error = projectCheckError(
+    flags.repoArg ?? '<missing>',
+    new RenderError(message, 2),
+    2,
+  );
+  error.repoArg = flags.repoArg;
+  if (flags.conclusionOutput && isAbsolute(flags.conclusionOutput)) {
+    error.conclusionOutput = flags.conclusionOutput;
+  }
+  return error;
+}
+
 // === 主流程 ===
 // 闭集参数解析：允许参数只有 --check / --assert-git / --status /
-// --refresh-coverage / --check-project / --repo <name> / --help / -h。
+// --refresh-coverage / --check-project / --conclusion-output <absolute-path> /
+// --read-proof / --proof-root <root> / --proof <relative> / --repo <name> /
+// --help / -h。
 // 未知选项、游离位置参数、重复取值参数、--repo 缺值或值本身是另一个选项，
 // 均以 RenderError（exit 2）失败，错误信息指出具体参数。不引入 CLI 框架。
 // --help / -h 由 main() 统一呈现：闭集解析先于配置读取与写盘，打印 USAGE_TEXT 后退出 0。
@@ -809,8 +974,12 @@ Usage:
                                         refresh only site-coverage-lock.json
   skill-family-doc-render --check-project --repo <name>
                                         read-only input, coverage, render and link checks
+  skill-family-doc-render --check-project --repo <name> --conclusion-output <absolute-path>
+                                        same read-only checks, then exclusive-write a professional conclusion
+  skill-family-doc-render --read-proof --proof-root <root> --proof <relative>
+                                        read one docs-family professional conclusion; do not rescan
 
-Reads public-release.json from the current working directory.`;
+Reads public-release.json from the current working directory except --read-proof.`;
 
 function parseArgs(argv) {
   const flags = {
@@ -819,7 +988,11 @@ function parseArgs(argv) {
     status: false,
     refreshCoverage: false,
     checkProject: false,
+    readProof: false,
     repoArg: null,
+    conclusionOutput: null,
+    proofRoot: null,
+    proof: null,
     help: false,
   };
   let i = 0;
@@ -835,6 +1008,8 @@ function parseArgs(argv) {
       flags.refreshCoverage = true;
     } else if (arg === '--check-project') {
       flags.checkProject = true;
+    } else if (arg === '--read-proof') {
+      flags.readProof = true;
     } else if (arg === '--help' || arg === '-h') {
       flags.help = true;
     } else if (arg === '--repo') {
@@ -846,7 +1021,13 @@ function parseArgs(argv) {
         throw new RenderError('[render-public-site] --repo 后必须跟一个有效的 repo 名（不能缺省，且值不能是另一个选项）', 2);
       }
       flags.repoArg = value;
-      i += 1; // 消费取值
+      i += 1;
+    } else if (arg === '--conclusion-output') {
+      i = takeValue(argv, i, '--conclusion-output', flags, 'conclusionOutput');
+    } else if (arg === '--proof-root') {
+      i = takeValue(argv, i, '--proof-root', flags, 'proofRoot');
+    } else if (arg === '--proof') {
+      i = takeValue(argv, i, '--proof', flags, 'proof');
     } else if (arg.startsWith('-')) {
       throw new RenderError(`[render-public-site] 参数错误: 未知选项 ${arg}`, 2);
     } else {
@@ -863,19 +1044,29 @@ function parseArgs(argv) {
   if ((flags.status || flags.refreshCoverage) && flags.repoArg === null) {
     throw new RenderError('[render-public-site] 参数错误: --status 与 --refresh-coverage 必须配合 --repo <name>', 2);
   }
+  if (flags.readProof && flags.checkProject) {
+    throw new RenderError('[render-public-site] 参数错误: --check-project 与 --read-proof 互斥', 2);
+  }
+  if (flags.readProof && (flags.check || flags.assertGit || flags.status || flags.refreshCoverage || flags.help || flags.conclusionOutput || flags.repoArg)) {
+    throw new RenderError('[render-public-site] 参数错误: --read-proof 不能与检查、覆盖、Git、帮助或 --conclusion-output 组合', 2);
+  }
+  if (flags.readProof && (flags.proofRoot === null || flags.proof === null)) {
+    throw new RenderError('[render-public-site] 参数错误: --read-proof 必须配合 --proof-root <root> 与 --proof <relative>', 2);
+  }
+  if (!flags.readProof && (flags.proofRoot !== null || flags.proof !== null)) {
+    throw new RenderError('[render-public-site] 参数错误: --proof-root 与 --proof 只能与 --read-proof 一起使用', 2);
+  }
+  if (flags.conclusionOutput && !flags.checkProject) {
+    throw new RenderError('[render-public-site] 参数错误: --conclusion-output 只能与 --check-project 一起使用', 2);
+  }
+  if (flags.conclusionOutput && !isAbsolute(flags.conclusionOutput)) {
+    throw projectModeError(flags, '参数错误: --conclusion-output 必须是绝对路径');
+  }
   if (flags.checkProject && (flags.check || flags.assertGit || flags.status || flags.refreshCoverage || flags.help)) {
-    throw projectCheckError(
-      flags.repoArg ?? '<missing>',
-      new RenderError('参数错误: --check-project 不能与其他检查、覆盖、Git 或帮助模式组合', 2),
-      2,
-    );
+    throw projectModeError(flags, '参数错误: --check-project 不能与其他检查、覆盖、Git 或帮助模式组合');
   }
   if (flags.checkProject && flags.repoArg === null) {
-    throw projectCheckError(
-      '<missing>',
-      new RenderError('参数错误: --check-project 必须配合 --repo <name>', 2),
-      2,
-    );
+    throw projectModeError(flags, '参数错误: --check-project 必须配合 --repo <name>');
   }
   return flags;
 }
@@ -886,7 +1077,20 @@ function parseArgs(argv) {
 // 单个 repo 内部（含泄漏扫描命中）保持 fail-fast。
 export async function main(argv = process.argv.slice(2), { cwd = process.cwd() } = {}) {
   // 闭集解析在读取任何配置或写盘之前完成；参数失败时目标树一个字节都不动。
-  const { check, assertGit, status, refreshCoverage, checkProject: projectCheck, repoArg, help } = parseArgs(argv);
+  const parsed = parseArgs(argv);
+  const {
+    check,
+    assertGit,
+    status,
+    refreshCoverage,
+    checkProject: projectCheck,
+    readProof,
+    repoArg,
+    conclusionOutput,
+    proofRoot,
+    proof,
+    help,
+  } = parsed;
   if (help) {
     console.log(USAGE_TEXT);
     return 0;
@@ -894,18 +1098,54 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
 
   const root = resolve(cwd);
 
+  if (readProof) {
+    const result = await readProfessionalProof({ proofRoot, proofPath: proof });
+    console.log(JSON.stringify(result, null, 2));
+    const code = readProofExitCode(result.status);
+    if (code === 0) return 0;
+    throw new RenderError(result.reason, code);
+  }
+
   // --- 读取发布配置 ---
   const releasePath = resolve(root, 'public-release.json');
   if (!existsSync(releasePath)) {
     const cause = new RenderError('[render-public-site] 未找到 public-release.json', 2);
-    throw projectCheck ? projectCheckError(repoArg, cause, 2) : cause;
+    const error = projectCheck ? projectCheckError(repoArg, cause, 2) : cause;
+    if (projectCheck && conclusionOutput) {
+      await emitProjectConclusionOrThrow({
+        outputPath: conclusionOutput,
+        root,
+        repoName: repoArg,
+        ok: false,
+        exitCode: 2,
+        message: error.message,
+        cause: error,
+        repoSelected: false,
+      }, error);
+    }
+    throw error;
   }
   let release;
   try {
     release = await readJsonContained(root, 'public-release.json', 'public-release.json', '(workspace)');
     assertValid(release, publicReleaseSchema, 'public-release.json');
   } catch (cause) {
-    if (projectCheck) throw projectCheckError(repoArg, cause, 2);
+    if (projectCheck) {
+      const error = projectCheckError(repoArg, cause, 2);
+      if (conclusionOutput) {
+        await emitProjectConclusionOrThrow({
+          outputPath: conclusionOutput,
+          root,
+          repoName: repoArg,
+          ok: false,
+          exitCode: 2,
+          message: error.message,
+          cause: error,
+          repoSelected: Boolean(repoArg),
+        }, error);
+      }
+      throw error;
+    }
     throw cause;
   }
 
@@ -921,12 +1161,38 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
     const hit = selected.find((r) => r.name === repoArg);
     if (!hit) {
       const cause = new RenderError(`[render-public-site] 未找到带 site 的 repo: ${repoArg}`, 2);
-      throw projectCheck ? projectCheckError(repoArg, cause, 2) : cause;
+      const error = projectCheck ? projectCheckError(repoArg, cause, 2) : cause;
+      if (projectCheck && conclusionOutput) {
+        await emitProjectConclusionOrThrow({
+          outputPath: conclusionOutput,
+          root,
+          repoName: repoArg,
+          ok: false,
+          exitCode: 2,
+          message: error.message,
+          cause: error,
+          repoSelected: false,
+        }, error);
+      }
+      throw error;
     }
     selected = [hit];
   }
   if (!selected.length) {
-    throw new RenderError('[render-public-site] public-release.json 中没有带 site 字段的 repo', 2);
+    const error = new RenderError('[render-public-site] public-release.json 中没有带 site 字段的 repo', 2);
+    if (projectCheck && conclusionOutput) {
+      await emitProjectConclusionOrThrow({
+        outputPath: conclusionOutput,
+        root,
+        repoName: repoArg ?? '<missing>',
+        ok: false,
+        exitCode: 2,
+        message: error.message,
+        cause: error,
+        repoSelected: false,
+      }, error);
+    }
+    throw error;
   }
 
   const results = [];
@@ -934,8 +1200,49 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
     try {
       if (status) await reportCoverageStatus(root, repo);
       else if (refreshCoverage) await refreshCoverageLock(root, repo);
-      else if (projectCheck) await checkProject(root, repo, release, leakLiterals);
-      else await renderRepo(root, repo, release, leakLiterals, { check, assertGit });
+      else if (projectCheck) {
+        let scanError = null;
+        try {
+          await checkProject(root, repo, release, leakLiterals);
+        } catch (cause) {
+          scanError = cause;
+        }
+        if (conclusionOutput) {
+          try {
+            await emitProjectConclusion({
+              outputPath: conclusionOutput,
+              root,
+              repoName: repo.name,
+              ok: !scanError,
+              exitCode: scanError ? (Number.isInteger(scanError.exitCode) ? scanError.exitCode : 1) : 0,
+              message: scanError ? scanError.message : 'ok',
+              cause: scanError,
+              docsCheck: scanError?.docsCheck || { finished: [...CHECK_STAGE_IDS], attempted: null, notReached: [] },
+              repoSelected: true,
+            });
+          } catch (cause) {
+            const writeError = asRenderError(cause);
+            results.push({
+              name: repo.name,
+              ok: false,
+              exitCode: 2,
+              message: scanError ? `${scanError.message}\n${writeError.message}` : writeError.message,
+              cause: writeError,
+            });
+            continue;
+          }
+        }
+        if (scanError) {
+          results.push({
+            name: repo.name,
+            ok: false,
+            exitCode: Number.isInteger(scanError.exitCode) ? scanError.exitCode : 1,
+            message: scanError.message,
+            cause: scanError,
+          });
+          continue;
+        }
+      } else await renderRepo(root, repo, release, leakLiterals, { check, assertGit });
       results.push({ name: repo.name, ok: true });
     } catch (err) {
       results.push({