@zxyycom/vibe-check 0.0.2 → 0.0.3

package/docs/api-mechanics.md

@@ -1,6 +1,6 @@
 # 深入理解 Vibe Check API 机制
 
-本文说明 package 的通用 invocation lifecycle：自定义 Check 如何经过 Definition validation、options preflight、execution 与 settlement，以及一次 Run 如何形成 dependency data、aggregation、outputs 和可判别结果。首次集成先阅读[package README](../README.md)；随包 Check 的 options、业务效果和安全边界由各自指南说明；单个 public 字段与函数签名以 installed declarations 为准。
+本文说明 package 的通用 invocation lifecycle：自定义 Check 如何经过 Definition validation、options preparation、execution 与 settlement，以及一次 Run 如何形成 dependency data、aggregation、outputs 和可判别结果。首次集成先阅读[package README](../README.md)；随包 Check 的 options、业务效果和安全边界由各自指南说明；单个 public 字段与函数签名以 installed declarations 为准。
 
 ## 一次 Run 的生命周期
 
@@ -12,37 +12,40 @@
     Project Definition
       │ run: validate Definition + RunControls, then normalize the Check tree
       ▼
-    validated Definition + complete static graph
-      │ before execution: apply cancellation and flag selection
-      │ prepared admission strategy readies one Run-local decision function when configured
+    validated Definition + normalized Check tree
+      │ before work: stop if cancelled; otherwise validate the complete static graph
+      ▼
+    complete static graph
+      │ when configured: prepare one Git change snapshot and derived flags
+      │ recheck cancellation, prepare the admission strategy, then form effective flag selection
       ▼
     initial control settlements + complete static Task graph
       │ Scheduler applies direct relations, mutex and parallel scheduling
       ▼
-    task-local preflight / Product-owned blocked unavailable outcomes
+    task-local preparation / Product-owned blocked unavailable outcomes
       │ admitted Checks continue to author callback
       ▼
     author execution + terminal settlement
       ▼
     snapshot + messages + durations
-      │ terminal measurement Hooks settle; if terminal context exists, prepared strategy completes once
-      │ optional aggregation + enabled output completion
+      │ terminal effects settle; if terminal context exists, prepared strategy delivers terminalEffect once
+      │ default or caller-local aggregation + enabled output completion
       ▼
     RunResult
 
 ### Selection 与 Scheduler readiness
 
