@zxyycom/vibe-check 0.0.2 → 0.0.3

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

@@ -1,17 +1,18 @@
 # 编写会正确结算的自定义 Check
 
-本专题面向需要把项目规则接入 Vibe Check 的调用方：选择 `preflight` 或 `execution`，读取 callback 输入，返回可信终态，并在需要时发布补充事实。先能用一个普通 `execution` 完成规则；只有必须在执行前准备或验证 options 时才增加 `preflight`。一次 Run 的公共生命周期、输出优先级和完整结果模型见 [API 机制](../api-mechanics.md)。
+本专题面向需要把项目规则接入 Vibe Check 的调用方：选择 `prepare` 或 `execute`，读取 callback 输入，返回可信终态，并在需要时发布补充事实。先能用一个普通 `execute` 完成规则；只有必须在执行前准备或验证 options 时才增加 `prepare`。一次 Run 的公共生命周期、输出优先级和完整结果模型见 [API 机制](../api-mechanics.md)。
 
 ## 选择扩展点
 
 | 需求 | 使用方式 | 不要用它做什么 |
 | --- | --- | --- |
-| 规则可直接测量并结算 | `execution(context)` | 不要在 callback 外留下未等待的工作。 |
-| 执行前验证或把 authoring options 变成 invocation-local 的准备值 | `preflight(options, signal)` 后接 `execution(context)` | 它不是全局启动 hook；只在本 Check 已获准入后运行。 |
+| 规则可直接测量并结算 | `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。`execution`、`preflight`、`parseData` 都是调用方实现的受信任回调。Product 只提供各自声明的输入；回调独立执行的 I/O 仍由调用方负责。
+`defineCheck(...)` 定义的 object 是公开 authoring surface。`prepare`、`execute`、`parseData` 都是调用方实现的受信任回调。Product 只提供各自声明的输入；回调独立执行的 I/O 仍由调用方负责。
 
 ## 定义 Check
 
@@ -34,13 +35,13 @@ const licensePolicy = defineCheck({
   checkId: "license-policy",
   displayName: "License policy",
   options: { denied: ["GPL-3.0-only"] },
-  preflight(options) {
+  prepare(options) {
     return hasValidLicensePolicyOptions(options)
       ? { status: "success", preparedOptions: options }
       : { status: "failure", action: "block", reason: { code: "invalid-options" } };
   },
-  visibility: "attention",
-  execution({ options, records, signal }) {
+  omitQuietPassedRow: true,
+  execute({ options, records, signal }) {
     if (signal.aborted) return { status: "unavailable", reason: { code: "cancelled" } };
 
     const deniedCount = options.denied.length;
@@ -57,51 +58,102 @@ const licensePolicy = defineCheck({
 });
 ```
 
+### 省略安静通过行
+
+把 `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` 只决定本次 Run 是否选择 executable Check；它不是权限、环境检测或 callback 内的条件替代。该字段的完整公开 grammar 是：
+`enabledByFlags` 决定 executable Check 是否参与本次 Run；它不替代权限、环境检测或 callback 内的业务条件。先选最简单的
+正向写法：单个 token 使用 `when: "token"`；组合 token 时导入 builder；只有命中的 downstream Check 还需要启动其
+`dependsOn` prerequisite 时才加入 `propagateDependsOn: true`。
 
 ```ts
-{
-  flags: ["token", ...],
-  mode: "all" | "any" | "none" | "not-all",
-  propagateDependsOn?: true
-}
+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: {} })
+});
 ```
 
