skill-family-doc-render 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 变更日志
 
+## 0.3.0 - 2026-09-07
+
+### 新增
+
+- 增加 `site.coverage` 和最小 `site-coverage-lock.json`，记录已审阅产品输入的文件摘要、
+  聚合摘要，以及启用 artifact-graph 时的版本锁摘要。
+- 增加只读的 `--status --repo <name>` 和只更新覆盖快照的
+  `--refresh-coverage --repo <name>`。状态命令会报告覆盖提交、当前摘要、变化文件、
+  权威版本值和建议执行的 Git diff 命令。
+- 状态命令从 `repo.source` 发现所属 Git 仓库。目标位于外层工作区中的独立内层仓库时，
+  覆盖提交、变化路径和 diff 建议只使用内层仓库历史。
+- 增加 `site.versionSources`。渲染器从收容于 `repo.source` 的 JSON 文件和 JSON Pointer
+  读取版本值，版本源文件自动加入覆盖输入。
+
+### 安全与兼容
+
+- 覆盖输入拒绝绝对路径、越界路径、空匹配和符号链接逃逸；覆盖锁始终排除自身，
+  避免形成摘要循环。
+- 保留现有静态 token 和按仓库名派生版本 token 的兼容行为；同名
+  `site.versionSources` 取值优先。
+
 ## 0.2.1 - 2026-09-06
 
 ### 变更

package/README.md

@@ -13,15 +13,21 @@ 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.
 
+> **Development status:** this worktree is the unpublished `0.3.0` candidate. The latest npm
+> release is `0.2.1`; it does not contain `site.coverage`, `site.versionSources`, `--status`, or
+> `--refresh-coverage`.
+
 ## Install
 
+Install the current published release with an exact version:
+
 ```sh
-npm install skill-family-doc-render@0.2.0
+npm install --save-exact skill-family-doc-render@0.2.1
 ```
 
 Requires Node.js `>=22.22.2 <23` (aligned with the skill-family foundation packages).
 
-0.2.0 consumes the three Foundation packages at the exact `0.18.0` pin:
+The unpublished 0.3.0 candidate consumes the three Foundation packages at the exact `0.18.0` pin:
 `skill-family-contracts@0.18.0`, `skill-family-harness-node@0.18.0` and
 `skill-family-engineering-kit@0.18.0` (the last one is used by the workspace profile check).
 The 0.2.0 baseline format and exit-code changes are breaking changes; existing 0.1.x users
@@ -30,24 +36,47 @@ notes.
 
 ## CLI
 
+The published 0.2.1 release supports rendering, drift checks, repository selection, and the Git
+index assertion:
+
 ```sh
 # render all repos with a site field (writes to disk)
-npx skill-family-doc-render@0.2.0
+npx skill-family-doc-render@0.2.1
 
 # drift check only: compare in-memory render against committed site-baseline.json, write nothing
-npx skill-family-doc-render@0.2.0 --check
+npx skill-family-doc-render@0.2.1 --check
 
 # render / check a single repo by name
-npx skill-family-doc-render@0.2.0 --repo <name>
+npx skill-family-doc-render@0.2.1 --repo <name>
 
 # additionally assert every rendered file is tracked in the git index
-npx skill-family-doc-render@0.2.0 --assert-git
+npx skill-family-doc-render@0.2.1 --assert-git
+```
+
+Run the unpublished 0.3.0 coverage commands from a local package checkout. The current directory
+must still be the workspace that owns `public-release.json`; adjust the script path when the
+package is nested in a monorepo:
+
+```sh
+# inspect whether reviewed product inputs have changed; writes nothing
+node bin/skill-family-doc-render.mjs --status --repo <name>
+
+# refresh only the reviewed-input snapshot after semantic and style review
+node bin/skill-family-doc-render.mjs --refresh-coverage --repo <name>
+```
+
+After 0.3.0 is published, consumers can install or invoke that exact release:
+
+```sh
+npm install --save-exact skill-family-doc-render@0.3.0
+npx skill-family-doc-render@0.3.0 --status --repo <name>
 ```
 
 Exit codes: `0` success; `1` drift class — `--check` drift, leak-scan hit, `--assert-git`
-missing files, missing/corrupt baseline; `2` configuration class — missing/invalid
-`public-release.json` or `pages.json`, JSON parse failures, unreplaced `@TOKEN@` placeholders,
-invalid `--repo` usage (the message includes the JSON field path). When several repos are
+missing files, missing/corrupt render baseline, or missing/stale coverage snapshot; `2`
+configuration/tool class — missing/invalid `public-release.json` or `pages.json`, JSON parse
+failures, unreplaced `@TOKEN@` placeholders, invalid `--repo` usage, invalid coverage inputs, or
+Git failure (the message includes the JSON field path). When several repos are
 rendered in one run, each repo is isolated: a failure in one does not stop the others, and the
 run ends with a summary of successes/failures plus a non-zero exit (2 if any failure was
 configuration-class, otherwise 1).
@@ -56,7 +85,8 @@ configuration-class, otherwise 1).
 
 The config file lives at the workspace root (resolved from `process.cwd()`). It is validated
 against `schemas/public-release.schema.json` (JSON Schema 2020-12, strict policy) before
-anything runs.
+anything runs. `coverage` and `versionSources` in the example below belong to the unpublished
+0.3.0 candidate.
 
 ```json
 {
@@ -72,6 +102,21 @@ anything runs.
         "dir": "site-src",
         "target": "docs",
         "pages": "pages.json",
+        "coverage": {
+          "lock": "site-coverage-lock.json",
+          "inputs": ["package.json", "src/**", "schemas/**"]
+        },
+        "versionSources": {
+          "@COMPONENT_VERSION@": {
+            "source": "package.json",
+            "pointer": "/version"
+          },
+          "@COMPONENT_TAG@": {
+            "source": "package.json",
+            "pointer": "/version",
+            "prefix": "component-v"
+          }
+        },
         "tokens": { "@CUSTOM_NOTE@": "any static placeholder" }
       }
     }
@@ -88,6 +133,13 @@ anything runs.
   `inPager: false` excludes a page from the prev/next pager. Page `id` is restricted to
   `[A-Za-z0-9][A-Za-z0-9_-]*`.
 - `forbiddenPublicPaths` / `privateLiterals` append project-specific literals to the leak scan.
+- `site.coverage` declares reviewed product inputs relative to `repo.source`. Each input accepts
+  `*` and `**` glob syntax and must match at least one file after the coverage lock itself is
+  excluded.
+- `site.versionSources` maps a token to an existing JSON file and an
+  [RFC 6901 JSON Pointer](https://www.rfc-editor.org/rfc/rfc6901). `prefix` and `suffix` format
+  the scalar value without copying the version into configuration. Every referenced JSON file
+  automatically joins the coverage inputs.
 
 ## Placeholders
 
@@ -103,7 +155,8 @@ Version tokens are derived automatically from the repo's `package.json` version
 - `@{NAME}_TAG@` — e.g. `my-project` → `@MY_PROJECT_TAG@` = `tagPrefix` + version
 - `@{NAME}_VERSION@` — the bare version
 
-`site.tokens` adds arbitrary static placeholder replacements on top. If a rendered page still
+`site.tokens` adds non-version static placeholder replacements. A token also declared in
+`site.versionSources` always takes its value from the JSON source. If a rendered page still
 contains an unreplaced `@TOKEN@` (`@[A-Z0-9_]+@`), the run fails fast (exit 2) naming the
 tokens and the file — placeholder typos never slip into the published site silently.
 
@@ -111,6 +164,29 @@ If a repo has no `package.json` (or no valid `version`), the version falls back
 with a loud `WARNING` on stderr, because that fallback is baked into the output and the
 baseline; a malformed `package.json` fails fast (exit 2).
 
+## Coverage status
+
+`--refresh-coverage --repo <name>` expands `site.coverage.inputs`, adds every configured version
+source, computes the file digests and closure digest, then atomically writes the declared coverage
+lock. It does not render the site or modify Git. The lock contains only:
+
+- `sha256`: the Foundation resource-closure digest;
+- `inputs`: sorted relative file paths and their byte digests;
+- `artifactGraphVersionLockSha256`: the current `artifacts/traceability-version-lock.json`
+  digest when the repository contains `artifact-graph.config.yaml`.
+
+`--status --repo <name>` recomputes the same facts without writing. It prints the last commit that
+changed the coverage lock, the current and recorded closure digests, changed covered files,
+current values from `site.versionSources`, and suggested `git diff` commands. A matching snapshot
+returns `0`; a missing or stale snapshot returns `1`. A site without `coverage`, a path escape, an
+empty glob, an invalid JSON pointer, a symlink escape, or a Git failure returns `2`.
+
+Coverage paths are relative to `repo.source`. Absolute paths, lexical traversal, realpath escape,
+and symlink escape are rejected through Foundation path containment. The coverage lock is always
+excluded from its own inputs, avoiding a digest cycle. `--status` requires a Git repository with a
+resolvable `HEAD`, because its report includes committed, staged, unstaged, and covered untracked
+changes.
+
 ## Leak scan
 
 Every output file — rendered pages **and** copied assets (`.html`/`.css`/`.js`/`.svg`) — is
@@ -151,30 +227,35 @@ dependencies:
 - [`skill-family-harness-node`](https://github.com/ifoohoo/skill-family-harness-node) — all file
   reads go through `resolveContained` / `readFileContained` (path traversal, symlink and realpath
   escapes rejected), per-file digests use `digestBytes`, the tree baseline is computed with
-  `computeResourceClosure`. Output is staged in a sibling directory under the target's canonical
-  parent, with contained writes through `writeFileAtomic`. A new target uses
+  `computeResourceClosure`, and coverage locks use `writeFileAtomic`. Output is staged in a
+  sibling directory under the target's canonical parent, with contained writes through
+  `writeFileAtomic`. A new target uses
   `createFixedSetPublicationManifest` followed by `publishFixedSet`; an existing target uses
   `replaceFixedSetAtomic`. Staging is removed after success or a clearly pre-commit failure;
   post-commit or indeterminate failures may retain it for diagnosis. These APIs do not add a
   broader atomicity guarantee than Foundation provides.
 - [`skill-family-contracts`](https://github.com/ifoohoo/skill-family-contracts) —
   `validateDocument` (JSON Schema 2020-12, strict policy) validates `public-release.json`,
-  `pages.json` and `site-baseline.json`; validation failure aborts with exit code 2.
+  `pages.json`, `site-baseline.json`, and `site-coverage-lock.json`; validation failure aborts
+  with exit code 2.
 
 ## License
 
 Apache-2.0
 
 <!-- release-skill:capability:safe-first-command -->
-> **Start here:** after installing the exact `skill-family-doc-render@0.2.0`, run
-> `./node_modules/.bin/skill-family-doc-render --check` — the drift check is read-only:
+> **Start here:** for the unpublished 0.3.0 candidate, run
+> `node bin/skill-family-doc-render.mjs --check` from its local checkout. Published 0.2.1 users
+> can run `./node_modules/.bin/skill-family-doc-render --check`. The drift check is read-only:
 > it renders in memory, compares against the committed `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.
 
 <!-- release-skill:capability:external-write-boundary -->
