@zxyycom/vibe-check 0.0.1 → 0.0.3

package/docs/guides/data-boundaries.md

@@ -0,0 +1,140 @@
+# Core 数据工具：JSON 规范化与结构快照
+
+这两组公开 Core 工具让调用方复用 Core 的数据处理规则：取得独立的 JSON 数据副本、生成确定性文本或字节，
+或检查配置对象和数组的外层结构。它们都从 package root 导入，无需创建 Check、Project Definition 或 Run。
+工具只负责下表所列的数据处理；调用方仍负责字段含义、取值范围和业务规则。
+
+## 选择工具
+
+两组工具解决不同问题，不是一条必须依次调用的流水线。
+
+| 需要的结果 | 选择 | 成功结果 | 不符合输入规则时 |
+| --- | --- | --- | --- |
+| 独立、递归冻结的 JSON 数据副本 | `canonicalizeJsonValue`；顶层必须是非数组对象时用 `canonicalizeJsonObject` | 规范化后的 JSON 值或对象 | 返回 `undefined` |
+| 确定性 JSON 文本或 UTF-8 字节 | `canonicalJsonText` / `canonicalJsonBytes` | 文本 / `Uint8Array`，内部已执行规范化，无须先调用 `canonicalize*` | 抛出 `TypeError` |
+| 字段恰好匹配的配置对象，或无空洞的标准数组 | `snapshotExactClosedRecord` / `snapshotClosedArray` | 冻结的浅副本，保留字段值或元素的引用 | 返回 `undefined` |
+
+JSON 规范化/序列化工具只接受下文定义的 JSON 数据；结构快照不要求字段值或元素是 JSON，因而也适合包含
+回调的配置。两组工具可分别使用：不先做结构快照，也能规范化或序列化；不先规范化，也能做结构快照。
+输入可以是程序构造的值，也可以是解析得到的数据；是否来自外部，不改变各工具的输入规则。
+
+## 取得独立的 JSON 副本
+
+当需要保留一份不会被调用方后续修改影响的数据时，使用规范化工具。对象版本直接约束顶层类型；
+value 版本也接受数组和 JSON 基本值。两者都会递归复制并冻结支持的数据，而不是冻结原对象。
+
+```ts
+import { canonicalizeJsonObject, canonicalizeJsonValue } from "@zxyycom/vibe-check";
+
+const authoredLimits = { maxFindings: 10 };
+const limits = canonicalizeJsonObject(authoredLimits);
+if (limits === undefined) throw new TypeError("Expected JSON object limits.");
+
+authoredLimits.maxFindings = 20;
+if (limits.maxFindings !== 10 || !Object.isFrozen(limits)) {
+  throw new Error("Expected an independent frozen limits object.");
+}
+
+// 顶层不一定是对象时，选择 value 版本。
+const fileList = canonicalizeJsonValue(["src/index.ts"]);
+if (!Array.isArray(fileList) || !Object.isFrozen(fileList)) {
+  throw new Error("Expected a frozen JSON array.");
+}
+```
+
+## 生成确定性文本或字节
+
+调用方先决定哪些字段参与比较或缓存身份，再选择文本或字节输出。同一组数据仅改变对象属性的插入顺序，
+不会改变输出；数组元素顺序仍然有意义。字节版本可直接用于摘要计算或二进制接口，不要求调用方重复编码步骤。
+摘要计算本身和缓存 key 的完整性不由这些工具负责。
+
+```ts
+import { canonicalJsonBytes, canonicalJsonText } from "@zxyycom/vibe-check";
+
+// 调用方决定哪些字段影响计算结果；工具只负责一致的数据表示。
+const cacheInputs = { mode: "strict", paths: ["src/index.ts"] };
+const keyText = canonicalJsonText(cacheInputs);
+const keyBytes = canonicalJsonBytes(cacheInputs);
+
+if (
+  keyText !== canonicalJsonText({ paths: ["src/index.ts"], mode: "strict" }) ||
+  new TextDecoder().decode(keyBytes) !== keyText
+) {
+  throw new Error("Expected one deterministic representation for the selected cache inputs.");
+}
+```
+
+## 检查含回调的配置结构
+
+结构快照可保留函数、`undefined` 和嵌套引用。先检查外层有哪些字段，再验证字段内容；需要检查嵌套数组时，
+单独调用数组工具。它们不把整个配置转换为 JSON，也不深复制或冻结回调及其关联对象。
+
+```ts
+import { snapshotClosedArray, snapshotExactClosedRecord } from "@zxyycom/vibe-check";
+
+const onComplete = () => "done";
+const authoredTask = { name: "build", onComplete, paths: ["src/index.ts"] };
+const task = snapshotExactClosedRecord(authoredTask, ["name", "onComplete", "paths"]);
+if (task === undefined || typeof task.name !== "string" || typeof task.onComplete !== "function") {
+  throw new TypeError("Expected a closed task configuration with a name and callback.");
+}
+
+// 外层字段检查不验证 paths 的内容；数组结构和元素语义分别检查。
+const selectedFiles = snapshotClosedArray(task.paths);
+if (selectedFiles === undefined || !selectedFiles.every((path) => typeof path === "string")) {
+  throw new TypeError("Expected a dense list of file paths.");
+}
+if (task.onComplete !== onComplete || task.paths !== authoredTask.paths) {
+  throw new Error("Expected the shallow snapshot to preserve callback and nested references.");
+}
+```
+
+## Canonical JSON
+
+### 输入与副本
+
+输入接受 `null`、boolean、string、有限 number、使用 `Array.prototype` 的无空洞数组，以及使用
+`Object.prototype` 或 null prototype 的对象。拒绝 `undefined`、非有限 number、function、symbol、bigint、
+循环引用、存取器属性、不可枚举的自有属性、数组额外自有属性和其它原型。数组自身的标准 `length` 属性是例外。
+共享但非循环的引用可以接受，规范化结果不承诺保留原引用之间的别名关系。
+
+`canonicalizeJsonValue` 返回独立、递归冻结的 JSON 值；`canonicalizeJsonObject` 额外要求顶层为非数组对象。
+数值 `-0` 转换为 `0`。结果中的对象使用 **null prototype**，没有继承的对象方法；检查属性时使用
+`Object.hasOwn`，不要调用 `result.hasOwnProperty`。结果数组仍使用 `Array.prototype`。
+
+`CanonicalJsonPrimitive`、`CanonicalJsonValue` 和 `CanonicalJsonObject` 只描述静态数据结构，便于声明参数和结果。
+它们不是运行时验证凭证：例如普通 `number` 类型仍可表示 `NaN`，对象类型也不能证明数据已冻结、具有 null prototype
+或没有循环。有限数值和其它输入约束只能由规范化函数在运行时检查，不能通过类型标注或断言取得。
+
+### 确定性序列化
+
+`canonicalJsonText` 输出无额外空白的 JSON 文本。对象 key 按 JavaScript 字符串 `<` 比较的顺序排列，
+数组保留元素顺序，`-0` 输出为 `0`；字符串和其余基本值按 JSON 表示规则输出。
+`canonicalJsonBytes` 返回该文本的 UTF-8 编码。这些表示规则属于公开契约，不随内部重构任意改变；
+它们不承诺遵循其它 canonical-JSON 标准或执行 Unicode normalization。
+
+**规范化对象不是已序列化的规范文本。** `JSON.stringify` 对整数索引属性的枚举顺序不同：对于含 `"2"`、`"10"`
+两个 key 的对象，原生序列化先输出 `"2"`，`canonicalJsonText` 则先输出 `"10"`。需要上述确定性格式时，
+直接使用 `canonicalJsonText` 或 `canonicalJsonBytes`，不要以 `JSON.stringify(canonicalizeJsonObject(...))` 替代。
+
+## 闭合快照
+
+`snapshotExactClosedRecord(value, keys)` 要求顶层是非数组的 plain/null-prototype 对象，且自有 key 恰好匹配
+调用方提供的无重复 string 列表；所有自有属性必须是可枚举的数据属性。缺字段、多字段、symbol key、存取器属性或
+不可枚举属性都会被拒绝。`keys` 应由调用方持有并保持稳定；成功结果是使用 `Object.prototype` 的冻结浅副本。
+
+`snapshotClosedArray(value)` 要求使用 `Array.prototype` 的无空洞数组，除标准 `length` 与可枚举索引外没有其它
+自有属性，也没有存取器属性。成功结果是冻结的标准数组浅副本。
+
+两种快照均不检查字段值或元素的业务类型，也不要求它们是 JSON：函数、`undefined`、嵌套对象和引用可以保留。
+嵌套内容不会被复制或递归冻结，`-0` 不会被转换。浅副本固定的是外层结构，不是整棵数据的内容；
+需要独立 JSON 副本时选择规范化工具，不要把浅快照当作深层验证结果。
+
+## 执行与适用边界
+
+工具读取属性描述符，不调用输入的 getter 或 `toJSON` 方法。反射 Proxy 时仍可能执行其 trap；
+trap 抛出导致输入无法读取时，按所选工具的失败模型返回 `undefined` 或抛出 `TypeError`，不承诺隔离 trap 的副作用。
+这不是任意 JavaScript 对象的安全沙箱。
+
+这些工具不解析 JSON 文本，不替代领域 schema 或字段验证，也不提供签名、认证、保密性或文件系统权限控制。
+调用方按实际用途选择工具及失败处理，不必为了使用它们引入 Core 的运行生命周期。

