@zxyycom/vibe-check 0.0.1 → 0.0.2

package/docs/checks/duplicate-detection.md

@@ -1,25 +1,41 @@
 # `duplicateDetection`
 
-返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
-
 ## 用途
 
-本页是 package consumer 配置和读取 `duplicateDetection` 的主指南。`duplicateDetection(options?)` 使用带默认值的
-policy 构造一个普通 `duplicate-detection` Check。该 Check 用 jscpd 比较自己批准的项目文件，把满足行数与 token
-policy 的重复片段报告为 supplemental Records，并分别报告 finding 总数与 blocking finding 数量。
+`duplicateDetection(options?)` 构造 `duplicate-detection` Check，用 jscpd 报告满足行数/token 策略的重复片段。
+它发布完整 Finding Records，并分别统计总数与 blocking 数量；waiver 不缩小 scanner 输入或 cache evidence。
+
+默认使用随 package 安装的 jscpd v5（manifest 范围 `^5.1.1`），无需另配 executable。
 
-默认 package command 使用随 `@zxyycom/vibe-check` 安装的 jscpd v5；项目无需选择版本、提供 executable 或复制默认 options：
+## 最小用法
+
+示例保留终端进度，不写 machine files。
 
 ```ts
-import { duplicateDetection } from "@zxyycom/vibe-check";
+import { defineConfig, duplicateDetection, run } from "@zxyycom/vibe-check";
 
-const check = duplicateDetection();
+const check = duplicateDetection({ findingPolicy: "blocking" });
+const result = await run(defineConfig({
+  checks: [check],
+  outputs: { machinePublication: { enabled: false } }
+}));
+const outcome = result.kind === "completed"
+  ? result.snapshot.checks.find(({ checkId }) => checkId === check.checkId)?.outcome
+  : undefined;
+if (result.kind !== "completed" || outcome?.status !== "passed") {
+  console.error(`Duplicate detection did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
 ```
 
+示例显式使用 `findingPolicy: "blocking"`，让未豁免的普通 Finding 导致失败；默认 `non-blocking` 只警告，不因 Finding 退出非零。
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
+显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
+
 ## 参数与默认配置
 
-顶层 `cache`、`codeAreas`、`findingPolicy` 与 `scanner` 都可省略；显式 `codeAreas[areaId]` 只要求提供
-`files` branch。无参调用物化成以下完整 Check options，调用方无需复制：
+顶层 options 都可省略；显式 area 必须提供 `files`。无参调用物化以下完整 options：
 
 ```ts
 {
@@ -32,22 +48,25 @@ const check = duplicateDetection();
       minimumTokens: 100
     }
   },