-> **External write boundary:** this CLI writes the declared target and a controlled sibling
-> staging directory, both within the target's canonical parent, with contained path checks.
+> **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` and `--check` write 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.
@@ -184,7 +265,12 @@ Apache-2.0
 
 ## Minimal example
 
+Use the local checkout while 0.3.0 remains unpublished:
+
 ```sh
-npx skill-family-doc-render@0.2.0 --help     # show usage
-npx skill-family-doc-render@0.2.0 --check    # read-only drift check — the safe first command
+node bin/skill-family-doc-render.mjs --help
+node bin/skill-family-doc-render.mjs --check
 ```
+
+Replace `node bin/skill-family-doc-render.mjs` with `npx skill-family-doc-render@0.3.0` only after
+the registry publishes 0.3.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-family-doc-render",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Config-driven GitHub Pages knowledge-site renderer for skill-family projects (multi-repo capable).",
   "author": "广州市风荷科技有限公司",
   "license": "Apache-2.0",

package/schemas/public-release.schema.json

@@ -29,6 +29,36 @@
               "dir": { "type": "string", "minLength": 1 },
               "target": { "type": "string", "minLength": 1 },
               "pages": { "type": "string", "minLength": 1 },
+              "coverage": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["lock", "inputs"],
+                "properties": {
+                  "lock": { "type": "string", "minLength": 1, "pattern": "^[^*?\\[\\]{}()!]+$" },
+                  "inputs": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": { "type": "string", "minLength": 1, "pattern": "^[^?\\[\\]{}()!]+$" }
+                  }
+                }
+              },
+              "versionSources": {
+                "type": "object",
+                "minProperties": 1,
+                "propertyNames": { "pattern": "^@[A-Z0-9_]+@$" },
+                "additionalProperties": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["source", "pointer"],
+                  "properties": {
+                    "source": { "type": "string", "minLength": 1, "pattern": "^[^*?\\[\\]{}()!]+$" },
+                    "pointer": { "type": "string", "pattern": "^/" },
+                    "prefix": { "type": "string" },
+                    "suffix": { "type": "string" }
+                  }
+                }
+              },
               "tokens": {
                 "type": "object",
                 "additionalProperties": {

package/schemas/site-coverage-lock.schema.json

@@ -0,0 +1,28 @@
+{
+  "$id": "https://github.com/ifoohoo/skill-family-doc-render/schemas/site-coverage-lock.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "site-coverage-lock.json",
+  "description": "知识站已审阅产品输入的最小字节快照；不保存版本、发布状态或人工结论。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sha256", "inputs"],
+  "properties": {
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "inputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "sha256"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+        }
+      }
+    },
+    "artifactGraphVersionLockSha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    }
+  }
+}

package/scripts/render-public-site.mjs

@@ -14,23 +14,24 @@
 // harness 化：所有配置 / 源文件读取经 readFileContained，staging 的相对输出经
 // writeFileAtomic 收容并原子写入（见 skill-family-harness-node）；树基线摘要用
 // computeResourceClosure，逐文件摘要用 digestBytes。
-// 配置、pages.json 与基线文件先经 skill-family-contracts validateDocument
+// 配置、pages.json、渲染基线与覆盖快照先经 skill-family-contracts validateDocument
 // （JSON Schema 2020-12，strict 策略）校验，校验失败 fail-fast。
 //
 // 错误分类（退出码语义）：
-//   exit 1 — 漂移类：--check 检出漂移、泄漏扫描命中、--assert-git 缺失、
-//            基线缺失 / 基线 JSON 损坏；
-//   exit 2 — 配置类：public-release.json / pages.json 缺失、非法或 JSON 解析失败、
-//            package.json JSON 解析失败、@TOKEN@ 占位符残留、--repo 参数无效；
+//   exit 1 — 漂移类：--check 检出漂移、覆盖快照缺失或落后、泄漏扫描命中、
+//            --assert-git 缺失、渲染基线缺失 / 基线 JSON 损坏；
+//   exit 2 — 配置或工具类：配置 / JSON / 覆盖输入非法、Git 调用失败、
+//            @TOKEN@ 占位符残留、--repo 参数无效；
 //   其余意外异常（HarnessError 等）原样抛出，CLI 归为 exit 1。
 //   可预期失败统一封装为 RenderError 携带 exitCode。
 import { existsSync, readFileSync } from 'node:fs';
-import { readdir, rm, mkdtemp, realpath } from 'node:fs/promises';
-import { resolve, relative, extname, join, dirname, basename } from 'node:path';
+import { readdir, rm, mkdtemp, realpath, stat, glob } from 'node:fs/promises';
+import { resolve, relative, extname, join, dirname, basename, posix } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import {
   resolveContained,
+  classifyPathInput,
   readFileContained,
   digestBytes,
   computeResourceClosure,
@@ -51,14 +52,17 @@ const publicReleaseSchema = JSON.parse(
 const siteBaselineSchema = JSON.parse(
   readFileSync(join(__dirname, '..', 'schemas', 'site-baseline.schema.json'), 'utf8'),
 );
+const siteCoverageLockSchema = JSON.parse(
+  readFileSync(join(__dirname, '..', 'schemas', 'site-coverage-lock.schema.json'), 'utf8'),
+);
 const pagesSchema = JSON.parse(
   readFileSync(join(__dirname, '..', 'schemas', 'pages.schema.json'), 'utf8'),
 );
 
 // 可预期失败（配置缺失、校验失败、check 漂移、泄漏命中等）以此类型抛出，携带退出码。
 export class RenderError extends Error {
-  constructor(message, exitCode = 2) {
-    super(message);
+  constructor(message, exitCode = 2, cause) {
+    super(message, cause === undefined ? undefined : { cause });
     this.exitCode = exitCode;
   }
 }
@@ -105,6 +109,301 @@ async function pkgVersion(root, source, name) {
   return doc.version;
 }
 
+function configError(name, message, cause) {
+  return new RenderError(`[render-public-site] ${name}: ${message}`, 2, cause);
+}
+
+async function repoSourceRoot(root, repo) {
+  const classification = classifyPathInput(repo.source);
+  if (!classification.ok) {
+    throw configError(repo.name, `repo.source 非法 (${classification.kind}): ${repo.source}`);
+  }
+  if (resolve(root, repo.source) === root) return root;
+  try {
+    return await resolveContained(root, repo.source);
+  } catch (cause) {
+    throw configError(repo.name, `repo.source 未收容于工作区: ${repo.source}`, cause);
+  }
+}
+
+async function containedOrConfig(root, relPath, repoName, fieldPath) {
+  try {
+    return await resolveContained(root, relPath);
+  } catch (cause) {
+    throw configError(repoName, `${fieldPath} 必须是收容于 repo.source 的相对路径: ${relPath}`, cause);
+  }
+}
+
+function jsonPointerValue(document, pointer, repoName, fieldPath) {
+  const segments = pointer.slice(1).split('/').map((segment) => {
+    if (/~(?:[^01]|$)/.test(segment)) {
+      throw configError(repoName, `${fieldPath} 不是有效 JSON Pointer: ${pointer}`);
+    }
+    return segment.replaceAll('~1', '/').replaceAll('~0', '~');
+  });
+  let value = document;
+  for (const segment of segments) {
+    if (value === null || typeof value !== 'object' || !Object.hasOwn(value, segment)) {
+      throw configError(repoName, `${fieldPath} 指向的字段不存在: ${pointer}`);
+    }
+    value = value[segment];
+  }
+  if (!['string', 'number', 'boolean'].includes(typeof value)) {
+    throw configError(repoName, `${fieldPath} 必须指向 string、number 或 boolean: ${pointer}`);
+  }
+  return value;
+}
+
+async function loadVersionSources(sourceRoot, repo) {
+  const definitions = repo.site.versionSources || {};
+  const cache = new Map();
+  const tokens = {};
+  const values = [];
+  const paths = new Set();
+  for (const [token, definition] of Object.entries(definitions)) {
+    const fieldPath = `site.versionSources.${token}`;
+    const sourceAbs = await containedOrConfig(sourceRoot, definition.source, repo.name, `${fieldPath}.source`);
+    let sourceStats;
+    try {
+      sourceStats = await stat(sourceAbs);
+    } catch (cause) {
+      throw configError(repo.name, `${fieldPath}.source 不可读取: ${definition.source}`, cause);
+    }
+    if (!sourceStats.isFile()) {
+      throw configError(repo.name, `${fieldPath}.source 必须指向 JSON 文件: ${definition.source}`);
+    }
+    let document = cache.get(definition.source);
+    if (document === undefined) {
+      try {
+        document = JSON.parse(await readFileContained(sourceRoot, definition.source, { encoding: 'utf8' }));
+      } catch (cause) {
+        if (cause instanceof SyntaxError) {
+          throw configError(repo.name, `${fieldPath}.source JSON 解析失败: ${definition.source}: ${cause.message}`, cause);
+        }
+        throw configError(repo.name, `${fieldPath}.source 读取失败: ${definition.source}`, cause);
+      }
+      cache.set(definition.source, document);
+    }
+    const rawValue = jsonPointerValue(document, definition.pointer, repo.name, `${fieldPath}.pointer`);
+    const renderedValue = `${definition.prefix || ''}${rawValue}${definition.suffix || ''}`;
+    tokens[token] = renderedValue;
+    values.push({ token, source: definition.source, pointer: definition.pointer, value: rawValue, renderedValue });
+    paths.add(posix.normalize(definition.source.replaceAll('\\', '/')));
+  }
+  return { tokens, values, paths: [...paths].sort() };
+}
+
+async function artifactGraphLockDigest(sourceRoot, repo) {
+  const configPath = 'artifact-graph.config.yaml';
+  const lockPath = 'artifacts/traceability-version-lock.json';
+  const configAbs = await containedOrConfig(sourceRoot, configPath, repo.name, 'artifact-graph config');
+  if (!existsSync(configAbs)) return undefined;
+  const lockAbs = await containedOrConfig(sourceRoot, lockPath, repo.name, 'artifact-graph version lock');
+  if (!existsSync(lockAbs)) {
+    throw configError(repo.name, `已启用 artifact-graph，但未找到 ${lockPath}`);
+  }
+  try {
+    return digestBytes(await readFileContained(sourceRoot, lockPath));
+  } catch (cause) {
+    throw configError(repo.name, `${lockPath} 读取失败`, cause);
+  }
+}
+
+async function computeCoverageSnapshot(sourceRoot, repo) {
+  const coverage = repo.site.coverage;
+  if (!coverage) throw configError(repo.name, 'site.coverage 未配置');
+  const lockPath = posix.normalize(coverage.lock.replaceAll('\\', '/'));
+  await containedOrConfig(sourceRoot, coverage.lock, repo.name, 'site.coverage.lock');
+  const versionSources = await loadVersionSources(sourceRoot, repo);
+  if (versionSources.paths.includes(lockPath)) {
+    throw configError(repo.name, 'site.coverage.lock 不能同时作为版本源');
+  }
+
+  const files = new Set();
+  for (const [index, pattern] of coverage.inputs.entries()) {
+    const fieldPath = `site.coverage.inputs[${index}]`;
+    if (pattern.split('/').includes('..')) {
+      throw configError(repo.name, `${fieldPath} 不能包含 .. 路径段: ${pattern}`);
+    }
+    // 首版只接受 * / **，避免 brace、extglob 或字符类先展开再越过收容检查。
+    if (/[?\[\]{}()!]/.test(pattern)) {
+      throw configError(repo.name, `${fieldPath} 只支持 * 与 ** 通配符: ${pattern}`);
+    }
+    await containedOrConfig(sourceRoot, pattern.replaceAll('*', '__coverage_glob__'), repo.name, fieldPath);
+    const matches = [];
+    try {
+      for await (const candidate of glob(pattern, { cwd: sourceRoot })) {
+        const normalized = posix.normalize(candidate.replaceAll('\\', '/'));
+        if (normalized === '.' || normalized === lockPath) continue;
+        const candidateAbs = await containedOrConfig(
+          sourceRoot,
+          normalized,
+          repo.name,
+          fieldPath,
+        );
+        const candidateStats = await stat(candidateAbs);
+        if (candidateStats.isFile()) matches.push(normalized);
+      }
+    } catch (cause) {
+      if (cause instanceof RenderError) throw cause;
+      throw configError(repo.name, `${fieldPath} 无法展开: ${pattern}`, cause);
+    }
+    if (!matches.length) {
+      throw configError(repo.name, `${fieldPath} 没有匹配任何输入文件: ${pattern}`);
+    }
+    for (const match of matches) files.add(match);
+  }
+  for (const versionPath of versionSources.paths) {
+    await containedOrConfig(sourceRoot, versionPath, repo.name, 'site.versionSources.source');
+    files.add(versionPath);
+  }
+
+  let closure;
+  try {
+    closure = await computeResourceClosure({
+      root: sourceRoot,
+      resources: [...files].sort().map((path) => ({ path, role: 'input' })),
+    });
+  } catch (cause) {
+    throw configError(repo.name, '覆盖输入摘要计算失败', cause);
+  }
+  const snapshot = {
+    sha256: closure.digest,
+    inputs: closure.resources.map(({ path, sha256 }) => ({ path, sha256 })),
+  };
+  const versionLockSha256 = await artifactGraphLockDigest(sourceRoot, repo);
+  if (versionLockSha256 !== undefined) {
+    snapshot.artifactGraphVersionLockSha256 = versionLockSha256;
+  }
+  assertValid(snapshot, siteCoverageLockSchema, `${repo.name} site-coverage-lock.json`);
+  return { snapshot, versionSources };
+}
+
+function git(root, args, repoName) {
+  try {
+    return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch (cause) {
+    const detail = String(cause.stderr || cause.message).trim();
+    throw configError(repoName, `Git 命令失败: git ${args.join(' ')}${detail ? `: ${detail}` : ''}`, cause);
+  }
+}
+
+function splitLines(text) {
+  return text ? text.split(/\r?\n/).filter(Boolean) : [];
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function coverageGitStatus(sourceRoot, repo, snapshot, baseline) {
+  const gitRoot = git(sourceRoot, ['rev-parse', '--show-toplevel'], repo.name);
+  const head = git(sourceRoot, ['rev-parse', 'HEAD'], repo.name);
+  const lockAbs = resolve(sourceRoot, repo.site.coverage.lock);
+  const lockGitPath = relative(gitRoot, lockAbs).replaceAll('\\', '/');
+  const coverageCommit = git(sourceRoot, ['log', '-1', '--format=%H', '--', lockGitPath], repo.name) || null;
+  const sourceGitPath = relative(gitRoot, sourceRoot).replaceAll('\\', '/') || '.';
+  const knownInputs = new Set([...(baseline?.inputs || []), ...snapshot.inputs].map((entry) => {
+    return relative(gitRoot, resolve(sourceRoot, entry.path)).replaceAll('\\', '/');
+  }));
+  if (snapshot.artifactGraphVersionLockSha256 || baseline?.artifactGraphVersionLockSha256) {
+    knownInputs.add(
+      relative(gitRoot, resolve(sourceRoot, 'artifacts/traceability-version-lock.json')).replaceAll('\\', '/'),
+    );
+  }
+  const changed = new Set();
+  const collect = (lines) => {
+    for (const path of lines) if (knownInputs.has(path)) changed.add(path);
+  };
+  if (coverageCommit) {
+    collect(splitLines(git(sourceRoot, ['diff', '--name-only', '--no-renames', `${coverageCommit}..${head}`], repo.name)));
+  } else {
+    for (const path of knownInputs) changed.add(path);
+  }
+  collect(splitLines(git(sourceRoot, ['diff', '--cached', '--name-only', '--no-renames'], repo.name)));
+  collect(splitLines(git(sourceRoot, ['diff', '--name-only', '--no-renames'], repo.name)));
+  collect(splitLines(git(sourceRoot, ['ls-files', '--others', '--exclude-standard'], repo.name)));
+
+  const suggestions = coverageCommit
+    ? [
+        `git diff ${coverageCommit}..HEAD -- ${shellQuote(sourceGitPath)}`,
+        `git diff --cached -- ${shellQuote(sourceGitPath)}`,
+        `git diff -- ${shellQuote(sourceGitPath)}`,
+      ]
+    : [
+        `git status --short -- ${shellQuote(sourceGitPath)}`,
+        `git diff HEAD -- ${shellQuote(sourceGitPath)}`,
+      ];
+  return { coverageCommit, changed: [...changed].sort(), suggestions };
+}
+
+async function readCoverageBaseline(sourceRoot, repo) {
+  const lockPath = repo.site.coverage.lock;
+  const lockAbs = await containedOrConfig(sourceRoot, lockPath, repo.name, 'site.coverage.lock');
+  if (!existsSync(lockAbs)) return null;
+  let baseline;
+  try {
+    baseline = JSON.parse(await readFileContained(sourceRoot, lockPath, { encoding: 'utf8' }));
+  } catch (cause) {
+    throw configError(repo.name, `覆盖快照 JSON 解析失败: ${lockPath}: ${cause.message}`, cause);
+  }
+  assertValid(baseline, siteCoverageLockSchema, `${repo.name} site-coverage-lock.json`);
+  return baseline;
+}
+
+async function refreshCoverageLock(root, repo) {
+  const sourceRoot = await repoSourceRoot(root, repo);
+  // 已存在的写入目标必须已经是覆盖快照，避免错误配置把普通项目文件当作锁覆盖。
+  await readCoverageBaseline(sourceRoot, repo);
+  const { snapshot } = await computeCoverageSnapshot(sourceRoot, repo);
+  try {
+    await writeFileAtomic(sourceRoot, repo.site.coverage.lock, `${JSON.stringify(snapshot, null, 2)}\n`);
+  } catch (cause) {
+    throw configError(repo.name, `覆盖快照写入失败: ${repo.site.coverage.lock}`, cause);
+  }
+  console.log(`[render-public-site --refresh-coverage] ${repo.name}: 已写入 ${repo.site.coverage.lock}`);
+  console.log(`[render-public-site --refresh-coverage] ${repo.name}: coverage-sha256=${snapshot.sha256}`);
+}
+
+async function reportCoverageStatus(root, repo) {
+  if (!repo.site.coverage) throw configError(repo.name, 'site.coverage 未配置');
+  const sourceRoot = await repoSourceRoot(root, repo);
+  const baseline = await readCoverageBaseline(sourceRoot, repo);
+  const { snapshot, versionSources } = await computeCoverageSnapshot(sourceRoot, repo);
+  const gitStatus = coverageGitStatus(sourceRoot, repo, snapshot, baseline);
+  const consistent = baseline !== null
+    && baseline.sha256 === snapshot.sha256
+    && JSON.stringify(baseline.inputs) === JSON.stringify(snapshot.inputs)
+    && baseline.artifactGraphVersionLockSha256 === snapshot.artifactGraphVersionLockSha256;
+  const state = baseline === null ? '缺失' : consistent ? '一致' : '落后';
+  console.log(`[render-public-site --status] ${repo.name}: ${state}`);
+  console.log(`  覆盖提交: ${gitStatus.coverageCommit || '（覆盖快照尚未提交）'}`);
+  console.log(`  当前输入摘要: ${snapshot.sha256}`);
+  console.log(`  快照输入摘要: ${baseline?.sha256 || '（缺失）'}`);
+  if (snapshot.artifactGraphVersionLockSha256 !== undefined) {
+    console.log(`  artifact-graph 版本锁摘要: ${snapshot.artifactGraphVersionLockSha256}`);
+  }
+  console.log('  变化文件:');
+  if (gitStatus.changed.length) {
+    for (const path of gitStatus.changed) console.log(`    - ${path}`);
+  } else {
+    console.log('    - （无）');
+  }
+  console.log('  版本源当前值:');
+  if (versionSources.values.length) {
+    for (const item of versionSources.values) {
+      console.log(`    - ${item.token}=${item.renderedValue} (${item.source}#${item.pointer})`);
+    }
+  } else {
+    console.log('    - （未配置）');
+  }
+  console.log('  建议 git diff:');
+  for (const command of gitStatus.suggestions) console.log(`    ${command}`);
+  if (!consistent) {
+    throw new RenderError(`[render-public-site --status] ${repo.name}: 覆盖快照${baseline === null ? '缺失' : '落后'}`, 1);
+  }
+}
+
 // --- 树摘要（基于 computeResourceClosure，排除 site-baseline.json 自身，防 hash 循环） ---
 async function treeDigest(rootAbs, files) {
   const closure = await computeResourceClosure({
@@ -183,13 +482,15 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit
     return `<footer class="site">\n  <div>© ${owner} · <a href="https://www.apache.org/licenses/LICENSE-2.0" rel="noopener noreferrer">Apache-2.0</a></div>\n  <div class="generated">generated by skill-family-doc-render</div>\n</footer>`;
   }
 
-  // 版本占位符：按 repo 名自动派生（@{NAME}_TAG@ / @{NAME}_VERSION@）+ site.tokens 静态补充
+  // 版本占位符：保留按 repo 名自动派生的兼容 token；显式 JSON 版本源最后覆盖静态 token。
   const version = await pkgVersion(root, repo.source, repo.name);
+  const versionSources = await loadVersionSources(sourceAbs, repo);
   const tn = tokenName(repo.name);
   const tokens = {
     [`@${tn}_TAG@`]: (repo.tagPrefix || `${repo.name}-v`) + version,
     [`@${tn}_VERSION@`]: version,
     ...(site.tokens || {}),
+    ...versionSources.tokens,
   };
   function replaceTokens(s) {
     let out = s;
@@ -353,7 +654,8 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit
 }
 
 // === 主流程 ===
-// 闭集参数解析：允许参数只有 --check / --assert-git / --repo <name> / --help / -h。
+// 闭集参数解析：允许参数只有 --check / --assert-git / --status /
+// --refresh-coverage / --repo <name> / --help / -h。
 // 未知选项、游离位置参数、重复取值参数、--repo 缺值或值本身是另一个选项，
 // 均以 RenderError（exit 2）失败，错误信息指出具体参数。不引入 CLI 框架。
 // --help / -h 由 main() 统一呈现：闭集解析先于配置读取与写盘，打印 USAGE_TEXT 后退出 0。
@@ -364,11 +666,22 @@ Usage:
   skill-family-doc-render --check        read-only drift check against site-baseline.json
   skill-family-doc-render --repo <name>  render / check a single repo by name
   skill-family-doc-render --assert-git   also assert rendered files are git-tracked
+  skill-family-doc-render --status --repo <name>
+                                        read-only coverage status and Git changes
+  skill-family-doc-render --refresh-coverage --repo <name>
+                                        refresh only site-coverage-lock.json
 
 Reads public-release.json from the current working directory.`;
 
 function parseArgs(argv) {
-  const flags = { check: false, assertGit: false, repoArg: null, help: false };
+  const flags = {
+    check: false,
+    assertGit: false,
+    status: false,
+    refreshCoverage: false,
+    repoArg: null,
+    help: false,
+  };
   let i = 0;
   while (i < argv.length) {
     const arg = argv[i];
@@ -376,6 +689,10 @@ function parseArgs(argv) {
       flags.check = true;
     } else if (arg === '--assert-git') {
       flags.assertGit = true;
+    } else if (arg === '--status') {
+      flags.status = true;
+    } else if (arg === '--refresh-coverage') {
+      flags.refreshCoverage = true;
     } else if (arg === '--help' || arg === '-h') {
       flags.help = true;
     } else if (arg === '--repo') {
@@ -395,6 +712,15 @@ function parseArgs(argv) {
     }
     i += 1;
   }
+  if (flags.status && flags.refreshCoverage) {
+    throw new RenderError('[render-public-site] 参数错误: --status 与 --refresh-coverage 不能同时使用', 2);
+  }
+  if ((flags.status || flags.refreshCoverage) && (flags.check || flags.assertGit)) {
+    throw new RenderError('[render-public-site] 参数错误: 覆盖命令不能与 --check 或 --assert-git 组合', 2);
+  }
+  if ((flags.status || flags.refreshCoverage) && flags.repoArg === null) {
+    throw new RenderError('[render-public-site] 参数错误: --status 与 --refresh-coverage 必须配合 --repo <name>', 2);
+  }
   return flags;
 }
 
@@ -404,7 +730,7 @@ function parseArgs(argv) {
 // 单个 repo 内部（含泄漏扫描命中）保持 fail-fast。
 export async function main(argv = process.argv.slice(2), { cwd = process.cwd() } = {}) {
   // 闭集解析在读取任何配置或写盘之前完成；参数失败时目标树一个字节都不动。
-  const { check, assertGit, repoArg, help } = parseArgs(argv);
+  const { check, assertGit, status, refreshCoverage, repoArg, help } = parseArgs(argv);
   if (help) {
     console.log(USAGE_TEXT);
     return 0;
@@ -442,13 +768,15 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
   const results = [];
   for (const repo of selected) {
     try {
-      await renderRepo(root, repo, release, leakLiterals, { check, assertGit });
+      if (status) await reportCoverageStatus(root, repo);
+      else if (refreshCoverage) await refreshCoverageLock(root, repo);
+      else await renderRepo(root, repo, release, leakLiterals, { check, assertGit });
       results.push({ name: repo.name, ok: true });
     } catch (err) {
       results.push({
         name: repo.name,
         ok: false,
-        exitCode: err instanceof RenderError ? err.exitCode : 1,
+        exitCode: Number.isInteger(err?.exitCode) ? err.exitCode : 1,
         message: err.message,
         cause: err,
       });