@zxyycom/vibe-check 0.0.1 → 0.0.2

package/docs/api-mechanics.md

@@ -12,183 +12,110 @@
     Project Definition
       │ run: validate Definition + RunControls, then normalize the Check tree
       ▼
-    declarative snapshot + fingerprint + complete static graph validation
-      │ sequential all-Check preflight barrier
+    validated Definition + complete static graph
+      │ before execution: apply cancellation and flag selection
+      │ prepared admission strategy readies one Run-local decision function when configured
       ▼
-    prepared Checks / blocked unavailable outcomes
-      │ build the ready task graph; apply dependency, mutex and parallel scheduling
+    initial control settlements + complete static Task graph
+      │ Scheduler applies direct relations, mutex and parallel scheduling
+      ▼
+    task-local preflight / 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
       ▼
     RunResult
 
-Run 在 preflight 前验证包含全部可执行 Check 的静态 task graph；完整 barrier 结束后，blocked Check 先结算为
-`unavailable`，其余 prepared Checks 再形成 ready task graph。Run snapshot 保存 Check facts；progress rendering 呈现
-execution lifecycle；machine publication 在 terminal snapshot 形成后写入 machine files。所有 author execution 都在完整
-preflight barrier 之后开始，optional aggregate 也在 terminal facts 结算后计算。
+### Selection 与 Scheduler readiness
 
-## Definition 与 invocation 的责任
+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 则可等待并读取该终态。
 
-- `defineCheck(value)` 保留 literal `checkId`、options 和 typed-provider parser 的 TypeScript inference。它与同 shape 普通 Check object 具有相同 runtime 语义。
-- `defineConfig(value)` 形成带默认 `apiVersion`、outputs 和 scheduler policy 的 Project Definition。
-- `run(definition, controls?)` 拥有 invocation validation 与 normalization：它关闭递归 Check grammar，detach / canonicalize authored options，并形成 declarative snapshot 与 fingerprint。
+### Task-local preflight 与 execution
 
-fingerprint 使用 normalized declarative fields；preflight 与 execution callbacks 保持为执行行为。同一份 Definition 可以重复调用，每次 Run 都从 authored input 派生自己的 project context、prepared options、terminal facts 和 output statuses。
+其余 Check 被 Scheduler 在 direct relation、mutex 与 capacity 允许后 admission，并在自己的 task 中执行 preflight，随后才执行 author callback。没有互相约束的 preflight 可以并行；它们不构成 Definition 顺序的全局 barrier。
 
-## options preflight 与 execution
+### Terminal snapshot、aggregation 与 outputs
 
-可执行 Check 可以提供 `preflight(options, signal)`，在 author execution 前准备本次 invocation 使用的 options。authored 与 prepared options 同形时可以直接使用 authored options；两种 shape 不同时，TypeScript 要求提供 preflight。
+Run snapshot 保存 Check facts；progress rendering 呈现 execution lifecycle；machine publication 在 terminal snapshot 形成后写入 machine files；optional aggregate 也在 terminal facts 结算后计算。
 
