@zxyycom/vibe-check 0.0.1 → 0.0.2

package/docs/checks/markdown-link-validation.md

@@ -1,12 +1,34 @@
 # `markdownLinkValidation`
 
-返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
-
 ## 用途
 
-本页说明 `markdownLinkValidation` 的 options、terminal effects 与安全边界。该 Check 离线验证 selected Markdown
-sources 中的本机链接、图片目标与标题锚点。`markdownLinkValidation(options?)` 补齐默认值并返回可直接放入 Project
-Definition `checks` 的普通 Check。
+`markdownLinkValidation(options?)` 构造普通 Check，离线验证所选 Markdown 中的本机链接、图片目标与标题锚点。
+
+## 最小用法
+
+示例保留终端进度，不写 machine files。
+
+```ts
+import { defineConfig, markdownLinkValidation, run } from "@zxyycom/vibe-check";
+
+const check = markdownLinkValidation({ findingPolicy: "blocking" });
+const result = await run(defineConfig({
+  checks: [check],
+  outputs: { machinePublication: { enabled: false } }
+}));
+const outcome = result.kind === "completed"
+  ? result.snapshot.checks.find(({ checkId }) => checkId === check.checkId)?.outcome
+  : undefined;
+if (result.kind !== "completed" || outcome?.status !== "passed") {
+  console.error(`Markdown link validation did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
+```
+
+示例显式使用 `findingPolicy: "blocking"`，让普通链接 Finding 导致失败；默认 `non-blocking` 只警告，不因 Finding 退出非零。
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
+显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -23,6 +45,9 @@ Definition `checks` 的普通 Check。
   validateCrossDocumentAnchors: true,
   rootExternalTargetMode: "report",
   requireNonEmptyDirectories: false,
+  cache: {
+    enabled: false
+  },
   limits: {
     maxMarkdownBytes: 1_048_576,
     maxOccurrences: 10_000,
@@ -31,23 +56,19 @@ Definition `checks` 的普通 Check。
 }
 ```
 