+  findingWaivers: [],
   scanner: {
     command: { kind: "package" }
   }
 }
 ```
 
-这里的 `defaultProjectFileSelection` 是从 package root 公开的深冻结完整基线；constructor 会把同值 files branch 物化到
-自己的 resolved options，调用方无需复制该对象；完整默认 glob 可直接从该 public value 读取。
+`defaultProjectFileSelection` 是 package root 公开的深冻结默认选择；constructor 会物化同值 files branch，无须手工复制。
 
 - 省略整个 `codeAreas` 时建立默认 `project` area。显式 map 必须至少包含一个非空 area id。
-- 每个显式 area 必须提供 `files` branch。`source` 只能是 `"filesystem" | "git-worktree"`，默认 `filesystem`。
-  `filesystem` 枚举普通文件且不解释 `.gitignore`；`git-worktree` 使用已跟踪文件和未被 Git 标准忽略规则排除的
-  未跟踪文件。来源不可用时 Check 结算为 `unavailable`，不会切换到另一来源。
-- `include` 与 `exclude` 都按 project-root-relative slash path 的 glob 匹配，exclude 优先。两者可分别省略并使用公开的
-  `defaultProjectFileSelection`；显式数组是完整替换值，`include: []` 不选择路径，`exclude: []` 不排除路径。
+- 每个显式 area 必须提供 `files` branch。共同 `{ source, include, exclude }` grammar、source failure 和数组替换见
+  [共享的 files 选择语义](../guides/collecting-project-files.md#共享的-files-选择语义)；本 Check 的 branch fields 可分别省略并使用公开的
+  `defaultProjectFileSelection`。
 - 顶层 `findingPolicy` 只能是 `"blocking" | "non-blocking"`，默认 `non-blocking`；area 可覆盖，省略时继承顶层值。
+- `findingWaivers` 省略时为 `[]`，并采用[共同 waiver authoring 与 audit](../guides/finding-waivers.md#identity-与-audit)。identity
+  恰为 `{ metric: "duplicate-tokens", locations }`；`locations` 至少两项，必须逐项复制 Finding Record 中的完整
+  `{ path, startLine, endLine }`。数组先按 path 文本升序，再按 `startLine`、`endLine` 数值升序严格排序。path 是 normalized
+  project-root-relative slash path，line 是正安全整数且
+  `endLine >= startLine`；缺失、重复或乱序 location 都会被拒绝。
 - `minimumLines` 与 `minimumTokens` 可省略并分别使用 `4` 和 `100`，显式值必须是正安全整数。
 - `cache.directory` 省略时为 `.cache/vibe-check`，相对路径从 project root 解析；`cache.enabled` 省略时为 `true`。
 - `scanner.command` 省略时为 `{ kind: "package" }`。
@@ -56,8 +75,7 @@ const check = duplicateDetection();
 
 ## 定制区域 policy
 
-调用方只声明要改变的 policy，不需要读取默认 Check。下面两个 area 各自拥有文件范围和阈值；省略的 file fields、
-finding policy 与阈值由 constructor 补齐。只有追加默认数组时才组合公开的 files 基线：
+下面两个 area 各自选择文件和阈值；省略字段使用默认值。追加默认排除项时才组合公开 files 基线：
 
 ```ts
 import { defaultProjectFileSelection, duplicateDetection } from "@zxyycom/vibe-check";
@@ -81,8 +99,33 @@ const sourceAndScriptsDuplicateDetection = duplicateDetection({
 });
 ```
 
-每个 `codeAreas[id]` 都是该区域文件范围、有效 finding policy 与行数/token 下限的单一事实源。上例的
-`scripts.exclude` 显式保留 common defaults 并追加测试文件；若只写 `["scripts/**/*.test.ts"]`，它会完整替换默认排除数组。
+上例保留默认排除项再追加测试文件；只写 `["scripts/**/*.test.ts"]` 会替换整个排除数组。
+Area 也是比较边界：仅属于 `source` 和仅属于 `scripts` 的文件不会互相形成 Finding。
+跨目录比较需另声明同时选中两类路径的 area；精确规则见[工作原理](#工作原理)。
+
+### 精确豁免一个重复片段
+
+Waiver identity 使用 Finding 发布的完整排序 ranges；不要只写 path pair，也不要把 token/line counts 写入 identity：
+
+```ts
+const duplicates = duplicateDetection({
+  findingPolicy: "blocking",
+  findingWaivers: [
+    {
+      identity: {
+        metric: "duplicate-tokens",
+        locations: [
+          { path: "src/generated/a.ts", startLine: 10, endLine: 30 },
+          { path: "src/generated/b.ts", startLine: 15, endLine: 35 }
+        ]
+      },
+      reason: "两个生成目标在下一版模板迁移前必须保持镜像。"
+    }
+  ]
+});
+```
+
+range 变化会让旧 waiver 进入[共同 audit](../guides/finding-waivers.md#identity-与-audit)，而不会误匹配同一文件组合中的另一个 fragment。
 
 ## 定制 jscpd executable
 
@@ -101,31 +144,26 @@ const customDuplicateDetection = duplicateDetection({
 });
 ```
 
