svharness 0.13.5 → 0.14.2

package/templates/_shared/build-skills/harness-build-skill-spec-builder.md

@@ -1,14 +1,14 @@
 ---
 name: harness-build-skill-spec-builder
 description: >
-  将需求文档转化为结构化 specs。驱动 raw → requirements → specs 两阶段管线，
-  并对产物做 specs/*/schema.json 校验。当用户说"条目化需求"、"生成 specs"、"构建 signals/ui/behavior/interfaces specs"、
+  将需求文档转化为结构化 requirements/specs，并执行覆盖率门禁。驱动 inventory → requirements → specs 两阶段管线，
+  并对 S40/S50 的完整性进行阻断校验。当用户说"条目化需求"、"生成 specs"、"构建 signals/ui/behavior/interfaces specs"、
   "structure requirements"、或由 harness-build-skill-orchestrator 委派给本 skill 时触发。
 ---
 
 # harness-build-skill-spec-builder（规格构建器）
 
-你每次只处理一个模块，把原始需求转化为**可被 schema 校验通过**的 specs。
+你每次只处理一个模块，把原始需求转化为可追溯 requirements 与可被 schema 校验通过的 specs。
 
 ## 输入
 
@@ -20,36 +20,48 @@ description: >
 - `__HARNESS_ROOT__specs/<layer>/schema.json` —— 每一层的校验目标
 - `__HARNESS_ROOT__harness.yaml` —— 确认哪些层当前激活
 
-## 两阶段管线
+## 两阶段管线（S40 / S50）
 
 ### 阶段 A：raw → requirements（条目化）
 
 执行步骤（强制顺序）：
-1. 先对 `requirements/raw/` 执行 `svharness convert` 到 `requirements/md/`，示例：
+
+1. 先完成源清点，输出 `__HARNESS_ROOT__requirements/_work/source-inventory.yaml`：
+   - 记录可追踪锚点列表（`anchors[]`）与分类计数（`counts_by_kind`）。
+   - 同时声明 `intake_profile.extraction_strategy`：`md_primary | raw_primary | hybrid | manual_assisted`。
+2. 若 `requirements/md/` 缺失对应产物，先执行 convert（示例）：
    - `svharness convert --input "__HARNESS_ROOT__requirements/raw" --output "__HARNESS_ROOT__" --type requirements`
-2. 校验 `requirements/raw/` 中每个非 `.md`、非 `.gitkeep` 文件，都在 `requirements/md/` 有同基名 `.md` 产物；若缺失，停止条目化并以表单提示用户补齐转换。
-3. 基于 `requirements/md/` 的转换结果进行条目抽取，为 `requirements/raw/` 下每个源文件产出一个 `__HARNESS_ROOT__requirements/yaml/<module>.requirements.yaml`，结构如下：
+3. 若文档结构损失严重（例如大量 `NaN`、表头错位、锚点缺失），不得硬用 `md_primary`，改用 `raw_primary` 或 `hybrid`。
+4. 基于选定策略抽取 requirements，为每个模块产出 `__HARNESS_ROOT__requirements/yaml/<module>.requirements.yaml`，结构如下：
 
 ```yaml
 module: <module>
 source_doc: "requirements/raw/<file>"
 extracted_at: <ISO8601 日期>
+intake_profile:
+  extraction_strategy: md_primary | raw_primary | hybrid | manual_assisted
 items:
   - id: REQ-<MODULE>-001
     category: functional | non-functional | constraint
     priority: must | should | may
     description: "一句话陈述需求"
     acceptance: "如何验证该需求满足"
+    source_anchor: "SyRD-..."
+    source_file: "requirements/raw/<file>"
+    source_section: "01_Function Spec"
+    aggregates: []
+    waived: false
     traces_to:
       - specs/<layer>/<module>.<layer>.yaml#<anchor>
 ```
 
 规则：
 - 条目 id **稳定**：一旦产出不得改写，新条目追加。
-- 每条 `description` 必须是**一句清晰的陈述**。
+- 有可追踪锚点时默认 1:1 条目化（细不能粗）。
+- 每条 `description` 必须是一句清晰陈述，不得写成聚合摘要。
 - `traces_to` 初始可为空，阶段 B 生成 specs 后回填。
-- `source_doc` 必须引用 `requirements/raw/` 下真实文件。
-- **禁止跳过转换直接抽取**：不得直接从 `requirements/raw/` 读取 `.xlsx/.pdf/.docx` 等原始文件生成条目，必须通过 `requirements/md/` 中间层。
+- `source_doc` 与 `source_file` 必须引用真实源文件。
+- 聚合仅在用户确认后允许，且必须带 `aggregates + aggregation_reason`。
 
 ### 阶段 B：requirements → specs（规格生成）
 
@@ -62,13 +74,36 @@ items:
    - 在本层的语义内回答相关需求条目
 4. 回填 `traces_to`：在 `requirements` 中把 spec 的路径/锚点记回对应条目。
 5. 校验 YAML 是否通过 schema（优先使用本地校验器；若无，对照 schema 的 `required` 与 `enum` 手动核对）。
+6. 生成 S40 覆盖率报告：`__HARNESS_ROOT__requirements/coverage-report.yaml`，至少包含：
+
+```yaml
+extraction_strategy: md_primary
+generated_at: "..."
+sources:
+  - file: "requirements/raw/<file>"
+    anchors_total: 100
+    anchors_mapped: 96
+    anchors_waived: 4
+    coverage_ratio: 0.96
+waived:
+  - anchor: "SyRD-..."
+    reason: "..."
+unmapped: []
+```
 
 ## 状态更新
 
 每完成一个模块后：
-- 更新 `__HARNESS_ROOT__.harness-build-state.yaml`（阶段 S40 或 S50，带每层子状态）。
+- 更新 `__HARNESS_ROOT__.harness-build-state.yaml`（阶段 S40/S50，带 coverage 字段）。
 - 刷新状态文件与 spec 文件的 `updated_at`。
 
+### S40 出口阻断（必须执行）
+
+在 S40 标 DONE 前必须输出表格并经用户确认：
+
+- 列：`源 ID | YAML REQ ID | 状态(mapped/waived/gap)`
+- 若存在 `gap` 且未完成 waiver，**禁止**标记 `S40_extract_requirements: DONE`。
+
 ## 守则（不得违反）
 
 - **不得无中生有**：所有需求必须来自 `__HARNESS_ROOT__requirements/raw/`。`requirements/raw/` 为空或仅含 `.gitkeep` 时，**必须以表单方式提示用户放入需求文档**，禁止自行生成占位内容。
@@ -85,6 +120,7 @@ items:
 随 agent 可能为 `.md` 或 `.mdc`）：
 
 - `harness-build-rule-convert-check` — 本 skill 消费 `requirements/md/` 与 `references/md/`，上游 S30_convert_docs 缺漏时拒绝条目化。
+- `harness-build-rule-requirements-extraction` — S40 提取策略、细粒度要求与覆盖率门禁。
 - `harness-build-rule-specs-schema` — specs 四域固定、schema.json 必过、字段增减需同步。
 - `harness-build-rule-orchestrator-flow` — 本 skill 仅服务 S40/S50，禁止跨阶段跳步。
 - `harness-build-rule-agent-agnostic` — 生成的 requirements/specs YAML 严禁出现具体 agent 名或私有语法。

package/templates/_shared/build-skills/harness-build-skills-main.md

@@ -37,11 +37,13 @@ skills 等**构建阶段**工作时，你不直接越级写产物，而是先完
 | id | 职责 | 典型触发 |
 |----|------|----------|
 | `harness-build-skill-orchestrator` | 读取状态机、输出状态卡片、阶段推进、更新 `next_action` | 「开始构建 harness」「继续 harness」「harness 进度」 |
-| `harness-build-skill-spec-builder` | raw → requirements YAML → specs YAML（schema 校验） | S40 / S50 阶段 |
+| `harness-build-skill-spec-builder` | inventory → requirements YAML → specs YAML（schema + 覆盖率门禁） | S40 / S50 阶段 |
 | `harness-build-skill-references-intake` | references 转换与结构化索引 | S60 阶段 |
 | `harness-build-skill-agent-env-merge` | baseline 自动提取确认 + extra-skills/rules 合并写入 | S61 / S65 阶段 |
 | `harness-build-skill-knowledge-builder` | baseline 样本 + runtime skills/tasks 索引 | S10(子任务) / S70 阶段 |
 | `harness-build-skill-wiki-writer` | 按 `baseline/wiki/TASKS.md` 逐页撰写 wiki | S10_wiki PENDING |
+| `harness-build-skill-pre-seal-review` | S85 合并审查（Part A 完整性 + Part B 深度质量，`HARNESS-REVIEW-REPORT.md`，C 级门禁） | S85 阶段 |
+| `harness-build-harness-data-review` | **已合并** → 使用 `harness-build-skill-pre-seal-review` | S85（兼容别名） |
 
 以上子 skill 的完整正文位于 `__HARNESS_BUILD_SKILLS_DIR__/<id>/` 下（文件名随 Agent 为 `SKILL.md` 或 `SKILL.mdc`）。
 

package/templates/_shared/meta/README.md.ejs

@@ -33,7 +33,8 @@
 7. **S65_customize_agent_env** —— 对 extra-skills/extra-rules（及已确认启用的 baseline 提取候选）执行合并写入；来源可来自 `_incoming/manifest.yaml`；冲突时"建议 → 确认 → 写入"
 8. **S70_runtime_assets** —— 产出运行期 skills 与 tasks（skills 是能力积木，tasks 是流程模板）
 9. **S80_seed_memory** —— Agent 播种初始 memory 分类
-10. **S90_finalize** —— `svharnessbuild seal` 将 `bootstrap_mode` 翻转为 false
+10. **S85_pre_seal_validation** —— `svharness doctor` 硬检查 + 全面语义审查
+11. **S90_finalize** —— 版本 bump、CHANGELOG、将 `bootstrap_mode` 翻转为 false
 
 ## 常用命令
 

package/templates/_shared/meta/task_list.md.ejs

@@ -0,0 +1,44 @@
+# task_list（阶段门禁清单）
+
+本清单在 `svharness build` 初始化时自动生成，用于人类可读的阶段执行与验收跟踪。
+
+- 项目：`<%= name %>`
+- 架构：`<%= arch %>`
+- 生成时间：`<%= createdAt %>`
+
+## 同步规则（避免双份真相）
+
+1. 机器状态以 `.harness-build-state.yaml` 为准。
+2. 本文件作为可读镜像；阶段推进时需同步更新勾选项。
+3. 如本文件与 state 冲突，以 state 为准并回写本文件。
+
+## S40_extract_requirements 门禁清单
+
+- [ ] 已生成并确认 `requirements/_work/source-inventory.yaml`
+- [ ] 已完成细粒度 requirements 条目化（可追踪锚点默认 1:1）
+- [ ] 已生成 `requirements/coverage-report.yaml`
+- [ ] 已处理 `gap/waiver`，且未闭环项已完成用户确认
+- [ ] 满足 DONE 条件后，state 标记 `S40_extract_requirements: DONE`
+
+## S50_generate_specs 门禁清单
+
+- [ ] 已产出四域 specs（signals/ui/behavior/interfaces）对应 YAML
+- [ ] REQ → spec 映射已建立（无映射项需显式 N/A 理由）
+- [ ] 已生成 specs 覆盖率结果（写入 state 或报告）
+- [ ] 满足 DONE 条件后，state 标记 `S50_generate_specs: DONE`
+
+## S85_pre_seal_validation 门禁清单
+
+- [ ] 已执行 `svharness doctor --mode pre-seal` 且 exit code = 0
+- [ ] 已产出 `HARNESS-REVIEW-REPORT.md`（含 Part A 完整性 + Part B 深度评分）
+- [ ] 报告 frontmatter：`gate_pass: true`，`overall_score >= 5.0`（C 级），`critical_count: 0`
+- [ ] 报告包含：源锚点/REQ→spec 覆盖率、深度 metrics、差距表与 Top-5 修复
+- [ ] 对 doctor warning 给出保留理由或修复说明
+- [ ] 审查结论已用户表单确认
+- [ ] state 已写入 `review_report_path`、`depth_review_score`、`review_gate_pass: true`
+- [ ] 满足 DONE 条件后，state 标记 `S85_pre_seal_validation: DONE`
+
+## 备注
+
+- 本文件不替代 state，仅用于可读性与协作审查。
+- 如阶段门禁规则升级，请同步更新本模板与相关 build-rules/build-skills。

package/templates/_shared/skeleton/agent-env/review-profiles/_default.yaml

@@ -0,0 +1,64 @@
+# 通用深度审查 profile（arch-agnostic）
+# S85 Part B 在未找到 <arch>.yaml 时使用本文件。
+schema_version: "1.0"
+min_depth_score: 5.0
+min_depth_grade: C
+
+dimension_weights:
+  quantitative_coverage: 0.20
+  signals_depth: 0.25
+  behavior_states: 0.15
+  interfaces_contract: 0.10
+  ui_authenticity: 0.15
+  source_data_integrity: 0.10
+
+# 仅当 harness.yaml specs.layers 含对应 name 时启用该维度
+layer_gates:
+  signals: signals_depth
+  behavior: behavior_states
+  interfaces: interfaces_contract
+  ui: ui_authenticity
+
+critical_patterns:
+  - id: P9
+    name: coverage_report_dishonest
+    severity: Critical
+    description: quantity_coverage=1.0 但 Part B 存在显著定性差距
+  - id: P7
+    name: bound_reference_broken
+    severity: Critical
+    description: UI/规格 bound_* 引用不存在的 ID
+  - id: P3
+    name: source_table_not_extracted
+    severity: Critical
+    description: 源 MD 大表区段未条目化到 specs（启发式）
+    requires_md_section: true
+
+heuristics:
+  index_signal_id_ratio_threshold: 0.80
+  oem_name_ratio_threshold: 0.20
+  req_per_state_ratio_warn: 10
+  req_per_state_ratio_fail: 20
+  nan_count_warn: 100
+  methods_empty_ratio_fail: 0.90
+  condition_truncated_chars: 80
+
+md_section_discovery:
+  # 不写死业务表名；用正则发现「大表格区段」
+  table_section_title_patterns:
+    - "(?i)signal\\s*list"
+    - "(?i)信号列表"
+    - "(?i)signal\\s*table"
+  function_spec_title_patterns:
+    - "(?i)function\\s*spec"
+    - "(?i)功能规格"
+    - "(?i)01_function"
+
+report:
+  filename: HARNESS-REVIEW-REPORT.md
+  frontmatter_required:
+    - review_version
+    - overall_score
+    - overall_grade
+    - critical_count
+    - gate_pass

package/templates/_shared/skeleton/agent-env/review-profiles/android-compose.yaml

@@ -0,0 +1,35 @@
+# android-compose 架构深度审查 profile（叠加 _default.yaml）
+schema_version: "1.0"
+extends: _default.yaml
+arch: android-compose
+
+# 车载 / Compose 域专有启发式（仅在本 arch 启用）
+oem_signal_name_patterns:
+  - "^P_[A-Z0-9_]+$"
+  - "^A_[A-Z0-9_]+$"
+  - "^L_[A-Z0-9_]+$"
+  - "^PCNOWDSP$"
+  - "^PCHGTM"
+  - "^CL_[A-Z0-9_]+$"
+  - "^M_[A-Z0-9_]+$"
+
+index_signal_id_patterns:
+  - "^CMDID_CHARGING_"
+  - "^Charging_[0-9_]+$"
+
+md_section_discovery:
+  table_section_title_patterns:
+    - "(?i)02[\\\\_]*signal[\\\\_]*list"
+    - "(?i)signal\\s*list"
+    - "(?i)信号列表"
+  syrd_anchor_pattern: "SyRD-[A-Za-z0-9-]+"
+
+signals_depth:
+  require_hmi2car_when_operate_signals_in_source: true
+  prefer_can_msg_id: true
+
+additional_critical_patterns:
+  - id: P1
+    name: index_only_signals
+    severity: Critical
+    description: 信号规格主要为索引式占位，缺少 OEM 命名或物理/协议字段

package/templates/svharness.config.example.yaml

@@ -35,6 +35,14 @@ apply:
   consistency: basic
   yes: true
 
+# doctor：封存前硬检查（S85 阶段 Agent 亦须调用）
+doctor:
+  harness: ./my-app-harness
+  mode: pre-seal
+  format: json
+  strict: false
+  verbose: false
+
 # convert：output 无 harness.yaml 时写入该目录；有 harness.yaml 时写入 <output>/<type>/md/
 convert:
   input: