@zxyycom/vibe-check 0.0.1 → 0.0.3

package/docs/guides/cache-results.md

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

package/docs/guides/callbacks.md

@@ -0,0 +1,93 @@
+# 生命周期位置与函数契约
+
+本页用“逻辑位置 → 实际执行契约”定位 Vibe Check 的扩展点。逻辑位置只说明某项职责相对领域事实发生的阶段；实际执行契约才定义路径、输入、调用次数、顺序、控制权和失败。相邻时点不表示共享 Hook。
+
+状态标记为：**当前公开**（package API）、**当前 Project**（Project Gate 自有）、**当前内部**（运行时私有）、**相邻 Change**（已有 owner、尚未接线）或**逻辑保留**（没有当前消费者）。只有当前实际契约给出可调用路径和签名。
+
+## 当前时间线
+
+```text
+Definition / Controls validation
+→ effective flag selection
+→ static graph and admission-strategy preparation
+→ Scheduler admission
+  → admitted Check: prepare → execute → settle
+→ sealed Scheduler measurement
+  → internal summary → terminalEffects[] → prepared terminalEffect
+→ effective Check aggregation
+→ Run result and output closure
+→ Project Gate initial result → resultContributor → exit/transcript
+```
+
+早期取消、无效图和策略准备失败不会形成 sealed terminal measurement。Check `prepare` 只在该 Check 获准入后运行；它不是 invocation-wide hook。
+
+## Product Check
+
+| 逻辑位置 | 状态与路径 | 职责、顺序与失败 | owner |
+| --- | --- | --- | --- |
+| 单项 options 准备 | **当前公开**：`Definition.checks[].prepare`，`CheckPreparation` | admitted Check 至多一次、早于 `execute`；block、throw 或非法结果只将该 Check 结算为 unavailable。 | [自定义 Check](extending-check-lifecycle.md) |
+| 开始执行 | **当前内部**：`CheckExecutionLifecycle.started` | prepare 成功后、execute 前同步投影；不能控制结果。 | Product Run |
+| 领域执行 | **当前公开**：`Definition.checks[].execute` | 形成本 Check result、messages 与 Records。 | [自定义 Check](extending-check-lifecycle.md) |
+| 单项结算 | **当前内部**：`CheckExecutionLifecycle.settled` | Core 接受唯一终态事实后同步一次，覆盖 control、dependency、preparation、execution 和取消。 | Product result model |
+
+```ts
+const check = defineCheck({
+  checkId: "license-policy",
+  displayName: "License policy",
+  options: { denied: ["GPL-3.0-only"] },
+  prepare(options) {
+    return { status: "success", preparedOptions: options };
+  },
+  execute({ options }) {
+    return { status: "passed", data: { deniedCount: options.denied.length } };
+  }
+});
+```
+
+## Project / invocation
+
+| 逻辑位置 | 状态与路径 | 职责、顺序与失败 | owner |
+| --- | --- | --- | --- |
+| Project facts 准备 | **相邻 Change** | `add-project-change-flags` 拥有选择前 Project facts；本 Change 不建立 callback。 | Project Definition owner |
+| 有效选择完成 | **当前内部**：`InvocationLifecycle.selectionSettled()` | 所有 flag-control settlements 被接受后、Scheduler graph run 前一次；与逐 Check 生命周期分离。 | Project Run owner |
+| 批量有效输入准备 | **相邻 Change** | `batch-declared-project-file-inputs` 拥有选择后的输入屏障。 | Project Run owner |
+| 有效 Check 汇总 | **当前公开**：`RunControls.checkAggregation(checks)` | 完整结算后至多一次；接收只读、canonical-order 的有效 `CoreCheck[]`，必须同步返回四态。省略时 Product strict-all；throw、Promise 或非法返回直接拒绝 `run`，不是 `RunResult` hook。 | [API 机制](../api-mechanics.md#runcontrols-与-check-aggregation) |
+
+## Admission / Scheduler
+
+| 逻辑位置 | 状态与路径 | 职责、顺序与失败 | owner |
+| --- | --- | --- | --- |
+| 策略准备 | **当前公开**：prepared strategy `prepare(context)` | static graph 有效后至多一次，返回 `decide` 和可选 `terminalEffect`。 | [调度 Check](scheduling.md) |
+| 准入决策 | **当前公开**：simple/prepared `.decide(context)` | 每个 decision boundary 同步提出 select/wait；Scheduler 验证并转换状态。 | Scheduler |
+| accepted action 测量 | **当前内部**：private collector | accepted transition 后记录，下一次 decide 只读取冻结 prefix。 | Scheduler owner |
+| 终态摘要 | **当前内部**：summary participant | sealed context 后最先运行并自行 contain writer failure。 | Scheduler owner |
+| 终态作用 | **当前公开**：`scheduler.terminalEffects[]` | internal summary 后依声明顺序 await；任一失败不阻止后续作用。 | [调度 Check](scheduling.md) |
+| prepared 策略终态作用 | **当前公开**：prepared `terminalEffect` | public effects 后、sealed context 存在时至多一次；与数组共享 `outputs.terminalEffects`。 | Scheduler owner |
+| 必达资源释放 | **逻辑保留** | 没有当前公开消费者；terminalEffect 不是 `finally`。 | future Change |
+
+terminal effect 可读取冻结 `SchedulerMeasurementContext`，不能修改 Scheduler 或 Check 结果。任一公开或 prepared effect 失败会使 `outputs.terminalEffects` 为 failed；正常 completed Run 映射为 `kind: "output"` / `scheduler-terminal-effects-failed`，取消或其它 primary failure 保持原结果。
+
+## Run output
+
+| 逻辑位置 | 状态与路径 | 职责、顺序与失败 | owner |
+| --- | --- | --- | --- |
+| Check preview | **当前公开**：`outputs.progressRendering.formatter` | 只格式化受预算限制的显示文本。 | [Run outputs](run-outputs.md) |
+| terminal-effect readback | **当前公开**：`RunResult.outputs.terminalEffects` | 汇总 Definition effects 与 prepared effect；Controls 不能注入。 | Run output owner |
+| Run result handling / policy | **逻辑保留** | 调用方在 `await run(...)` 后自行处理；Product 未提供内部 policy hook。 | future Change |
+
+## Project Gate
+
+| 逻辑位置 | 状态与路径 | 职责、顺序与失败 | owner |
+| --- | --- | --- | --- |
+| Gate 结果贡献 | **当前 Project**：`PROJECT_GATE_RUN_CONFIG.resultContributor(context)` | exact candidate Run 形成 `initialResult` 后至多一次；只能返回已验证 message list。 | Project Gate |
+| Gate 结果决定 | **当前内部**：initial result → contribution → exit mapper | adapter 追加 messages、原样保留 initial status；throw 或非法列表为 unavailable。 | Project Gate owner |
+| transcript 完成 | **当前内部**：`ProjectGateTranscript.complete` | final result 与 exit 已确定后写入一次；失败 fail closed。 | Project Gate owner |
+
+`resultContributor` 不是 package API、插件系统或完整结果 transform。它能读 `initialResult`、selection、candidate、timing 与 Run facts，但不能重写 status。
+
+## 精确契约
+
+- Check authoring、取消、reason 和 callback context： [自定义 Check](extending-check-lifecycle.md)。
+- Definition validation、closed grammar 和 fingerprint：Project Definition owner（工作区维护材料）。
+- Scheduler measurement、策略及 output priority： [调度 Check](scheduling.md) 与 [Run outputs](run-outputs.md)。
+- Gate candidate binding、result contribution、exit 与 transcript：Project Gate owner（工作区维护材料）。

package/docs/guides/check-dependencies.md

@@ -0,0 +1,152 @@
+# 读取 Check 依赖与类型化数据
+
+需要把一项 Check 的结果交给另一项使用时，先声明 direct `dependsOn` 或 `observes`，再通过 dependency reader 读取上游结果，并用 provider parser 恢复业务类型。需要上游通过才开始时选择 `dependsOn`；需要审计任意终态时选择 `observes`。若同一次 Run 的 direct prerequisite 还必须交接不能 canonicalize 的 reference（例如 `Map` 或 typed bytes），provider 在 `defineCheck` 中声明 `handoff: true`，consumer 才能以 provider object 读取它。这些关系还约束 Scheduler 准入，调度预算见[调度 Check](scheduling.md)。
+
+## 先选择读取契约
+
+| consumer 要解决的问题 | provider 声明与 consumer 读取 | 不能获得的能力 |
+| --- | --- | --- |
+| 只需要已结算的 canonical final data，或需要审计任意终态 | 以 `dependsOn` 或 `observes` 声明 relation；使用 string `get(checkId)` 或 `list()` | 不保留原始 reference identity，也不能读取未声明或传递 provider。 |
+| 必须在同一次 Run 内交接不可 canonicalize 的 reference | provider 声明 `handoff: true`，在 `passed` 返回 `handoff`；consumer 将 provider 设为 direct `dependsOn` 并调用 `get(provider)` | 不授权 `observes`、string ID、传递 provider 或任何 Run 外读取；reference 不会发布。 |
+
+`handoff: true` 是唯一的 authoring declaration：它必须写在 `defineCheck(...)` 的 executable provider 上，不是数据、parser、serializer 或 author 创建的 token。Product 在 package-runtime 内部的 WeakMap 注册该 provider identity；identity 只连接已定义 provider、Definition 与 execution，不是 package API 或跨 package instance 的兼容协议。每次 Run 的 private store 才暂存已接受的 handoff reference。`handoff` 只可为 executable provider 的精确 `true`；container、其它值和自有 `undefined` 都会在 Definition validation 被拒绝。
+
+## 完整运行示例
+
+```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",
+  // `true` 是唯一的 runtime declaration；返回值的 handoff 类型由 execution 自动推断。
+  handoff: true,
+  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 };
+  },
+  execute() {
+    const bytesByPath = new Map<string, Uint8Array>([
+      ["src/index.ts", new TextEncoder().encode("export {}\n")]
+    ]);
+    return {
+      status: "passed",
+      data: { files: ["src/index.ts"], version: CHANGED_FILES_DATA_VERSION },
+      handoff: bytesByPath
+    };
+  }
+});
+
+const analyzeChangedFiles = defineCheck({
+  checkId: "analyze-changed-files",
+  displayName: "Analyze changed files",
+  dependsOn: [changedFiles.checkId],
+  execute({ dependencies }) {
+    const read = dependencies.get(changedFiles);
+    if (!read.ok) return { status: "unavailable", reason: { code: read.error.code } };
+
+    // canonical data 仍在 parser 边界；handoff 保留 same-Run reference identity。
+    const data = changedFiles.parseData(read.data);
+    const firstFile = data.files[0];
+    const firstFileBytes = firstFile === undefined ? undefined : read.handoff.get(firstFile);
+    if (firstFileBytes === undefined) {
+      return { status: "unavailable", reason: { code: "changed-file-bytes-unavailable" } };
+    }
+    return {
+      status: "passed",
+      data: { analyzedByteCount: firstFileBytes.byteLength, 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}`);
+```
+
+上例的 `handoff: true` 是 provider 的最小 runtime declaration；`passed` result 中的 `Map<string, Uint8Array>` 自动成为 provider-aware read 的 handoff 类型。provider 只能在 `passed` branch 返回同型、non-null 的 `handoff`；`dependencies.get(changedFiles)` 只在 current Run 中由 direct `dependsOn` consumer 成功，返回 provider 的 canonical `data` 和同一 `Map` reference。fan-out consumer 读取的也是这个引用，而 repeated Run 不共享它。
+
+先收窄 `get` 的 `ok`，再显式调用 producer 的 `parseData(read.data)`：parser 继续只负责 detached、deep-frozen canonical data，绝不解析或 clone `handoff`。`dependsOn` 保证 callback 只在 provider `passed` 后开始；`!read.ok` 仍是读取边界防御。九个随包 Check 都提供 `parseData` 和同实现的 package-root parser，名称与类型见各自指南。
+
+provider-object read 的失败不返回上游 `data` 或 `handoff`：输入不是 `handoff: true` 定义的 provider，或不是 effective direct `dependsOn` 时，错误为 `dependency-not-declared`；已获 direct authorization 但本次 execution 没有接受到该 provider 的 `passed` handoff 时，错误为 `upstream-handoff-unavailable`。consumer 必须像示例一样先处理 `!read.ok`，不能把 TypeScript 推断当作运行时授权。
+
+handoff 保留 identity，因此 Product 不会 freeze、clone、serialize、缓存或验证其领域含义。producer 与所有 consumer 必须把它作为 immutable observation：上例不调用 `Map#set`，也不改写其中的 `Uint8Array`。execution graph 结束时 Product 清空自己的 private-store reference；该 `clear()` **不是** disposer，不会调用 `close`、`dispose` 或任意 symbol hook。真实资源的创建者/调用方必须以显式 graph ordering、consumer `try/finally` 或 Run 外层 lifecycle 在最后一个 consumer 后清理，不能依赖 handoff store、GC 或 machine/diagnostic publication。
+
+## 批量审计 direct outcomes
+
+审计任意终态时声明 `observes`，再用 `dependencies.list()` 读取 direct union 的冻结 `{ checkId, outcome }[]`。四态 outcome 都是正常可观察事实；以下 Check 从中形成自己的结果，而不修改 producer：
+
+```ts
+const auditChangedFiles = defineCheck({
+  checkId: "audit-changed-files",
+  displayName: "Audit changed files",
+  observes: [changedFiles.checkId, analyzeChangedFiles.checkId],
+  execute({ dependencies }) {
+    const observations = dependencies.list();
+    const readable = observations.filter(
+      ({ outcome }) =>
+        outcome.status === "passed" || outcome.status === "failed",
+    );
+    const changedFilesObservation = readable.find(
+      ({ checkId }) => checkId === changedFiles.checkId,
+    );
+    if (changedFilesObservation === undefined) {
+      return {
+        status: "unavailable",
+        reason: { code: "changed-files-data-unavailable" },
+      };
+    }
+
+    const data = changedFiles.parseData(changedFilesObservation.outcome.data);
+    return {
+      status: "passed",
+      data: {
+        directDependencyCount: observations.length,
+        changedFileCount: data.files.length,
+      },
+    };
+  },
+});
+```
+
+读取 `passed` / `failed` data 后仍需调用 producer parser；其余状态保留原 reason。consumer 可据此形成 summary、I/O、Records、messages 与自身终态，但不能修改、取消、重跑或重结算 producer。
+
+## Provider 类型与解析边界
+
+通过 `defineCheck({ execute, parseData })` 建立 typed provider：同步 parser 的返回类型同时约束该 Check 的 `passed` / `failed` data，返回值保留必需的 `parseData`。普通递归 `Check` 类型本身不声明 parser；仅写 `satisfies Check` 或 inline `defineConfig` 不建立该类型关系。没有 parser 的普通 Check 仍合法，container 则不能声明 parser。
+
+TypeScript 拒绝 async 或返回 `PromiseLike` 的 parser，即使推断结果类型很宽。canonical JSON 中非 callable 的 `then` 字段仍是普通数据。JavaScript 或显式 cast author object 上的 function parser 可以通过 runtime Definition validation，但不会因此取得 TypeScript 关系；自有 `parseData: undefined` 规范化为省略。
+
+parser 接收 Check-facts-owned 的 detached、deep-frozen canonical object，而不是原始 author object 或 JSON 文本。provider 拥有 shape、版本、业务不变量与抛错策略；Product 不自动调用 parser，也不另建 parser-rejection result。consumer 在自己的 execution 中调用 parser 时，未捕获的抛错沿用 Check execution 的失败边界。
+
+同版本可信 provider 若已有测试保证 shape，可以把 parser 用作 identity/type anchor；这不是对 JavaScript、cast、跨版本 artifact 或不可信输入的运行时验证。此类输入应由 provider 显式验证。每个随包 Check 的同名 `parseData` 与 package-root parser 只解析单个 final-data object，不替代 [machine publication/schema 验证](../output.md)。
+
+## Direct relation 与读取规则
+
+- `dependsOn` 与 `observes` 命名同一 Definition 中的 executable Check。两者各自可继承父 collection；精确数组完整替换（`[]` 清空），`inherit({ add, remove })` 显式增删后去重。一个 provider 不得同时出现在两类 relation 中。
+- `dependsOn` 等所有 direct provider 通过才允许本 Check 的 preparation/execution；任一 provider 非 `passed` 时，本 Check 在 author work 前成为 `unavailable / dependency-not-passed`，reason 带 direct blocker `checkIds`，duration 为 `null`。`observes` 只等待终态，不要求通过。
+- `get(checkId)` 是 non-generic string read，只授权 normalized effective `dependsOn ∪ observes` 的 direct ID（包括各自继承项）。未声明、传递或 malformed ID 返回不泄露 upstream fact 的 `dependency-not-declared`。
+- `get(provider)` 是 provider-aware read，只接受以 `handoff: true` 定义的 provider object，并且只授权 normalized effective direct `dependsOn`。成功时固定为该 provider literal `checkId`、`status: "passed"`、canonical `data` 与 typed `handoff`；direct `observes`、transitive、未声明、lookalike provider 或本次未接受 handoff 都 fail closed，不泄露 upstream data/reference。它不改变 string `get(checkId)` 或 `list()` 的授权、shape 与四态 observation。
+- 已声明 provider 的 `passed` / `failed` 返回 `ok: true`、status 与 canonical data；`not-applicable` / `unavailable` 返回 `ok: false`、该 status 与 `upstream-data-unavailable`。TypeScript 类型本身不授予访问权。
+- `list()` 无参返回同一 direct union 的完整四态 observations，按 normalized effective direct ID 稳定排序并去重；数组、每项与 Core-owned outcome 都冻结。不读取传递、未声明或 ambient executed Checks，也不提供 Records、scheduler timing 或全局历史。