-Run 先验证包含全部可执行 Check 的静态 graph，再处理 invocation cancellation 与 flag selection。[flag 规则](guides/extending-check-lifecycle.md#按-flag-选择-check)产生一次 private effective selection；未被选择项先结算为 `not-applicable / flag-condition-not-matched`，不会再次 admission。它们仍属于同一张 graph：`dependsOn` dependent 在 preflight 前结算为 `unavailable / dependency-not-passed`，`observes` consumer 则可等待并读取该终态。
+Run 先验证 Definition 与 Controls 并规范化 Check tree；若 signal 已取消，会在静态 graph validation 和获取 Git 前结束调用。否则 Product 验证包含全部可执行 Check 的静态 graph。Definition 配置 `changes` 时，Product 随后只取得一次 Git changed-path snapshot，按声明 region 生成受保护的 `vibe-check:change:<id>` flags；可信零命中保留空 evidence，获取失败保留 unavailable evidence 并保守提供所有已声明 change flags。再次检查 cancellation 后，caller/derived flags 共同形成一次 private effective selection。[flag 规则](guides/extending-check-lifecycle.md#按-flag-选择-check)定义其条件；未被选择项先结算为 `not-applicable / flag-condition-not-matched`，不会再次 admission。它们仍属于同一张 graph：`dependsOn` dependent 在 preparation 前结算为 `unavailable / dependency-not-passed`，`observes` consumer 则可等待并读取该终态。
 
-### Task-local preflight 与 execution
+### Task-local preparation 与 execution
 
-其余 Check 被 Scheduler 在 direct relation、mutex 与 capacity 允许后 admission，并在自己的 task 中执行 preflight，随后才执行 author callback。没有互相约束的 preflight 可以并行；它们不构成 Definition 顺序的全局 barrier。
+其余 Check 被 Scheduler 在 direct relation、mutex 与 capacity 允许后 admission，并在自己的 task 中执行 preparation，随后才执行 author callback。没有互相约束的 preparation 可以并行；它们不构成 Definition 顺序的全局 barrier。
 
 ### Terminal snapshot、aggregation 与 outputs
 
-Run snapshot 保存 Check facts；progress rendering 呈现 execution lifecycle；machine publication 在 terminal snapshot 形成后写入 machine files；optional aggregate 也在 terminal facts 结算后计算。
+Run snapshot 保存所有 Check facts；progress rendering 呈现 execution lifecycle；machine publication 在 terminal snapshot 形成后写入 machine files。aggregation 在完整 terminal facts 结算后、正常 final progress 和 machine publication 前，读取本次有效 Check 列表；默认或 caller-local 函数都不改写 snapshot。
 
-prepared strategy 的 `prepare / decide / complete` 顺序、失败与取消边界由[调度专题](guides/scheduling.md#已准备的-custom-strategy)定义；这些回调不能回写已结算 Check facts。
+prepared strategy 的 `prepare / decide / terminalEffect` 顺序、失败与取消边界由[调度专题](guides/scheduling.md#已准备的-custom-strategy)定义；这些回调不能回写已结算 Check facts。
 
 ## Definition 与 invocation 的责任
 
@@ -53,12 +56,13 @@ prepared strategy 的 `prepare / decide / complete` 顺序、失败与取消边
 | 想设置什么 | 参数位置 | 与另一份输入的关系 |
 | --- | --- | --- |
 | 检查内容、领域 options、依赖与 Check 约束 | Definition 的 `checks` 中各项 Check | Controls 不能替换 Checks 或覆盖 Check options；领域输入继续由 owning Check 或显式 provider 承接。 |
-| 调度并行预算、资源总量、策略与终态观察回调 | Definition 的 `scheduler` | Controls 没有 scheduler override，也不能注入 `measurementHooks`。 |
+| Git comparison 与 change-flag regions | Definition 的 `changes` | 每次 Run 在 selection 前获取一次 Git evidence；Controls 不能伪造或直接提供 `vibe-check:change:` flag。 |
+| 调度并行预算、资源总量、策略与终态观察回调 | Definition 的 `scheduler` | Controls 没有 scheduler override，也不能注入 `terminalEffects`。 |
 | 默认 machine、diagnostic 与 progress 输出方式 | Definition 的 `outputs` | 建立可重复使用的默认值；默认目录、预览数量和 formatter 都可在这里配置。 |
 | 本次根目录、选择 flags 与协作取消 | Controls 的 `projectRoot`、`flags`、`signal` | 只属于本次调用，不是 `defineConfig` 字段。 |
 | 本次 Check 产物与 progress 日志目标、diagnostic 文件命名 | Controls 的 `checkArtifactBaseDirectory`、`progressLogFile`、`diagnosticLogFileNaming` | 只属于本次调用；它们本身不是 Definition outputs 的默认值或 override。 |
 | 本次开关输出、更换 machine / diagnostic 目录、调整 progress 预览 | Controls 的 `outputs` | 只覆盖当前调用明确提供的字段，其余继承 Definition 默认值。 |
-| 本次选择哪些 Check statuses、按什么规则形成 aggregate | Controls 的 `checkAggregation` | 显式、无默认值；省略时 `aggregate: null`，不改写各项 Check outcome。 |
+| 本次怎样解释有效 Check facts | Controls 的 `checkAggregation` | 可选同步函数；省略时使用严格默认折叠，不改写各项 Check outcome。 |
 
 **两处 `outputs` 是默认值和逐字段覆盖值。** 只关闭本次 machine publication 不影响 progress、diagnostics 或下次调用；省略/`undefined` 不覆盖，`false`、预览数量 `0` 和清除 formatter 的 `null` 有效。字段默认值和示例见[输出指南](guides/run-outputs.md)。
 
@@ -66,21 +70,124 @@ prepared strategy 的 `prepare / decide / complete` 顺序、失败与取消边
 
 ### 定义与调用如何处理输入
 
-- `defineCheck(value)` 保留 literal `checkId`、options 和 typed-provider parser 的 TypeScript inference。它与同 shape 普通 Check object 具有相同 runtime 语义。
-- `defineConfig(value)` 形成带默认 `apiVersion`、outputs 和 scheduler policy 的 Project Definition。
+- `defineCheck(value)` 保留 literal `checkId`、options、typed-provider parser 和 `handoff: true` 的 TypeScript inference。它与同 shape 普通 Check object 具有相同 runtime 语义。
+- `defineConfig(value)` 形成带默认 `apiVersion`、outputs 和 scheduler policy 的 Project Definition；可选 `changes` 声明 Git comparison 与 change-flag regions。
 - `defineAdmissionPolicy(value)` 只保留 closed admission policy literal、特别是 custom strategy 的 inference；它与同形 inline policy value 等价。
 - `run(definition, controls?)` 拥有 invocation validation 与 normalization：它关闭递归 Check grammar，detach / canonicalize authored options，并形成 declarative snapshot 与 fingerprint。
 
-fingerprint 使用 normalized declarative fields；preflight、execution 与 custom admission callbacks 都保持为执行行为。scheduler fingerprint 区分 `static` 与 `custom`，且不包含 callback identity、source 或 closure。同一份 Definition 可以重复调用，每次 Run 都从 authored input 派生自己的 project context、prepared options、terminal facts 和 output statuses。
+fingerprint 使用 normalized declarative fields；preparation、execution 与 custom admission callbacks 都保持为执行行为。scheduler fingerprint 区分 `static` 与 `custom`，且不包含 callback identity、source 或 closure。同一份 Definition 可以重复调用，每次 Run 都从 authored input 派生自己的 project context、prepared options、terminal facts 和 output statuses。
+
+## 随包 Check 的构造器项目声明
 
-## options preflight 与 execution
+九个固定身份的随包构造器在现有顶层 options 同时接收领域 policy 与项目 Check 声明：
+`duplicateDetection`、`fileMetrics`、`functionMetrics`、`jsonValidation`、`jsonSchemaValidation`、
+`markdownLinkValidation`、`markdownLint`、`secretDetection` 与 `maintenanceReminders`。前八项使用原有
+object input；`maintenanceReminders(entries)` 保持可用，并增加含 `entries` 的 object input。`commandCheck`
+保持自己的既有 contract。
 
-Check 在获准入后执行自己的 `preflight(options, signal)`，再以 prepared options 或 fallback 进入 `execution`；block 或非法准备结果使本项 `unavailable`。不同 prepared shape 的类型要求、三种返回形式、冻结与取消边界见[自定义 Check 的 preflight](guides/extending-check-lifecycle.md#preflight准备阻止或带-fallback-继续)。
+`PackageCheckAuthoringOptions<Id extends string = string>` 是从 package root 导出的可复用项目声明类型。它的全部字段如下；
+每个字段与 ordinary Check 上的同名字段具有相同含义：
+
+| 字段 | 作用 | 详细规则 owner |
+| --- | --- | --- |
+| `checkId?` | 为实例声明 identity；省略时使用该构造器的默认 literal ID。 | Project Definition 的 validation |
+| `displayName?` | 覆盖该构造器的默认显示名。自定义 `checkId` 不会派生新名称。 | 同上 |
+| `enabledByFlags?` | 声明 selection condition。 | [按 flag 选择 Check](guides/extending-check-lifecycle.md#按-flag-选择-check) |
+| `checks?` | 声明 children，使可执行 Check 同时承担 containment scope。 | [递归组合与继承](#递归组合与继承) |
+| `dependsOn?`、`observes?` | 声明 direct relation；可使用 `inherit(...)`。 | [Check 依赖与类型化数据](guides/check-dependencies.md) |
+| `maxParallel?`、`admissionPriority?`、`mutex?`、`resourceClaims?` | 声明 scheduling 与资源需求。 | [调度 Check](guides/scheduling.md) |
+| `omitQuietPassedRow?` | 控制 progress 中 quiet passed row 的呈现。 | [递归组合与继承](#递归组合与继承) |
+
+构造器 input 是 closed top-level object：它只接受所属 Check 的领域字段和这组项目字段。构造器负责安全快照、
+默认 identity/display name、可在本地判断的字段 shape，以及两类字段的分流。默认 overload 返回该 Check 的默认 literal；
+custom overload 要求 input 的静态类型含必填 `{ checkId: Id }`，并返回同一 `Id`；已宽化为通用 options 类型的变量使用
+broad overload，返回 `string` identity。各 Check guide 给出本 Check 的三个签名、默认 identity/display name 与领域字段。
+
+项目字段投影到最终 Check 声明；它们不进入 resolved `.options`、`prepare`、`execute` 或 execution
+`context.options`。随包构造器仍拥有 `prepare`、`execute`、`parseData` 与 handoff 行为，不能通过这些 options 覆盖。
+`defineConfig`/`run` 随后负责完整 tree 的语义校验、normalization 与运行。
+
+## 按文件变化选择 Check
+
+`changes` 让 Definition 从一次 Git comparison 派生选择用的 change flags。`source` 的完整形状是
+`{ compareWith: string }`；`compareWith` 是 Git revision。`flags` 把非空 region ID 映射到 project-root-relative、
+exclude-first glob region。region 的 `include` 必填，`exclude` 可省略且省略等同 `[]`；显式 `undefined`、`null` 或非数组值不合法。
+有效 `projectRoot` 可以嵌套在 repository 内；Git paths 与 region matching 都相对这个 root。
+
+一次 invocation 的数据流固定如下：
+
+```text
+caller flags ─────────────────────────────┐
+Git snapshot → matched change flags ──────┼→ canonical effective flags → selection and project.flags
+Git snapshot ─────────────────────────────└→ project.changes (files or unavailable reason)
+```
+
+可信 snapshot 只发布命中至少一个 region 的稳定 `{ path, flags }` records；一个 path 可命中多个 regions。可信零命中为
+`{ ok: true, files: [] }`，因此不派生 change flag。Git revision、repository 或 path evidence 不可信时为
+`{ ok: false, reason }`，不带 `files`，但会把全部声明的 change flags 加入 effective flags，以保守选择可能依赖它们的 Check。
+Controls 只能传普通 caller flags，不能传入 `vibe-check:change:` prefix。
+
+```ts
+import { changeFlag, defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
+
+const sourceChanged = defineCheck({
+  checkId: "source-changed",
+  displayName: "Source changed",
+  enabledByFlags: { when: changeFlag("source") },
+  execute: ({ project }) => {
+    const changes = project.changes;
+    if (changes === undefined) {
+      return { status: "unavailable", reason: { code: "changes-not-configured" } };
+    }
+    return {
+      status: "passed",
+      data: {
+        evidence: changes.ok ? "matched" : "unavailable-conservative",
+        effectiveFlags: project.flags,
+        matchedPaths: changes.ok ? changes.files.map(({ path }) => path) : []
+      }
+    };
+  }
+});
+
+const definition = defineConfig({
+  changes: {
+    source: { compareWith: "origin/main" },
+    flags: {
+      source: { include: ["src/**"], exclude: ["src/generated/**"] }
+    }
+  },
+  checks: [sourceChanged],
+  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}`);
+const outcome = result.snapshot.checks.find(({ checkId }) => checkId === sourceChanged.checkId)
+  ?.outcome;
+if (outcome?.status !== "passed" && outcome?.status !== "not-applicable") {
+  throw new Error("Change-aware Check did not settle successfully");
+}
+```
+
+这个示例的 Check 由 `changeFlag("source")` 选择：命中时读取可信 paths，可信零命中时结算为
+`not-applicable`，unavailable evidence 时仍运行但以 `changes.ok === false` 区分结果。`project.flags` 始终是上图的 canonical effective set；`project.changes` 才是 files 或 unavailable reason 的
+evidence channel。要编写 condition、`prepare` 或 `execute`，继续阅读[Check lifecycle](guides/extending-check-lifecycle.md)。
+
+## options preparation 与 execution
+
+Check 在获准入后执行自己的 `prepare(options, signal, project?)`，再以 prepared options 或 fallback 进入 `execute`；block 或非法准备结果使本项 `unavailable`。不同 prepared shape 的类型要求、三种返回形式、冻结与取消边界见[自定义 Check 的 `prepare`](guides/extending-check-lifecycle.md#prepare准备阻止或带-fallback-继续)。
 
 ## terminal result、Records 与 messages
 
 每个可执行 Check 返回一个 terminal result：`passed` / `failed` 带 Check-owned object final data；`not-applicable` 表示本次无适用工作，可省略 reason；`unavailable` 表示无法形成可信结论，必须带非空 `reason.code`。两者都没有 final data；无领域 data 的成功/失败结果可返回 `{}`。settlement 会 detach、canonicalize 并关闭 final data；callback throw、malformed result 或 noncanonical data 对应 `unavailable` outcome。
 
+需要在同一 Run 的 direct prerequisite 间保留引用 identity 时，provider 在 `defineCheck({ handoff: true, ... })` 作最小声明，并只在 accepted `passed` result 返回 non-null object/function reference。handoff 类型由该 result 自动推断；direct `dependsOn` consumer 以 `dependencies.get(provider)` 一次取得 canonical data 和 typed reference。provider 的 `parseData` 仍只处理 canonical data。`handoff: true` 背后的 WeakMap identity 是 Product 内部细节；handoff 是 invocation-private capability，不属于 terminal Check facts。
+
 final data 与 Record data 使用 canonical JSON object：root 不能是数组，拒绝不支持的 prototype/descriptor、getter、cycles、sparse arrays 和 non-finite numbers，不调用 `toJSON`。接受后形成 detached、deep-frozen 的 null-prototype facts；不要依赖 JavaScript own-key enumeration 推断 canonical 文本顺序。
 
 `records.report({ id }, data)` 在 owning Check namespace 内追加 supplemental Record。每个 `id` 非空且在该 Check 内唯一，Record data 使用 canonical JSON object；无效或重复 Record 把 owning Check 结算为 `unavailable`。settlement 保留此前已经接受的 Records；Record 数量不决定 status。结算后 reporter 关闭，late write 抛错且不能更改事实。
@@ -93,11 +200,11 @@ progress 只呈现这些事实，不修改它们。预览默认值、formatter
 
 ## 递归组合与继承
 
-每个节点使用唯一 `checkId` 和非空 `displayName`；可执行节点也可以包含子节点，containment 只贡献 scheduling scope，不额外产生 snapshot 层级。带 `execution` 的节点形成自己的 outcome；没有 `execution` 的节点只组织子 Check 和 scheduling scope。普通对象字段表示显式 replacement；`inherit({ add, remove })` 只用于在父 `dependsOn`、`observes` 或 `mutex` collection 上增删。解析后，每个可执行节点拥有自己的 effective options、passed prerequisites、terminal observations、mutexes、visibility、parallel budget 与 admission priority。
+每个节点使用唯一 `checkId` 和非空 `displayName`；可执行节点也可以包含子节点，containment 只贡献 scheduling scope，不额外产生 snapshot 层级。带 `execute` 的节点形成自己的 outcome；没有 `execute` 的节点只组织子 Check 和 scheduling scope。普通对象字段表示显式 replacement；`inherit({ add, remove })` 只用于在父 `dependsOn`、`observes` 或 `mutex` collection 上增删。解析后，每个可执行节点拥有自己的 effective options、passed prerequisites、terminal observations、mutexes、normalized `omitQuietPassedRow` 人读呈现策略、parallel budget 与 admission priority。该策略不继承给 children，也不属于 terminal facts；它只供 progress renderer 决定 quiet-pass row 的保留与编号格式。
 
 ## 类型化依赖数据
 
-使用 direct `dependsOn` 取得成功 prerequisite，使用 direct `observes` 等待并审计任意终态；从 `dependencies.get` / `list` 读取冻结事实，再由 producing Check 的 `parseData` 恢复业务类型。完整的[依赖数据指南](guides/check-dependencies.md)说明读取授权、继承、parser 边界与运行示例。
+使用 direct `dependsOn` 取得成功 prerequisite，使用 direct `observes` 等待并审计任意终态；从 string `dependencies.get` / `list` 读取冻结事实，再由 producing Check 的 `parseData` 恢复业务类型。以 `handoff: true` 声明的 provider object 可用于 `dependencies.get(provider)`，向 direct prerequisite consumer 同时交付 frozen canonical data 与 same-Run reference。完整的[依赖数据指南](guides/check-dependencies.md)说明读取授权、继承、parser、identity 与 cleanup 边界，并给出运行示例。
 
 ## RunControls 与 Check aggregation
 
@@ -107,11 +214,23 @@ progress 只呈现这些事实，不修改它们。预览默认值、formatter
 - `flags` 是可省略的 dense 非空 string-token 数组，省略、`undefined` 或 `[]` 得到冻结空数组；合法 tokens 被复制、去重并稳定排序，完整集合进入 callback project context。
 - `checkArtifactBaseDirectory` 是可选、invocation-only 的 Check artifact base；它使用非空且无 U+0000 的受信任 directory grammar，relative text 从 effective `projectRoot` 解析，absolute text 直接作为 target。它不进入 Definition fingerprint，不创建 output status，也不授予 Check 读取 base、sibling directory、machine/diagnostic output 或 cross-Run state 的能力；没有配置时 callback 的 `artifactDirectory` 为 `null`。
 - `progressLogFile` 是可选、invocation-only 的 terminal-progress tee target，使用同一非空且无 U+0000 target grammar；它不会改变 Definition outputs、Definition fingerprint 或 Check callback capability。
-- `signal` 供 preflight 与 execution 协作取消；取消结果记录对应 phase。
+- `signal` 供 preparation 与 execution 协作取消；取消结果记录对应 phase。
 - `diagnosticLogFileNaming` 可选 `"unique"`（默认）或 `"channel"`，只控制本次 core/scheduler 日志 basename，不启用 diagnostics、不进入 Definition fingerprint。
-- `checkAggregation` 显式选择 `checks: "all"`、Check-ID list 或 `"effective"`，并以 `all` / `any`、`unavailable`、`notApplicable` 与 `empty` policy 形成 invocation aggregate。`"effective"` 只复用本次 private flag-and-dependency selection；`"all"` 和 ID list 不模拟或修改它。
+- `checkAggregation` 可选为同步 `CheckAggregation` 函数：`(checks: readonly CoreCheck[]) => CheckAggregate`。Product 只在完整结算后按 canonical Check order 传入本次有效列表；它不传入未选 Check、完整 snapshot、Records、messages、输出状态或控制对象。`CoreCheck` 提供 `checkId`、四态 `outcome`，以及 passed/failed outcome 的既有 final data。
+
+aggregation 是 terminal outcomes 之外的 invocation-level fact。省略函数时，非空有效列表且所有 Check 都为 `passed` 得到 `passed`；空列表或任一 `failed`、`unavailable`、`not-applicable` 得到 `failed`。提供函数时，它可以同步返回闭合四态 `passed`、`failed`、`not-applicable` 或 `unavailable`，以调用方的领域规则解释同一列表。函数不能等待、选择 Check、修改 facts 或进入 Definition fingerprint。
+
+例如，下面的调用方只把有效列表中的 `failed` 视为本次领域失败；函数直接返回字面量，不能标记为 `async`：
+
+```ts
+const result = await run(definition, {
+  checkAggregation(checks) {
+    return checks.some((check) => check.outcome.status === "failed") ? "failed" : "passed";
+  }
+});
+```
 
-aggregation 是 terminal outcomes 之外的 invocation-level fact。它在完整 terminal facts 结算后产生 `passed`、`failed`、`not-applicable` 或 `unavailable`；未配置 policy 时 `aggregate` 为 `null`。`"effective"` 的 empty selection 仍由 caller `empty` policy 结算，且不会把 private selection projection 到 `RunResult`、machine、diagnostic 或 callback。consumer 需要调用级结论时显式选择 policy，同时保留每项 Check outcome。
+函数抛错、抛出非 `Error` 值、返回 Promise/thenable 或其它值会使 `run(...)` 的 Promise 直接拒绝；这不是 `RunResult` 的 configuration、execution 或 output branch。Product 关闭本次 diagnostic/progress writer，不呈现正常成功 summary，也不发布正常 machine result。调用方应在 `await run(...)` 周围按自己的错误边界处理这类 authoring fault；普通 Definition、Controls、planning、Check execution 和 output 故障仍按既有 `RunResult` 分支结算。
 
 ## RunResult 分支
 
@@ -121,11 +240,11 @@ aggregation 是 terminal outcomes 之外的 invocation-level fact。它在完整
 
 | 分支 | 可用 facts 与处理方式 |
 | --- | --- |
-| `completed` | 完整 `snapshot`、`checkDurations`、`checkMessages`、`outputs` 与可选 `aggregate`；继续读取单项 Check outcome。 |
-| `output` | 完整 Check facts 与 output failure diagnostic；消费 facts 并处理失败的 output。 |
-| `cancelled` / `phase: "execution"` | 取消时关闭的 snapshot、durations 与 messages；按 cancellation result 处理。 |
+| `completed` | 完整 `snapshot`、`checkDurations`、`checkMessages`、`outputs` 与非空四态 `aggregate`；继续读取单项 Check outcome。handoff 已在 execution graph 关闭时清除，不在此结果中。 |
+| `output` | 完整 `snapshot`、`checkDurations`、`checkMessages` 与四态 `aggregate`，另有 output failure diagnostic；消费 facts 并处理失败的 output。 |
+| `cancelled` / `phase: "execution"` | 取消时关闭的 snapshot、durations 与 messages；没有 aggregate，按 cancellation result 处理。 |
 | `cancelled` / `phase: "pre-work"` 或 `"planning"` | invocation metadata 与 cancellation phase；按 phase 结束调用。 |
-| `configuration` | Definition、controls 或 aggregation selection diagnostic；project callback 执行数为零。 |
+| `configuration` | Definition 或 Controls diagnostic；project callback 执行数为零。 |
 | `planning` | task-graph diagnostic 与 invocation metadata。 |
 | `execution` | Product execution-settlement diagnostic 与 invocation metadata。`diagnostic.code === "admission-policy-failed"` 表示 custom policy 已停止 admission、取消 pending 并 drain started work；它不是 Check terminal status，也不携带 partial snapshot。 |
 

package/docs/changelog.md

@@ -1,13 +1,156 @@
 # 变更日志
 
-本页随包提供版本变化与升级影响，按版本组织。
+本页随包提供版本变化与升级影响，按版本组织；具体行为规范由链接的用户指南拥有。
+
+## 0.0.3
+
+本节记录 `0.0.3` 相对 `v0.0.2` 的净变化。Node `>=24.18` 的宿主要求与包根程序化入口保持不变。
+
+### 从 0.0.2 升级
+
+按项目实际使用的能力完成以下调整，再运行项目类型检查与代表性 Run，复核有效选择、单项终态、
+`aggregate`、Records 与输出失败处理。`RunResult.kind === "completed"` 仍不表示质量检查通过。
+
+1. **调整自定义 Check 的回调与类型名称。**
+   `preflight` → `prepare`，`execution` → `execute`；
+   `CheckPreflight` / `CheckPreflightResult` → `CheckPreparation` / `CheckPreparationResult`，旧字段不保留兼容别名。
+   按原因码分类时，将 `preflight-threw`、`invalid-preflight-result` 改为
+   `preparation-threw`、`invalid-preparation-result`。
+   `prepare(options, signal, project?)` 每次 Run 都取得与 `execute` 一致的冻结项目上下文，
+   但公开类型的第三参数可省略，读取前须处理该分支；同时复核 options 深度只读类型推导。
+   见[自定义 Check](./guides/extending-check-lifecycle.md)。
+2. **调整调度终态回调与状态读取。**
+   `scheduler.measurementHooks`、`SchedulerMeasurementHook` 与已准备策略的 `complete` 分别改为
+   `scheduler.terminalEffects`、`SchedulerTerminalEffect` 与 `terminalEffect`。
+   状态改读 `RunResult.outputs.terminalEffects`，诊断码改为 `scheduler-terminal-effects-failed`。
+   没有终态测量时不保证调用，资源释放不能依赖它。
+   见[调度扩展](./guides/scheduling.md#已准备的-custom-strategy)。
+3. **复核聚合结果与定制函数的失败处理。**
+   `completed` / `output` 默认带 `aggregate`：有效 Check 非空且全部 `passed` 才为 `passed`，
+   空列表或任一其它终态均为 `failed`；取消分支不新增聚合结果。
+   旧 `checkAggregation` 策略对象改为同步 `(checks: readonly CoreCheck[]) => CheckAggregate`，
+   读取规范顺序的只读有效列表，返回四态之一，不修改 Check 事实。
+   函数抛错、返回 Promise/thenable 或非法值会直接拒绝 Run Promise，而非形成 `RunResult` 分支；
+   此时不发布正常完成摘要或机器结果，调用方须处理 `await run(...)` 的拒绝。
+   见[聚合契约](./api-mechanics.md#runcontrols-与-check-aggregation)。
+4. **把 flag 选择改为组合条件。**
+   `enabledByFlags: { flags, mode }` 改为 `{ when, propagateDependsOn? }`。
+   `when` 使用 `CheckFlagCondition`：字符串表示单个 token，组合使用
+   `all`、`any`、`none`、`notAll`、`exactlyOne`、`not` 或对应递归 AST。
+   `dependsOn` 传播仍须显式启用，`observes` 不参与扩展。
+   见[flag 条件](./guides/extending-check-lifecycle.md#按-flag-选择-check)；新增 Git 选择见下节。
+5. **替换进度呈现的 `visibility`。**
+   删除旧字段；需要省略安静通过行时，在普通可执行 Check 上声明 `omitQuietPassedRow: true`。
+   它只接受字面量 `true`，容器不能声明，也不继承给子项。
+   安静通过指 `passed` 且已接受 Records/messages 均为空；只改变人读行，完整快照、时长和机器事实保持不变。
+   进度新增配置数与实际省略数，启用策略的行不编号，普通行仍按全局完成数编号。
+   `maintenanceReminders` 保持默认省略安静通过行；随包构造器接受 boolean，可用 `false` 撤销默认。
+   见[进度呈现](./guides/run-outputs.md#progress-rendering)。
+
+### 新能力与现有 Check 修复
+
+#### 项目声明与 Git 变化选择
+
+- **九个随包构造器接受项目声明**：领域 options 同一顶层可声明标识、flags、关系、调度与呈现策略，
+  公开 `PackageCheckAuthoringOptions`；既有领域配置无需迁移。项目字段与执行 options 分离，构造器仍拥有回调、
+  解析函数与 handoff。`maintenanceReminders(entries)` 保持可用，并增加对象输入；`commandCheck` 使用自己的契约。
+  字段清单、字面量类型推导与校验见[构造器项目声明](./api-mechanics.md#随包-check-的构造器项目声明)。
+- **Definition 新增 `changes`**：以 `source: { compareWith }` 声明 Git revision，以路径区域派生
+  `changeFlag(id)`。每次 Run 在选择前获取一次证据；可信零命中为 `{ ok: true, files: [] }`，
+  证据不可用时不伪造 files，而保守派生全部已声明 change flags。
+  回调的 `project.flags` 包含调用方与派生 tokens，路径或不可用原因从 `project.changes` 读取；
+  Controls 拒绝 `vibe-check:change:` 前缀。`include` 必填，`exclude` 省略等同 `[]`，非法输入仍拒绝。
+  见[文件变化选择](./api-mechanics.md#按文件变化选择-check)。
+
+#### 外部命令与 Markdown 检查
+
+- **新增 [`commandCheck`](./guides/command-check.md)**：以无 shell 的单个可执行程序与独立参数接入 Check，
+  必填超时与 stdout/stderr 各自的字节上限。完整数字退出码默认 `0` 为 `passed`、非零为 `failed`；
+  启动失败、超时、输出超限、信号终止、transcript 失败与取消保留不可用结算。
+  默认调用方基础环境为空、输出丢弃，Product 最后注入固定纯文本/禁用颜色变量。
+  可显式选择环境继承、调用时解析或 transcript 产物。
+  完整且未中断的数字退出（如启用 transcript，其写入也须成功）才调用 `afterCommand.execute`，用领域结果替代默认结算；
+  可选 `afterCommand.parseData` 建立类型化提供方。stdout/stderr 不自动发布，凭据、原始输出及派生数据的
+  访问控制、保留与清理由调用方负责。
+- **新增 [`markdownLint`](./checks/markdown-lint.md) 与 `parseMarkdownLintData`**：
+  新增固定运行依赖 `markdownlint@0.41.1`，提供八项默认规则；`link-fragments` 须显式启用，
+  本地目标/锚点完整性仍由 `markdownLinkValidation` 检查。默认 Finding 为 `non-blocking`，可设为 `blocking`。
+  可选逐文件 findings 缓存默认关闭，使用调用方拥有的绝对目录；仍读取源码并重新结算策略与终态，
+  损坏/不可用时重新计算，容量与清理由调用方管理。
+  精确 `findingWaivers` 按 `path`、`rule`、完整 `range` 与 reason 对账，保留全部 Finding，
+  未命中/过宽发布 audit。`findingCount` 包含已豁免项；消费 `MarkdownLintRecordData` 时须覆盖 audit 分支。
+
+#### 依赖交接与数据工具
+
+- **新增同一次 Run 内的私有 handoff**：提供方以 `defineCheck({ handoff: true, ... })` 声明，
+  在已接受的 `passed` 结果交付对象/函数引用；直接 `dependsOn` 消费方用 `dependencies.get(provider)`
+  同时读取规范化 data 与类型化引用，不扩大 `observes` 或传递依赖的权限。
+  引用不进入 fingerprint、快照、RunResult、输出、聚合或缓存；执行图结束只清除 Product 自己的引用。
+  提供方/消费方须保持只读观察，资源创建者/调用方负责释放。见[依赖交接](./guides/check-dependencies.md)。
+- **公开六项 [Core 数据工具](./guides/data-boundaries.md)**：
+  `canonicalizeJsonObject` / `canonicalizeJsonValue`、`canonicalJsonText` / `canonicalJsonBytes` 与
+  `snapshotExactClosedRecord` / `snapshotClosedArray` 从包根导出。
+  JSON 工具生成独立规范化副本或确定性文本/字节；结构工具只快照并冻结外层，保留嵌套与回调引用。
+- **`reconcileFindingWaivers` 的 `waivers` 可省略**：省略或显式 `undefined` 等同 `[]`；
+  仍验证全部 Finding 标识，保留顺序与引用，非法配置仍拒绝。已传数组无需修改；
+  `ReconcileFindingWaiversOptions["waivers"]` 类型消费者须处理新增 `undefined` 分支。
+  见[Finding waiver](./guides/finding-waivers.md#输入与默认值)。
+
+#### 兼容修复与指南
+
+- **[`fileMetrics`](./checks/file-metrics.md) 支持大量精确路径分批传输 SCC**：
+  全部批次验收成功才发布一份统一测量，任一失败拒绝整次扫描，不发布部分结果；无新增公共配置。
+- **修复 [`secretDetection`](./checks/secret-detection.md) 的 Windows 读取分支**：
+  用路径/文件描述符的设备与 inode 身份握手，避免仅因缺少 `O_NOFOLLOW` 提前拒绝普通文件；
+  POSIX 仍要求 `O_NOFOLLOW`，软链接、非普通文件或不可靠身份仍拒绝。
+  此可移植性修复不扩展受支持平台承诺，也不提供恶意文件系统沙箱。
+- **新增[从质量目标构建项目 Gate](./guides/building-project-gate.md)指南**：
+  可执行场景覆盖命令接入、共享准备、依赖与观察、选择、自建缓存、资源约束和诊断转换。
+
+`run.json` / `records.ndjson` 继续使用 [v4 machine schema](./output.md)；
+RunResult API 与各 Check 的 Record 变化须分别复核，不能仅以 schema 版本判断兼容性。
+
+### 实现与仓库维护
+
+本节面向仓库维护者，不增加包消费者的运行入口。
+
+- 随包工具迁入 `package-tools` 责任层，保持既有包根导入；收紧 TypeScript/Oxlint 与公开依赖边界检查。
+- Project Gate 复用 `commandCheck`，`afterGate` 改为 `resultContributor`；按材料责任重组验收，
+  用 change flags 收窄增量选择，显式启用 Markdown lint/cache；性能预算按总耗时与 Check 分布告警。
+- 候选包复用原始编译产物并收窄缓存失效；重整材料验证、投影与治理验证入口。
+
+### 0.0.3 相关提交
+
+提交用于追溯实现；具体行为规范见以上指南，精确签名见安装包声明。
+
+| 变更主题 | 提交 |
+| --- | --- |
+| 扩展生命周期与只读 options 类型 | `502dd799`、`155b781d` |
+| 默认与同步定制聚合 | `454a00ed` |
+| Git change flags、组合条件与可省略 exclude | `4a9426d7`、`f619f5c5`、`8638ed77`、`f6af3a53` |
+| 随包构造器项目声明 | `09113635` |
+| `commandCheck` 与完成阶段 | `a4f761ac`、`2229e2ca` |
+| Markdown lint、缓存与精确 waiver | `ae3e05e1`、`5206ae78`、`c2054034` |
+| 安静通过行呈现 | `2d2c532a`、`66bfce61` |
+| 私有 handoff 与公开数据工具 | `9d09b785`、`0c6608ff` |
+| SCC 分批与秘密检测文件读取 | `693a89be`、`2c991d6d` |
+| 可省略 Finding waiver | `8d522ebf` |
+| 项目 Gate 构建指南 | `3d4c97cb` |
+| Gate 命令、材料与增量接线 | `a41e4b96`、`54f7da1b`、`a508fc48`、`9cd1238d`、`ddc60c31` |
+| candidate 编译复用与文档材料校验 | `106929d8`、`fb6944df`、`bdbe685d`、`abda82a6` |
+
+**历史说明更正**：下方 `0.0.2` 按真实 `v0.0.2` tag 恢复 `preflight`、`measurementHooks` 与 `afterGate`；
+后续改名归于 `0.0.3` 的 `502dd799`，handoff 归于 tag 后的 `9d09b785`。
+此更正仅修订发布说明，不改变 `0.0.2` 已发布产物或发布日期。
 
 ## 0.0.2
 
+发布日期：2026-09-09。
+
 本节按主题记录 `@zxyycom/vibe-check` 的 `0.0.2` 相对 `0.0.1` 的净变化。
 升级影响随对应变更列出，提交记录集中在[相关提交](#相关提交)。
 
-正式发布后，在 Node `>=24.18` 环境安装精确版本并更新 lockfile；按所用能力完成调整后，
+在 Node `>=24.18` 环境安装精确版本并更新 lockfile；按所用能力完成调整后，
 运行项目 typecheck 和代表性 Run，复核 Check 终态、Finding/Records、aggregation 与诊断。
 
 ### 产品变化

package/docs/checks/duplicate-detection.md

@@ -7,6 +7,26 @@
 
 默认使用随 package 安装的 jscpd v5（manifest 范围 `^5.1.1`），无需另配 executable。
 
+## 构造器项目声明
+
+`duplicateDetection` 有三类 overload：`duplicateDetection(options?: DuplicateDetectionOptions<"duplicate-detection">)`
+保留默认 literal；`duplicateDetection<Id>(options: DuplicateDetectionOptions<Id> & { checkId: Id })` 保留 custom literal；
+已宽化为 `DuplicateDetectionOptions` 的变量返回 `string` identity。默认 `checkId` 是 `duplicate-detection`，默认 `displayName` 是 `Duplicate detection`；`codeAreas`、
+`findingPolicy`、`findingWaivers`、`cache` 与 `scanner` 仍是本 Check 的领域 options。
+
+例如，为较昂贵的扫描声明较低并行度和独立 identity：
+
+```ts
+const duplicateScan = duplicateDetection({
+  checkId: "source-duplicate-scan",
+  maxParallel: 1,
+  codeAreas: { source: { files: { include: ["src/**/*.ts"] } } }
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
 ## 最小用法
 
 示例保留终端进度，不写 machine files。
@@ -30,8 +50,7 @@ if (result.kind !== "completed" || outcome?.status !== "passed") {
 
 示例显式使用 `findingPolicy: "blocking"`，让未豁免的普通 Finding 导致失败；默认 `non-blocking` 只警告，不因 Finding 退出非零。
 
-本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
-显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -234,7 +253,7 @@ Run progress 预览边界见 [呈现 Check Finding](../guides/presenting-finding
 
 上述 `unavailable` 都发生在完整 Finding 集合形成前，因此不发布 applied/unused/overmatched waiver audit。
 
-通用 preflight 机制见 [options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+通用 preparation 机制见 [options preparation 与 execution](../api-mechanics.md#options-preparation-与-execution)。
 
 ## I/O 与安全边界
 

package/docs/checks/file-metrics.md

@@ -8,6 +8,26 @@ waiver 在完整 Finding 集合上对账，不从 SCC 输入排除路径。
 运行环境须提供默认 `scc` command，或配置已授权的 `scanner.executable`；两者均须支持精确 SCC 4.0.0 version output
 与 CSV contract。安装与协议见[定制 SCC executable](#定制-scc-executable)。
 
+## 构造器项目声明
+
+`fileMetrics` 有三类 overload：`fileMetrics(options?: FileMetricsOptions<"file-metrics">)` 保留默认 literal；
+`fileMetrics<Id>(options: FileMetricsOptions<Id> & { checkId: Id })` 保留 custom literal；已宽化为
+`FileMetricsOptions` 的变量返回 `string` identity。默认 `checkId` 是 `file-metrics`，默认 `displayName` 是 `File metrics`；`codeAreas`、`findingPolicy`、
+`findingWaivers` 与 `scanner` 仍是本 Check 的领域 options。
+
+例如，可在同一 Definition 中用独立 identity 选择 source 指标，并保留默认展示名：
+
+```ts
+const sourceMetrics = fileMetrics({
+  checkId: "source-file-metrics",
+  enabledByFlags: { when: "source-changed" },
+  codeAreas: { source: { files: { include: ["src/**/*.ts"] } } }
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `sourceMetrics.options` 或执行时的
+`context.options`；完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
 ## 最小用法
 
 示例保留终端进度，不写 machine files。
@@ -31,8 +51,7 @@ if (result.kind !== "completed" || outcome?.status !== "passed") {
 
 示例显式使用 `findingPolicy: "blocking"`，让未豁免的普通 Finding 导致失败；默认 `non-blocking` 只警告，不因 Finding 退出非零。
 
-本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
-显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -126,8 +145,8 @@ SCC CSV 的 `Complexity` 字段是 file-metrics 使用的 decision-token measure
 
 1. Check 先按文件 `source` 分组；每种不同来源只枚举一次候选文件，再为每个 area 应用自己的 `include` / `exclude`，
    并保存 path 到全部实际 area IDs 的 membership。
-2. Check 对全部路径稳定排序、去重，只把这个 exact-path union 交给 SCC 一次。
-3. 每条 SCC measurement 必须声明属于该 union 的 source path；任一越界 measurement 会拒绝整批结果。
+2. Check 对全部路径稳定排序、去重，并把这个 union 作为一次 logical SCC scan。adapter 按私有的 Windows UTF-16 argv 上界传输：安全的小输入仍由一个 process 承载；较大输入按原顺序分成一个或多个非空 exact-path batches。分批不会让 SCC 重新发现路径，也不形成新的 options、Records 或公开结果。
+3. 每个 process batch 都必须先完成 CSV 与该 batch 的 exact-scope 验收；全部 batch 成功后 adapter 才拒绝重复 measurement path、稳定排序并交回统一结果。任一 process、CSV、scope 或汇合失败都会拒绝整个 logical scan，不发布已完成 batch 的部分 measurement。
 4. 对属于多个区域的文件，Check 分别计算各区域的有效代码行上限，并使用其中最小的严格上限：
 
    ```text
@@ -150,8 +169,8 @@ const customFileMetrics = fileMetrics({
 custom executable 必须直接接受 SCC CLI 参数。public scanner policy 只选择 executable；owning adapter 固定执行以下协议：
 
 - availability probe：`--version`
-- measurement：`--no-config --by-file --format csv <approved exact paths...>`
-- process timeout：由 adapter 固定，不属于项目策略
+- measurement：每个私有 batch 都执行 `--no-config --by-file --format csv <approved exact paths...>`；全部 batch 仍是一份 logical measurement
+- process timeout 与 stdout/stderr output budget：由 adapter 固定并覆盖完整 logical scan，不属于项目策略
 
 需要 prefix arguments 的通用 runtime（例如 `node path/to/tool.js`）不是受支持的直接 command；项目应提供一个已授权的
 专用 wrapper executable。当前 adapter 只接受 SCC `4.0.0` 的 version output 与对应 CSV header contract。

package/docs/checks/function-metrics.md

@@ -5,6 +5,26 @@
 `functionMetrics` 是普通 Check，评估每个函数的 NLOC、cyclomatic complexity（CCN）、最大 nesting depth 与 parameter count。
 它使用随包 TypeScript analyzer 分析所选的受支持源文件。
 
+## 构造器项目声明
+
+`functionMetrics` 有三类 overload：`functionMetrics(options?: FunctionMetricsOptions<"function-metrics">)`
+保留默认 literal；`functionMetrics<Id>(options: FunctionMetricsOptions<Id> & { checkId: Id })` 保留 custom literal；
+已宽化为 `FunctionMetricsOptions` 的变量返回 `string` identity。默认 `checkId` 是 `function-metrics`，默认 `displayName` 是 `Function metrics`；`codeAreas`、
+`findingPolicy` 与 `findingWaivers` 仍是本 Check 的领域 options。
+
+例如，按关系等待生成步骤后执行一个独立的函数指标实例：
+
+```ts
+const generatedFunctionMetrics = functionMetrics({
+  checkId: "generated-function-metrics",
+  dependsOn: ["generate-sources"],
+  codeAreas: { generated: { files: { include: ["generated/**/*.ts"] } } }
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
 ## 最小用法
 
 示例保留终端进度，不写 machine files。
@@ -28,8 +48,7 @@ if (result.kind !== "completed" || outcome?.status !== "passed") {
 
 示例显式使用 `findingPolicy: "blocking"`，让未豁免的普通 Finding 导致失败；默认 `non-blocking` 只警告，不因 Finding 退出非零。
 
-本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
-显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置