-preflight 返回以下三种 closed result 之一：
+prepared strategy 的 `prepare / decide / complete` 顺序、失败与取消边界由[调度专题](guides/scheduling.md#已准备的-custom-strategy)定义；这些回调不能回写已结算 Check facts。
 
-| 结果 | execution 输入与 Check outcome |
-| --- | --- |
-| `{ status: "success", preparedOptions, messages? }` | 使用 `preparedOptions` 进入 execution。 |
-| `{ status: "failure", action: "block", reason, messages? }` | owning Check 以 `unavailable` 结算。 |
-| `{ status: "failure", action: "continue", reason, fallback, messages? }` | 使用 `fallback` 进入 execution。 |
+## Definition 与 invocation 的责任
 
-Run 按 Definition 顺序执行所有 Check 的 preflight，完整 barrier 结束后才启动 Check scheduler。preflight throw、malformed result 或 noncanonical prepared value 把 owning Check 结算为 `unavailable`。prepared options 与 fallback 都会成为 detached、deep-frozen 的 invocation-local value；preflight messages 与后续 terminal outcome 共同呈现 preparation 结果。
+### 参数应该放在哪里
 
-Package root 的 `defaultProjectFileSelection` 只是 file-selecting constructor 共用的可组合、深冻结 baseline；spread 该
-value 不会建立跨 Check global config。部分 constructor 原样物化它，具有更窄文件类型能力的 constructor 从相同
-source/exclude 派生精准默认 include；显式 `include` / `exclude` 数组始终由 owning Check 视为完整替换。每项实际默认与
-selected-but-rejected 行为由对应 Check 指南说明。
+**Definition 定义项目怎么检查；Controls 指定这一次怎么运行。** `defineConfig(...)` 的返回值是可重复使用的 Definition，`run(definition, controls?)` 的第二个参数只作用于当前调用；没有本次调整时，使用 `run(definition)`。
 
-## terminal result、Records 与 messages
+| 想设置什么 | 参数位置 | 与另一份输入的关系 |
+| --- | --- | --- |
+| 检查内容、领域 options、依赖与 Check 约束 | Definition 的 `checks` 中各项 Check | Controls 不能替换 Checks 或覆盖 Check options；领域输入继续由 owning Check 或显式 provider 承接。 |
+| 调度并行预算、资源总量、策略与终态观察回调 | Definition 的 `scheduler` | Controls 没有 scheduler override，也不能注入 `measurementHooks`。 |
+| 默认 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 返回一个 terminal result：`passed` / `failed` 带 Check-owned object final data；`not-applicable` / `unavailable` 以 reason 表示本次调用的数据边界。settlement 会 detach、canonicalize 并关闭 final data；callback throw、malformed result 或 noncanonical data 对应 `unavailable` outcome。
+**两处 `outputs` 是默认值和逐字段覆盖值。** 只关闭本次 machine publication 不影响 progress、diagnostics 或下次调用；省略/`undefined` 不覆盖，`false`、预览数量 `0` 和清除 formatter 的 `null` 有效。字段默认值和示例见[输出指南](guides/run-outputs.md)。
 
-`records.report({ id }, data)` 在 owning Check namespace 内追加 supplemental Record。每个 `id` 非空且在该 Check 内唯一，Record data 使用 canonical JSON object；无效或重复 Record 把 owning Check 结算为 `unavailable`。settlement 保留此前已经接受的 Records。
+相对输出路径从本次 effective `projectRoot` 解析；可复用的默认目录通常放 Definition，本次独占目录通常放 Controls 的对应 output override。Controls 不进入 Definition 的 declarative fingerprint。它也不是任意配置合并对象：unknown fields 会在 author work 前被拒绝；精确 grammar 与结果见下文[RunControls 与 Check aggregation](#runcontrols-与-check-aggregation)。
 
-`messages?` 是 owning Check 可选的有序人读说明；consumer 必须先按 outcome 处理事实，不能用 message presence 推断状态。final data、Records 和 messages 分别承载主要事实、补充事实和人读说明。随包 Check 的额外 message 保证由各自指南说明。
+### 定义与调用如何处理输入
 
-## Finding waiver reconciliation
+- `defineCheck(value)` 保留 literal `checkId`、options 和 typed-provider parser 的 TypeScript inference。它与同 shape 普通 Check object 具有相同 runtime 语义。
+- `defineConfig(value)` 形成带默认 `apiVersion`、outputs 和 scheduler policy 的 Project Definition。
+- `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。
 
-`reconcileFindingWaivers({ findings, identify, waivers })` 是 package root 提供的独立 helper，供 custom Check 或其它
-finding producer 在**完整** finding 候选集合形成后对账。`identify(finding)` 对输入顺序中的每个原 finding 接收完整
-finding；调用方自行选择稳定的语义 identity，例如 path、function name 和 metric 的组合。`identify` 的结果与
-`waiver.identity` 都必须可安全 materialize 为 canonical JSON，helper 按 canonical JSON 的结构而非对象引用匹配。
+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。
 
-每项 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。
+## options preflight 与 execution
 
-输出 `findings` 保持输入顺序，并在每项结果中保留同一个原 finding reference。applied waiver 附带的 evidence 是 detached、
-deep-frozen 的 canonical materialization，因此调用方之后修改 authored identity 或 reason 不会改变结果。helper 只返回
-finding disposition 和 waiver audit；它不发布 Record、message 或 terminal outcome。采用它的 Check 自己决定如何发布证据及
-如何结算 actionable finding。
+Check 在获准入后执行自己的 `preflight(options, signal)`，再以 prepared options 或 fallback 进入 `execution`；block 或非法准备结果使本项 `unavailable`。不同 prepared shape 的类型要求、三种返回形式、冻结与取消边界见[自定义 Check 的 preflight](guides/extending-check-lifecycle.md#preflight准备阻止或带-fallback-继续)。
 
-## 递归组合与继承
+## terminal result、Records 与 messages
 
-带 `execution` 的节点形成自己的 outcome；没有 `execution` 的节点只组织子 Check 和 scheduling scope。普通对象字段表示显式 replacement；`inherit({ add, remove })` 只用于在父 `dependsOn` 或 `mutex` collection 上增删。解析后，每个可执行节点拥有自己的 effective options、dependencies、mutexes、visibility 与 parallel budget。
+每个可执行 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。
 
-## 类型化依赖数据
+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 文本顺序。
 
-producer 同时声明 `execution` 与 `parseData`，从而拥有 final-data contract。consumer 先声明 direct `dependsOn`，再用非泛型 `dependencies.get(checkId)` 读取 canonical data、收窄 `ok`，最后调用 producer 的 parser。
-
-### 完整运行示例
-
-```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: read.status, 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}`);
-```
-
-dependency reader 为已声明且具有 `passed` / `failed` final data 的 direct dependency 返回 `ok: true`，并保留 upstream status；其它读取返回包含原因的 `ok: false`。producer parser 负责 shape、invariant 和 compatibility validation，consumer 显式调用它恢复 provider data。七个随包 Check 都提供 `parseData` 和同实现的 package-root parser；名称与类型见各自指南。
+`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 抛错且不能更改事实。
 
-## RunControls 与 Check aggregation
+`messages?` 是 owning Check 可选的有序人读说明；consumer 必须先按 outcome 处理事实，不能用 message presence 推断状态。final data、Records 和 messages 分别承载主要事实、补充事实和人读说明。随包 Check 的额外 message 保证由各自指南说明。
 
-`RunControls` 只作用于一次 `run(definition, controls)`：
+author `messages` 是无空洞的有序数组，每项是精确 `{ level, code, message }`：level 为 `info | warning | error`，code 和 message 均为非空字符串。Product 不 trim、Unicode normalize、去重或设置 item/正文长度上限；省略、自有 `undefined` 和 `[]` 都表示无 messages。非法 attachment 使 owning Check 不可用且不接受 partial messages。捕获的 console 复用同一 readback shape，使用 `console-<method>` code。
 
-- `projectRoot` 决定项目相对路径的解析根。
-- `flags` 成为 callback 可读的 normalized project context。
-- `signal` 供 preflight 与 execution 协作取消；取消结果记录对应 phase。
-- `outputs` 覆盖本次 diagnostic logging、machine publication 或 progress rendering。
-- `checkAggregation` 选择 `checks`，并以 `all` / `any`、`unavailable`、`notApplicable` 与 `empty` policy 形成 invocation aggregate。
+progress 只呈现这些事实，不修改它们。预览默认值、formatter、console capture 与日志见[配置 Run 输出与诊断](guides/run-outputs.md)。
 
-aggregation 是 terminal outcomes 之外的 invocation-level fact。它在完整 terminal facts 结算后产生 `passed`、`failed`、`not-applicable` 或 `unavailable`；未配置 policy 时 `aggregate` 为 `null`。consumer 需要调用级结论时显式选择 policy，同时保留每项 Check outcome。
+## 递归组合与继承
+
+每个节点使用唯一 `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。
 
-Check-specific invocation facts 由 owning Check 的 options 或 producing Check 的 final data 承载。多个 Checks 共享同一事实时，producer 负责 acquisition policy 与 data shape，下游通过 direct `dependsOn` 读取；上面的 typed dependency 示例聚焦这条 data handoff。
+## 类型化依赖数据
 
-## outputs 与 RunResult 边界
+使用 direct `dependsOn` 取得成功 prerequisite，使用 direct `observes` 等待并审计任意终态；从 `dependencies.get` / `list` 读取冻结事实，再由 producing Check 的 `parseData` 恢复业务类型。完整的[依赖数据指南](guides/check-dependencies.md)说明读取授权、继承、parser 边界与运行示例。
 
-Definition outputs 提供 diagnostic logging、machine publication 与 progress rendering 三项独立 defaults，RunControls 可以只覆盖当前调用需要的部分。configuration 成功后的职责如下：
+## RunControls 与 Check aggregation
 
-- 只有 diagnostic logging 或 machine publication 至少一项启用时，Run 才在创建 invocation 阶段捕获一次 immutable wall-clock `startedAtUtc`；两项都禁用时不读取或序列化 wall clock。
-- 启用的 diagnostic logging 在 preflight 前以该 instant 命名 UTC-compact log path，并按事实形成顺序记录 Product core 已知的 invocation、planning、scheduler、handoff 与 output 时间线。每个事件以序号、单调 elapsed、可筛选的 `[]` 标签和 event name 开始；普通事实使用 `key=value`，超出当前主行容量的事实进入有界 continuation line。标签只突出 Run、Check、phase、Scheduler decision 和 outcome 等高频阅读轴；Scheduler decision 的顶层 `kind` / `taskId` 与 Record observation 的顶层 `result` 已由标签完整表达时，不在 facts 中重复。
-- 启用的 machine publication 将同一个 instant 投影为 `run.json` 的 `invocation.timestamp`，所以 timestamp 不是 publication 完成时间；两项同时启用时，日志文件名与 machine timestamp 必须共享该一次捕获。
-- progress rendering 呈现人读 lifecycle。三项 output 都由 Run 调度，并分别返回 status。
+`RunControls` 只作用于一次 `run(definition, controls)`：
 
-这些 diagnostic 行不建立可解析 schema。Run 结束前最后一条可写 diagnostic event 是 `run.terminal-before-log-close`：它只证明 terminal fact 已写入、logger close 尚未确认，随后才尝试关闭日志。
+- `projectRoot` 决定项目相对路径的解析根；省略时使用调用时的工作目录。
+- `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。
+- `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 不模拟或修改它。
 
-只有 non-configuration `RunResult` 具有有效 output configuration 与 `outputs` readback。此时
-`outputs.diagnosticLogging` 的形状为 `{ enabled, status, file }`，其中 `status` 是
-`"disabled" | "not-run" | "succeeded" | "failed"`；禁用时 `file` 为 `null`，启用时即使文件创建失败也保留预先计算的、
-project-root-relative `run-<UTC 紧凑时间>-<UUID>.log` 目标。无效 Definition、controls 或 aggregation selection 直接返回
-configuration diagnostic，不创建诊断日志。
+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。
 
-diagnostic logging 只服务当前人工诊断：它没有 parser、schema/version、跨版本格式兼容、`latest`、retention 或跨 invocation
-discovery contract，也不替代 Check final data、Record、terminal message 或 Check/process adapter 自有的 transcript。logging
-failure 只把该 output 标为 failed，不改写已形成的 Check/Record facts，也不阻断 progress rendering 或 machine publication 的
-闭合。多个 output 都失败时，`RunResult.outputs` 保留每项 status；唯一 `output` diagnostic 依次选择 progress rendering、
-machine publication、diagnostic logging。diagnostic logging 不进入 machine v4；其 machine-field 排除见
-[机器输出契约](output.md)。Check final-data parser 只处理已经取得的单个 data object，不替代该契约。
+## RunResult 分支
 
-progress rendering 在 TTY 中维护 running region，在 plain output 与 `TERM=dumb` 中只追加 settled rows。`visibility: "attention"` 只隐藏无 messages 的 passed settled row，不改变 outcome、Records 或 machine output；accepted message 的 code 保留在 `RunResult.checkMessages`，终端只呈现 level 与正文。renderer failure 进入对应 output status，不改写已形成的 Check facts。
+输出的配置、日志目标、readback statuses 和 failure 优先级见[配置 Run 输出与诊断](guides/run-outputs.md#输出状态与失败处理)。本节说明调用方如何先判别 Run，再读取 Check facts。
 
 按 `RunResult.kind` 和 cancellation phase 读取结果：
 
@@ -200,6 +127,6 @@ progress rendering 在 TTY 中维护 running region，在 plain output 与 `TERM
 | `cancelled` / `phase: "pre-work"` 或 `"planning"` | invocation metadata 与 cancellation phase；按 phase 结束调用。 |
 | `configuration` | Definition、controls 或 aggregation selection diagnostic；project callback 执行数为零。 |
 | `planning` | task-graph diagnostic 与 invocation metadata。 |
-| `execution` | Product execution-settlement 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。 |
 
-Check `failed` 是已结算的业务 outcome；Run `execution` 是 invocation infrastructure diagnostic；Run `output` 是完整 Check facts 附带的 diagnostic logging、publication 或 rendering failure diagnostic。
+Check `failed` 是已结算的业务 outcome；Run `execution` 是 invocation infrastructure diagnostic；Run `output` 是完整 Check facts 附带的 output failure diagnostic。

package/docs/changelog.md

@@ -0,0 +1,157 @@
+# 变更日志
+
+本页随包提供版本变化与升级影响，按版本组织。
+
+## 0.0.2
+
+本节按主题记录 `@zxyycom/vibe-check` 的 `0.0.2` 相对 `0.0.1` 的净变化。
+升级影响随对应变更列出，提交记录集中在[相关提交](#相关提交)。
+
+正式发布后，在 Node `>=24.18` 环境安装精确版本并更新 lockfile；按所用能力完成调整后，
+运行项目 typecheck 和代表性 Run，复核 Check 终态、Finding/Records、aggregation 与诊断。
+
+### 产品变化
+
+#### 运行环境与包材料
+
+- **宿主改为 Node `>=24.18`**，取代 Bun `>=1.3.14`；仓库开发脚本和 Gate 继续使用 Bun。
+  集成入口保持为包根的程序化 API。
+- **补全包声明与发现信息**，调整导出类型命名。
+- **变更日志随包交付**，由 README 直接链接，便于按安装版本查阅变化与升级影响。
+- **增加运行依赖和来源材料**：引入 `@secretlint/core`、private-key rule 与 `immutable`；
+  `licenses/` 收录分析器翻译的 attribution、NOTICE、license 和 provenance。
+  根 `LICENSE` 保持 MIT，包 manifest 的 license expression 为 `MIT AND Apache-2.0 AND BSD-2-Clause`。
+
+#### 随包 Check
+
+- **新增 [`secretDetection`](./checks/secret-detection.md)** 与 `parseSecretDetectionData`：
+  在显式 `files` 范围内检测高置信 PEM private key，并提供结果数据、Records 和 waiver 类型。
+- **[`functionMetrics`](./checks/function-metrics.md) 内置 TypeScript 分析器**：
+  移除 `scanner` 配置及 Python/Lizard 运行前提，内部翻译基线更新到 Lizard 1.24。
+  新增 `nestingDepth`，默认 `maximum` 为 `7`；CCN Record 增加按源码顺序排列的
+  `complexityContributors: { token, line }[]`。升级时需复核新增 Finding 和 Record 结构。
+- **[`duplicateDetection`](./checks/duplicate-detection.md) 更新引擎并修复比较范围**：
+  包运行依赖 `jscpd` 从 `^5.0.11` 升至 `^5.1.1`；仓库开发依赖锁定 `5.1.1`。
+  修复项目相对路径输入漏报；重复 locations 必须共享至少一个 code area，跨区域比较需配置共同 area。
+- **[`fileMetrics`](./checks/file-metrics.md) 改用 SCC `4.0.0` 协议**：
+  环境需提供兼容的 `scc` 命令，Rust `?` 的复杂度计数随之调整。
+- **三个指标 Check 接入 Finding waiver**：`duplicateDetection`、`fileMetrics`、`functionMetrics`
+  增加可审计的 waiver 标识与配置，默认 `findingPolicy` 仍为 `non-blocking`。
+- **[`markdownLinkValidation`](./checks/markdown-link-validation.md#parse-facts-cache) 增加显式解析缓存**：
+  使用单文件 JSONL 保存 parse facts；每次运行仍重新形成 Check 结果。
+
+#### Check 依赖与选择
+
+- **区分成功前置和终态观测**：`dependsOn` 要求所有直接 provider 为 `passed`；否则 dependent
+  跳过回调，结算为 `unavailable / dependency-not-passed`。
+  新增 `observes`，供需要等待上游任意终态的汇总或审计使用。
+- **`preflight` 随所属 Check 准入执行**：由整次 Run 的全局 barrier 改为本 Check 的执行前阶段，
+  受依赖、互斥、容量和取消约束；独立 Check 的准备可以并发。
+- **新增 `enabledByFlags`**：支持 `all`、`any`、`none`、`not-all`。匹配的 root 显式设置
+  `propagateDependsOn: true` 时，传递选中其 `dependsOn` 前置，即使前置自身 flag 条件未命中；
+  省略时不传播，`observes` 不参与扩展。`checkAggregation.checks: "effective"` 聚合本次有效选择。
+- **新增 `dependencies.list()`**：返回冻结、稳定排序的直接 `dependsOn ∪ observes` 四态 observation；
+  `get()` 同样以该直接关系集合授权。
+
+用法见[自定义 Check](./guides/extending-check-lifecycle.md)与[依赖和类型化数据](./guides/check-dependencies.md)。
+
+#### 调度与观测
+
+- **声明资源与顺序偏好**：Check 增加 `resourceClaims`、`admissionPriority`，scheduler 增加
+  `resourceCapacities`；资源从 `preflight` 到 settlement 原子持有，priority 在合法 ready 候选中排序。
+- **自定义准入策略**：`scheduler.admissionPolicy` 支持 `custom/simple` 与调用级 `custom/prepared`
+  生命周期；`defineAdmissionPolicy` 辅助类型推导，策略可取得动作后性能 observation。
+- **终态测量 hook**：`scheduler.measurementHooks` 接收调度测量，状态从
+  `RunResult.outputs.measurementHooks` 读取。正常完成 Run 的 hook 失败可按输出失败优先级形成
+  `kind: "output"`、`scheduler-measurement-hooks-failed`；已有取消或执行诊断保持优先。
+- **独立模拟与本地历史策略**：`createAdmissionGraph` 构造不可变静态调度模拟；
+  `createLearnedCriticalPathStrategy` 将调用方管理的时长历史接入 prepared strategy。
+
+配置与边界见[调度指南](./guides/scheduling.md)。
+
+#### 输出与文件工具
+
+- **诊断日志分为 `core` / `scheduler` 两个 channel**：旧 `diagnosticLogging.file` 改为
+  `diagnosticLogging.channels.core.file` 与 `.scheduler.file`，各有独立 status。
+  `diagnosticLogFileNaming` 支持默认 `unique` 与固定 `channel`；固定名称冲突时失败，保留原文件。
+- **完善 progress 与 console 呈现**：捕获 Check 回调及其已等待异步工作中的 `console.*`，覆盖
+  `preflight` 并在 settlement 后呈现；直接 stdout/stderr、stream 或子进程输出独立于该捕获机制。
+  新增 `presentCheckFindings` 生成有界消息摘要，并增加 Record 预览。`progressRendering` 支持
+  formatter、条数和文本长度限制，配置错误定位到具体字段。
+- **提供调用级路径上下文**：新增 `invocationId`、Check 专属 `artifactDirectory`，以及 Controls 的
+  `checkArtifactBaseDirectory`、`progressLogFile`。machine 与 diagnostic 输出目录统一为可信目标：
+  相对路径从本次 `projectRoot` 解析，绝对路径直接使用；不提供路径沙箱或目录清理。
+- **新增 [`cacheJsonByKey`](./guides/cache-results.md)**：按调用方的 key、namespace/version、
+  目录、解析与计算函数缓存本地 JSON 结果，并返回读写状态；
+  并发协调和清理由调用方负责。
+- **新增 [`collectProjectFiles`](./guides/collecting-project-files.md)**：
+  按共享 selection 规则同步收集一次项目文件，返回冻结的相对路径快照。
+
+输出细节见[Run 输出与诊断](./guides/run-outputs.md)。`run.json` 与 `records.ndjson`
+继续采用 [v4 machine schema](./output.md)；上述 RunResult 和 Check Record 变化需分别复核。
+
+### 实现与仓库维护
+
+本节面向维护者，涵盖内部优化、Gate、包验收与协作工具。
+
+- **私有实现优化**：分析器 reader 采用 suffix fast path；admission core 采用不可变选择索引、
+  反向索引、计数器和持久 frontier，保持公开 DTO、顺序与回调契约。
+- **Gate 配置集中化**：统一 definition manifest，分离 checks/runtime，`afterGate` 归 definition
+  所有；命令收敛为 `bun run check`，提供默认 required、focused flags 与独占 `--all` 选择。
+- **Gate 选择与质量策略**：复用 flag 传递和 effective aggregation；仓库质量 Finding 设为 blocking。
+  root `maxParallel` 为 `3`，Bun test runners 与 repository scans 各最多并行 `2` 个。
+- **Gate 证据结构化**：调用目录按 owner 分配 artifacts、channel logs 和 machine 输出；
+  native diagnostics、lint/format failures 增加结构化 Records。
+- **强化包验收并复用 candidate**：增加 Node external consumer、实际引擎及安装依赖许可检查、
+  analyzer Worker/翻译材料验收；static release manifest 纳入 fingerprint。完整 Gate 复用已准备
+  candidate，物理生命周期验证改为显式 `package:candidate:integration`。
+- **增加显式研究与维护入口**：`source-mapping` 检查来源 ledger/identity/pin，`--sync` 更新派生 pin；
+  Lizard 性能命令提供 A/B/C 分层测量，`admission:simulate` 提供虚拟准入平台；
+  `maintenance:lizard-upstream` 提供非阻断的上游查询。
+- **重整文档与治理**：按读者、随包范围和规则 owner 组织阅读路径，更新 Change Plan、Decision Records、
+  Investigation Report 契约及索引；历史变更材料统一通过 Git 恢复。
+- **集中维护文档发布映射**：`docs/package-documents.json` 声明 Markdown、Check 指南和 machine 材料的
+  源文件与包内路径，构建、fingerprint 和包材料验收共同读取；包内链接检查覆盖 machine Markdown。
+- **明确发布工作区与交接**：项目分支采用无前缀语义名称，发布准备与冻结源码分别在实现和 detached
+  工作区进行；正式包验收、发布、版本标签与合回 main 按同一源码身份衔接。Package 文档按职责拆分。
+- **增加可选 post-commit hook**：显式设置 `core.hooksPath` 后，在 `main` 每小时至多尝试一次
+  non-force、no-tag 的 `origin/main` 推送；失败不阻断 commit。
+
+维护入口见[仓库维护文档](https://github.com/zxyycom/vibe-check/blob/c0af9fff429ea22602432b542f743af29f305fa4/docs/navigation.md#仓库工具与测试)。
+
+### 相关提交
+
+按变更主题在[源码仓库](https://github.com/zxyycom/vibe-check)检索提交；提交号用于定位实现变化。
+
+| 变更主题 | 提交 |
+| --- | --- |
+| Node 宿主 | `73a1d239`、`d765971a` |
+| 包声明与发现信息 | `80ff28e8` |
+| 运行依赖与来源材料 | `c239eab8`、`9ee0263e` |
+| `secretDetection` | `a9d53de8` |
+| `functionMetrics` | `0f317f2d`、`d356dcb4`、`e8f9ccb3`、`5ff3149e` |
+| `duplicateDetection` | `21b4d23a`、`741fefe0`、`113d6344` |
+| `fileMetrics` | `5bdda4db` |
+| Finding waiver | `8c6eddb0` |
+| Markdown 解析缓存 | `bf49676f`、`00c364b5` |
+| `dependsOn` / `observes` | `88160edd` |
+| `preflight` 时序 | `88160edd`、`da6ea93f` |
+| flags 与 effective aggregation | `8fdb840b`、`da6ea93f`、`fb695143` |
+| `dependencies.list()` | `7bcd56d4`、`88160edd` |
+| 资源容量与准入优先级 | `29438d69`、`4ee8ca30` |
+| 自定义准入策略 | `c9760932`、`80eec565`、`281e7711` |
+| 终态测量 hook | `2103c4e5` |
+| 调度模拟与本地历史策略 | `e83baa3e`、`822a1ef4` |
+| 诊断 channel | `c30eaa65`、`752b7e8f` |
+| progress / console / Finding 摘要 | `c30eaa65`、`5813738e`、`f2201ec1`、`47add411`、`92c6ec5d`、`eea8169b` |
+| 调用级路径与输出目录 | `a5f2d044`、`92c6ec5d`、`54336c4e` |
+| `cacheJsonByKey` | `72722d6f` |
+| `collectProjectFiles` | `bf3d6e79` |
+| reader 与 admission core 优化 | `dd9635d0`、`cea4d1db` |
+| Gate 配置 | `84c44124`、`1b11ccda`、`5ae74e6d` |
+| Gate 选择与质量策略 | `fb695143`、`c428530a`、`b30477b6` |
+| Gate 结构化诊断 | `a5f2d044`、`6afa910a`、`acade164` |
+| 包验收与 candidate 复用 | `73a1d239`、`21b4d23a`、`9ee0263e`、`c239eab8`、`6b19ec8f`、`fa4d45f5` |
+| 研究与维护入口 | `3ea6180c`、`e2bad655`、`f7e9f353`、`853b30ea` |
+| 文档与治理 | `94979fe1`、`7e76da8b`、`917517dc`、`761df044` |
+| post-commit hook | `d71f388c`、`931a0c12` |