package/docs/guides/collecting-project-files.md

@@ -0,0 +1,59 @@
+# 选择与收集项目文件
+
+本文说明随包 Check 共用的文件选择规则，以及独立收集 path 的工具。只配置现有 Check 时，直接阅读[共享的 files 选择语义](#共享的-files-选择语义)；需要自行取得文件列表时使用下方工具。
+
+`collectProjectFiles(...)` 是 package root 的同步工具，供普通项目脚本或自定义 Check 按 Vibe Check 的显式文件选择规则取得**一份**项目文件 path 快照。它只收集 path；调用方仍拥有 Check eligibility、内容读取、安全边界、Finding、Record 和终态结算。
+
+## 最小用法
+
+```ts
+import { collectProjectFiles, defaultProjectFileSelection } from "@zxyycom/vibe-check";
+
+const selectedPaths = collectProjectFiles({
+  projectRoot: ".",
+  selection: {
+    ...defaultProjectFileSelection,
+    exclude: [...defaultProjectFileSelection.exclude, "**/fixtures/**"],
+    include: ["src/**/*.ts"]
+  }
+});
+
+if (!Object.isFrozen(selectedPaths)) {
+  throw new Error("Expected an immutable project-file snapshot");
+}
+```
+
+## 共享的 files 选择语义
+
+需要选择项目文件的随包 Check 使用 `{ source, include, exclude }`：`source` 明确选择 `filesystem` 或 `git-worktree`，include/exclude 使用 project-root-relative、`/` 分隔的 minimatch glob，点号开头的路径也参与匹配，exclude 优先。Project change regions 复用同一 include/exclude matcher，但只对 Git 已得出的 changed-path candidates 匹配，不重新枚举 project files。来源不可用时不切换来源；Check 将它结算为 `unavailable`，下方独立工具则同步 throw。
+
+`defaultProjectFileSelection` 是深冻结、可组合的基线，不是全局配置。它排除常见 VCS/Product state、dependencies、build/generated、cache、coverage、log、temporary 与 virtual-environment paths。`duplicateDetection`、`fileMetrics` 与 `jsonSchemaValidation` 原样采用该基线；`functionMetrics`、`jsonValidation` 与 `markdownLinkValidation` 保留 source/exclude，按支持文件类型派生默认 include。`secretDetection` 要求显式完整 selection。精确默认列表可从导出值读取，各 Check 的实际默认与 eligibility 见其指南。
+
+Check constructor 接受省略字段时，由 owning Check 物化默认值；显式 `include` / `exclude` 数组完整替换相应默认值，`include: []` 不选择路径，`exclude: []` 不排除路径。需要追加排除时像上例一样 spread；多个 Check 共享范围时显式复用 TypeScript value。各 Check 的 area policy、accepted/rejected input 与内容安全边界仍各自独立。
+
+## 工具输入、来源与结果
+
+每次调用都必须给出 `projectRoot` 与完整 `selection: { source, include, exclude }`：
+
+| 输入                | 要求与作用                                                                                                                                |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `projectRoot`       | 非空且不含 U+0000 的路径；相对路径从调用时的工作目录解析，绝对路径直接使用。示例的 `"."` 是调用方显式选择当前目录，并非省略字段的默认值。 |
+| `selection.source`  | 只能是 `"filesystem"` 或 `"git-worktree"`，决定候选路径来源。                                                                             |
+| `selection.include` | 无空洞的字符串数组，每项是相对 root、使用 `/` 的 glob；路径至少命中一项才被选中，`[]` 不选择任何路径。                                    |
+| `selection.exclude` | 同样是无空洞的字符串数组；命中任一 glob 就排除，`[]` 不增加排除条件。排除优先于包含。                                                     |
+
+这些对象只接受列出的自有数据字段，不接受额外字段或 getter/setter；数组也不接受额外属性或 accessor 元素。工具不在遗漏 root 时替调用方选择目录；显式 root 不是路径隔离、文件系统沙箱或文件内容可读性的承诺。
+
+本工具不物化 `ProjectFileSelectionOptions` 的省略字段；要使用基线，像示例一样显式 spread `defaultProjectFileSelection`。匹配和替换规则见上节。
+
+返回值是相对解析后 root、使用 `/`、按稳定文本顺序排序并去重的冻结数组。没有匹配 path 时，返回冻结的空数组；返回后文件是否仍存在、是否可读或内容是否变化不在此工具承诺范围内。它不会读取文件内容，也不与 Check 或其它调用共享原子快照。
+
+`filesystem` 递归枚举 root 下普通文件，不跟随符号链接，也不解释 `.gitignore`。
+
+`git-worktree` 使用 Git 已跟踪文件和未被 Git 标准忽略规则排除的未跟踪文件。已初始化且确为独立 Git worktree 的 submodule 当前文件也会加入，并返回相对本次 project root 的路径；gitlink 目录本身不是文件候选。两种来源都在候选收集后应用上述 glob 选择；即使 `include: []`，来源不可用仍是失败，不会被当作成功空结果。
+
+## 失败与调用边界
+
+options、root 或完整 selection 不合法时，调用同步抛出 `TypeError`；例如缺失/多余字段、accessor value、非法 source、非 string glob、空 root 或含 U+0000 的 root 都不被接受。选定 filesystem 无法遍历或 Git source 不可用时，同步抛出带失败路径或 Git 来源上下文的普通 `Error`；工具绝不改用另一来源或把失败伪装成空数组。
+
+每次同步收集一份完整 selection，不接受 `AbortSignal`，不支持中途取消。需要处理多份 selection 时分别调用，并由调用方决定合并语义；内容读取与检查结果仍由调用方负责。

package/docs/guides/command-check.md

@@ -0,0 +1,155 @@
+# 执行外部命令的 Check
+
+`commandCheck(...)` 将一个单一、无 shell 的外部 command 接入 ordinary Check lifecycle。Product 负责进程启动、协作取消、超时、受限输出捕获和默认终态；调用方可在 spawn 前解析本次 environment，并在完整命令结果上完成领域结算。
+
+默认模式适合 exit status 已足够表达检查结果的工具。需要将完整 command 的 stdout/stderr 转为领域 data、Records 或 typed provider 时，使用 `afterCommand`；工具协议、参数语义、解析规则和保存的业务数据始终由调用方拥有。
+
+## 最小用法
+
+下例以当前 Node executable 构造一个通过的 Check。`process.execPath` 是绝对 executable path，不依赖 shell 或 `PATH`；省略的 environment 使用 exact-empty，output 使用 discard。
+
+```ts
+import { commandCheck, defineConfig, run } from "@zxyycom/vibe-check";
+
+const nodeProbe = commandCheck({
+  checkId: "node-probe",
+  displayName: "Node probe",
+  executable: process.execPath,
+  arguments: ["--eval", "process.exit(0)"],
+  timeoutMs: 5_000,
+  outputByteLimit: 64 * 1024
+});
+
+const definition = defineConfig({
+  checks: [nodeProbe],
+  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 === nodeProbe.checkId
+)?.outcome;
+if (outcome?.status !== "passed" || outcome.data.exitCode !== 0) {
+  throw new Error("Node probe did not produce the expected passed outcome");
+}
+```
+
+## 输入与 ordinary Check 组合
+
+`commandCheck<Id>(input)` 返回 ordinary Check，且 `checkId` 保留调用方的 literal type。`checkId`、`displayName`、`executable`、`timeoutMs` 与 `outputByteLimit` 必填；constructor 对 closed input policy 做 runtime validation，非法 input 抛出 `TypeError`。preparation 再次无法验证 options 时，该 Check 结算为 `unavailable / invalid-options`。
+
+它还接受 ordinary authoring 的 `enabledByFlags`、`checks`、`dependsOn`、`observes`、`maxParallel`、`admissionPriority`、`mutex`、`resourceClaims` 与 `omitQuietPassedRow`。选择、依赖和调度语义由[自定义 Check](extending-check-lifecycle.md)与[调度 Check](scheduling.md)拥有。
+
+| 字段 | 要求与默认值 |
+| --- | --- |
+| `executable` | 必填：非空且不含 NUL 的 executable；可为绝对 path 或由平台在最终 environment 中解析的名称。 |
+| `arguments` | 可选，默认 `[]`：dense readonly string array；元素可为空但不得含 NUL，每个元素作为独立 argv 传递。 |
+| `workingDirectory` | 可选，默认 project root：非空且不含 NUL；relative path 从 project root 解析，absolute path 保持原 target。 |
+| `environment` | 可选，默认 `{ mode: "exact" }`。它与 `resolveEnvironment` 互斥，见[环境](#环境)。 |
+| `resolveEnvironment` | 可选：在 spawn 前为本次 invocation 返回 closed environment policy，见[环境](#环境)。 |
+| `timeoutMs` | 必填：正安全整数，限定一次 command execution。 |
+| `outputByteLimit` | 必填：正安全整数，stdout 和 stderr 各自的 byte ceiling。 |
+| `output` | 可选，默认 `{ mode: "discard" }`。见[输出](#输出)。 |
+| `afterCommand` | 可选：完整 numeric-exit command 的 caller-owned completion，见[调用方完成阶段](#调用方完成阶段)。 |
+
+command 由 executable 和独立 arguments 表示，不是 shell string、pipeline 或 workflow。
+
+## 环境
+
+环境是 closed policy。静态 `environment` 与 invocation-time `resolveEnvironment` 互斥；两者都省略时，child 使用 exact-empty environment。
+
+| policy | child base environment |
+| --- | --- |
+| `{ mode: "exact", variables? }` | 只使用 `variables` 中的 `Record<string, string>`；省略 variables 即 exact-empty。 |
+| `{ mode: "inherit", overrides? }` | execution start snapshot `process.env`；string override 覆盖 key，`null` 删除 key。 |
+
+这张 policy 只确定 caller base environment。Product 在它之后加入固定 plain-text/no-color variables：`CARGO_TERM_COLOR=never`、`CLICOLOR=0`、`CLICOLOR_FORCE=0`、`FORCE_COLOR=0`、`NO_COLOR=1`、`PNPM_CONFIG_COLOR=false`、`PY_COLORS=0`、`TERM=dumb`、`UV_NO_COLOR=1` 与 `npm_config_color=false`。这些 keys 最后覆盖静态 policy 或 resolver 返回 policy 中的同名 value；不能通过此 API 请求 colorized child output。
+
+`resolveEnvironment(context)` 在 spawn 前接收 `project`、direct `dependencies`、prepared command `options` 和取消 `signal`，并返回（或 resolve 为）同一张 policy 表中的值。其返回值同样先作为 caller base environment，再由 Product 加入上述固定 keys。它适合把当前 project 或已声明依赖转换为本次 command 的最小环境：
+
+```ts
+const projectCommand = commandCheck({
+  checkId: "project-command",
+  displayName: "Project command",
+  executable: process.execPath,
+  arguments: ["--eval", "process.exit(0)"],
+  resolveEnvironment: ({ project }) => ({
+    mode: "exact",
+    variables: { PROJECT_ROOT: project.root }
+  }),
+  timeoutMs: 5_000,
+  outputByteLimit: 64 * 1024
+});
+```
+
+resolver throw 或返回非法 policy 时，不启动 child，Check 结算为 `unavailable / command-environment-resolution-failed`。environment names、values 与 policy object 拒绝 unknown fields、accessor/prototype tricks、`undefined`、非 string 值及 NUL；resolved environment 不会自动进入 Check facts、messages 或 diagnostics。
+
+## 输出
+
+`output` 只选择 child material 的处理边界，不改变默认 terminal mapping。
+
+| policy | 行为 |
+| --- | --- |
+| `{ mode: "discard" }` | 默认。Product 在受 `outputByteLimit` 约束的 invocation memory 中捕获 stdout/stderr，并在结算后释放；它不自动发布 child material。 |
+| `{ mode: "transcript" }` | Product 将 running state 与 final status metadata、raw stdout、raw stderr 原子写入此 Check artifact directory 的固定 `process.log`。 |
+
+transcript 是显式 opt-in artifact capability。没有 `artifactDirectory`，或 running/final write 失败时，Check 为 `unavailable / command-transcript-unavailable`。`process.log` 不包含 executable、arguments、environment 或 native error text。
+
+## 调用方完成阶段
+
+`afterCommand` 把完成 callback 与可选 typed-provider parser 放在同一个对象：
+
+```ts
+const reportCommand = commandCheck({
+  checkId: "report-command",
+  displayName: "Report command",
+  executable: process.execPath,
+  arguments: ["--eval", 'process.stdout.write("report")'],
+  timeoutMs: 5_000,
+  outputByteLimit: 64 * 1024,
+  afterCommand: {
+    execute: ({ command, records }) => {
+      records.report({ id: "report-command" }, { stdoutLength: command.stdout.length });
+      return { status: "passed", data: { report: command.stdout } };
+    },
+    parseData: (data) => {
+      if (typeof data.report !== "string") throw new TypeError("report must be a string");
+      return { report: data.report };
+    }
+  }
+});
+```
+
+Product 只在 child 具有 numeric exit，且未取消、未 timeout、未达到 output limit、未被 signal 终止时调用 `afterCommand.execute`。若选择 transcript，final write 也必须先成功。callback context 是 ordinary `CheckExecutionContext` 加上 invocation-local `command: { exitCode, stdout, stderr }`；它可以返回普通 `CheckResult` 并按 ordinary Check contract 报告 Records。这个返回值取代完整命令的默认 exit-code mapping。
+
+存在 `parseData` 时，返回值是 typed provider Check，parser 负责验证 callback 返回的 data；没有 parser 时，返回值仍是 ordinary Check。`stdout`、`stderr` 仅在 callback context 中提供，不会因 callback 存在而自动发布。调用方决定是否把派生数据或 Records 放入自己的结果边界，并负责其中的敏感信息处理。
+
+## 默认终态与失败边界
+
+未使用 `afterCommand` 时，完整 numeric exit 的 `passed` 和 `failed` 返回 `CommandCheckFinalData` 的 `{ exitCode: number }`；command-owned unavailable 分支使用 `CommandCheckUnavailableReasonCode`。
+
+| process cause | 默认 Check terminal outcome |
+| --- | --- |
+| exit code `0` | `passed / { exitCode: 0 }` |
+| numeric nonzero exit | `failed / { exitCode }` |
+| startup failure | `unavailable / command-start-failed` |
+| resolver throw 或非法 policy | `unavailable / command-environment-resolution-failed` |
+| timeout | `unavailable / command-timeout` |
+| stdout 或 stderr 达到 byte limit | `unavailable / command-output-limit-exceeded` |
+| 非 timeout、非 cancellation signal | `unavailable / command-terminated-by-signal` |
+| transcript capability 或 write failure | `unavailable / command-transcript-unavailable` |
+| 无法验证 prepared options | `unavailable / invalid-options` |
+| Core 观察到 caller cancellation | `unavailable / execution-cancelled` |
+
+同时出现多个底层终态标记时，Product 以 **nonzero exit → cancellation → timeout → max-buffer → signal → startup failure → zero exit** 的顺序选择默认 cause。只有完整 numeric exit 才能进入 `afterCommand`；其它分支保留 Product-owned mapping。callback 自身的 throw 或 settlement 继续由 ordinary Check/Core lifecycle 处理。
+
+## 安全边界与公开类型
+
+默认 exact-empty environment 与 discard output 避免 ambient credential 和 child material 自动进入结果或日志。选择 `inherit`、`transcript` 或在 `afterCommand` 发布派生数据时，调用方负责对应 environment、artifact 和结果边界的访问控制、保留和清理。
+
+package root 提供 `commandCheck` 及 `CommandCheckInput`、`CommandCheck`、`CommandCheckWithAfterCommand`、`TypedCommandCheck`、`CommandCheckEnvironment`、`CommandEnvironmentContext`、`CommandEnvironmentResolver`、`AfterCommand`、`AfterCommandContext`、`AfterCommandExecution`、`CompletedCommand`、`CommandCheckOutput`、`CommandCheckFinalData` 与 `CommandCheckUnavailableReasonCode`；精确签名见安装包 declarations。它不提供 shell、pipeline、workflow 或 process-exit adapter，也不保证平台解析的 command 存在。