-`executable` 必须是已授权、可执行且**直接接受 jscpd CLI 参数**的 command。public scanner policy 只选择 command；
-owning adapter 负责 version probe、exact-path config、JSON report 与 jscpd 的自动 worker policy。实际版本用于区分 cache
-provenance，不要求 custom command 等于 package 当前安装的版本。
-
-需要靠前置参数才能转发到 jscpd 的通用 runtime（例如 `node path/to/jscpd.js`）不是受支持的 custom command；应直接
-提供 jscpd executable 或一个已授权的专用 wrapper executable。
-
-默认 package command 使用安装包声明并由 package manager 解析的兼容 jscpd v5。package 或 custom command 的实际版本都会
-隔离 cache；command、config 或 report 不兼容时，Check fail closed 为 `unavailable`，不会把无法完成的扫描伪装成零
-finding。
+`executable` 必须是项目已授权、可执行且直接接受 jscpd CLI 参数的 command。
+需要前置参数的 runtime（如 `node path/to/jscpd.js`）不受支持，可改用已授权的专用 wrapper executable。
+adapter 拥有 version probe、exact-path config、JSON report 与自动 worker policy；调用方只选择 command。
+custom 版本无需等于 package 版本，但实际版本会隔离 cache；不兼容或失败的具体结算见[不可用原因](#not-applicable-与-unavailable)。
 
 ## 工作原理
 
 Check 先按文件 `source` 分组；每种不同来源只枚举一次候选文件，再为各 `codeAreas[id].files` 应用自己的
 `include` / `exclude`，最后把全部路径去重成一个批准的精确范围。一个路径可同时属于多个 area；全部 exact paths 仍
-一次性交给 jscpd，因此同 area、跨 area 与重叠 area 文件都会互相比较：
+一次性交给 jscpd，但 raw scanner 候选只有在全部 location 至少共享一个 area 时才进入 Finding：
 
 1. jscpd 使用所有实际输入 area 中最低的 line 阈值和最低的 token 阈值取得完整候选。
-2. 每个 raw fragment 的 location path 必须属于本次完整 exact scope；任一路径越界都会拒绝整批 measurement。
-3. Check 按 location path 恢复它匹配的全部 areas。fragment 的 line count 和 token count 必须分别达到所有涉及 area
-   对应阈值中的最大值，才形成 finding。
-
-例如 `source` 使用 line `3` / token `20`，`scripts` 使用 line `10` / token `100` 时，scanner 使用 line `3` /
-token `20` 取得候选；跨这两个 area 的 8-line / 120-token fragment 和 12-line / 80-token fragment 都会被过滤，只有
-同时达到 line `10` 与 token `100` 的 fragment 会保留。
+2. 每个 raw fragment 的 location path 必须属于本次完整 exact scope，且完整 location ranges 必须互不相同；路径越界或
+   同一路径同一区间的自我匹配都会拒绝整批 measurement。
+3. Check 恢复每个 location 所属的 area IDs，并取所有 location 集合的交集。交集为空的 fragment 不形成 Finding、Record、
+   message 或 final count。
+4. 交集非空时，fragment 的 `codeAreas` 恰为稳定排序的共同 area IDs；line count 和 token count 必须分别达到这些共同 area
+   阈值中的最大值。
+5. 完整可信 Finding candidates 形成后才执行 waiver reconciliation；source/scanner/cache failure 不伪造 audit。Applied
+   Finding 保留 Record，unused/overmatched authoring 形成独立 audit Record，然后 Check 按 actionable disposition 结算。
 
 cache 只保存通过 exact-input 校验的 scanner fragments；无论是否命中 cache，当前 area annotation 与最终 policy filtering
 都走同一路径。只有 package/custom command identity、实际 jscpd 版本、当前 commit、完整 exact-input fingerprint 和实际
@@ -134,9 +172,10 @@ cache 只保存通过 exact-input 校验的 scanner fragments；无论是否命
 
 ## 效果与结果
 
-每个可信 finding 都形成 Record，不因 policy 或先前 finding 而省略。若 fragment 涉及多个 areas，只要任一 effective
-`findingPolicy` 为 `blocking`，该 Record 的 `blocking` 就为 `true`。正常 final data 恰为
-`{ findingCount, blockingFindingCount }`；前者等于 Records 数量，后者等于其中 `blocking: true` 的数量。
+每个可信 finding 都形成 Record，不因 policy 或先前 finding 而省略。若 fragment 的共同 areas 多于一个，只要任一共同
+area 的 effective `findingPolicy` 为 `blocking`，该 Record 的 `blocking` 就为 `true`。正常 final data 恰为
+`{ findingCount, blockingFindingCount }`；前者是完整 duplicate Finding 数量，后者是仍 actionable 且 blocking 的数量。
+Waiver audit Records 不进入这两个计数。
 `blockingFindingCount > 0` 时 outcome 为 `failed`，否则为 `passed`，所以 passed outcome 可以携带 non-blocking Records。
 
 每个 Record data 使用以下字段：
@@ -148,23 +187,43 @@ cache 只保存通过 exact-input 校验的 scanner fragments；无论是否命
   tokenCount: number,
   lineCount: number,
   codeAreas: string[],
-  locations: Array<{ path: string; startLine: number; endLine: number }>
+  locations: Array<{ path: string; startLine: number; endLine: number }>,
+  waiver?: { reason: string }
+}
+```
+
+Applied Finding 增加 `waiver.reason` 并把 Record `blocking` 置为 `false`，其它事实不变。Unused/overmatched authoring 使用：
+
+```ts
+{
+  kind: "finding-waiver-audit",
+  identity: { metric: "duplicate-tokens", locations },
+  matchCount: number,
+  reason: string,
+  status: "unused" | "overmatched"
 }
 ```
 
-`failed` 的 `blocking-findings` message 与携带 non-blocking Records 的 `passed` 的 `non-blocking-findings` message 都会引导
-调用方检查本 Check 的 Records。由本 Check 结算的 `unavailable` 会使用对应 `reason.code` 提供 error message；零 finding
-的 `passed` 与 `not-applicable` 不合成人为提示。
+每条 unused/overmatched audit 的 Record ID 是
+`/finding-waiver-audit/sha256:<canonical-identity-digest>`；该保留前缀与 normal duplicate Record ID domain 不相交。
+
+`duplicateDetection` 的 detail messages 按仍 actionable 的稳定 Finding 顺序；每条只包含 token/line counts 和最多两个
+项目相对 location，更多 location 只显示剩余数量。完整集合仍从本 Check 的 Records 读取；通用的 terminal Finding 呈现与
+Run progress 预览边界见 [呈现 Check Finding](../guides/presenting-findings.md)。由本 Check 结算的 `unavailable` 会使用对应
+`reason.code` 提供 error message；零 finding 的 `passed` 与 `not-applicable` 不合成人为提示。Applied waiver 另附
+`finding-waived` info；unused/overmatched authoring 附 warning，并从 audit Record 保留完整 identity 与 reason。
 
 用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseDuplicateDetectionData(value)` 验证 final data。两者返回
 `DuplicateDetectionFinalData`，Record 与不可用原因可分别用 `DuplicateDetectionRecordData` 和
 `DuplicateDetectionUnavailableReasonCode` 标注；authoring / resolved options types 是 `DuplicateDetectionOptions` 与