-`enabledByFlags` 只可写在 executable Check 上，container 不接受也不向 children 继承它；额外字段或非法 mode 会在 author work 前使 Definition validation 失败。`flags` 必须是无空洞的非空列表，每个 token 是非空字符串；Product 会复制、去重、稳定排序并冻结它。其它未声明 tokens 不影响 predicate。没有 `enabledByFlags` 的 executable Check 默认被选择。 `all` 要求全部声明 token 存在，`any` 要求至少一个存在，`none` 要求全部不存在，`not-all` 要求至少一个不存在；它们都不是“恰好一个”的条件。predicate 不命中且未被下述依赖传播带入时，Check 在自己的 preflight / execution 前以 `not-applicable / flag-condition-not-matched` 结算，duration 为 `null`。
+### 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` prerequisite 一并加入本次选择；省略字段保持仅选择 direct match 的行为，不能写 `false`。这份传递闭包覆盖其中 dependency 自己的 flag predicate miss：被带入的 dependency 会继续正常调度，而不会先因 flag 结算为 `not-applicable`。`observes` 不参与该扩展选择；未被选择的 dependency 才仍可成为 `not-applicable` outcome，dependent 的 hard prerequisite 是否通过仍由 Scheduler 处理。需要带值 flag、恰好一个或嵌套布尔条件时，在 `execution` 中基于 `context.project.flags` 做项目自己的解释，并继续用 preflight/execution 结算真正的环境条件。
+`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。
 
-## `preflight`：准备、阻止或带 fallback 继续
+## `prepare`：准备、阻止或带 fallback 继续
 
-`preflight(options, signal)` 收到 authoring options 的深度只读视图和这次 Run 的同一取消 signal。authored 与 prepared options 同形时可省略 preflight；两种 shape 不同时，TypeScript 要求提供它。它只能返回以下三种结果（每种都可附有序 `messages`）：
+`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 交给 `execution` 的 `context.options`。
-- `{ status: "failure", action: "block", reason }`：本 Check 使用该 reason 直接结算为 `unavailable`，不接受 `fallback`，不会运行 `execution`。
+- `{ 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 并冻结后再交给 `execution`；不要修改传入 options，也不要把它当作跨 Run 缓存。preflight throw/reject 使用 `preflight-threw`，非法结果/message/reason 或非 canonical prepared/fallback 使用 `invalid-preflight-result`，只使本项 `unavailable`，不是整个 Definition 的配置错误。block 或 preparation failure 尚未开始 author execution，duration 为 `null`；已经接受的 preparation messages 仍保留。execution 的 throw、非法返回值和 Record 写入错误也会由 Product 结算为本项不可用。
+准备值只属于本次 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 结算为本项不可用。
 
-## `execution` 可读取与可写入的内容
+## `execute` 可读取与可写入的内容
 
-`execution(context)` 的输入是 Product 提供、不可变或受控的 callback context：
+`execute(context)` 的输入是 Product 提供、不可变或受控的 callback context：
 
 | 输入 | 可以做什么 | 边界 |
 | --- | --- | --- |
 | `invocationId` | 关联本次 Run 的工作。 | 同一次 Run 的 callback 使用相同 ID，不是跨 Run state。 |
 | `options` | 使用本 Check 已准备的 options。 | 不修改；不是原始 authoring object。 |
-| `project.root` / `project.flags` | 使用本次规范化的绝对根目录和 flags。 | Product 只按 token presence 做选择；项目可自行解释完整 flags，但它们不证明环境或权限。 |
+| `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`。`messages` 是有序的人读补充信息，不保证每个 outcome 都有；把完整或敏感详情留在调用方拥有的安全位置，不要依赖 progress 文本保存事实。
+成功与失败都必须返回 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 的业务类型时，调用 provider Check 的 `parseData`。完整示例和读取授权见[依赖数据指南](check-dependencies.md)。
+必须取得上游成功 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 的外部工作，也不替调用方回收文件、网络或子进程资源。
 

package/docs/guides/finding-waivers.md

@@ -21,6 +21,14 @@ const reconciled = reconcileFindingWaivers({
 });
 ```
 
+## 输入与默认值
+
+`waivers` 可省略；省略或传入 `undefined` 都等同于 `[]`，表示没有配置豁免。例如
+`reconcileFindingWaivers({ findings, identify })` 仍验证每项 Finding identity，将全部 Finding 标为
+`actionable`，返回空 `waiverAudits`，并保留原 Finding 的顺序与引用。
+
+`findings` 与 `identify` 仍必填；`null`、非数组及非法 waiver 配置仍抛出 `TypeError`，不会被当作无豁免。
+
 ## identity 与 audit
 
 `identify(finding)` 对输入顺序中的每个原 finding 接收完整 finding。调用方自行选择稳定的语义