-上面的代码块是无参调用物化后的完整 resolved options；`exclude` 表示 constructor detached-copy 了 package root 公开
-`defaultProjectFileSelection.exclude` 的全部条目，不是调用方必须复制的输入。所有顶层 authoring fields 都可省略，
-`files` 与 `limits` 内的字段也可分别省略。显式 `include` / `exclude` 数组是完整替换值；显式宽泛 include 选中的非 Markdown
-path 会产生拒绝 Finding，而不是被静默过滤。
-
-- `files` 定义 Markdown source selection；source 可选 `filesystem` 或 `git-worktree`，selected path 必须命中
-  `include` 且不能命中 `exclude`。filesystem 不解释 `.gitignore`；git-worktree 使用已跟踪文件和未被 Git 标准忽略
-  规则排除的未跟踪文件。其中 extension 大小写不敏感的 `.md` / `.markdown` 成为 sources，direct targets 仅用于
-  resolution；来源不可用时 Check 结算为 `unavailable`，不会切换到另一来源。
-- `findingPolicy` 为 `blocking | non-blocking`，默认 `non-blocking`。它只结算本 Check 的 normal local-reference
-  findings：`blocking` 使 finding outcome 为 `failed`，`non-blocking` 保留相同的 Records、计数与 final data，但以
-  `passed` outcome 和 warning message 提示；它不会改写 Project Run、aggregation 或 Gate outcome。
+无参调用物化上述完整 options，`exclude` 是公开 `defaultProjectFileSelection.exclude` 的独立副本。
+所有顶层字段及 `files`、`limits` 子字段都可省略。
+
+- `files` 遵循[共享 files 选择语义](../guides/collecting-project-files.md#共享的-files-选择语义)。只有大小写不敏感的
+  `.md` / `.markdown` 成为 sources；其它 selected paths 发布拒绝 Finding。direct targets 仅供 resolution，不扩大 source selection。
+- `findingPolicy` 为 `blocking | non-blocking`，默认 `non-blocking`，只决定本 Check 的普通链接 Finding 是否导致失败，不改写 Run、aggregation 或 Gate outcome；Records 与计数不随 policy 改变。
 - `requireExistingTargets` 控制缺失 direct local target 是否是 finding。
 - `validateSameDocumentAnchors` / `validateCrossDocumentAnchors` 分别控制当前文档与直接 Markdown target 的 heading
   lookup。
 - `rootExternalTargetMode` 为 `ignore | report | validate`；只有显式 `validate` 才授权 bounded root-external target I/O。
 - `requireNonEmptyDirectories` 启用时最多读取 direct directory 的一个 entry，不递归遍历。
+- `cache` 默认 `{ enabled: false }`，不访问 cache filesystem，且不能带 `directory`。启用 branch 必须为
+  `{ enabled: true, directory }`，其中 directory 是非空、无 U+0000 的 host-absolute path；安全与失败行为见 [Parse-facts cache](#parse-facts-cache)。
 - `limits` 限制单文档 bytes、全部 semantic occurrences 与 direct target reads；constructor 会补齐该 branch 中省略的
   fields。`maxMarkdownBytes` 不得超过 `16_777_216`，`maxOccurrences` 不得超过 `100_000`，
   `maxTargetReads` 不得超过 `10_000`。
@@ -69,13 +90,24 @@ const documentationLinks = markdownLinkValidation({
 });
 ```
 
+### Parse-facts cache
+
+启用后，cache 在调用方指定的 absolute directory 保存可删除的 Markdown parse facts；调用方负责目录容量与删除。
+它不是输出目录，也不提供机密性或防篡改保护；不愿复制到本地状态的 Markdown 不应启用 cache。
+
+命中只避免重复计算 parse facts；每次仍用当前 selection、Markdown bytes 与 target policy 形成 Finding、Record 和 outcome，
+不改变 Check ID 或 finding policy。无法恢复 facts 时 fresh-parse；写入失败只影响后续复用，不改变本次结果或任何发布字段。
+publication 开始前取消不会启动写入；append 开始后会等待完成。cache 不缓存 settlement，也不保证跨进程协调、持久性或自动清理。
+
 ## 工作原理
 
-Check 验证 options，收集 Markdown source paths，每份 source decode / parse 一次，再处理 supported inline、
-reference 与 autolink occurrences。完整 selected paths 先按 `.md` / `.markdown` suffix 分为 accepted/rejected，每个
-rejected path 产生 supplemental Record，只有 accepted path 成为 source。target file、directory 与 GitHub-priority heading
-anchor 按上面 policy 做 bounded validation；每个 link finding 产生另一种 supplemental Record。direct target 可以参与当前
-occurrence validation，source discovery 始终由 `files` selection 决定。
+Check 先验证 options，按本页 suffix 规则完整分类 selected paths，为 rejected paths 发布 Records，再解析 accepted sources。
+对 file、directory 与 GitHub-priority heading anchor 按 policy 做 bounded validation；每个普通链接 Finding 另发 Record。
+
+一次 invocation 内，同一 canonical Markdown target 的成功 parsed headings 可以被多个 cross-document anchor occurrence
+复用。它只复用首次成功 snapshot：target 随后变化时，本次 invocation 继续使用该 snapshot；target failure 不被 memoize。每个
+occurrence 仍独立完成 destination classification、containment 与 endpoint probe，并且在 memo lookup 前消耗一个
+`maxTargetReads` 额度。因此 `targetReadCount` 和 limit 仍是 logical occurrence 计数，不是 physical file-read 计数。
 
 受支持 occurrence 包含 inline link/image、已定义的 full/collapsed/shortcut reference、explicit autolink 和选定的 GFM
 autolink literal。YAML front matter、code/fenced code、HTML attribute、普通 prose URL 与 undefined reference 不进入本
@@ -84,9 +116,8 @@ Check 的 occurrence 集合。HTTP(S)、`mailto:` 与其它非本地 target 只
 ## 效果与结果
 
 没有 normal link finding 时 outcome 为 `passed`；有 normal link finding 时，`findingPolicy: "blocking"` 为 `failed`，
-`findingPolicy: "non-blocking"` 为 `passed`。input rejection 固定 non-blocking，不受该 policy 影响。两种 finding policy 都
-保留相同的 final data 与每 finding 一条 Record；blocking link finding 附带 `invalid-local-links` error message，
-non-blocking link finding 附带同 code 的 warning message。正常 final data 恰为：
+`findingPolicy: "non-blocking"` 为 `passed`。input rejection 固定 non-blocking，不受该 policy 影响。
+两种 policy 保留相同 final data 与每 Finding 一条 Record。正常 final data 恰为：
 
 ```ts
 {
@@ -99,8 +130,9 @@ non-blocking link finding 附带同 code 的 warning message。正常 final data
 ```
 
 `occurrenceCount` 包含所有 parser-semantic occurrences，包括没有进入 local target validation 的项；
-`targetReadCount` 统计进入 direct endpoint validation 的 occurrence；`findingCount - rejectedInputCount` 是 normal link
-finding 数量并且不超过 `occurrenceCount`。每个 normal link finding 恰好形成一条 Record，data 恰为：
+`targetReadCount` 统计进入 direct endpoint validation 的 logical occurrence（包括 target-memo hit）；`findingCount -
+rejectedInputCount` 是 normal link finding 数量并且不超过 `occurrenceCount`。每个 normal link finding 恰好形成一条 Record，data
+恰为：
 
 ```ts
 {
@@ -139,9 +171,12 @@ path 或 fragment。
 ```
 
 blocking finding 的 `failed` outcome 携带 `invalid-local-links` error message；non-blocking finding 的 `passed` outcome
-携带同 code 的 warning message；两者都引导调用方检查 Records 的 source range、target 与 reason。存在 rejected input 时
-另附一条 `input-rejected` warning，只汇总数量而不省略逐路径 Record。由本 Check 结算的 `unavailable` 使用对应
-`reason.code` 提供可操作 error message；无 Finding 的 `passed` 与 `not-applicable` 不合成人为提示。
+携带同 code 的 warning message。`markdownLinkValidation` 的 detail messages 先按 normal link、再按 input rejection 的稳定
+顺序：normal 摘要只含 source project-relative path、start line/column、occurrence kind 与封闭 reason，不复制 target；rejection
+摘要只含项目相对 path。存在 rejected input 时仍先附 `input-rejected` 数量 warning；完整 source range、safe target 与 reason
+仍从 Records 读取。通用的 terminal Finding 呈现与 Run progress 预览边界见
+[呈现 Check Finding](../guides/presenting-findings.md)。由本 Check 结算的 `unavailable` 使用对应 `reason.code` 提供可操作
+error message；无 Finding 的 `passed` 与 `not-applicable` 不合成人为提示。
 
 用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseMarkdownLinkValidationData(value)` 验证 final data。两者返回
 `MarkdownLinkValidationFinalData`；Records 与原因可用 `MarkdownLinkValidationRecordData`、
@@ -154,18 +189,18 @@ blocking finding 的 `failed` outcome 携带 `invalid-local-links` error message
 selected path 数量为零时结算为 `not-applicable / no-eligible-input`。selected 非空但全部 rejected 时，不解析 source，直接以
 带 final data、Records 与 warning 的 `passed` 结算。`unavailable.reason.code` 使用以下受控值：
 
-| `reason.code` | 触发边界与调用方检查项 |
-| --- | --- |
-| `invalid-options` | constructor 返回后形成的 replacement options 不是完整 closed resolved shape；重新调用 `markdownLinkValidation(options)` 或恢复完整字段。 |
-| `project-root-unavailable` | project root 无法 canonicalize；检查路径存在性与访问权限。 |
-| `source-unavailable` | source collection、读取、decode 或 containment 失败；检查 source 与 file-selection 来源。 |
-| `source-too-large` | 某个 selected Markdown source 超过 `maxMarkdownBytes`。 |
-| `markdown-parse-failed` | selected source 无法形成完整 parser facts。 |
-| `invalid-local-destination` | local destination 无法按受支持的 path/URI grammar 安全解析。 |
-| `target-unavailable` | target containment probe、I/O、decode、parse 或 directory read 失败；Markdown anchor target 超过 `maxMarkdownBytes` 也属于此分支。 |
-| `occurrence-limit-exceeded` | semantic occurrence 总数超过 `maxOccurrences`。 |
-| `target-read-limit-exceeded` | direct endpoint validation work 超过 `maxTargetReads`。 |
-| `cancelled` | invocation signal 取消本 Check；不要把结果解释为 clean validation。 |
+| `reason.code`                | 触发边界与调用方检查项                                                                                                                   |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `invalid-options`            | constructor 返回后形成的 replacement options 不是完整 closed resolved shape；重新调用 `markdownLinkValidation(options)` 或恢复完整字段。 |
+| `project-root-unavailable`   | project root 无法 canonicalize；检查路径存在性与访问权限。                                                                               |
+| `source-unavailable`         | source collection、读取、decode 或 containment 失败；检查 source 与 file-selection 来源。                                                |
+| `source-too-large`           | 某个 selected Markdown source 超过 `maxMarkdownBytes`。                                                                                  |
+| `markdown-parse-failed`      | selected source 无法形成完整 parser facts。                                                                                              |
+| `invalid-local-destination`  | local destination 无法按受支持的 path/URI grammar 安全解析。                                                                             |
+| `target-unavailable`         | target containment probe、I/O、decode、parse 或 directory read 失败；Markdown anchor target 超过 `maxMarkdownBytes` 也属于此分支。       |
+| `occurrence-limit-exceeded`  | semantic occurrence 总数超过 `maxOccurrences`。                                                                                          |
+| `target-read-limit-exceeded` | direct endpoint validation work 超过 `maxTargetReads`。                                                                                  |
+| `cancelled`                  | invocation signal 取消本 Check；不要把结果解释为 clean validation。                                                                      |
 
 这些边界不发布 partial link-finding Records，也不提供 final data；若 selected classification 已完成，已发布的
 rejected-input Records 与对应 warning 仍保留。通用 preflight 语法见
@@ -174,19 +209,12 @@ rejected-input Records 与对应 warning 仍保留。通用 preflight 语法见
 ## I/O 与安全边界
 
 source I/O scope 只包含通过 `.md` / `.markdown` eligibility 的 accepted paths；rejected path 不读取内容。resolver I/O scope
-是本地 filesystem，HTTP、DNS、TLS 与 redirect request 数为零。默认 `report` mode 对 root-external
-target 形成 finding，显式 `validate` mode 授权 bounded read。published facts 排除 raw external absolute path、target
-bytes 与 remote credentials。
+是本地 filesystem，HTTP、DNS、TLS 与 redirect request 数为零。默认 `report` mode 对 root-external target 形成 finding，显式
+`validate` mode 授权 bounded read。published facts 排除 raw external absolute path、target bytes 与 remote credentials。
 
-## 最小用法
-
-```ts
-import { defineConfig, markdownLinkValidation, run } from "@zxyycom/vibe-check";
-const result = await run(defineConfig({ checks: [markdownLinkValidation()] }));
-```
+启用 `cache` 会额外访问调用方指定 directory，并可能写入上文所列 source-derived parse facts；它不改变 published facts，
+也不把 cache directory 当作 security boundary。调用方应仅传入自己信任、可删除的 absolute directory。
 
 ## 适用边界
 
-该 Check 只评估本机 target 与 heading-anchor integrity，不评估 remote URL reachability 或 HTML attribute links。项目需要
-这些能力时，应另外提供明确拥有网络或 HTML parsing policy 的 Check；当前 `markdownLinkValidation` 不会隐式扩展到这些
-输入。
+该 Check 不评估 remote URL reachability 或 HTML attribute links；需要时另配拥有明确网络或 HTML parsing policy 的 Check。

package/docs/checks/secret-detection.md

@@ -0,0 +1,129 @@
+# `secretDetection`
+
+## 用途
+
+`secretDetection({ files })` 是随包 ordinary Check，发现高置信 PEM private-key material。它不是全面 credential protection，也不验证 secret 有效性。
+
+## 最小用法
+
+示例保留终端进度，不写 machine files。
+
+```ts
+import { defineConfig, run, secretDetection } from "@zxyycom/vibe-check";
+
+const check = secretDetection({
+  files: { source: "filesystem", include: ["src/**/*"], exclude: ["**/generated/**"] }
+});
+const result = await run(defineConfig({
+  checks: [check],
+  outputs: { machinePublication: { enabled: false } }
+}));
+const outcome = result.kind === "completed"
+  ? result.snapshot.checks.find(({ checkId }) => checkId === check.checkId)?.outcome
+  : undefined;
+if (result.kind !== "completed" || outcome?.status !== "passed") {
+  console.error(`Secret detection did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
+```
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
+显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
+
+## 参数与默认配置
+
+`files` 必填，且必须是完整 `{ source, include, exclude }` value；它是唯一的输入授权，不提供隐式全仓库 fallback。
+
+```ts
+{
+  files: { source: "filesystem", include: ["src/**/*", "config/**/*"], exclude: ["**/generated/**"] },
+  maximumFileBytes: 1_048_576,
+  maximumTotalBytes: 8_388_608,
+  maximumFileCount: 2_048,
+  findingWaivers: []
+}
+```
+
+代码块中的 `files` 是示例选择，其余为默认值。三个 limit 都是正安全整数，可收窄或显式提高。
+files grammar、source failure 与数组替换见[共享 files 选择语义](../guides/collecting-project-files.md#共享的-files-选择语义)。
+options 不接受 arbitrary regex、command、baseline、detector allowlist 或 message suppression。
+
+## 工作原理
+
+1. 按显式 `files` 收集 exact project-relative paths，先应用文件数限制。
+2. 在本仓库验证的 POSIX Node runtime 中，以 `O_NOFOLLOW` 打开 final leaf；在同一 descriptor 上检查 regular-file、size，
+   并在单文件/剩余总预算内分块读取。未满足安全读取条件的路径不获 detector coverage。
+3. 成功读取后检查 NUL 与 fatal UTF-8，只有 approved text 交给 private adapter；它不接收 project root，也不重新枚举文件。
+
+adapter 固定使用 [Secretlint v13.0.5](https://github.com/secretlint/secretlint/releases/tag/v13.0.5) 中 MIT-licensed 的
+`@secretlint/core@13.0.5` 与 `@secretlint/secretlint-rule-privatekey@13.0.5` 单规则集合。
+第三方 source/result/message/data/exception 只短暂存在 invocation-owned memory；立即投影为 rule ID、path、safe line/column、
+`text-document` structural class 与 ordinal，不返回 raw value、substring、hash、message 或 stack。
+
+## 效果与结果
+
+`parseSecretDetectionData(data)`（或返回 Check 的 `parseData`）只在 `passed` 或 `failed` 时验证并恢复：
+
+```ts
+{ selectedFileCount, scannedFileCount, findingCount, waivedFindingCount, coverageGapCount }
+```
+
+`selectedFileCount` 是 exact selection 数；其中 `scannedFileCount` 获 bounded text coverage，`coverageGapCount` 未获得，
+恒有 `scannedFileCount + coverageGapCount === selectedFileCount`。`findingCount` 包括所有安全 Finding；
+`waivedFindingCount` 是被唯一 waiver 匹配的子集，不得大于总数。未 waived 的 Finding 是 actionable。
+
+非空 selection 中，存在 actionable Finding 或 coverage gap 即 `failed`，否则 `passed`。Records 分为：
+
+- `secret-finding`：只含 blocking、rule ID、path、safe location、structural class、ordinal，以及 applied 时的 `waiver.reason`。
+- `coverage-gap`：`{ kind: "coverage-gap", path, reason, blocking: true }`，不可豁免。
+- `finding-waiver-audit`：unused/overmatched authoring 的 identity、reason、matchCount 与 status，不豁免任何 Finding。
+
+Actionable Finding 附 `secret-findings` error，coverage gap 附 `incomplete-coverage` error；applied waiver 附 `finding-waived` info，
+unused/overmatched 附 warning。公开类型为 `SecretDetectionOptions`、`ResolvedSecretDetectionOptions`、`SecretDetectionFinalData`、
+`SecretDetectionRecordData` 与 `SecretDetectionUnavailableReasonCode`。
+
+`findingWaivers` 采用[共同 waiver reconciliation/audit](../guides/finding-waivers.md#随包-check-的采用边界)：identity 恰为
+`{ path, ruleId: "@secretlint/secretlint-rule-privatekey", structuralClass: "text-document", ordinal }`，不含 value/message/line/hash。
+唯一匹配的 finding 是 **waived finding**：它仍保留原 finding Record 与 reason，但不再计入 actionable finding。coverage gap
+与 unavailable 不受 waiver 影响。
+
+```ts
+const check = secretDetection({
+  files: { source: "filesystem", include: ["src/**/*"], exclude: [] },
+  findingWaivers: [
+    {
+      identity: {
+        ordinal: 1,
+        path: "src/legacy-key-fixture.ts",
+        ruleId: "@secretlint/secretlint-rule-privatekey",
+        structuralClass: "text-document"
+      },
+      reason: "已跟踪的 synthetic fixture；移除前保留此精确 waiver。"
+    }
+  ]
+});
+```
+
+上例的 identity 应从该 Check 的安全 finding Record 复制；不要根据 detector message、secret 值、hash 或 line 自行构造。`reason` 会作为 waiver evidence 发布，因此只写不含敏感材料的说明。
+
+## `not-applicable` 与 `unavailable`
+
+空 selection 为 `not-applicable / no-eligible-input`，无 final data；configured waiver 仍产生 unused audit。
+
+- NUL、invalid UTF-8、单文件/总 bytes/文件数超限是 deterministic `coverage-gap`，使 Check `failed`。
+  成功 descriptor read 的 raw bytes 先消耗总预算，即使随后成为 non-text gap。
+- symlink、非 regular file、read/change failure 或 runtime 不支持 `O_NOFOLLOW` descriptor open：`source-unavailable`。
+- whole-Check `unavailable` 的 closed reasons 为 `invalid-options`、`scan-input-unavailable`、`source-unavailable`、
+  `detector-unavailable`、`detector-protocol-failed`、`execution-cancelled`。它们附同 code 的 error message，无 final data 或 partial result。
+
+## I/O 与安全边界
+
+I/O 只限 files 选择的 local paths；无 command、network、history、environment、home、binary 或 remote secret-manager I/O。
+raw detector material 不进入 result、Record、message、machine output、cache、log 或 error。
+
+POSIX no-follow 只绑定 final leaf；Node 没有 portable `openat`/dirfd traversal，无法保证中间目录或已打开 inode 不被恶意并发替换。
+需要该隔离级别时，调用方须使用 OS-level sandbox。
+
+## 适用边界
+
+只选择需保护的 text-bearing paths；发现材料后应移除或使用精确、带理由的 waiver，不将本 Check 当作全面 secret scanner。

package/docs/examples/artifacts/mixed-outcomes/definition.ts

@@ -59,11 +59,11 @@ const releaseInputs = defineCheck({
   }
 });
 
-// 一个 downstream policy：读取内置 Check 和 typed provider 的 final data。
+// 一个 downstream policy：观察内置 Check 和 typed provider 的 terminal outcome，再读取可用 final data。
 const releasePolicy = defineCheck({
   checkId: "example-release-policy",
   displayName: "Example release policy",
-  dependsOn: inherit({ add: [releaseInputs.checkId] }),
+  observes: inherit({ add: [releaseInputs.checkId] }),
   options: { minimumFileCount: 2 },
   visibility: "attention",
   execution({ dependencies, options, records }) {
@@ -151,7 +151,7 @@ const optionalDocumentation = defineCheck({
       : { status: "not-applicable", reason: { code: "documentation-disabled" } }
 });
 
-// block preflight 会在任何 Check execution 开始前把本 Check 结算为 unavailable。
+// block preflight 只阻止本 Check 的 execution，并将其结算为 unavailable；不相关的 Check 仍可并行。
 const externalReview = defineCheck({
   checkId: "example-external-review",
   displayName: "Example external review",
@@ -176,12 +176,12 @@ const externalReview = defineCheck({
   execution: () => ({ status: "passed", data: { reviewed: true } })
 });
 
-// 组织节点自身不产生 outcome；children 继承 packageManifest dependency 和并行预算。
+// 组织节点自身不产生 outcome；children 继承 packageManifest observation 和并行预算。
 const releaseWorkflow = defineCheck({
   checkId: "example-release-workflow",
   displayName: "Example release workflow",
   checks: [releaseInputs, releasePolicy, optionalDocumentation, externalReview],
-  dependsOn: [packageManifest.checkId],
+  observes: [packageManifest.checkId],
   maxParallel: 2
 });
 

package/docs/guides/cache-results.md

@@ -0,0 +1,63 @@
+# 缓存计算结果
+
+`cacheJsonByKey(...)` 是 package 预提供的可选工具：当 custom Check 或普通项目代码已经能生成**完整的 semantic key**时，
+调用它复用 caller-owned 的本地 canonical JSON 计算结果。调用完成后，调用方可按自己的 Check 或项目流程继续处理该结果。
+
+## 最小用法
+
+```ts
+import { cacheJsonByKey } from "@zxyycom/vibe-check";
+
+const directory = `/tmp/my-project-vibe-check-cache-${Date.now()}-${Math.random()}`;
+let measurements = 0;
+const options = {
+  compute: () => ({ bytes: ++measurements * 1024 }),
+  directory,
+  key: "bundle-input:source-v3:tool-v1",
+  namespace: "my-project.bundle-size",
+  parse(value: unknown): { readonly bytes: number } {
+    if (
+      value === null ||
+      typeof value !== "object" ||
+      Array.isArray(value) ||
+      typeof (value as { bytes?: unknown }).bytes !== "number"
+    ) {
+      throw new TypeError("Invalid bundle-size cache payload");
+    }
+    return value as { readonly bytes: number };
+  },
+  version: "1"
+};
+const first = await cacheJsonByKey(options);
+const second = await cacheJsonByKey(options);
+if (first.source !== "computed" || second.source !== "cache" || measurements !== 1) {
+  throw new Error("Expected one computation followed by a cache hit");
+}
+```
+
+## key、payload 与结果
+
+调用方提供 absolute、信任且可删除的 `directory`、非空 `namespace`、payload `version`、opaque
+`key`、同步 `parse` 与同步/异步 `compute`。`key` 必须覆盖所有会改变 computation 结果的输入、
+实现版本、options、toolchain 与声明的外部状态；helper 不判断 key 是否完整。
+
+helper 对固定 API version、namespace、version 和 key 的 canonical structure 计算 SHA-256 identity，
+只以 digest 命名 entry。raw key 不进入文件名、envelope、result 或 helper-owned diagnostics。磁盘 entry
+在 closed envelope、identity、canonical object payload 与同步 parser 都成功前不可信；只有全部通过才是 hit。
+miss、invalid payload 或 read failure 后，helper 恰好调用一次 `compute`，并让 computed payload 经过相同的
+detached canonical-object/parser boundary。
+
+返回的冻结 result envelope 表示本次 helper 调用，而非 Check 结算：hit 为
+`{ source: "cache", read: "hit", write: "not-attempted" }`；computed 为
+`{ source: "computed", read: "miss" | "invalid" | "failed", write: "stored" | "failed" }`。compute 或
+parser failure 直接传播且不写 entry；storage failure 不改变已接受的 computed value，也不自动创建 Check
+message、Record 或 terminal status。parser owner 决定是否进一步冻结它返回的 domain value。
+
+## 并发与安全边界
+
+写入在 caller directory 内经 unique temporary file 和 atomic rename 发布。并发 miss 可以重复 computation，
+但 target 只作为完整有效 entry 读取。需要避免重复 computation 时由调用方协调并发；缓存目录的清理也由调用方负责。
+
+directory 是 caller 信任且可删除的本地 state，不提供 containment、remote sharing、authenticity 或 secret
+protection；不得将 secret、token 或低熵敏感材料放入 key，SHA-256 digest 也不是保密机制。consumer 自己
+决定是否把 `read` / `write` observation 转换为 Check 事实。

package/docs/guides/callbacks.md

@@ -0,0 +1,34 @@
+# 按作用位置选择回调（Hook）
+
+当你知道想在“执行前准备”“检查时决定结果”“显示时调整文本”或“结束后处理统计”，却不确定应该使用哪个回调时，从本文选择接入位置。本文按接入位置说明公开回调的分工；字段签名以 installed declarations 为准，项目定义与本次运行的参数归属见 [API 机制](../api-mechanics.md#参数应该放在哪里)。
+
+## 先按三条链路理解位置
+
+- **单项 Check**：被 Scheduler 准入 → `preflight` 准备 options → `execution` 形成结果 → Product 验证并结算。某项准备被阻断时不会继续 execution；不同 Check 可以并发。
+- **人读说明**：Check 用 `presentCheckFindings` 将 Finding 转成 messages 并附到自己的结果 → Product 显示明细时用 progress `formatter` 调整预览文本。前者在 Check 生成说明的位置，后者在终端显示的位置，两者都不替代检查结果的判定。
+- **调度策略**：graph 准备好后，可选 `prepare` 形成当前 Run 的策略 → Scheduler 调用 `decide` 零次或多次，每次同步返回一个 select / wait proposal → Scheduler 停止准入、等待已启动任务并封闭统计 → `measurementHooks` 观察终态 → 存在 terminal context 时调用可选 `complete`。simple strategy 不经过 `prepare`。
+
+完整 Run 的验证、取消与输出衔接仍由 [API 生命周期](../api-mechanics.md#一次-run-的生命周期)说明。
+
+## 回调的配置位置与权限
+
+先确定要在什么位置做什么，再选择对应字段。下表用于定位，不是一条所有回调都会执行的串行流程：不同 Check 可以并发，progress 也会随运行持续呈现。
+
+| 作用位置与目的 | 写在哪里 | 接收什么、产生什么 | 能改变的范围 |
+| --- | --- | --- | --- |
+| **调度开始前：准备本次调度策略** | Definition 的 [`scheduler.admissionPolicy.strategy`](scheduling.md#已准备的-custom-strategy) 选择 `kind: "prepared"`，提供 `prepare` | 接收静态 graph，返回本次使用的 `decide` 与可选 `complete` | 准备策略自己的运行状态，不执行 Check。 |
+| **调度选择时：决定建议先运行哪项** | [simple strategy 的 `decide`](scheduling.md#自定义准入-policy)，或 `prepare` 返回值中的 `decide` | 接收当前准入 context，同步返回 select / wait proposal | 只提出选择，Scheduler 仍检查依赖、互斥、容量与取消。 |
+| **单项 Check 被准入后、执行前：准备 options** | [`preflight`](extending-check-lifecycle.md#preflight准备阻止或带-fallback-继续) | 接收 authored options 和 signal，返回 prepared options、fallback 或阻断结果 | 影响这项 Check 是否继续及其 execution 输入，不是整个 Run 的前置 hook。 |
+| **单项 Check 执行时：检查并决定自己的结果** | [`defineCheck({ execution, ... })`](extending-check-lifecycle.md) | 接收 Check context，返回四态 terminal result，可报告 Records | 形成这项 Check 的领域结果；Product 验证并封闭事实，不开放事后改写结果的通用 hook。 |
+| **Check 生成 Finding 说明时：选择如何描述发现** | [`presentCheckFindings({ message, omittedMessage, ... })`](presenting-findings.md) | 单项 Finding 或省略集合转成 `CheckMessage`，helper 返回 messages | 由 Check 将说明附到自己的结果；不是终端 renderer，也不负责决定通过或失败。 |
+| **终端显示已结算 Check 的明细时：调整预览文本** | Definition 或 Controls 的 [`outputs.progressRendering.formatter`](run-outputs.md#配置-preview-文本) | 接收选中项的默认文本和预算，同步返回替代文本 | 只改变终端预览，不改写完整 Records、messages 或 Check outcome。 |
+| **调度停止且已启动任务结束后：观察终态统计** | Definition 的 [`scheduler.measurementHooks`](scheduling.md#观察终态-measurement) | 接收冻结的 graph、settlement observations 与 raw measurement | 消费或保存终态观察，不能重跑任务或改写 Check facts。 |
+| **终态观察交付后：完成本次已准备策略** | `prepare` 返回值中的可选 `complete` | 存在 sealed terminal context 时接收该 context，至多调用一次 | 完成策略自己的终态工作；不是保证所有失败路径都会调用的通用 `finally`。 |
+
+## 结算结果与结算后工作
+
+**“结算结果”和“结算后做事”不同。** Check 的 `execution` 与领域 policy 决定本项结果；本次 `checkAggregation` 从已结算状态派生 Run aggregate，它是配置而不是回调。若要根据完整 `RunResult` 决定 CI 退出码或做项目后处理，在项目代码 `await run(...)` 之后处理；这不是 Product 提供的另一组生命周期 hook。
+
+## 回调失败如何反馈
+
+`preflight` / `execution` 的失败由 owning Check 结算。progress formatter、measurement Hooks 与 prepared `complete` 的失败通过对应 output status 反馈，并保留已形成的 Check facts；原本正常完成的 Run 会成为 `kind: "output"`，已有取消或执行失败则保留主结果。完整优先级见[输出状态与失败处理](run-outputs.md#输出状态与失败处理)。

package/docs/guides/check-dependencies.md

@@ -0,0 +1,121 @@
+# 读取 Check 依赖与类型化数据
+
+需要把一项 Check 的结果交给另一项使用时，先声明 direct `dependsOn` 或 `observes`，再通过 dependency reader 读取上游结果，并用 provider parser 恢复业务类型。需要上游通过才开始时选择 `dependsOn`；需要审计任意终态时选择 `observes`。这些关系还约束 Scheduler 准入，调度预算见[调度 Check](scheduling.md)。
+
+## 完整运行示例
+
+```ts
+import { defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
+
+const CHANGED_FILES_DATA_VERSION = 1 as const;
+
+type ChangedFilesData = Readonly<{
+  readonly files: readonly string[];
+  readonly version: typeof CHANGED_FILES_DATA_VERSION;
+}>;
+
+const changedFiles = defineCheck({
+  checkId: "changed-files",
+  displayName: "Changed files",
+  parseData(data): ChangedFilesData {
+    if (
+      data.version !== CHANGED_FILES_DATA_VERSION ||
+      !Array.isArray(data.files) ||
+      !data.files.every((value): value is string => typeof value === "string")
+    ) {
+      throw new TypeError("Unsupported changed-files data");
+    }
+    return { files: data.files, version: data.version };
+  },
+  execution() {
+    return {
+      status: "passed",
+      data: { files: ["src/index.ts"], version: CHANGED_FILES_DATA_VERSION }
+    };
+  }
+});
+
+const analyzeChangedFiles = defineCheck({
+  checkId: "analyze-changed-files",
+  displayName: "Analyze changed files",
+  dependsOn: [changedFiles.checkId],
+  execution({ dependencies }) {
+    const read = dependencies.get(changedFiles.checkId);
+    if (!read.ok) return { status: "unavailable", reason: { code: read.error.code } };
+
+    const data = changedFiles.parseData(read.data);
+    return { status: "passed", data: { analyzedFileCount: data.files.length } };
+  }
+});
+
+const definition = defineConfig({
+  checks: [changedFiles, analyzeChangedFiles],
+  outputs: {
+    diagnosticLogging: { enabled: false },
+    machinePublication: { enabled: false },
+    progressRendering: { enabled: false }
+  }
+});
+
+const result = await run(definition);
+if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
+```
+
+上例先收窄 `get` 的 `ok`，再显式调用 producer 的 `parseData`。`dependsOn` 保证 callback 只在 provider `passed` 后开始；`!read.ok` 仍作为读取边界防御。八个随包 Check 都提供 `parseData` 和同实现的 package-root parser，名称与类型见各自指南。
+
+## 批量审计 direct outcomes
+
+审计任意终态时声明 `observes`，再用 `dependencies.list()` 读取 direct union 的冻结 `{ checkId, outcome }[]`。四态 outcome 都是正常可观察事实；以下 Check 从中形成自己的结果，而不修改 producer：
+
+```ts
+const auditChangedFiles = defineCheck({
+  checkId: "audit-changed-files",
+  displayName: "Audit changed files",
+  observes: [changedFiles.checkId, analyzeChangedFiles.checkId],
+  execution({ dependencies }) {
+    const observations = dependencies.list();
+    const readable = observations.filter(
+      ({ outcome }) =>
+        outcome.status === "passed" || outcome.status === "failed",
+    );
+    const changedFilesObservation = readable.find(
+      ({ checkId }) => checkId === changedFiles.checkId,
+    );
+    if (changedFilesObservation === undefined) {
+      return {
+        status: "unavailable",
+        reason: { code: "changed-files-data-unavailable" },
+      };
+    }
+
+    const data = changedFiles.parseData(changedFilesObservation.outcome.data);
+    return {
+      status: "passed",
+      data: {
+        directDependencyCount: observations.length,
+        changedFileCount: data.files.length,
+      },
+    };
+  },
+});
+```
+
+读取 `passed` / `failed` data 后仍需调用 producer parser；其余状态保留原 reason。consumer 可据此形成 summary、I/O、Records、messages 与自身终态，但不能修改、取消、重跑或重结算 producer。
+
+## Provider 类型与解析边界
+
+通过 `defineCheck({ execution, parseData })` 建立 typed provider：同步 parser 的返回类型同时约束该 Check 的 `passed` / `failed` data，返回值保留必需的 `parseData`。普通递归 `Check` 类型本身不声明 parser；仅写 `satisfies Check` 或 inline `defineConfig` 不建立该类型关系。没有 parser 的普通 Check 仍合法，container 则不能声明 parser。
+
+TypeScript 拒绝 async 或返回 `PromiseLike` 的 parser，即使推断结果类型很宽。canonical JSON 中非 callable 的 `then` 字段仍是普通数据。JavaScript 或显式 cast author object 上的 function parser 可以通过 runtime Definition validation，但不会因此取得 TypeScript 关系；自有 `parseData: undefined` 规范化为省略。
+
+parser 接收 Check-facts-owned 的 detached、deep-frozen canonical object，而不是原始 author object 或 JSON 文本。provider 拥有 shape、版本、业务不变量与抛错策略；Product 不自动调用 parser，也不另建 parser-rejection result。consumer 在自己的 execution 中调用 parser 时，未捕获的抛错沿用 Check execution 的失败边界。
+
+同版本可信 provider 若已有测试保证 shape，可以把 parser 用作 identity/type anchor；这不是对 JavaScript、cast、跨版本 artifact 或不可信输入的运行时验证。此类输入应由 provider 显式验证。每个随包 Check 的同名 `parseData` 与 package-root parser 只解析单个 final-data object，不替代 [machine publication/schema 验证](../output.md)。
+
+## Direct relation 与读取规则
+
+- `dependsOn` 与 `observes` 命名同一 Definition 中的 executable Check。两者各自可继承父 collection；精确数组完整替换（`[]` 清空），`inherit({ add, remove })` 显式增删后去重。一个 provider 不得同时出现在两类 relation 中。
+- `dependsOn` 等所有 direct provider 通过才允许本 Check 的 preflight/execution；任一 provider 非 `passed` 时，本 Check 在 author work 前成为 `unavailable / dependency-not-passed`，reason 带 direct blocker `checkIds`，duration 为 `null`。`observes` 只等待终态，不要求通过。
+- `get(checkId)` 是 non-generic string read，只授权 normalized effective `dependsOn ∪ observes` 的 direct ID（包括各自继承项）。未声明、传递或 malformed ID 返回不泄露 upstream fact 的 `dependency-not-declared`。
+- 已声明 provider 的 `passed` / `failed` 返回 `ok: true`、status 与 canonical data；`not-applicable` / `unavailable` 返回 `ok: false`、该 status 与 `upstream-data-unavailable`。TypeScript 类型本身不授予访问权。
+- `list()` 无参返回同一 direct union 的完整四态 observations，按 normalized effective direct ID 稳定排序并去重；数组、每项与 Core-owned outcome 都冻结。不读取传递、未声明或 ambient executed Checks，也不提供 Records、scheduler timing 或全局历史。