-`ResolvedDuplicateDetectionOptions`。parser 只适用于 `passed` / `failed` data，shape 或计数不变量不匹配时抛出
+`ResolvedDuplicateDetectionOptions`，waiver authoring 可用 `DuplicateDetectionFindingLocation`、
+`DuplicateDetectionFindingIdentity` 与 `DuplicateDetectionFindingWaiver` 标注。parser 只适用于 `passed` / `failed` data，shape 或计数不变量不匹配时抛出
 `TypeError`。
 
 ## `not-applicable` 与 `unavailable`
 
-- 少于两个合格 exact inputs：`not-applicable / no-eligible-input`。
+- 少于两个合格 exact inputs：完整 Finding 集合确定为空，结果为 `not-applicable / no-eligible-input`，configured waiver
+  全部形成 `unused` audit。
 - constructor 后形成的 resolved options 不符合完整 shape：`unavailable / invalid-options`。
 - 所配置的 filesystem 或 git-worktree 来源无法形成候选快照：`unavailable / source-unavailable`。
 - package/custom command 缺失、version probe 失败或无法形成可识别版本 provenance：
@@ -173,21 +232,14 @@ cache 只保存通过 exact-input 校验的 scanner fragments；无论是否命
 - cache 写入失败：`unavailable / cache-write-failed`。
 - report、fragment 或 exact-input membership 无法形成可信完整结果：`unavailable / external-result-invalid`。
 
+上述 `unavailable` 都发生在完整 Finding 集合形成前，因此不发布 applied/unused/overmatched waiver audit。
+
 通用 preflight 机制见 [options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
 
 ## I/O 与安全边界
 
-execution 启动一次本机 jscpd 调用；输入只包含各 `codeAreas[id].files` 批准的 exact paths 去重并集。显式配置
-`scanner.command.kind: "custom"` 表示项目授权执行其中的 executable；所有传入参数由 owning adapter 生成。该 Check
-不发起网络请求。
-
-## 最小用法
-
-```ts
-import { defineConfig, duplicateDetection, run } from "@zxyycom/vibe-check";
-
-const result = await run(defineConfig({ checks: [duplicateDetection()] }));
-```
+execution 仅把各 area 批准路径的去重并集交给本机 jscpd，不发起网络请求。
+custom command 是项目明确授权的 executable，参数均由 adapter 生成；共用 scanner 不扩大 area 比较边界。
 
 ## 适用边界
 

package/docs/checks/file-metrics.md

@@ -1,30 +1,42 @@
 # `fileMetrics`
 
-本页完整说明 package consumer 如何构造、配置和读取 `fileMetrics`。package 总入口见
-[README 的随包 Check 概览](../../README.md#随包提供的-check)；普通 Check 的 preflight、Run 与结果读取机制见
-[深入 API 机制](../api-mechanics.md)。
-
 ## 用途
 
-`fileMetrics(options?)` 返回一个普通 `file-metrics` Check。该 Check 使用 SCC 测量各区域所选文件的代码行数，
-将超过区域策略的文件发布为 supplemental Records，并分别报告 finding 总数与 blocking finding 数量。可选的声明式
-waiver 在完整 finding 集合形成后对账；它不会把路径排除在 SCC 输入之外。
+`fileMetrics(options?)` 构造 `file-metrics` Check，用 SCC 测量文件代码行数，报告超限 Records 及总数、blocking 数量。
+waiver 在完整 Finding 集合上对账，不从 SCC 输入排除路径。
+
+运行环境须提供默认 `scc` command，或配置已授权的 `scanner.executable`；两者均须支持精确 SCC 4.0.0 version output
+与 CSV contract。安装与协议见[定制 SCC executable](#定制-scc-executable)。
+
+## 最小用法
 
-无参调用使用完整默认策略：
+示例保留终端进度，不写 machine files。
 
 ```ts
-import { fileMetrics } from "@zxyycom/vibe-check";
+import { defineConfig, fileMetrics, run } from "@zxyycom/vibe-check";
 
-const check = fileMetrics();
+const check = fileMetrics({ findingPolicy: "blocking" });
+const result = await run(defineConfig({
+  checks: [check],
+  outputs: { machinePublication: { enabled: false } }
+}));
+const outcome = result.kind === "completed"
+  ? result.snapshot.checks.find(({ checkId }) => checkId === check.checkId)?.outcome
+  : undefined;
+if (result.kind !== "completed" || outcome?.status !== "passed") {
+  console.error(`File metrics did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
 ```
 
-执行这个 Check 时，project runtime 需要让默认 `scc` command 可用，或在 `scanner.executable` 中选择项目已授权且
-兼容 SCC 3.7.0 version output 与 CSV contract 的 executable。
+示例显式使用 `findingPolicy: "blocking"`，让未豁免的普通 Finding 导致失败；默认 `non-blocking` 只警告，不因 Finding 退出非零。
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
+显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
-顶层 `codeAreas`、`findingPolicy`、`findingWaivers` 与 `scanner` 都可省略。每个 `codeAreas[areaId]` 同时拥有文件选择和代码行
-策略，因此不同区域可以选择不同文件并使用不同上限。无参调用物化以下完整、冻结的 Check options：
+顶层 options 都可省略；每个 area 独立选择文件与代码行策略。无参调用物化以下完整、冻结的 options：
 
 ```ts
 {
@@ -46,20 +58,18 @@ const check = fileMetrics();
 }
 ```
 
-这里的 `defaultProjectFileSelection` 是从 package root 公开的深冻结完整基线；constructor 会把同值 files branch 物化到
-自己的 resolved options，调用方无需复制该对象；完整默认 glob 可直接从该 public value 读取。
+`defaultProjectFileSelection` 是 package root 公开的深冻结默认选择；constructor 会物化同值 files branch，无须手工复制。
 
 ### 字段规则
 
 - 省略整个 `codeAreas` 时，constructor 建立默认 `project` 区域。显式 `codeAreas` 必须至少包含一个
   非空 area ID。
-- 每个显式区域必须提供 `files`。`source` 只能是 `"filesystem" | "git-worktree"`，默认 `filesystem`；filesystem
-  不解释 `.gitignore`，git-worktree 使用已跟踪文件和未被 Git 标准忽略规则排除的未跟踪文件。来源不可用时 Check
-  结算为 `unavailable`，不会切换到另一来源。
-- `include` 与 `exclude` 都按 project-root-relative slash path 的 glob 匹配，exclude 优先。省略时使用公开的
-  `defaultProjectFileSelection`；显式数组是完整替换值，`include: []` 不选择路径，`exclude: []` 不排除路径。
+- 每个显式区域必须提供 `files`。共同 `{ source, include, exclude }` grammar、source failure 和数组替换见
+  [共享的 files 选择语义](../guides/collecting-project-files.md#共享的-files-选择语义)；本 Check 的 branch fields 省略时使用公开的
+  `defaultProjectFileSelection`。
 - 顶层 `findingPolicy` 只能是 `"blocking" | "non-blocking"`，默认 `non-blocking`；area 可覆盖，省略时继承顶层值。
-- `findingWaivers` 省略时为 `[]`。每项必须是 `{ identity: { metric: "code-lines", path }, reason }`；`path` 必须已经是
+- `findingWaivers` 省略时为 `[]`，并采用[共同 waiver authoring 与 audit](../guides/finding-waivers.md#identity-与-audit)。每项必须是
+  `{ identity: { metric: "code-lines", path }, reason }`；`path` 必须已经是
   normalized project-root-relative slash path：非空、不以 `/` 开头、不含 `\\`、Windows drive prefix、空 segment、`.` 或 `..`。
   `reason` 必须非空，同一 `{ metric, path }` 不得重复。它不接受 callback 或 glob：metric 和 path 是该 Check 承诺的稳定
   identity，实际行数与上限仍会随策略变化。
@@ -98,8 +108,7 @@ const sourceAndTests = fileMetrics({
 });
 ```
 
-本例只覆盖各区域显式给出的字段；省略的文件字段、finding policy 和代码行字段继续使用 package 默认值。`tests` area
-通过公开的深冻结 `defaultProjectFileSelection` 保留 common exclusions，再追加项目的 fixture 规则。
+省略字段沿用默认值；`tests` 保留默认排除项并追加 fixture 规则。
 
 ### 单个区域的有效上限
 
@@ -141,11 +150,12 @@ const customFileMetrics = fileMetrics({
 custom executable 必须直接接受 SCC CLI 参数。public scanner policy 只选择 executable；owning adapter 固定执行以下协议：
 
 - availability probe：`--version`
-- measurement：`--by-file --format csv <approved exact paths...>`
+- measurement：`--no-config --by-file --format csv <approved exact paths...>`
 - process timeout：由 adapter 固定，不属于项目策略
 
 需要 prefix arguments 的通用 runtime（例如 `node path/to/tool.js`）不是受支持的直接 command；项目应提供一个已授权的
-专用 wrapper executable。当前 adapter 只接受 SCC `3.7.0` 的 version output 与对应 CSV header contract。
+专用 wrapper executable。当前 adapter 只接受 SCC `4.0.0` 的 version output 与对应 CSV header contract。
+`--no-config` 隔离 `SCC_CONFIG_PATH` 与项目中的 ambient SCC config；adapter 不读取 consumer SCC 参数或 config。
 
 ### 安装兼容 SCC
 
@@ -153,12 +163,12 @@ custom executable 必须直接接受 SCC CLI 参数。public scanner policy 只
 
 ```toml
 [tools]
-go = "1.25"
-"go:github.com/boyter/scc/v3" = { version = "v3.7.0", depends = ["go"] }
+go = "1.26.4"
+"go:github.com/boyter/scc/v4" = { version = "v4.0.0", depends = ["go"] }
 ```
 
 运行 `mise install` 后，用 `scc --version` 确认当前 project runtime 能解析到该命令。若项目使用其它安装方式，只要
-`scanner.executable` 指向已授权、直接接受上述协议并产生 SCC 3.7.0-compatible output 的 executable 即可。
+`scanner.executable` 指向已授权、直接接受上述协议并产生精确 SCC 4.0.0 version output 和受支持 CSV header 的 executable 即可。
 
 ## 效果与结果
 
@@ -183,14 +193,15 @@ non-blocking 或 waived finding Records。
 
 精确命中一项 finding 的 waiver 会保留原 finding Record，并写入 `waiver.reason`、将 `blocking` 设为 `false`，同时附加
 `finding-waived` info message。未命中或命中多项的 waiver 不会隐藏 finding；各自产生一条 `kind: "finding-waiver-audit"`
-Record，带 identity、reason、matchCount 和 `"unused" | "overmatched"` status，并附 warning。这样 stale 或过宽配置可见，
-而不是悄悄失效或覆盖多个 finding。audit Record ID 使用 `/finding-waiver-audit/<identity.path>`，该 leading-slash domain
+Record，带 identity、reason、matchCount 和 `"unused" | "overmatched"` status，并附 warning。
+audit Record ID 使用 `/finding-waiver-audit/<identity.path>`，该 leading-slash domain
 与正常 finding 的 normalized relative path ID 不相交。
 
-`failed` 的 `blocking-findings` message 与携带 non-blocking Records 的 `passed` 的 `non-blocking-findings` message 都会引导
-调用方检查本 Check 的 Records。由本 Check 结算的 `unavailable` 会使用对应 `reason.code` 提供 error message；没有 finding
-且没有 waiver audit 时，`passed` 与 `not-applicable` 不合成人为提示。若已配置 waiver，即使 exact-path union 为空，Check
-仍会对已知空 finding 集合产生 `unused` audit Record 和 warning，同时保持 `not-applicable / no-eligible-input` outcome。
+`fileMetrics` 的 detail messages 按稳定 path 顺序，包含项目相对 path、code lines、effective limit 和 areas；完整 finding 集合从
+本 Check 的 Records 读取。通用的 terminal Finding 呈现与 Run progress 预览边界见
+[呈现 Check Finding](../guides/presenting-findings.md)。
+由本 Check 结算的 `unavailable` 会使用对应 `reason.code` 提供 error message；没有 finding 且没有 waiver audit 时，`passed` 与
+`not-applicable` 不合成人为提示。
 
 用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseFileMetricsData(value)` 验证 final data。两者返回
 `FileMetricsFinalData`，Record 与不可用原因可分别用 `FileMetricsRecordData` 和
@@ -215,14 +226,6 @@ Record，带 identity、reason、matchCount 和 `"unused" | "overmatched"` statu
 execution 只启动本机已授权的 SCC executable，输入仅包含各区域批准的 exact paths 去重并集。该 Check 不发起网络请求，
 也不把 raw SCC stdout/stderr 直接发布为稳定 Check 或 Record data。
 
-## 最小用法
-
-```ts
-import { defineConfig, fileMetrics, run } from "@zxyycom/vibe-check";
-
-const result = await run(defineConfig({ checks: [fileMetrics()] }));
-```
-
 ## 适用边界
 
 该 Check 只评估文件级代码行策略。函数级 NLOC、cyclomatic complexity 与 parameter count 由