@zxyycom/vibe-check 0.0.1 → 0.0.2

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 优先。来源不可用时不切换来源；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/extending-check-lifecycle.md

@@ -0,0 +1,112 @@
+# 编写会正确结算的自定义 Check
+
+本专题面向需要把项目规则接入 Vibe Check 的调用方：选择 `preflight` 或 `execution`，读取 callback 输入，返回可信终态，并在需要时发布补充事实。先能用一个普通 `execution` 完成规则；只有必须在执行前准备或验证 options 时才增加 `preflight`。一次 Run 的公共生命周期、输出优先级和完整结果模型见 [API 机制](../api-mechanics.md)。
+
+## 选择扩展点
+
+| 需求 | 使用方式 | 不要用它做什么 |
+| --- | --- | --- |
+| 规则可直接测量并结算 | `execution(context)` | 不要在 callback 外留下未等待的工作。 |
+| 执行前验证或把 authoring options 变成 invocation-local 的准备值 | `preflight(options, signal)` 后接 `execution(context)` | 它不是全局启动 hook；只在本 Check 已获准入后运行。 |
+| 保存不决定终态的逐项事实 | `context.records.report({ id }, data)` | Record 不能替代 `passed`、`failed`、`not-applicable` 或 `unavailable`。 |
+| 读取已声明上游结果 | `dependsOn` 或 `observes`，再从 `context.dependencies` 读取 | 不能读取未声明、传递或任意已运行的 Check。 |
+
+`defineCheck(...)` 定义的 object 是公开 authoring surface。`execution`、`preflight`、`parseData` 都是调用方实现的受信任回调。Product 只提供各自声明的输入；回调独立执行的 I/O 仍由调用方负责。
+
+## 定义 Check
+
+下例同时展示 options 验证、取消、Record、message 和 terminal data。例子的固定输入只为独立运行；接入项目时应以自己拥有的读取或测量逻辑替换它。
+
+```ts
+import { defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
+
+function hasValidLicensePolicyOptions(options: object): boolean {
+  const denied: unknown = Reflect.get(options, "denied");
+  return (
+    Object.keys(options).length === 1 &&
+    Object.hasOwn(options, "denied") &&
+    Array.isArray(denied) &&
+    denied.every((license) => typeof license === "string")
+  );
+}
+
+const licensePolicy = defineCheck({
+  checkId: "license-policy",
+  displayName: "License policy",
+  options: { denied: ["GPL-3.0-only"] },
+  preflight(options) {
+    return hasValidLicensePolicyOptions(options)
+      ? { status: "success", preparedOptions: options }
+      : { status: "failure", action: "block", reason: { code: "invalid-options" } };
+  },
+  visibility: "attention",
+  execution({ options, records, signal }) {
+    if (signal.aborted) return { status: "unavailable", reason: { code: "cancelled" } };
+
+    const deniedCount = options.denied.length;
+    if (deniedCount > 0) {
+      records.report({ id: "denied-license" }, { count: deniedCount });
+      return {
+        status: "failed",
+        data: { deniedCount },
+        messages: [{ level: "warning", code: "denied-license", message: "Denied licenses found." }]
+      };
+    }
+    return { status: "passed", data: { deniedCount: 0 } };
+  }
+});
+```
+
+## 按 flag 选择 Check
+
+`enabledByFlags` 只决定本次 Run 是否选择 executable Check；它不是权限、环境检测或 callback 内的条件替代。该字段的完整公开 grammar 是：
+
+```ts
+{
+  flags: ["token", ...],
+  mode: "all" | "any" | "none" | "not-all",
+  propagateDependsOn?: true
+}
+```
+
+`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`。
+
+只有字面量 `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 结算真正的环境条件。
+
+## `preflight`：准备、阻止或带 fallback 继续
+
+`preflight(options, signal)` 收到 authoring options 的深度只读视图和这次 Run 的同一取消 signal。authored 与 prepared options 同形时可省略 preflight；两种 shape 不同时，TypeScript 要求提供它。它只能返回以下三种结果（每种都可附有序 `messages`）：
+
+- `{ status: "success", preparedOptions }`：把准备后的 object 交给 `execution` 的 `context.options`。
+- `{ status: "failure", action: "block", reason }`：本 Check 使用该 reason 直接结算为 `unavailable`，不接受 `fallback`，不会运行 `execution`。
+- `{ 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 结算为本项不可用。
+
+## `execution` 可读取与可写入的内容
+
+`execution(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，但它们不证明环境或权限。 |
+| `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 文本保存事实。
+
+## 依赖与取消的实践
+
+必须取得上游成功 data 才能开始时，声明 `dependsOn`，并先检查 `dependencies.get(id).ok`；上游未提供 data 时返回 `unavailable`，而不是猜测空值。需要等上游无论何种终态都结算后再审计时，声明 `observes`，用 `dependencies.list()` 处理各项 outcome。需要恢复 provider 的业务类型时，调用 provider Check 的 `parseData`。完整示例和读取授权见[依赖数据指南](check-dependencies.md)。
+
+对 `fetch`、子进程或自有异步 API，把 `signal` 传下去；若已取消，尽快停止并返回 `unavailable`。Vibe Check 不会取消调用方没有连接 signal 的外部工作，也不替调用方回收文件、网络或子进程资源。
+
+## 下一步
+
+- 需要安排多个 Check、编写 admission policy、模拟假设分支或复用本地时长历史时，阅读[调度 Check](scheduling.md)。
+- 需要组合/继承 Check 或理解 dependency data、aggregation、machine outputs 的共同结果模型时，阅读[API 机制](../api-mechanics.md)。
+- 只需使用 package 提供的检查时，从 [README 的 Check 概览](../../README.md#随包提供的-check)进入对应指南。

package/docs/guides/finding-waivers.md

@@ -0,0 +1,45 @@
+# 对账 Finding waiver
+
+`reconcileFindingWaivers({ findings, identify, waivers })` 是 package 预提供的可选工具：当 custom Check 或其它 Finding
+producer 已形成**完整** Finding 候选集合，并需要保留原始证据地审计 waiver 时调用它。它不会按
+message 过滤、在扫描前排除输入或删除 Finding；采用方仍拥有 Records、messages 和 terminal outcome。
+
+## 最小用法
+
+```ts
+import { reconcileFindingWaivers } from "@zxyycom/vibe-check";
+
+const reconciled = reconcileFindingWaivers({
+  findings: [{ metric: "api-compatibility", symbol: "createClient" }],
+  identify: ({ metric, symbol }) => ({ metric, symbol }),
+  waivers: [
+    {
+      identity: { metric: "api-compatibility", symbol: "createClient" },
+      reason: "兼容窗口保留到下一个 major release。"
+    }
+  ]
+});
+```
+
+## identity 与 audit
+
+`identify(finding)` 对输入顺序中的每个原 finding 接收完整 finding。调用方自行选择稳定的语义
+identity，例如 path、function name 和 metric 的组合。`identify` 的结果与 `waiver.identity` 都必须可安全
+materialize 为 canonical JSON，helper 按 canonical JSON 的结构而非对象引用匹配。
+
+每项 waiver 的 identity 必须唯一且 reason 为非空 string。重复 canonical identity、无法 canonicalize 的
+finding 或 waiver identity、无效 reason，或 malformed / hostile waiver authoring 都抛出 `TypeError`。每个
+configured waiver 都在完整集合上获得 audit：`0` 次匹配是 `unused`，`1` 次是 `applied`，`>1` 次是
+`overmatched`；过宽 waiver 不会豁免任一 finding。
+
+输出 `findings` 保持输入顺序，并在每项结果中保留同一个原 finding reference。applied waiver 附带的 evidence
+是 detached、deep-frozen 的 canonical materialization，因此调用方之后修改 authored identity 或 reason 不会改变
+结果。helper 只返回 finding disposition 和 waiver audit；它不发布 Record、message 或 terminal outcome。
+
+## 随包 Check 的采用边界
+
+[`fileMetrics`](../checks/file-metrics.md)、[`functionMetrics`](../checks/function-metrics.md)、
+[`duplicateDetection`](../checks/duplicate-detection.md) 与 [`secretDetection`](../checks/secret-detection.md)
+提供原生 `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 发布，不能包含敏感材料。

package/docs/guides/learned-scheduling.md

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

package/docs/guides/presenting-findings.md

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

package/docs/guides/run-outputs.md

@@ -0,0 +1,145 @@
+# 配置 Run 输出与诊断
+
+需要调整终端显示、保存机器结果或排查一次 Run 时，先按目的选择输出，再配置本次覆盖、预览或日志目标。下文先说明常用配置，再说明如何读取输出状态和处理失败；Check facts 与 Run 分支的共同模型见 [API 机制](../api-mechanics.md#runresult-分支)。
+
+## 默认输出与本次覆盖
+
+`defineConfig` 默认启用 progress rendering 和 machine publication（目录 `artifacts/vibe-check`），关闭 diagnostic logging（默认目录 `.log/vibe-check`）。Definition 的 `outputs` 保存可复用默认值，RunControls 的 `outputs` 逐字段覆盖本次调用；省略或 `undefined` 不覆盖，`false`、数量 `0` 与 `formatter: null` 都有明确作用。即使关闭对应输出，提供的字段仍须通过 validation。参数归属见 [Definition 与 invocation](../api-mechanics.md#参数应该放在哪里)。
+
+## 常用配置
+
+先按目的选择字段。表中的 `outputs.*` 均可写入 Definition 作为默认值，也可写入 RunControls 只调整本次调用；其它字段只属于本次 Run。
+
+| 想做什么 | 设置什么 | 得到什么 |
+| --- | --- | --- |
+| 开关终端进度 | `outputs.progressRendering.enabled` | `true` 显示人读 lifecycle；`false` 关闭呈现，Check 仍正常执行与结算。 |
+| 调整每项明细数量 | `outputs.progressRendering.recordPreviewLimit`、`messagePreviewLimit` | 每个 settled row 默认分别最多显示 5 条；`0` 隐藏该类明细并保留省略数量。 |
+| 调整单条预览长度 | `outputs.progressRendering.textPreviewCodePointLimit` | 默认最多 240 个 Unicode code points；数值边界和 formatter 用法见下文。 |
+| 保存机器结果 | `outputs.machinePublication.enabled`、`directory` | terminal snapshot 形成后写入 machine files；稳定消费格式见[机器输出契约](../output.md)。 |
+| 开启排障日志 | `outputs.diagnosticLogging.enabled: true`，按需设置 `directory` | 为本次 Run 写入 core 与 scheduler 日志。 |
+| 保存终端进度副本 | RunControls 的 `progressLogFile` | 将相同的 terminal presentation 镜像到指定文件。 |
+| 在本次隔离目录中使用固定日志文件名 | RunControls 的 `diagnosticLogFileNaming: "channel"`，同时开启 diagnostic logging | 使用 `core.log`、`scheduler.log`；目录选择与冲突行为见[日志与输出目标](#日志与输出目标)。 |
+
+## Check messages 与受管 progress
+
+Check terminal `messages` 是有序的人读补充信息；consumer 仍按 outcome 处理 final data 和 Records。表中的两项 preview 数量必须为非负 safe integer，文本预算必须为正 safe integer；短预算时 `… [truncated]` 只保留放得下的 marker 前缀。accepted Records 与 final data 按各自的 `RunResult` / machine contract 保留，messages 保留在 `RunResult.checkMessages`；截断、formatter 或关闭呈现均不改写它们。
+
+在 callback 已等待的异步工作中通过全局 `console.*` 发出的文本，会作为该 Check 的 `console-<method>` messages 呈现。它适合短的人读诊断：不要向 console 写入 secret，也不要依赖 progress 文本保存完整事实。`process.stdout.write`、`process.stderr.write`、流式或 child-process 输出应写入 Check-owned file、transcript 或独立 logger；这些输出不具有可靠的 Check 归属，直接写入受管 terminal 也可能与 progress 交错。需要稳定补充说明时，在 terminal result 返回结构化 `messages`；从 Finding 生成有限摘要可用[呈现工具](presenting-findings.md)。
+
+### 配置 preview 文本
+
+需要在终端中保留长文本的前后片段时，把同步 `formatter` 写进 Definition。它接收冻结的 `{ kind, text, maxCodePoints }`：`kind` 是 `"record"` 或 `"message"`，`text` 是选中项未转义、未截断的默认正文（Record 为 local ID 加 canonical JSON，message 为正文），`maxCodePoints` 是当前文本预算。Product 仅对数量限制内的项调用一次，先 Records 后 messages；返回值仍由 Product 转义并限长。如下例把长文本折叠为头尾片段，并在本次 Run 单独缩小 Record 数量：
+
+```ts
+import {
+  defineCheck,
+  defineConfig,
+  run,
+  type ProgressPreviewFormatter
+} from "@zxyycom/vibe-check";
+
+const headAndTail: ProgressPreviewFormatter = ({ text, maxCodePoints }) => {
+  const points = [...text];
+  if (points.length <= maxCodePoints) return text;
+  const tailLength = Math.max(1, Math.floor(maxCodePoints / 3));
+  const headLength = Math.max(0, maxCodePoints - tailLength - 1);
+  return `${points.slice(0, headLength).join("")}…${points.slice(-tailLength).join("")}`;
+};
+
+const detail = defineCheck({
+  checkId: "detail",
+  displayName: "Detail",
+  execution: ({ records }) => {
+    records.report({ id: "long-detail" }, { text: "a verbose diagnostic value" });
+    return { status: "passed", data: {} };
+  }
+});
+
+const definition = defineConfig({
+  checks: [detail],
+  outputs: {
+    machinePublication: { enabled: false },
+    progressRendering: { formatter: headAndTail, textPreviewCodePointLimit: 48 }
+  }
+});
+
+const result = await run(definition, {
+  outputs: { progressRendering: { recordPreviewLimit: 1 } }
+});
+if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
+```
+
+文本预算只限制转义后的 preview 正文（含截断 marker），不包含缩进、label、换行、汇总或省略提示；Unicode code points 不等于终端列宽或 graphemes。
+
+formatter 返回空字符串仍是一条呈现项；throw 或返回非字符串（包括 Promise/thenable）只使 `outputs.progressRendering` failed，不回退默认文本，也不改变 Check/Record/message facts。它是 trusted project code：可见完整默认文本，不能把预算当成 redaction/access control，Product 不 sandbox 其独立 I/O 或 detached work。`formatter: null` 可在 RunControls 明确清除 Definition formatter；省略或 `undefined` 不覆盖。Definition 的数值与 formatter 种类参与 declarative fingerprint，但函数 identity/source/closure 以及 RunControls 覆盖均不参与。
+
+## 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。
+
+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。
+
+## 日志与输出目标
+
+machine publication 与 diagnostic logging 的 `directory` 都是调用方选择的非空、无 U+0000 的受信任 target：相对路径从 effective `projectRoot` 解析，绝对路径直接使用；它们不提供 containment 或 sandbox 语义。`progressLogFile` 使用相同的路径规则。
+
+diagnostic logging 为当前 invocation 写入人工诊断。它用于关联 Run、Check、phase 与 Scheduler 行为；日志不是 parser/schema、跨 invocation discovery 或 retention contract，也不替代 Check final data、Record 或 message。
+
+diagnostic 文件默认使用 `core-<utc-compact>-<uuid>.log` 与 `scheduler-<utc-compact>-<uuid>.log`。调用方已有隔离的 invocation 目录时，可以在 controls 同时设置 `diagnosticLogFileNaming: "channel"` 与 `outputs.diagnosticLogging: { enabled: true, directory: "<本次目录>" }`，得到 `core.log` 与 `scheduler.log`，不额外创建目录层级。Product 不保证该目录独占：每 channel 始终 exclusive-create，冲突即 failed，不覆盖、追加或退回唯一名；两个 channel 不是原子事务，一个失败时另一个仍可成功。从 channel `file` 读取实际目标；命名选项只控制文件名；日志内容保留 invocation ID、共享 sequence 与 elapsed-time correlation 信息。
+
+启用 diagnostic logging 时，scheduler channel 可给出本次 Run 的 `scheduler.summary`：它帮助解释 admission、等待、capacity 与 tail 的当前诊断投影。time 与 capacity 指标只描述 Scheduler 行为，不表示 CPU、memory、thread 或 process 的 OS utilization；需要 machine-readable 结论时，仍读取 machine output 和 Check facts。
+
+## 排查输出配置错误
+
+本次 `outputs` 覆盖值不合法时，Run 在执行 Check 或创建输出前返回 `kind: "configuration"`。
+先检查 `diagnostic.kind === "invalid-run-controls"`，再按 `path` 定位本次 controls 中的字段。
+`reason: "unknown-key"` 表示应删除或更正该字段名；`reason: "invalid-value"` 时，输出覆盖值诊断还提供
+`expected` 说明合法值要求。例如 `recordPreviewLimit: -1` 返回：
+
+```json
+{
+  "kind": "invalid-run-controls",
+  "path": "controls.outputs.progressRendering.recordPreviewLimit",
+  "reason": "invalid-value",
+  "expected": "non-negative-safe-integer"
+}
+```
+
+| `expected` | 合法值要求 |
+| --- | --- |
+| `plain-data-object` | 普通或 null-prototype 对象，只含可枚举的自有字符串 data properties；不能使用数组、accessor 或 symbol key。 |
+| `boolean` | `true` 或 `false`。 |
+| `function-or-null` | formatter 函数或 `null`；函数的同步返回要求见[preview 配置](#配置-preview-文本)。 |
+| `non-negative-safe-integer` | 大于等于 `0` 的安全整数。 |
+| `positive-safe-integer` | 大于 `0` 的安全整数。 |
+| `non-empty-string-without-nul` | 非空且不含 U+0000 的字符串；路径规则见[日志与输出目标](#日志与输出目标)。 |
+
+即使对应输出已关闭，显式提供的字段仍须合法。对象本身无法安全读取时，`path` 指向该对象，不尝试执行
+getter 来寻找更深字段。诊断不回显被拒绝的值；unknown key 诊断不提供 `expected`，其它 controls 诊断也可能
+省略它。Definition 的无效输出配置仍通过 `invalid-project-definition` 指向 `definition.outputs`。
+
+## 输出状态与失败处理
+
+只有 non-configuration `RunResult` 具有有效 output configuration 与 `outputs` readback。每项 status 使用 `"disabled" | "not-run" | "succeeded" | "failed"`。`RunResult.outputs.progressRendering` 返回 `{ enabled, status }`；预览文本、effective limits 与 formatter 由配置和呈现流程使用，不包含在返回值中。
+
+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` 可见。
+
+### 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 状态
+
+`scheduler.measurementHooks` 在 Definition 中配置，不能由 RunControls 注入或覆盖。终态观察交付给调用方配置的 generic Hooks 与 prepared strategy 的 public `complete`；调用顺序和 context 见[调度专题](scheduling.md#观察终态-measurement)。
+
+`outputs.measurementHooks` 的形状为 `{ enabled, status }`：
+
+| 条件 | `enabled` / `status` |
+| --- | --- |
+| normalized `scheduler.measurementHooks` 非空，或 successful prepared strategy 实际提供 `complete` | `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。 |