package/docs/guides/extending-check-lifecycle.md

@@ -0,0 +1,164 @@
+# 编写会正确结算的自定义 Check
+
+本专题面向需要把项目规则接入 Vibe Check 的调用方：选择 `prepare` 或 `execute`，读取 callback 输入，返回可信终态，并在需要时发布补充事实。先能用一个普通 `execute` 完成规则；只有必须在执行前准备或验证 options 时才增加 `prepare`。一次 Run 的公共生命周期、输出优先级和完整结果模型见 [API 机制](../api-mechanics.md)。
+
+## 选择扩展点
+
+| 需求 | 使用方式 | 不要用它做什么 |
+| --- | --- | --- |
+| 规则可直接测量并结算 | `execute(context)` | 不要在 callback 外留下未等待的工作。 |
+| 执行前验证或把 authoring options 变成 invocation-local 的准备值 | `prepare(options, signal, project?)` 后接 `execute(context)` | 它不是全局启动 hook；只在本 Check 已获准入后运行。 |
+| 保存不决定终态的逐项事实 | `context.records.report({ id }, data)` | Record 不能替代 `passed`、`failed`、`not-applicable` 或 `unavailable`。 |
+| 读取已声明上游结果 | `dependsOn` 或 `observes`，再从 `context.dependencies` 读取 | 不能读取未声明、传递或任意已运行的 Check。 |
+| 向 direct prerequisite consumer 交接 same-Run reference | 在 provider 上声明 `handoff: true`，并在 `passed` result 返回 `handoff` | 不能用它发布到 RunResult、machine、progress、diagnostic 或 cache；不扩大 `observes` 权限。 |
+
+`defineCheck(...)` 定义的 object 是公开 authoring surface。`prepare`、`execute`、`parseData` 都是调用方实现的受信任回调。Product 只提供各自声明的输入；回调独立执行的 I/O 仍由调用方负责。
+
+## 定义 Check
+
+下例同时展示 options 验证、取消、Record、message 和 terminal data。例子的固定输入只为独立运行；接入项目时应以自己拥有的读取或测量逻辑替换它。
+
+```ts
+import { defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
+
+function hasValidLicensePolicyOptions(options: object): boolean {
+  const denied: unknown = Reflect.get(options, "denied");
+  return (
+    Object.keys(options).length === 1 &&
+    Object.hasOwn(options, "denied") &&
+    Array.isArray(denied) &&
+    denied.every((license) => typeof license === "string")
+  );
+}
+
+const licensePolicy = defineCheck({
+  checkId: "license-policy",
+  displayName: "License policy",
+  options: { denied: ["GPL-3.0-only"] },
+  prepare(options) {
+    return hasValidLicensePolicyOptions(options)
+      ? { status: "success", preparedOptions: options }
+      : { status: "failure", action: "block", reason: { code: "invalid-options" } };
+  },
+  omitQuietPassedRow: true,
+  execute({ options, records, signal }) {
+    if (signal.aborted) return { status: "unavailable", reason: { code: "cancelled" } };
+
+    const deniedCount = options.denied.length;
+    if (deniedCount > 0) {
+      records.report({ id: "denied-license" }, { count: deniedCount });
+      return {
+        status: "failed",
+        data: { deniedCount },
+        messages: [{ level: "warning", code: "denied-license", message: "Denied licenses found." }]
+      };
+    }
+    return { status: "passed", data: { deniedCount: 0 } };
+  }
+});
+```
+
+### 省略安静通过行
+
+把 `omitQuietPassedRow: true` 写在 **executable Check** 上，可在它安静通过时省略其
+settled row。它不是一般 boolean 开关：公开类型和 closed runtime grammar 只接受字面量
+`true`；省略或自有 `undefined` 都表示默认 `false`。container 不能声明它，它也不会继承给
+children；`false`、旧 `visibility` 字段和其它值都会使 Definition validation 失败。
+
+需要按调用方自己的条件启用时，组合对象以加入或省略字段，不要把条件结果赋给该字段：
+
+例如，在 Check object 中写
+`...(shouldReduceSuccessfulOutput ? { omitQuietPassedRow: true as const } : {})`；条件为否时字段不存在，
+条件为真时才加入 literal opt-in。
+
+这里的**安静通过**精确定义为 `status: "passed"`，且该次 settlement 接受的 Records 和
+messages 都为空。final `data` 不参与判定；`recordPreviewLimit`、`messagePreviewLimit`、
+formatter 返回的文本和终端截断也不会把已有 accepted detail 变成安静通过。非通过 outcome，
+或带任一 accepted Record/message 的通过，都会保留 settled presentation。具体终端格式、计数
+与默认输出边界见[进度呈现](run-outputs.md#progress-rendering)。
+
+## 按 flag 选择 Check
+
+`enabledByFlags` 决定 executable Check 是否参与本次 Run；它不替代权限、环境检测或 callback 内的业务条件。先选最简单的
+正向写法：单个 token 使用 `when: "token"`；组合 token 时导入 builder；只有命中的 downstream Check 还需要启动其
+`dependsOn` prerequisite 时才加入 `propagateDependsOn: true`。
+
+```ts
+import { all, any, changeFlag, defineCheck } from "@zxyycom/vibe-check";
+
+const sourceAware = defineCheck({
+  checkId: "source-aware",
+  displayName: "Source aware",
+  enabledByFlags: {
+    when: any(all("required", changeFlag("source")), "force"),
+    propagateDependsOn: true
+  },
+  execute: () => ({ status: "passed", data: {} })
+});
+```
+
+### Condition grammar
+
+`CheckFlagCondition` 是 builder、raw JSON、Definition snapshot 与 evaluator 共用的唯一递归 AST；非空字符串
+本身就是 atom leaf。
+
+| 要表达什么 | 写法 | 约束 |
+| --- | --- | --- |
+| 单个 token | `when: "token"` | token 非空；只测试 presence。 |
+| 全部、任一、全无、非全、恰一 | `all`、`any`、`none`、`notAll`、`exactlyOne` | 每个 builder 至少接收一个字符串或嵌套 condition。 |
+| 反转一个 condition | `not(condition)` | 只接收一个 condition。 |
+| 生成或序列化 set condition | raw `{ kind, conditions }` | `kind` 为 `all` / `any` / `none` / `not-all` / `exactly-one`；`conditions` 是非空列表。 |
+| 生成或序列化 unary condition | raw `{ kind: "not", condition }` | `condition` 是唯一 child。 |
+
+Definition 复制、验证并冻结这个 AST；set child 的顺序和重复次数保留，因此重复 child 仍影响
+`exactlyOne`。`changeFlag(id)` 只生成受保护的 `vibe-check:change:<id>` string token（literal `id` 保留 literal type）；
+它不读取 Git。使用该 token 时，Definition 必须在同一 `changes.flags` 声明 `id`，否则在 author work 前失败。需要
+Git source、regions 与 `project.changes` evidence 时，使用[按文件变化选择 Check](../api-mechanics.md#按文件变化选择-check)。
+
+### Selection and propagation
+
+没有 `enabledByFlags` 的 executable Check 默认参与选择。condition 命中时 Check 参与选择；不命中且未被传播带入时，
+它在 preparation/execution 前以 `not-applicable / flag-condition-not-matched` 结算，duration 为 `null`。
+
+`propagateDependsOn: true` 只把命中 root 的传递 `dependsOn` closure 加入本次选择。被带入的 dependency 即使自身
+condition 不命中也按普通 lifecycle 调度；`observes` 永不进入 closure，hard prerequisite 是否通过仍由 Scheduler 决定。
+省略 propagation 保持 direct-match selection。Definition 拥有 closed validation、snapshot/fingerprint；Run 拥有
+effective selection 和 callback projection。
+
+## `prepare`：准备、阻止或带 fallback 继续
+
+`prepare(options, signal, project?)` 收到 authoring options 的深度只读视图、这次 Run 的同一取消 signal，以及同 `execute` 一致的只读 project context。Product 每次 Run 都传入第三参数；公开 callback 类型把它标为 optional，以兼容调用方直接调用既有两参数 callback。需要读取它时先处理 optional value，而不是推断配置 `changes` 时 Product 会省略 project。authored 与 prepared options 同形时可省略 `prepare`；两种 shape 不同时，TypeScript 要求提供它。它只能返回以下三种结果（每种都可附有序 `messages`）：
+
+- `{ status: "success", preparedOptions }`：把准备后的 object 交给 `execute` 的 `context.options`。
+- `{ status: "failure", action: "block", reason }`：本 Check 使用该 reason 直接结算为 `unavailable`，不接受 `fallback`，不会运行 `execute`。
+- `{ status: "failure", action: "continue", fallback, reason, messages? }`：以 `fallback` 继续执行。`reason` 是 Check-owned diagnostic identity，不会单独形成 outcome；需要让调用方观察准备诊断时，在 `messages` 返回说明，随后仍以 execution 的 terminal outcome 为准。
+
+准备值只属于本次 invocation，Product 会 canonicalize 并冻结后再交给 `execute`；不要修改传入 options，也不要把它当作跨 Run 缓存。preparation throw/reject 使用 `preparation-threw`，非法结果/message/reason 或非 canonical prepared/fallback 使用 `invalid-preparation-result`，只使本项 `unavailable`，不是整个 Definition 的配置错误。block 或 preparation failure 尚未开始 author execution，duration 为 `null`；已经接受的 preparation messages 仍保留。execution 的 throw、非法返回值和 Record 写入错误也会由 Product 结算为本项不可用。
+
+## `execute` 可读取与可写入的内容
+
+`execute(context)` 的输入是 Product 提供、不可变或受控的 callback context：
+
+| 输入 | 可以做什么 | 边界 |
+| --- | --- | --- |
+| `invocationId` | 关联本次 Run 的工作。 | 同一次 Run 的 callback 使用相同 ID，不是跨 Run state。 |
+| `options` | 使用本 Check 已准备的 options。 | 不修改；不是原始 authoring object。 |
+| `project.root` / `project.flags` / `project.changes` | 使用本次规范化的绝对根目录、同一 effective flag 集，以及已配置时同一次冻结的 change result。 | caller token 与 derived change token 在注入后都只按 presence 参与选择和 callback；`changes` evidence 不证明环境或权限。 |
+| `dependencies` | 读取已声明 direct `dependsOn` / `observes` 的终态。 | `get` 不授权未声明或传递依赖；`list` 不是全局执行历史。 |
+| `artifactDirectory` | 写本 Check 的 invocation-local artifact；未授权时为 `null`。 | 不推导 sibling、machine、diagnostic 或跨 Run state 的路径。 |
+| `records` | 发布 object-shaped supplemental facts。 | 每个 ID 仅在本 Check 内唯一，且不会决定 status。 |
+| `signal` | 在可等待工作中协作退出。 | 取消后不要启动背景工作或把部分结果伪装为通过。 |
+
+成功与失败都必须返回 object-shaped final `data`；`not-applicable` 表示当前没有适用工作，`unavailable` 表示无法形成可信结果并必须带稳定 `reason.code`。声明 `handoff: true` 的 provider 还必须在 `passed` 返回同型 non-null object/function `handoff`；其它 branch 和 ordinary Check 不能携带该字段。`messages` 是有序的人读补充信息，不保证每个 outcome 都有；把完整或敏感详情留在调用方拥有的安全位置，不要依赖 progress 文本保存事实。
+
+## 依赖与取消的实践
+
+必须取得上游成功 data 才能开始时，声明 `dependsOn`，并先检查 `dependencies.get(id).ok`；上游未提供 data 时返回 `unavailable`，而不是猜测空值。需要等上游无论何种终态都结算后再审计时，声明 `observes`，用 `dependencies.list()` 处理各项 outcome。需要保留 provider reference identity 时，provider-aware `dependencies.get(provider)` 只对 direct `dependsOn` 成功；继续调用 provider Check 的 `parseData(read.data)`，不要把 parser 用于 `read.handoff`。完整示例、immutable observation 和 explicit resource cleanup 边界见[依赖数据指南](check-dependencies.md)。
+
+对 `fetch`、子进程或自有异步 API，把 `signal` 传下去；若已取消，尽快停止并返回 `unavailable`。Vibe Check 不会取消调用方没有连接 signal 的外部工作，也不替调用方回收文件、网络或子进程资源。
+
+## 下一步
+
+- 需要安排多个 Check、编写 admission policy、模拟假设分支或复用本地时长历史时，阅读[调度 Check](scheduling.md)。
+- 需要组合/继承 Check 或理解 dependency data、aggregation、machine outputs 的共同结果模型时，阅读[API 机制](../api-mechanics.md)。
+- 只需使用 package 提供的检查时，从 [README 的 Check 概览](../../README.md#随包提供的-check)进入对应指南。

package/docs/guides/finding-waivers.md

@@ -0,0 +1,87 @@
+# 对账 Finding waiver
+
+`reconcileFindingWaivers({ findings, identify, waivers })` 是 package 预提供的可选工具：当 custom Check 或其它 Finding
+producer 已形成**完整** Finding 候选集合，并需要保留原始证据地审计 waiver 时调用它。它不会按
+message 过滤、在扫描前排除输入或删除 Finding；采用方仍拥有 Records、messages 和 terminal outcome。
+
+## 最小用法
+
+```ts
+import { reconcileFindingWaivers } from "@zxyycom/vibe-check";
+
+const reconciled = reconcileFindingWaivers({
+  findings: [{ metric: "api-compatibility", symbol: "createClient" }],
+  identify: ({ metric, symbol }) => ({ metric, symbol }),
+  waivers: [
+    {
+      identity: { metric: "api-compatibility", symbol: "createClient" },
+      reason: "兼容窗口保留到下一个 major release。"
+    }
+  ]
+});
+```
+
+## 输入与默认值
+
+`waivers` 可省略；省略或传入 `undefined` 都等同于 `[]`，表示没有配置豁免。例如
+`reconcileFindingWaivers({ findings, identify })` 仍验证每项 Finding identity，将全部 Finding 标为
+`actionable`，返回空 `waiverAudits`，并保留原 Finding 的顺序与引用。
+
+`findings` 与 `identify` 仍必填；`null`、非数组及非法 waiver 配置仍抛出 `TypeError`，不会被当作无豁免。
+
+## identity 与 audit
+
+`identify(finding)` 对输入顺序中的每个原 finding 接收完整 finding。调用方自行选择稳定的语义
+identity，例如 path、function name 和 metric 的组合。`identify` 的结果与 `waiver.identity` 都必须可安全
+materialize 为 canonical JSON，helper 按 canonical JSON 的结构而非对象引用匹配。
+
+每项 waiver 的 identity 必须唯一且 reason 为非空 string。重复 canonical identity、无法 canonicalize 的
+finding 或 waiver identity、无效 reason，或 malformed / hostile waiver authoring 都抛出 `TypeError`。每个
+configured waiver 都在完整集合上获得 audit：`0` 次匹配是 `unused`，`1` 次是 `applied`，`>1` 次是
+`overmatched`；过宽 waiver 不会豁免任一 finding。
+
+输出 `findings` 保持输入顺序，并在每项结果中保留同一个原 finding reference。applied waiver 附带的 evidence
+是 detached、deep-frozen 的 canonical materialization，因此调用方之后修改 authored identity 或 reason 不会改变
+结果。helper 只返回 finding disposition 和 waiver audit；它不发布 Record、message 或 terminal outcome。
+
+## 随包 Check 的采用边界
+
+[`fileMetrics`](../checks/file-metrics.md)、[`functionMetrics`](../checks/function-metrics.md)、
+[`duplicateDetection`](../checks/duplicate-detection.md)、[`secretDetection`](../checks/secret-detection.md)
+与 [`markdownLint`](../checks/markdown-lint.md)
+提供原生 `findingWaivers` option，其 authoring 为 closed `{ identity, reason }`。它们先形成完整、可信的 Finding 集合再对账；waiver 不缩小 scanner/detector input、不删除原 Finding，也不把 `unavailable` 伪装成 audit。其它随包 Check 暂无同名原生 option。
+
+各 Check 指南完整定义自己的 identity grammar、可 waiver scope、Record/message/final-data 与 status effect。`secretDetection` 的 identity 不含 secret 值、message、line 或 hash，且不能豁免 coverage gap 或 `unavailable`；reason 会作为 evidence 发布，不能包含敏感材料。
+
+## 为 Markdown lint 声明精确例外
+
+人工确认某条 lint Finding 是可接受的例外后，将其公开 Record data 的 `path`、`rule`、完整 `range` 复制到 identity，再说明接受原因。下例 Record 值仅作示意；实际应复制本次检查的证据，不应动态豁免所有扫描结果。
+
+```ts
+import {
+  markdownLint as lintWithWaivers,
+  type MarkdownLintRecordData,
+  type MarkdownLintFindingWaiver
+} from "@zxyycom/vibe-check";
+
+// 示例：已人工复核的一条 Record data，实际使用时复制自己检查得到的值。
+const reviewedFinding: MarkdownLintRecordData = {
+  kind: "lint-finding",
+  path: "docs/legacy.md",
+  rule: "fenced-code-language",
+  range: { start: { line: 8, column: 1 }, end: { line: 8, column: 1 } }
+};
+const { path, rule, range } = reviewedFinding;
+const acceptedException: MarkdownLintFindingWaiver = {
+  identity: { path, rule, range },
+  reason: "此处演示未指定语言的原始围栏，保留例外并继续检查其它 Finding。"
+};
+const lintWithAcceptedException = lintWithWaivers({
+  findingPolicy: "blocking",
+  findingWaivers: [acceptedException]
+});
+// 将 lintWithAcceptedException 加入项目 checks；不是删除原 Finding。
+void lintWithAcceptedException;
+```
+
+将返回的 Check 放入项目的 `checks` 后，完整 lint 才会对账。唯一匹配保留 Finding 并附 waiver reason，未匹配或多匹配产生可见 audit；行列漂移不会自动迁移配置。计数、缓存组合及失败边界由 [Markdown lint 指南](../checks/markdown-lint.md#精确-finding-waiver)完整定义。

package/docs/guides/learned-scheduling.md

@@ -0,0 +1,83 @@
+# 用本地时长历史调度 Check
+
+希望同一项目后续运行时依据历史时长选择 ready Check，可以用 `createLearnedCriticalPathStrategy` 创建策略，接入 `scheduler.admissionPolicy`。你提供本地状态目录和可比较任务的 identity，策略据此估计时长；下文说明配置、history 不可用时的退化与观察方式。通用 prepared strategy 的调用顺序与失败边界见[调度专题](scheduling.md#已准备的-custom-strategy)。
+
+## learned critical-path strategy
+
+```ts
+import {
+  createLearnedCriticalPathStrategy,
+  defineCheck,
+  defineConfig,
+  run
+} from "@zxyycom/vibe-check";
+
+function scheduledCheck(checkId: string) {
+  return defineCheck({
+    checkId,
+    displayName: checkId,
+    execute: () => ({ status: "passed" as const, data: {} })
+  });
+}
+
+// 调用方选择不与其它 Run 共用的绝对目录，并负责后续清理；不会从 projectRoot 解析。
+const stateDirectory = `/tmp/vibe-check-learned-history-${Date.now()}-${Math.random()}`;
+const strategy = createLearnedCriticalPathStrategy({
+  stateDirectory,
+  identityForTask: (task) => ({
+    taskId: task.taskId,
+    // 在调用方的 key 中保留所有影响时长可比性的因素。
+    implementationVersion: "example-v1"
+  }),
+  observe(event) {
+    // 这是调用方尽力而为的观察点，不是 Product diagnostic channel。
+    if (event.kind === "history-unavailable") console.warn(event.reason);
+  }
+});
+const definition = defineConfig({
+  checks: [scheduledCheck("first"), scheduledCheck("second")],
+  outputs: {
+    diagnosticLogging: { enabled: false },
+    machinePublication: { enabled: false },
+    progressRendering: { enabled: false }
+  },
+  scheduler: {
+    admissionPolicy: { kind: "custom", strategy },
+    maxParallel: 1
+  }
+});
+
+const first = await run(definition);
+const second = await run(definition);
+if (first.kind !== "completed" || second.kind !== "completed") {
+  throw new Error("Expected both learned strategy Runs to complete");
+}
+```
+
+## 配置 history 与任务 identity
+
+`stateDirectory` 必须是调用方提供的非空 absolute、可写且可删除的目录；helper 不从 effective
+`projectRoot` 解析它。它是调用方信任的本地性能状态，不是 filesystem sandbox、secret storage、remote cache 或跨进程锁；
+调用方负责 retention 和清理。history identity 虽会被 hash 成文件关联所用的 digest，digest 不是保密机制：不得把 secret、token
+或低熵敏感输入放进 identity。`identityForTask(task)` 必须返回 canonical-JSON-compatible identity，并显式包含所有会改变
+时长可比性的 options、flags、环境或实现版本；helper 不读取 normalized Check options、Run flags 或 `projectRoot` 来补全它。
+
+`sampleWindow` 的范围是 1–32（默认 32），`maxHistorySeries` 是 1–4096（默认 4096），`coldStartDurationMs` 必须为正有限数（默认 1）；
+这些 model knobs 会进入 helper 生成的 history key。非 absolute/空 `stateDirectory` 或非法 model knob 会在 factory 创建时 throw；
+这类 authoring/configuration error 不属于一次 Run 的 optimization 退化。
+
+## 退化与观察
+
+首次运行、缺失、损坏、不兼容或 read-failed history
+会被当作空 history：已有 learned estimate 的同一 Run 可为未知 Task 提供 project prior，否则使用 cold start。identity 无效、无法
+完成 setup/prediction/critical-path preparation 时，策略退化为普通 static decision，并以 `history-unavailable` 报告；record/write
+失败只影响后续 Run 的 history，并以 `recording-unavailable` 报告。上述 history 退化均不改变本次 Task membership、Check facts、
+aggregate、machine output 或质量结算。
+
+每个策略选择的 `select` proposal 会产生带 task ID、estimate、critical-path score、sample count 和 source 的
+`selection-proposed` event；它不确认 Task 已实际 admission。observer 是 caller-owned best-effort callback：同步 throw 或 rejected
+Promise 会被忽略，返回的 Promise 不会被 await，因此 callback 可以在 `run(...)` 返回后继续，Run 完成也不证明 observation sink
+已完成。通过 `observe` 接收 helper 事件，通过 `stateDirectory` 保存 history；需要持久化事件时，由调用方管理自己的 sink。
+这些 helper 状态独立于 Product 的 diagnostic channels、output statuses、Check facts、machine output 和 `RunResult`。
+
+策略通过每次 decision 的 measurement context 工作，只在既有 selection layer 比较 score；Scheduler 仍重检[准入约束](scheduling.md)。实际运行成本取决于 graph、history 和 observer，应在目标 workload 上测量；history 优化不代表 [Run 或 Check 质量通过](../api-mechanics.md#runresult-分支)。

package/docs/guides/presenting-findings.md

@@ -0,0 +1,54 @@
+# 呈现 Check Finding
+
+`presentCheckFindings(...)` 把 producing Check 已经形成且稳定排序的 Finding 投影为有限的 `CheckMessage[]`。它适用于需要在 terminal result 中给出人读摘要、同时由 Check 在 Records、artifact、transcript 或其它实际位置保留完整事实的场景。
+
+## 最小用法
+
+```ts
+import { presentCheckFindings } from "@zxyycom/vibe-check";
+
+const findings = [
+  { blocking: true, line: 12, path: "src/config.ts", summary: "Missing required value" },
+  { blocking: false, line: 8, path: "src/legacy.ts", summary: "Deprecated option" }
+];
+
+const messages = presentCheckFindings({
+  findings,
+  limit: 1,
+  message: (finding) => ({
+    code: "finding-detail",
+    level: finding.blocking ? "error" : "warning",
+    message: `${finding.path}:${finding.line} ${finding.summary}`
+  }),
+  omittedMessage: ({ omittedCount, omittedFindings, presentedCount, totalCount }) => ({
+    code: "findings-omitted",
+    level: omittedFindings.some((finding) => finding.blocking) ? "error" : "warning",
+    message: `${omittedCount} more of ${totalCount} findings after the first ${presentedCount}`
+  })
+});
+
+if (messages.length !== 2 || messages[1]?.code !== "findings-omitted") {
+  throw new Error("Expected one Finding message and one overflow message");
+}
+
+const terminalResult = { status: "failed" as const, data: { findings }, messages };
+void terminalResult; // The producing Check attaches these messages to its terminal result.
+```
+
+## 输入与投影
+
+调用方提供稳定排序的 `findings`、非负 safe-integer `limit`、为每个呈现项生成 message 的 hook，以及存在省略项时生成汇总 message 的 hook。helper 只调用前 `limit` 项的 `message` hook；超限时调用一次 `omittedMessage`。后者收到完整计数、`presentedCount` 与原 `omittedFindings` references，因此 producing Check 可以按省略项的实际等级选择 summary，并明确完整明细的位置。
+
+`limit: 0` 只产生省略汇总；空 Finding 数组返回空 messages。无效 limit 在任何 hook 执行前抛出 `TypeError`。
+
+返回数组及其中的 message 对象均被冻结。producing Check 把它附到自己的 terminal result，并继续拥有 Finding shape、完整事实位置和 terminal outcome；helper 不保存或发布 Finding facts。
+
+## 随包 Check 的采用
+
+[`fileMetrics`](../checks/file-metrics.md)、[`functionMetrics`](../checks/function-metrics.md)、
+[`duplicateDetection`](../checks/duplicate-detection.md) 和
+[`markdownLinkValidation`](../checks/markdown-link-validation.md) 自动使用相同的 presentation helper，并在各自实现中固定
+`limit: 10`；调用方不能通过这些 Check 的 options 调整该值。因而每个 Check terminal result 最多包含十条 Finding detail
+messages；Finding 超过十条时另有一条 `findings-omitted` summary。完整 Finding facts 仍由各 Check 的 Records 承载。
+Run progress 的[预览限制](run-outputs.md#check-messages-与受管-progress)独立于本 helper 的 message 数量，不改写 terminal result 或完整 facts。
+各 Check guide 只说明自己的 Finding shape、detail 字段、排序和 terminal policy。