@zxyycom/vibe-check 0.0.2 → 0.0.3

package/docs/checks/json-schema-validation.md

@@ -5,6 +5,28 @@
 `jsonSchemaValidation(options?)` 构造普通 Check，使用显式 schema registry 与 instance bindings 验证 JSON instances。
 先声明 schema 与 binding；无参调用不发现 schema，并结算为 `not-applicable / no-bindings`。
 
+## 构造器项目声明
+
+`jsonSchemaValidation` 有三类 overload：
+`jsonSchemaValidation(options?: JsonSchemaValidationOptions<"json-schema-validation">)` 保留默认 literal；
+`jsonSchemaValidation<Id>(options: JsonSchemaValidationOptions<Id> & { checkId: Id })` 保留 custom literal；
+已宽化为 `JsonSchemaValidationOptions` 的变量返回 `string` identity。默认 `checkId` 是 `json-schema-validation`，默认 `displayName` 是 `JSON Schema validation`；`files`、
+`maximumBytes`、`schemaIdentity`、`referenceResolution`、`schemas` 与 `bindings` 仍是本 Check 的领域 options。
+
+例如，将 API schema 校验声明为只在 API 变更时选择的独立 Check：
+
+```ts
+const apiSchema = jsonSchemaValidation({
+  checkId: "api-schema",
+  enabledByFlags: { when: "api-changed" },
+  schemas: [{ id: "urn:example:api", path: "schema/api.json" }],
+  bindings: [{ id: "api", instancePath: "fixtures/api.json", schemaId: "urn:example:api" }]
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
 ## 最小用法
 
 示例保留终端进度，不写 machine files。
@@ -32,8 +54,7 @@ if (result.kind !== "completed" || outcome?.status !== "passed") {
 }
 ```
 
-本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
-显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -103,7 +124,7 @@ fragment 的精确 HTTPS origin；`pathPrefix` 最长 256 字符，从 `/` 开
 
 ## 工作原理
 
-constructor 补齐并冻结 closed options；获 Scheduler admission 后先 preflight，再建立 selected path set、加载 registry、
+constructor 补齐并冻结 closed options；获 Scheduler admission 后先 preparation，再建立 selected path set、加载 registry、
 按 identity policy 编译并验证 bindings。selected set 外的声明路径形成 `out-of-scope` issue，不扩大读取范围。
 schema document、compile 与 instance issues 均形成 Records。
 