@@ -39,7 +47,41 @@ configured waiver 都在完整集合上获得 audit：`0` 次匹配是 `unused`
 ## 随包 Check 的采用边界
 
 [`fileMetrics`](../checks/file-metrics.md)、[`functionMetrics`](../checks/function-metrics.md)、
-[`duplicateDetection`](../checks/duplicate-detection.md) 与 [`secretDetection`](../checks/secret-detection.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

@@ -16,7 +16,7 @@ function scheduledCheck(checkId: string) {
   return defineCheck({
     checkId,
     displayName: checkId,
-    execution: () => ({ status: "passed" as const, data: {} })
+    execute: () => ({ status: "passed" as const, data: {} })
   });
 }
 

package/docs/guides/run-outputs.md

@@ -49,7 +49,7 @@ const headAndTail: ProgressPreviewFormatter = ({ text, maxCodePoints }) => {
 const detail = defineCheck({
   checkId: "detail",
   displayName: "Detail",
-  execution: ({ records }) => {
+  execute: ({ records }) => {
     records.report({ id: "long-detail" }, { text: "a verbose diagnostic value" });
     return { status: "passed", data: {} };
   }
@@ -75,10 +75,34 @@ formatter 返回空字符串仍是一条呈现项；throw 或返回非字符串
 
 ## Progress rendering
 
-TTY 使用可更新的 running region；plain output 与 `TERM=dumb` 只追加 settled presentation。每个可见 settled row 保留 measured duration 或 `not run`；完整、canonical-ordered `RunResult.checkDurations` 仍保留所有 Check，未执行项为 `null`。`visibility: "attention"` 只隐藏既无 accepted Record 也无 author/captured message 的 passed settled row，不隐藏 running Check。
+TTY 使用可更新的 running region；plain output 与 `TERM=dumb` 从不输出 running row，只追加
+settled presentation。每个可见 settled row 保留 measured duration 或 `not run`；完整、
+canonical-ordered `RunResult.checkDurations` 仍保留所有 Check，未执行项为 `null`。
+
+启用 `omitQuietPassedRow: true` 的 executable Check 在 TTY 中运行时仍可见，但 running row 与
+所有保留的 settled row 都使用无编号的 `· <name>` 格式。它安静通过时不写 settled row；安静
+通过是 `passed` 且 accepted Records/messages 均为空，final data、preview limit、formatter 文本和
+终端截断不改变这个判定。带 accepted detail 的通过，以及 `failed`、`not-applicable`、`unavailable`
+都保留为无编号 settled row，并继续使用既有 duration、reason、detail、escaping 和颜色规则。
+
+没有该策略的 row 继续显示 `[n/total]`。`n` 是全部 executable Checks 的全局 completion
+accounting：每次 settlement 都推进，即使对应 quiet-pass row 被省略，因此保留的普通 row 可以跳号；
+它不是可见结果行的 ID。flag-condition-not-matched 仍按既有 Definition 顺序进入原因聚合块，
+不形成 running row；该聚合优先于 quiet-pass 省略。
+
+至少一个 normalized executable Check 启用该策略时，header 精确追加
+`· <configured> configured for quiet-pass omission`，例如 `total 12 checks · 3 configured for quiet-pass omission`。
+这里的 `configured` 是静态声明数，包含本次因 flags 未匹配而未启动的 Check。final summary 在
+既有 `elapsed` 前精确追加 `quiet-pass rows omitted: <actual>`；`actual` 只计 renderer 实际省略的
+quiet pass，不计 flag mismatch、未完成的潜在省略或任一保留 row。因此两个数可以不同。没有
+configured Check 时，header、final summary、terminal 与 progress tee 的既有 bytes 保持不变。
 
 flag control barrier 结束后，因 `enabledByFlags` 未匹配而未启动的 Checks 以一个原因块分组呈现，而非逐项 settled row；dependency activation 带入的 Check 不在该组。两种显示压缩都不改变 Check facts、accounting 或结果。配置 `progressLogFile` 时，同一 rendered bytes 先写 terminal、再写 file；file setup/write/close failure 使 progress output failed，但不吞掉 terminal presentation。
 
+这项呈现策略不新增或改写 `RunResult`、machine schema 或 Check lifecycle facts；它只改变人读
+row 的保留和编号格式。当前已发布版本的 [changelog](../changelog.md) 历史不由这项规则改写；
+升级说明由相应发布变更按实际版本净差异维护。
+
 ## 日志与输出目标
 
 machine publication 与 diagnostic logging 的 `directory` 都是调用方选择的非空、无 U+0000 的受信任 target：相对路径从 effective `projectRoot` 解析，绝对路径直接使用；它们不提供 containment 或 sandbox 语义。`progressLogFile` 使用相同的路径规则。
@@ -124,22 +148,24 @@ getter 来寻找更深字段。诊断不回显被拒绝的值；unknown key 诊
 
 channel setup、write 或 close failure 只使对应 output failed，不改写已经形成的 Check/Record facts，也不阻断其它 output 结算。
 
-当 primary Run 已正常完成时，output failure 使结果成为 `kind: "output"`；多个 failure 依次选择 progress rendering、machine publication、diagnostic logging、measurement hooks 的第一个作为 diagnostic。`scheduler-measurement-hooks-failed` 因而只表示 measurement hook 是按该顺序选中的 failure；cancellation 或 execution diagnostic 保持原有 primary result，hook failure 仍在 `outputs.measurementHooks.status` 可见。
+`checkAggregation` 不是 output formatter，也不产生 output status。它在完整 Check settlement 后、正常 final progress summary 与 machine publication 前同步解释有效 Check 列表。若该函数抛错、返回 Promise/thenable 或非法四态值，`run(...)` 直接拒绝：Product 会关闭本次 diagnostic/progress writer，但不呈现正常成功 summary、不发布正常 machine result，也不返回可读取 output status 的 `RunResult`。调用方应处理这个 Promise rejection；它不能靠 `kind: "output"` 恢复。
+
+当 primary Run 已正常完成时，output failure 使结果成为 `kind: "output"`；多个 failure 依次选择 progress rendering、machine publication、diagnostic logging、terminal effects 的第一个作为 diagnostic。`scheduler-terminal-effects-failed` 因而只表示 terminal effect 是按该顺序选中的 failure；cancellation 或 execution diagnostic 保持原有 primary result，terminal-effect failure 仍在 `outputs.terminalEffects.status` 可见。
 
 ### Diagnostic channel 状态
 
 `outputs.diagnosticLogging` 的形状为 `{ enabled, status, channels }`，其中 `channels` 是 `core`、`scheduler` 的 `{ enabled, status, file }` map。禁用 channel 的 `file` 为 `null`；启用 channel 即使创建文件失败也保留预先计算的 `path.relative(projectRoot, resolvedFile)`，因此 root 外 target 可含 `..`，跨卷时平台可以返回 absolute path。任一 enabled channel failed 时 aggregate status 为 `failed`，只有全部 enabled channel succeeded 时为 `succeeded`。
 
-### Measurement hook 状态
+### Terminal effect 状态
 
-`scheduler.measurementHooks` 在 Definition 中配置，不能由 RunControls 注入或覆盖。终态观察交付给调用方配置的 generic Hooks 与 prepared strategy 的 public `complete`；调用顺序和 context 见[调度专题](scheduling.md#观察终态-measurement)。
+`scheduler.terminalEffects` 在 Definition 中配置，不能由 RunControls 注入或覆盖。终态观察交付给调用方配置的 Definition effects 与 prepared strategy 的 public `terminalEffect`；调用顺序和 context 见[调度专题](scheduling.md#交付终态-measurement)。
 
-`outputs.measurementHooks` 的形状为 `{ enabled, status }`：
+`outputs.terminalEffects` 的形状为 `{ enabled, status }`：
 
 | 条件 | `enabled` / `status` |
 | --- | --- |
-| normalized `scheduler.measurementHooks` 非空，或 successful prepared strategy 实际提供 `complete` | `enabled: true`。 |
+| normalized `scheduler.terminalEffects` 非空，或 successful prepared strategy 实际提供 `terminalEffect` | `enabled: true`。 |
 | 两者都没有 | `enabled: false`，`status: "disabled"`。 |
 | enabled Run 没有 sealed terminal sequence | `status: "not-run"`。 |
-| sealed sequence 中所有 generic Hooks 与可选 public `complete` 都成功 | `status: "succeeded"`。 |
-| 任一 generic Hook 或 `complete` throw/reject | `status: "failed"`；后续 `complete` success 不会覆盖已记录的 generic failure。 |
+| sealed sequence 中所有 Definition effects 与可选 public `terminalEffect` 都成功 | `status: "succeeded"`。 |
+| 任一 Definition effect 或 `terminalEffect` throw/reject | `status: "failed"`；后续 `terminalEffect` success 不会覆盖已记录的 Definition-effect failure。 |

package/docs/guides/scheduling.md

@@ -1,6 +1,6 @@
 # 按项目约束调度 Check
 
-本专题面向已经有多个自定义 Check、需要表达并发约束、改变 ready task 的选择顺序的调用方。默认 `{ kind: "static" }` 已经遵守依赖、mutex、root/scoped 并行预算、named resource capacity 和取消；只有这些不变式之外的**选择偏好**需要项目规则时，才使用 custom policy（包括 learned helper 返回的 prepared strategy）。Check 自己的 options、preflight、execution 与取消处理见[编写自定义 Check](extending-check-lifecycle.md)。
+本专题面向已经有多个自定义 Check、需要表达并发约束、改变 ready task 的选择顺序的调用方。默认 `{ kind: "static" }` 已经遵守依赖、mutex、root/scoped 并行预算、named resource capacity 和取消；只有这些不变式之外的**选择偏好**需要项目规则时，才使用 custom policy（包括 learned helper 返回的 prepared strategy）。Check 自己的 options、preparation、execution 与取消处理见[编写自定义 Check](extending-check-lifecycle.md)。
 
 ## 选择正确的工具
 
@@ -10,10 +10,10 @@
 | 为可计数共享资源声明并发容量 | `scheduler.resourceCapacities` 与 Check 的 `resourceClaims` | capacity 与 claim 都是本次 Run 的静态 units。 |
 | 只指定静态相对顺序 | Check 的 `admissionPriority` | 在 Scheduler 的 relation、mutex、容量和取消约束内排序 ready Task。 |
 | 每次 ready selection 根据当前事实选择一个 task | `scheduler.admissionPolicy` 的 `custom/simple` strategy | 向 Scheduler 提交一个 selection proposal。 |
-| 先异步准备本 Run 专用决策 closure，或在终态 measurement 后收尾 | `custom/prepared` strategy | `prepare` 形成 Run-local closure，`complete` 消费 terminal measurement。 |
+| 先异步准备本 Run 专用决策 closure，或在终态 measurement 后收尾 | `custom/prepared` strategy | `prepare` 形成 Run-local closure，`terminalEffect` 消费 terminal measurement。 |
 | 对独立静态图比较假设分支 | [`createAdmissionGraph(...)`](simulating-admission.md) | 不执行 Check；在独立专题中建立并比较 immutable successor。 |
 | 多次运行后按本地时长历史改善选择 | `createLearnedCriticalPathStrategy(...)` 作为 `custom/prepared` strategy | 使用调用方管理的本地 history 形成选择偏好。 |
-| Run 结束后保存项目自己的调度统计 | `scheduler.measurementHooks` | 接收冻结的 terminal measurement 作为 side effect 输入。 |
+| Run 结束后保存项目自己的调度统计 | `scheduler.terminalEffects` | 接收冻结的 terminal measurement 作为 side effect 输入。 |
 
 `admissionPriority` 必须是有符号 safe integer；Check 节点省略时继承最近显式祖先值，没有祖先声明时为 `0`。
 
@@ -29,14 +29,14 @@ const firstAudit = defineCheck({
   displayName: "First audit",
   mutex: ["exclusive-audit"],
   resourceClaims: { worker: 1, capacityUnits: 2 },
-  execution: () => ({ status: "passed", data: {} })
+  execute: () => ({ status: "passed", data: {} })
 });
 
 const secondAudit = defineCheck({
   checkId: "second-audit",
   displayName: "Second audit",
   mutex: ["exclusive-audit"],
-  execution: () => ({ status: "passed", data: {} })
+  execute: () => ({ status: "passed", data: {} })
 });
 
 export default defineConfig({
@@ -64,7 +64,7 @@ const executionOrder: string[] = [];
 const compile = defineCheck({
   checkId: "compile",
   displayName: "Compile",
-  execution() {
+  execute() {
     executionOrder.push("compile");
     return { status: "passed", data: {} };
   }
@@ -75,7 +75,7 @@ const publish = defineCheck({
   checkId: "publish",
   dependsOn: [compile.checkId],
   displayName: "Publish",
-  execution() {
+  execute() {
     executionOrder.push("publish");
     return { status: "passed", data: {} };
   }
@@ -132,11 +132,11 @@ custom `decide(context)` 可通过 `context.measurement` 读取当前 decision b
 - `measurementCount` 是当前已捕获 action observation 的数量。
 - `measurementAt(index)` 只读取这个 context 冻结的 prefix；`0 <= index < measurementCount` 之外返回 `undefined`。每项说明上一次 accepted `select` 或 `wait` 后的 effects 与 interval，不声明某个 action 导致了时长、critical path 或 CPU 使用。
 
-用它在**在线选择**时比较当前累计事实；不要把它当作完整逐 Task 历史或终态报告。需要 Run 结束后的完整 graph、settled tasks 与 raw measurement，改用下面的 `scheduler.measurementHooks`；prepared strategy 的 `complete` 同样只在有 terminal measurement 时运行。
+用它在**在线选择**时比较当前累计事实；不要把它当作完整逐 Task 历史或终态报告。需要 Run 结束后的完整 graph、settled tasks 与 raw measurement，改用下面的 `scheduler.terminalEffects`；prepared strategy 的 `terminalEffect` 同样只在有 terminal measurement 时运行。
 
 ## 已准备的 custom strategy
 
-需要在 Scheduler 开始前异步读取调用方自己的配置，并把结果形成本 Run 专用 decision closure 时，使用 `{ kind: "prepared", prepare }`。每个 graph-ready Run 最多调用一次 `prepare`；它返回同步 `decide` 和可选的 `complete(terminal)`。下例优先选择可准入的 `second`，否则选择第一个可准入候选，并在 `complete` 中保存终态任务计数：
+需要在 Scheduler 开始前异步读取调用方自己的配置，并把结果形成本 Run 专用 decision closure 时，使用 `{ kind: "prepared", prepare }`。每个 graph-ready Run 最多调用一次 `prepare`；它返回同步 `decide` 和可选的 `terminalEffect(terminal)`。下例优先选择可准入的 `second`，否则选择第一个可准入候选，并在 `terminalEffect` 中保存终态任务计数：
 
 ```ts
 import { defineAdmissionPolicy, defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
@@ -147,7 +147,7 @@ function scheduledCheck(checkId: string) {
   return defineCheck({
     checkId,
     displayName: checkId,
-    execution: () => ({ status: "passed" as const, data: {} })
+    execute: () => ({ status: "passed" as const, data: {} })
   });
 }
 
@@ -167,7 +167,7 @@ const strategy = defineAdmissionPolicy({
             ? { kind: "wait" as const }
             : { kind: "select" as const, taskId: next.taskId };
         },
-        complete(terminal) {
+        terminalEffect(terminal) {
           settledTaskCount = terminal.execution.settledTasks.length;
         }
       };
@@ -193,13 +193,13 @@ if (result.kind !== "completed" || settledTaskCount !== 2) {
 
 策略需要的配置、logger 或 clock 由调用方提供并捕获在 closure 中；context 只提供调度事实，真实 Task 启动与结算由 Scheduler 控制。准备失败与终态收尾边界如下。
 
-### 观察终态 measurement
+### 交付终态 measurement
 
-任何 scheduler policy 都可配置 `scheduler.measurementHooks`。每个 hook 在 Scheduler 已有 terminal measurement 后收到冻结的 `{ graph, execution, rawMeasurement }`；它适合调用方自己的统计、记录或后续处理，不能修改 Task、Check facts、aggregate 或选择历史。若同时配置 generic hook 与 prepared `complete`，generic hooks 先结算，随后才调用 `complete`。如果任一 hook 或 `complete` 抛错或 reject，`result.outputs.measurementHooks.status` 为 `failed`；Check facts 不变，原本正常完成的 Run 可映射为 `kind: "output"`，已有 `cancelled` / `execution` 主结果保持不变。
+任何 scheduler policy 都可配置 `scheduler.terminalEffects`。每个 effect 在 Scheduler 已有 terminal measurement 后收到冻结的 `{ graph, execution, rawMeasurement }`；它适合调用方自己的统计、记录或后续处理，不能修改 Task、Check facts、aggregate 或选择历史。若同时配置 Definition effect 与 prepared `terminalEffect`，Definition effects 先结算，随后才调用 `terminalEffect`。如果任一 effect 或 `terminalEffect` 抛错或 reject，`result.outputs.terminalEffects.status` 为 `failed`；Check facts 不变，原本正常完成的 Run 可映射为 `kind: "output"`，已有 `cancelled` / `execution` 主结果保持不变。
 
-终态 measurement 不同于 `decide` 所读 `context.measurement` 的在线观察前缀。需要逐项业务数据、失败原因或 Records 时，在 Check 的 `execution` 中形成事实，再从 `RunResult` 读取。
+终态 measurement 不同于 `decide` 所读 `context.measurement` 的在线观察前缀。需要逐项业务数据、失败原因或 Records 时，在 Check 的 `execute` 中形成事实，再从 `RunResult` 读取。
 
-`prepare` 只在 graph 已有效且 Run 尚未于 pre-work / planning 取消后调用；它没有 cancellation signal、timeout 或“必有 complete”的 cleanup 保证。prepare reject 会结束为 `admission-strategy-preparation-failed`。一旦 Run 进入 Scheduler，正常结束、取消或 policy fault 的 drain 只要 seal 出 terminal measurement，都会在 generic hooks 后调用 `complete`；早期 setup / execution failure 没有 terminal measurement 时不会调用它。因此不要在 `prepare` 中取得必须依赖 `complete` 释放的资源。
+`prepare` 只在 graph 已有效且 Run 尚未于 pre-work / planning 取消后调用；它没有 cancellation signal、timeout 或“必有 terminalEffect”的 cleanup 保证。prepare reject 会结束为 `admission-strategy-preparation-failed`。一旦 Run 进入 Scheduler，正常结束、取消或 policy fault 的 drain 只要 seal 出 terminal measurement，都会在 Definition effects 后调用 `terminalEffect`；早期 setup / execution failure 没有 terminal measurement 时不会调用它。因此不要在 `prepare` 中取得必须依赖 `terminalEffect` 释放的资源。
 
 保存后续 Run 会使用的 caller-owned data 时，先根据自己的目标定义“可接受样本”。`rawMeasurement.timing.availability === "available"` 只证明终态 timing facts 可读，不证明 Run quality 成功；`settledTasks.kind === "completed"` 是 Scheduler settlement，不等于 Check `passed`，且 context 不提供 `RunResult.kind`。若业务只允许成功 Run，先暂存候选，在 `run(...)` 返回后同时核对 `result.kind` 与业务要求的 Check outcomes 或 aggregate，再决定是否提交。`kind: "completed"` 本身不表示质量检查全部通过。
 

package/docs/output.md

@@ -31,8 +31,9 @@ Check-local parser。
 也启用，二者共享该 instant。两项 output 都禁用时，Run 不读取或序列化 wall clock。每个 Check row 包含
 `checkId`、`displayName` 和一种 terminal outcome：`passed` / `failed` 带 object-shaped final `data`；
 `not-applicable` / `unavailable` 带受控 reason，前者可以省略 reason。Aggregation、所有 Run output status 与
-diagnostic channel files、duration、author terminal messages、Product-captured Check console messages、visibility 和
-progress presentation 不属于 machine fields。
+diagnostic channel files、duration、author terminal messages、Product-captured Check console messages、
+`omitQuietPassedRow` 人读呈现策略和 progress presentation 不属于 machine fields。quiet-pass row 的省略、
+无编号格式及 configured/actual 计数都不改变 terminal Check facts 或 v4 publication。
 
 每个 `records.ndjson` row 的结构是：
 
@@ -63,7 +64,7 @@ canonical replacement 已发生后的 handled failure 会清理可能混合的 c
 
 两个 canonical files 是独立 filesystem paths，rename 不提供跨路径原子可见性。并发 reader 可能观察到 mixed
 generation，因此必须按完整集合执行 fingerprint validation；需要 generation pointer、reader lock 或跨路径 atomic
-visibility 的系统，应在 Vibe Check 契约之外建立自己的读取协议。
+原子可见性的系统，应在 Vibe Check 契约之外建立自己的读取协议。
 
 ## 随包材料与版本
 
@@ -78,9 +79,9 @@ visibility 的系统，应在 Vibe Check 契约之外建立自己的读取协议
 
 示例的输入与结果可按三条路径核对：
 
-- `jsonValidation` 显式检查 `package.json`，保留默认 source/exclude；自定义 provider 在空 authored files 时以 preflight fallback 继续并通过。
+- `jsonValidation` 显式检查 `package.json`，保留默认 source/exclude；自定义 provider 在空 authored files 时以 preparation fallback 继续并通过。
 - 递归 workflow 继承 manifest dependency；policy 用 `inherit` 追加 provider，解析两份 upstream data，再形成 failed data 与两条 Records。container 不产生 Check row。
-- 另两项分别直接 `not-applicable` 与被本项 preflight block 为 `unavailable`，不阻挡无 relation 的其它 Check。preflight 和 policy messages 仅进入 `RunResult.checkMessages`。
+- 另两项分别直接 `not-applicable` 与被本项 preparation block 为 `unavailable`，不阻挡无 relation 的其它 Check。preparation 和 policy messages 仅进入 `RunResult.checkMessages`。
 
 checked-in outputs 在只含有效 `package.json` 的隔离 root 中执行该 Definition 后生成，仅把 invocation ID 与 timestamp 固定为文档值。直接 `run(definition)` 会根据你的实际 `package.json` 形成结果和本次 metadata，并更新 project root 下 `artifacts/vibe-check` 中的两份 canonical files；示例 facts 不是对任意项目结果的保证。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxyycom/vibe-check",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "通用 TypeScript 质量门禁工具，提供可组合 Check、类型安全 API 和结构化结果。",
   "keywords": [
     "quality-gate",
@@ -49,6 +49,7 @@
     "github-slugger": "2.0.0",
     "immutable": "5.1.9",
     "jscpd": "^5.1.1",
+    "markdownlint": "0.41.1",
     "mdast-util-from-markdown": "2.0.3",
     "mdast-util-frontmatter": "2.0.1",
     "mdast-util-gfm": "3.1.0",