---
name: hook-product-structure-validation
type: pattern
when: 'L4校验, 产物结构, check_write, check_bash, artifact_validator'
scope: ['*']
products:
  - '*'
id: cap-kdoc-write-artifact-validator
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
priority: P2
specificity: 2
version: 1.1.0
last_reviewed: '2026-06-01'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
stages: ["*"]
owner_mechanism_id: mc-engine-runtime
---

# Hook 层产物结构校验

## 概述

在 check_write 和 check_bash 的写入钩子中增加 L4 产物结构校验。
当写入已知产物类型的 .md 文件时，自动校验结构完整性。

## 何时使用

- 当 AI 通过 write 工具或 bash 命令写入 .md 产物文件时自动触发
- 当需要验证产物文档是否满足 Schema 定义的结构约束时

## 是否 hard block

advisory — L4 校验初始为 advisory（warning 为主），不 hard block 正常写入流程。
仅当严重缺失（≥ 3 个问题 + ≥ 2 个章节缺失）时才 blocked。
后续根据误报率数据决定是否升级为 enforced。

## 证据要求

- 路径推断（ARTIFACT_ALIASES + .soloforge/output/）测试通过
- 内容校验（完整内容 pass / 部分缺失 warning / 严重缺失 blocked）测试通过
- 非 .md 文件和短内容直接跳过

## 人工确认/降级边界

- L4 校验不阻断首次产物生成（首次可能为草稿）
- blocked 时人工可确认跳过
- 无法推断产物类型的文件自动 pass

## 校验流程

1. 从文件路径推断产物类型
2. 从 Schema 注册中心获取结构定义
3. 校验必填章节和表格
4. 根据缺失程度判定：pass / warning / blocked