@@ -181,7 +202,7 @@ binding 数量为零时结算为 `not-applicable / no-bindings`。`unavailable.r
 
 任一 `unavailable` 分支都不提供 final data；此前已经接受的 issue Records 继续保留。
 
-通用 preflight 语法见 [options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+通用 preparation 语法见 [options preparation 与 execution](../api-mechanics.md#options-preparation-与-execution)。
 
 ## I/O 与安全边界
 

package/docs/checks/json-validation.md

@@ -5,6 +5,26 @@
 `jsonValidation(options?)` 构造普通 Check，严格验证所选小写 `.json` 文档的完整性，报告 syntax error、duplicate key
 与 incomplete document。
 
+## 构造器项目声明
+
+`jsonValidation` 有三类 overload：`jsonValidation(options?: JsonValidationOptions<"json-validation">)`
+保留默认 literal；`jsonValidation<Id>(options: JsonValidationOptions<Id> & { checkId: Id })` 保留 custom literal；
+已宽化为 `JsonValidationOptions` 的变量返回 `string` identity。默认 `checkId` 是 `json-validation`，默认 `displayName` 是 `JSON validation`；`files` 与
+`maximumBytes` 仍是本 Check 的领域 options。
+
+例如，用明确的项目 identity 和展示名只检查配置文件：
+
+```ts
+const configJson = jsonValidation({
+  checkId: "config-json",
+  displayName: "Configuration JSON",
+  files: { include: ["config/**/*.json"] }
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
 ## 最小用法
 
 示例保留终端进度，不写 machine files。
@@ -26,8 +46,7 @@ if (result.kind !== "completed" || outcome?.status !== "passed") {
 }
 ```
 
-本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
-显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -63,7 +82,7 @@ const configJsonValidation = jsonValidation({
 
 ## 工作原理
 
-constructor 补齐并冻结 closed options，获 Scheduler admission 后先 preflight，再按本页 suffix 规则完整分类输入。
+constructor 补齐并冻结 closed options，获 Scheduler admission 后先 preparation，再按本页 suffix 规则完整分类输入。
 每个 rejected path 先发布 Record；accepted path 才读取、解析，无效文档另发 Record。
 
 strict-document boundary 先按 byte length 应用 `maximumBytes`，再依次区分 BOM、fatal UTF-8、strict JSON grammar 与 decoded
@@ -132,8 +151,8 @@ Records 与 warning 的 `passed` 结算。`unavailable.reason.code` 只使用以
 | `execution-cancelled` | invocation signal 在可观察工作边界取消本 Check | 检查调用方取消原因，不把结果解释为 clean validation |
 
 后续文件导致 `unavailable` 时，分类阶段的 rejected-input Records 与先前已接受的 invalid-file Records 均保留，但本 Check
-不提供 final data；对应 rejection warning 也随 terminal error message 一起保留。通用 preflight 语法见
-[options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+不提供 final data；对应 rejection warning 也随 terminal error message 一起保留。通用 preparation 语法见
+[options preparation 与 execution](../api-mechanics.md#options-preparation-与-execution)。
 
 ## I/O 与安全边界
 

package/docs/checks/maintenance-reminders.md

@@ -4,6 +4,32 @@
 
 `maintenanceReminders(entries)` 创建固定 ID 为 `maintenance-reminders` 的 Check，用 Git first-parent history 提醒定期复核。
 
+## 构造器项目声明
+
+`maintenanceReminders` 保留 `maintenanceReminders(entries)`，并为 object input 提供三类 overload：
+`MaintenanceRemindersInput<"maintenance-reminders">` 保留默认 literal；带必填
+`{ checkId: Id }` 的 `MaintenanceRemindersInput<Id>` 保留 custom literal；宽化为
+`MaintenanceRemindersInput` 的变量返回 `string` identity。默认 `checkId` 是 `maintenance-reminders`，默认
+`displayName` 是 `Maintenance reminders`；`entries` 是唯一领域 policy，object input 的其余顶层字段用于项目声明。
+
+例如，为需要单独选择的提醒设置 identity 与 flag 条件：
+
+```ts
+const dependencyReview = maintenanceReminders({
+  checkId: "dependency-review",
+  enabledByFlags: { when: "dependencies-changed" },
+  entries: [{
+    id: "dependencies",
+    baseCommit: "0123456789abcdef0123456789abcdef01234567",
+    limits: { commits: 40 },
+    message: "Review dependency updates."
+  }]
+});
+```
+
+两种调用形式都返回原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
 ## 最小用法
 
 示例保留终端进度，不写 machine files。
@@ -35,8 +61,7 @@ if (result.kind !== "completed" || outcome?.status !== "passed") {
 将占位 commit ID 换成项目 first-parent history 中的真实复核 commit；不存在的基线产生条目 `unavailable`。
 示例使用 `enforcing`，会因到期或不可测量失败；默认 `advisory` 只提醒。
 
-本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
-显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -62,7 +87,7 @@ ReadonlyArray<{
 - `mode` 省略时为 `advisory`；`enforcing` 使到期或不可测量的条目令所属 Check 失败。
 
 constructor 把输入固定为完整 options `{ entries, git: { executable: "git" } }`。所属 Check 获 Scheduler admission 后，其 task-local
-preflight 在自身 execution 前验证 unknown、sparse、duplicate 或 malformed entries；失败时当前 Check 以
+preparation 在自身 execution 前验证 unknown、sparse、duplicate 或 malformed entries；失败时当前 Check 以
 `unavailable / invalid-options` 结算。
 
 ## 工作原理
@@ -157,7 +182,7 @@ Git/历史测量的普通失败会保留完整 final data，并把受影响条
 每个 whole-Check `unavailable` 都携带与 `reason.code` 相同 code 的 error message，并指出应恢复 options、检查取消原因或
 检查 package/runtime integrity。entry-level `unavailable` 仍按上一节保留 final data 与项目编写的提醒正文。
 
-通用 preflight 语法见 [options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+通用 preparation 语法见 [options preparation 与 execution](../api-mechanics.md#options-preparation-与-execution)。
 
 ## I/O 与安全边界
 
@@ -166,5 +191,4 @@ request 数为零，baseline 更新由维护者提交。
 
 ## 适用边界
 
-该 Check 适用于按 commit count 或 changed-line count 提醒维护复核。是否把 `enforcing` failure 转为调用级阻断，
-由 `RunControls.checkAggregation` policy 决定。
+该 Check 适用于按 commit count 或 changed-line count 提醒维护复核。有效的 `enforcing` failure 会使默认严格 `aggregate` 为 `failed`；调用方负责把该调用级结论映射为自己的阻断或退出行为。只有需要不同领域解释时，才提供 `RunControls.checkAggregation` 同步函数。

package/docs/checks/markdown-link-validation.md

@@ -4,6 +4,27 @@
 
 `markdownLinkValidation(options?)` 构造普通 Check，离线验证所选 Markdown 中的本机链接、图片目标与标题锚点。
 
+## 构造器项目声明
+
+`markdownLinkValidation` 有三类 overload：
+`markdownLinkValidation(options?: MarkdownLinkValidationOptions<"markdown-link-validation">)` 保留默认 literal；
+`markdownLinkValidation<Id>(options: MarkdownLinkValidationOptions<Id> & { checkId: Id })` 保留 custom literal；
+已宽化为 `MarkdownLinkValidationOptions` 的变量返回 `string` identity。默认 `checkId` 是 `markdown-link-validation`，默认 `displayName` 是 `Markdown link validation`；`files`、
+`findingPolicy`、target policy、`cache` 与 `limits` 仍是本 Check 的领域 options。
+
+例如，让文档链接检查观察生成文档并使用独立 identity：
+
+```ts
+const docsLinks = markdownLinkValidation({
+  checkId: "documentation-links",
+  observes: ["generate-docs"],
+  files: { include: ["docs/**/*.md"] }
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
 ## 最小用法
 
 示例保留终端进度，不写 machine files。
@@ -27,8 +48,7 @@ if (result.kind !== "completed" || outcome?.status !== "passed") {
 
 示例显式使用 `findingPolicy: "blocking"`，让普通链接 Finding 导致失败；默认 `non-blocking` 只警告，不因 Finding 退出非零。
 
-本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
-显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -203,8 +223,8 @@ selected path 数量为零时结算为 `not-applicable / no-eligible-input`。se
 | `cancelled`                  | invocation signal 取消本 Check；不要把结果解释为 clean validation。                                                                      |
 
 这些边界不发布 partial link-finding Records，也不提供 final data；若 selected classification 已完成，已发布的
-rejected-input Records 与对应 warning 仍保留。通用 preflight 语法见
-[options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+rejected-input Records 与对应 warning 仍保留。通用 preparation 语法见
+[options preparation 与 execution](../api-mechanics.md#options-preparation-与-execution)。
 
 ## I/O 与安全边界
 

package/docs/checks/markdown-lint.md

@@ -0,0 +1,167 @@
+# `markdownLint`
+
+## 用途与组合
+
+`markdownLint(options?)` 是 package 提供的 ordinary Check，用于检查已选择 Markdown source 的结构和明确内容缺陷。它的公共契约由本页完整定义；`files` 的共同选择语义见[选择与收集项目文件](../guides/collecting-project-files.md)。
+
+它与 [`markdownLinkValidation`](./markdown-link-validation.md) 分工互补：`markdownLint` 检查本页列出的结构与内容规则；`markdownLinkValidation` 检查本地 link target 与 anchor 完整性。需要两类 evidence 时，将两个 Check 一起放入 `checks`；`link-fragments` 默认不启用，避免默认产生与链接 Check 重复的 same-document anchor evidence。
+
+## 构造器项目声明
+
+`markdownLint` 有三类 overload：`markdownLint(options?: MarkdownLintOptions<"markdown-lint">)` 保留默认 literal；
+`markdownLint<Id>(options: MarkdownLintOptions<Id> & { checkId: Id })` 保留 custom literal；已宽化为
+`MarkdownLintOptions` 的变量返回 `string` identity。默认 `checkId` 是 `markdown-lint`，默认 `displayName` 是 `Markdown lint`。
+`files`、`findingPolicy`、`findingWaivers`、`rules`、`limits` 与 `cache` 是本 Check 的领域 options，不属于项目展示字段。
+
+例如，为文档 lint 声明项目展示和进度呈现策略：
+
+```ts
+const documentationLint = markdownLint({
+  checkId: "documentation-lint",
+  displayName: "Documentation lint",
+  omitQuietPassedRow: true,
+  files: { include: ["docs/**/*.md"] }
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
+## 参数与默认配置
+
+`markdownLint` 只接受以下闭合 options。未知字段、未知或重复规则、空规则数组，以及不是正安全整数或超过上限的 limit，会在构造 Check 时以 `TypeError` 拒绝。
+
+| 字段 | 默认值 | 契约 |
+| --- | --- | --- |
+| `files` | 选择大小写不敏感的 `.md` 与 `.markdown` 路径 | 通过 project-file selection 指定本次 source 范围。|
+| `findingPolicy` | `"non-blocking"` | lint Finding 保留为 evidence；设为 `"blocking"` 时，有未豁免 lint Finding 的 Check 结算为 `failed`。|
+| `findingWaivers` | `[]` | 带非空理由的精确 Finding 例外；完整 lint 后对账，不删除 Finding。见下方精确豁免边界。|
+| `rules` | 下表八项默认规则 | 省略时使用默认集；提供非空数组时完整替换默认集。数组只可含下表九个名称，resolved 顺序固定为 Product catalog 顺序。|
+| `limits.maxMarkdownBytes` | `1_048_576`，最大 `16_777_216` | 单个 source 的 UTF-8 字节上限。|
+| `limits.maxFindings` | `10_000`，最大 `100_000` | 整次 execution 可形成的 lint Finding 上限。|
+| `cache` | `{ enabled: false }` | 显式启用时为 `{ enabled: true, directory }`；directory 必须是调用方拥有的绝对路径。见下方缓存边界。|
+
+### 规则 catalog
+
+| Public rule | 默认启用 | 报告的缺陷 |
+| --- | --- | --- |
+| `heading-increment` | 是 | 标题层级一次增加超过一级。|
+| `no-reversed-links` | 是 | 反向 `()[]` link 语法。|
+| `no-missing-space-atx` | 是 | ATX heading marker 后缺少空格。|
+| `fenced-code-language` | 是 | fenced code block 缺少语言。|
+| `no-empty-links` | 是 | link destination 或 fragment 为空。|
+| `no-alt-text` | 是 | Markdown image 缺少 alt text。|
+| `link-fragments` | 否；仅显式选择 | same-document fragment 未匹配标题。|
+| `reference-links-images` | 是 | full/collapsed reference link 或 image 缺少 definition。|
+| `table-column-count` | 是 | GFM pipe table 的行列数不一致。|
+
+backend 规则名、preset、rule object、rule 参数、parser plugin 和自动修复不是公共配置。
+
+## 工作原理
+
+每次 execution 只收集一次 `files` 选中的路径并稳定排序。选中但后缀不是 `.md` 或 `.markdown` 的路径不会读取内容，而是各发布一条 non-blocking `input-rejected / unsupported-file-type` Record。accepted source 必须位于 project root 内、是 regular file、可作为 UTF-8 读取且不超过 `maxMarkdownBytes`；Check 按路径顺序逐文件执行，并在文件前后响应取消。
+
+私有 adapter 使用随包固定的 `markdownlint@0.41.1` Promise `strings` API，只接收已读取的 source text，不接收项目路径或文件系统权限。inline config 固定禁用；文件开头的 YAML、TOML 和 JSON front matter 受支持。pipe table、HTML comment 与未支持扩展的识别以该固定 backend 版本的实际行为为准，不承诺与任意 Markdown renderer 等价。
+
+### 逐文件 findings 缓存
+
+缓存默认关闭，不访问缓存目录。显式启用后，每次 execution 仍完成以下工作：
+
+1. 按当前 `files` 选择路径，确认每份 source 位于 project root 内、符合大小限制，并读取、解码当前 UTF-8 内容。
+2. 对未变化的 source 复用已验证的逐文件 findings；内容、所选规则或 backend 版本变化时重新 lint。缓存身份还包含 source path 与内部 adapter 契约版本。
+3. 根据本次完整遍历结算 Finding 总量限制、记录顺序、Finding policy、Records、消息与终态。缓存命中不复用 Check outcome。
+
+只有成功计算的 findings 可写入缓存。损坏或不可用的缓存会重新计算，不会被视为空结果；取消、source 读取失败、backend 失败及超限仍按原有终态结算。adapter 的规则配置或 finding 解释变化时，维护者必须提升内部缓存契约版本。
+
+缓存目录由调用方指定，保存由 source 派生的 findings 和 identity 摘要，不保存原文。调用方应使用可信、可删除的绝对目录并管理容量；该目录不提供防篡改、机密性或自动清理保证。
+
+### 精确 Finding waiver
+
+`findingWaivers` 是闭合的 `{ identity, reason }` 数组；每项 identity 只包含公开 `lint-finding` Record data 的 `path`、`rule`、`range`。复核一条 Finding 后，完整复制这三个字段并填写非空 reason，不解析 Record ID，也不要自动把全部新 Finding 转成 waiver。[配置示例](../guides/finding-waivers.md#为-markdown-lint-声明精确例外)展示同一 authoring。
+
+- `path` 是规范 project-relative `/` 路径，不解释 glob；`rule` 必须是本页 catalog 中的公共规则名。
+- `range` 只含 `start`、`end`，两者只含正安全整数 `line`、`column`；两端同行，end column 不小于 start column。使用完整的一基 UTF-16 range，包括 end-exclusive 的 end；point range 的两端相等。
+- 类型为 `MarkdownLintFindingIdentity` 与 `MarkdownLintFindingWaiver`。未知字段、非法位置、空 reason、重复 identity、稀疏数组或 accessor 配置在构造 Check 时以 `TypeError` 拒绝；合法配置被独立、递归冻结地快照。
+
+每次完成全部 source traversal 后，Check 使用[通用 reconciliation](../guides/finding-waivers.md#identity-与-audit)按完整 identity 对账：
+
+| 匹配次数 | Finding 与 audit | 结算影响 |
+| --- | --- | --- |
+| 恰好一条 | 原 Finding 保留原 id、位置与规则，增加 `waiver: { reason }`，并发布 `finding-waived` 信息消息。 | 该 Finding 不再阻断。 |
+| 零条 | 发布 `finding-waiver-audit / unused` Record 与 warning。 | 不豁免其它 Finding；audit 本身不阻断。 |
+| 多条 | 发布 `finding-waiver-audit / overmatched` Record 与 warning，所有匹配 Finding 均保留。 | 所有匹配 Finding 继续接受原 findingPolicy 判断。 |
+
+audit Record data 包含 `kind: "finding-waiver-audit"`、`identity`、`reason`、`matchCount` 与 `status: "unused" | "overmatched"`，其类型为 `MarkdownLintFindingWaiverAuditRecordData`。不为 applied 另发 audit Record，因为原 Finding 上已有 waiver evidence。
+
+完全相同位置、规则和路径的多条 Finding 不会按 ordinal 任挑一条豁免；不同 end range 则是不同 identity。编辑导致路径或位置漂移时，旧 waiver 会变为 unused，应人工更新或删除。reason 会进入公开 Records 和消息，不得包含秘密或敏感原文。
+
+waiver 不改变文件选择、规则、source 读取、`maxFindings` 或缓存 facts：所有原始 Finding 仍计入上限，每次 cache hit 后也按当前 waiver 重新结算。rejected input、source/backend 失败、超限和取消不可豁免；没有 selected path 时继续 N/A，不对账；无法取得完整 lint 时不发布 partial lint 或 waiver audit。省略或传入空数组保持既有输出。
+
+## I/O 与安全边界
+
+Check 不读取 backend 配置文件，不访问网络，不读取 project root 外的 source；默认不写入项目，显式启用缓存时只写调用方指定的缓存目录。调用方通过 `files` 决定 source 范围。
+
+## 效果与结果
+
+成功 execution 的 lint Record 为：
+
+```ts
+{
+  kind: "lint-finding",
+  path,
+  rule,
+  range: { start: { line, column }, end: { line, column } }
+}
+```
+
+应用精确 waiver 的 lint Record 还包含 `waiver: { reason }`；未豁免时不增加该字段。unused/overmatched audit 见上节，`MarkdownLintRecordData` 同时覆盖 lint、input-rejected 和 waiver-audit 三种 Record。
+
+`path` 是 project-relative path。`range` 使用一基 UTF-16 line/column，end 是同一行 end-exclusive position；backend 未提供 range 时使用该行 column 1 的 point range。普通 lint 诊断消息只包含 Product-owned path、position、public rule 与固定摘要，不泄漏 backend message、context、source、fix、URL 或异常；waiver 消息另含调用方显式提供的 reason，其公开边界见上方精确豁免说明。
+
+成功 execution 的 final data 为 `{ sourceFileCount, findingCount, rejectedInputCount }`：`sourceFileCount` 是成功 lint 的 accepted source 数量；`findingCount` 是全部 lint Findings（包括已豁免项）与 rejected inputs 的合计，因而不小于 `rejectedInputCount`。audit 不计入 findingCount，该计数不代表阻断数；通过 lint Record 上的 waiver evidence 区分已豁免项。
+
+用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseMarkdownLintData(value)` 验证 `passed` / `failed` outcome 的 final data。两者返回 `MarkdownLintFinalData`；Record 和不可用原因可分别用 `MarkdownLintRecordData` 与 `MarkdownLintUnavailableReason` 标注，authoring / resolved options types 是 `MarkdownLintOptions` 与 `ResolvedMarkdownLintOptions`。parser 要求完整且无额外字段、计数为非负安全整数，并验证 `findingCount >= rejectedInputCount`；不匹配时抛出 `TypeError`。`not-applicable` 与 `unavailable` 不提供可解析的 final data。
+
+| 条件 | 结算 | 发布内容 |
+| --- | --- | --- |
+| 没有 selected path | `not-applicable / no-eligible-input` | 不发布 final data。|
+| 全部 selected path 被后缀资格拒绝 | `passed` | rejected-input Records、可能的 unused waiver audit、warning 和 final data。|
+| 无 lint Finding | `passed` | final data，以及已配置但未命中的 waiver audit。|
+| 有 lint Finding 且 `findingPolicy: "non-blocking"` | `passed` | 全部 lint Records、waiver evidence/audit、消息和 final data。|
+| 有未豁免 lint Finding 且 `findingPolicy: "blocking"` | `failed` | 全部 lint Records、waiver evidence/audit、消息和 final data。|
+| 全部 lint Finding 已豁免 | `passed` | 全部 lint Records 及 waiver evidence、消息和 final data。|
+| root、source、limit、backend、协议或取消阻止完整结果 | `unavailable` | 不发布 final data 或 partial lint Findings；已完成资格分类的 rejected-input Records 与 warning 保留。|
+
+## `not-applicable` 与 `unavailable`
+
+`unavailable` 的稳定 reason code 是 `invalid-options`、`project-root-unavailable`、`source-unavailable`、`source-too-large`、`finding-limit-exceeded`、`backend-failed`、`backend-protocol-invalid` 或 `cancelled`。其中 `source-unavailable` 包含 selection、containment、读取或 UTF-8 decode 无法完成的情形。
+
+## 最小用法
+
+```ts
+import { defineConfig, markdownLint, run } from "@zxyycom/vibe-check";
+
+const check = markdownLint({ findingPolicy: "blocking" });
+const definition = defineConfig({
+  checks: [check],
+  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 === check.checkId)?.outcome;
+if (outcome?.status !== "passed" && outcome?.status !== "not-applicable") {
+  throw new Error(`Markdown lint did not pass: ${outcome?.status ?? "no outcome"}`);
+}
+if (outcome.status === "not-applicable") console.warn("No Markdown input selected; no lint evidence.");
+```
+
+本例对 blocking Finding 和其它 Check 失败退出非零；`not-applicable` 仅表示没有可检查的 Markdown，不是 lint 通过的证据。默认严格 `aggregate` 会把有效的 `not-applicable` 结论为 `failed`，调用方可将其映射为 Gate 失败；需要不同领域解释时才提供同步 `checkAggregation` 函数。仅有 `RunResult.kind === "completed"` 不代表 Check 通过。
+
+## 适用边界
+
+本 Check 的 package 默认仍为 advisory，缓存默认关闭。Project Gate 以独立的 `markdown-lint` identity 使用八项默认规则、完整 `docs/**/*.md` 与 `changes/**/*.md` corpus，以及 non-blocking Finding policy。required 在 Markdown 文档或其实现输入变更时运行；`--materials`、`--quality`、`--all` 可强制运行。Gate 显式使用 `.cache/vibe-check/markdown-lint-findings/` 复用逐文件 findings，不缩小检查范围或改变 consumer 默认值；独立的 Markdown link validation 仍负责链接目标完整性。

package/docs/checks/secret-detection.md

@@ -4,6 +4,26 @@
 
 `secretDetection({ files })` 是随包 ordinary Check，发现高置信 PEM private-key material。它不是全面 credential protection，也不验证 secret 有效性。
 
+## 构造器项目声明
+
+`secretDetection` 有三类 overload：`secretDetection(options: SecretDetectionOptions<"secret-detection">)`
+保留默认 literal；`secretDetection<Id>(options: SecretDetectionOptions<Id> & { checkId: Id })` 保留 custom literal；
+已宽化为 `SecretDetectionOptions` 的变量返回 `string` identity。默认 `checkId` 是 `secret-detection`，默认 `displayName` 是 `Secret detection`；必填 `files` 以及
+`maximumFileBytes`、`maximumTotalBytes`、`maximumFileCount` 与 `findingWaivers` 仍是本 Check 的领域 options。
+
+例如，按变化选择一个只覆盖部署配置的独立 secret Check：
+
+```ts
+const deploymentSecrets = secretDetection({
+  checkId: "deployment-secrets",
+  enabledByFlags: { when: "deployment-changed" },
+  files: { source: "filesystem", include: ["deploy/**/*"], exclude: [] }
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
 ## 最小用法
 
 示例保留终端进度，不写 machine files。
@@ -27,8 +47,7 @@ if (result.kind !== "completed" || outcome?.status !== "passed") {
 }
 ```
 
-本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
-显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -51,8 +70,10 @@ options 不接受 arbitrary regex、command、baseline、detector allowlist 或
 ## 工作原理
 
 1. 按显式 `files` 收集 exact project-relative paths，先应用文件数限制。
-2. 在本仓库验证的 POSIX Node runtime 中，以 `O_NOFOLLOW` 打开 final leaf；在同一 descriptor 上检查 regular-file、size，
-   并在单文件/剩余总预算内分块读取。未满足安全读取条件的路径不获 detector coverage。
+2. 在受支持 POSIX runtime 中，先用 `lstat` 取得 final leaf 的 regular-file 身份，再以 `O_NOFOLLOW` 打开 descriptor，
+   并要求 descriptor 的 device/inode 身份与路径身份一致。随后在同一 descriptor 上检查 size，并在单文件/剩余总预算内
+   分块读取。symlink、无可靠文件身份或身份在打开前变化的路径不获 detector coverage。Windows 分支会以 read-only flag
+   尝试同一身份握手，避免仅因平台缺少 `O_NOFOLLOW` 就预先拒绝普通文件；这是 portability optimization，不扩展受支持平台契约。
 3. 成功读取后检查 NUL 与 fatal UTF-8，只有 approved text 交给 private adapter；它不接收 project root，也不重新枚举文件。
 
 adapter 固定使用 [Secretlint v13.0.5](https://github.com/secretlint/secretlint/releases/tag/v13.0.5) 中 MIT-licensed 的
@@ -112,7 +133,8 @@ const check = secretDetection({
 
 - NUL、invalid UTF-8、单文件/总 bytes/文件数超限是 deterministic `coverage-gap`，使 Check `failed`。
   成功 descriptor read 的 raw bytes 先消耗总预算，即使随后成为 non-text gap。
-- symlink、非 regular file、read/change failure 或 runtime 不支持 `O_NOFOLLOW` descriptor open：`source-unavailable`。
+- symlink、非 regular file、无法取得可靠 device/inode 身份、open 前身份变化、POSIX 不支持 `O_NOFOLLOW` 或 read/change
+  failure：`source-unavailable`。
 - whole-Check `unavailable` 的 closed reasons 为 `invalid-options`、`scan-input-unavailable`、`source-unavailable`、
   `detector-unavailable`、`detector-protocol-failed`、`execution-cancelled`。它们附同 code 的 error message，无 final data 或 partial result。
 
@@ -121,8 +143,10 @@ const check = secretDetection({
 I/O 只限 files 选择的 local paths；无 command、network、history、environment、home、binary 或 remote secret-manager I/O。
 raw detector material 不进入 result、Record、message、machine output、cache、log 或 error。
 
-POSIX no-follow 只绑定 final leaf；Node 没有 portable `openat`/dirfd traversal，无法保证中间目录或已打开 inode 不被恶意并发替换。
-需要该隔离级别时，调用方须使用 OS-level sandbox。
+这些检查只绑定 final leaf；Node 没有 portable `openat`/dirfd traversal，无法保证中间目录不被恶意并发替换，也无法排除
+已打开 inode 的同长度并发写入。Windows portability branch 未经本次原生 Windows 文件系统验证；路径若在 `lstat` 后被换为
+redirection，底层 open 可能取得目标 descriptor，但身份不匹配时不会读取或交给 detector。需要已承诺的 POSIX 边界之外的
+平台保证或更强隔离时，调用方须自行验证目标 runtime，并使用 OS-level sandbox。
 
 ## 适用边界
 

package/docs/examples/artifacts/mixed-outcomes/definition.ts

@@ -12,7 +12,7 @@ const packageManifest = jsonValidation({
   files: { include: ["package.json"] }
 });
 
-// 一个 typed provider：preflight 用 fallback 准备 invocation-local options。
+// 一个 typed provider：preparation 用 fallback 准备 invocation-local options。
 const releaseInputs = defineCheck({
   checkId: "example-release-inputs",
   displayName: "Example release inputs",
@@ -29,7 +29,7 @@ const releaseInputs = defineCheck({
     }
     return { files: [...files], version: 1 };
   },
-  preflight(options) {
+  prepare(options) {
     if (options.files.length > 0) {
       return { status: "success", preparedOptions: options };
     }
@@ -47,8 +47,8 @@ const releaseInputs = defineCheck({
       ]
     };
   },
-  visibility: "attention",
-  execution({ options, signal }) {
+  omitQuietPassedRow: true,
+  execute({ options, signal }) {
     if (signal.aborted) {
       return { status: "unavailable", reason: { code: "execution-cancelled" } };
     }
@@ -65,8 +65,8 @@ const releasePolicy = defineCheck({
   displayName: "Example release policy",
   observes: inherit({ add: [releaseInputs.checkId] }),
   options: { minimumFileCount: 2 },
-  visibility: "attention",
-  execution({ dependencies, options, records }) {
+  omitQuietPassedRow: true,
+  execute({ dependencies, options, records }) {
     const manifestRead = dependencies.get(packageManifest.checkId);
     if (!manifestRead.ok) {
       return {
@@ -145,18 +145,18 @@ const optionalDocumentation = defineCheck({
   checkId: "example-optional-documentation",
   displayName: "Example optional documentation",
   options: { enabled: false },
-  execution: ({ options }) =>
+  execute: ({ options }) =>
     options.enabled
       ? { status: "passed", data: { reviewed: true } }
       : { status: "not-applicable", reason: { code: "documentation-disabled" } }
 });
 
-// block preflight 只阻止本 Check 的 execution，并将其结算为 unavailable；不相关的 Check 仍可并行。
+// block preparation 只阻止本 Check 的 execution，并将其结算为 unavailable；不相关的 Check 仍可并行。
 const externalReview = defineCheck({
   checkId: "example-external-review",
   displayName: "Example external review",
   options: { serviceConfigured: false },
-  preflight(options) {
+  prepare(options) {
     if (options.serviceConfigured) {
       return { status: "success", preparedOptions: options };
     }
@@ -173,7 +173,7 @@ const externalReview = defineCheck({
       ]
     };
   },
-  execution: () => ({ status: "passed", data: { reviewed: true } })
+  execute: () => ({ status: "passed", data: { reviewed: true } })
 });
 
 // 组织节点自身不产生 outcome；children 继承 packageManifest observation 和并行预算。