svharness 0.14.2 → 0.14.7

package/templates/_shared/build-rules/harness-build-rule-specs-schema.md

@@ -20,24 +20,28 @@ specs/
 - 字段增减/重命名时，`schema.json` 与对应 yaml 必须**同一提交**更新，不得分两步。
 - yaml 中不得出现任何具体 agent 名（qoder/codechat/cursor/claude-code/opencode 等）— 违反 agent-agnostic 铁律。
 
-## requirements 追溯字段建议（S40/S50 配套）
+## requirements 追溯字段要求（S40/S50 配套）
 
-为提升 requirements/specs 完整性，`requirements/yaml/*.requirements.yaml` 的条目建议包含：
+为提升 requirements/specs 完整性，`requirements/yaml/*.requirements.yaml` 的条目必须包含：
 
+- `title`: 条目短索引标题（仅用于导航与表格展示）
+- `source_excerpt`: 源文档原文摘录（可多行）
+- `description`: 完整需求陈述（不得弱于 source_excerpt）
 - `source_anchor`: 可追踪源锚点（如 `SyRD-*`、章节+行号）
-- `source_file`: 源文件路径（通常在 `requirements/raw/`）
+- `source_file`: Agent 可读的文本源路径——`requirements/md/<同名>.md`（convert 产物）或 `requirements/raw/` 下的 md/txt/代码文件；禁止引用 xlsx/pdf/docx 等难解析格式
 - `source_section`: 源章节或表格区域
 - `aggregates`: 聚合锚点列表（仅在显式聚合时）
 - `aggregation_reason`: 聚合原因（聚合时必填）
 - `waived`: 是否作为门禁豁免项
 - `waived_reason`: 豁免原因（waived 为 true 时必填）
 
-以上为推荐字段，不改变四域 specs 的 schema 强约束。
+以上要求与 `requirements/yaml/schema.json` 保持一致；不满足时不得推进到 S50。
 
 ## 校验节点
 
 - S50_generate_specs 退出前：所有 yaml 逐一过 schema 校验，失败则阶段状态置 FAILED。
 - 后续阶段读取 specs 时不做 schema 校验（已由 S50 把关），但仍不得修改已冻结字段。
+- specs 内容不得退化为索引式占位（仅 `id`/`name` 且缺少语义字段）；发现此类情况应在 S50 判为失败或在 S85 记 Critical。
 
 ## 正反例
 

package/templates/_shared/build-skills/harness-build-skill-pre-seal-review.md

@@ -62,6 +62,7 @@ profile 提供：`min_depth_score`、`dimension_weights`、`critical_patterns`
 **阶段合规**：对照 `.harness-build-state.yaml`，S00–S80 在封存前应 DONE（S10_wiki 若不存在则跳过）。
 
 **可追溯**：若存在 `requirements/yaml/*.yaml`，每条需求须在已声明 spec 层有映射、`aggregates` 或合法 `waived`。
+**完整性抽检**：随机抽检至少 5 条（或按规模取样），校验 `description` 是否覆盖 `source_excerpt` 中的条件、数值、枚举、时序。
 
 **其它**：references/wiki 一致性；构建期表单确认（`harness-build-rule-user-interaction`）；中文与 agent-agnostic 扫尾。
 
@@ -89,6 +90,7 @@ Part A 结论写入报告「Part A 清单」章节，逐项 PASS/WARN/FAIL/N/A
 - 索引式 ID 占比（如 `CMDID_<模块>_<编号>` 且无 `enum_values`/`can_msg_id`）
 - 方向分布：仅 `car2hmi` 无 `hmi2car` → WARN/FAIL
 - 字段深度：仅 id/name/direction/type/traces_to → 索引式
+- 对 `enum` 类型：缺少 `enum_values` 视为深度不足（至少 WARN，可按 profile 记 Critical）
 
 **若 profile 提供 `oem_signal_name_patterns`**：计算 OEM 名占比；`< threshold` → 索引式规格（模式 P1，可 Critical）。
 
@@ -96,6 +98,7 @@ Part A 结论写入报告「Part A 清单」章节，逐项 PASS/WARN/FAIL/N/A
 
 - `req_count / state_count` > profile 阈值 → 严重不足（P4）
 - `transitions < states * 1.5` → WARN
+- `guard` / `action` 为空或出现「见需求」「TBD」占位语义 → WARN/FAIL
 
 ### 维度 4：interfaces 契约（仅当存在 specs/interfaces）
 

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

@@ -44,10 +44,18 @@ items:
   - id: REQ-<MODULE>-001
     category: functional | non-functional | constraint
     priority: must | should | may
-    description: "一句话陈述需求"
+    title: "短索引标题（用于表格与路由）"
+    source_excerpt: |
+      从 source_anchor 对应原文复制的完整摘录（允许多行）。
+      必须保留条件、数值、枚举、时序等关键信息。
+    description: |
+      基于 source_excerpt 的完整需求陈述。
+      允许整理语序，但信息集合不得缩小。
     acceptance: "如何验证该需求满足"
     source_anchor: "SyRD-..."
-    source_file: "requirements/raw/<file>"
+    # AI 可读文本源（二选一，禁止引用 xlsx/pdf/docx 等难解析格式）：
+    source_file: "requirements/md/<file>.md"          # 原始为 pdf/xlsx/docx 等 → 引用 convert 产物
+    # source_file: "requirements/raw/<file>.md"       # 或 raw 下本身可读的 md/txt/代码文件
     source_section: "01_Function Spec"
     aggregates: []
     waived: false
@@ -58,10 +66,17 @@ items:
 规则：
 - 条目 id **稳定**：一旦产出不得改写，新条目追加。
 - 有可追踪锚点时默认 1:1 条目化（细不能粗）。
-- 每条 `description` 必须是一句清晰陈述，不得写成聚合摘要。
+- `title` 仅作索引；不得把 `title` 充当完整需求描述。
+- `source_excerpt` 必须来自源文档原文；禁止写成「见上文」「同前」等替代语。
+- `description` 必须覆盖 `source_excerpt` 的关键约束；不得删减条件、数值、枚举、时序。
 - `traces_to` 初始可为空，阶段 B 生成 specs 后回填。
-- `source_doc` 与 `source_file` 必须引用真实源文件。
+- `source_doc` 记录原始入库路径（`requirements/raw/<原始文件名>`），用于资产追溯。
+- `source_file` 必须指向 **Agent 可直接读取的文本源**，路径二选一：
+  - `requirements/md/<同名>.md` —— 原始为 pdf/xlsx/docx 等时，引用 S30 convert 后的 Markdown；
+  - `requirements/raw/<file>` —— 原始本身即为 `.md`、`.txt` 或源代码文件（如 `.kt`、`.xml`、`.proto` 等）。
+  - **禁止**将 `requirements/raw/` 下的 xlsx、pdf、docx、图片等 AI 难处理格式写入 `source_file`。
 - 聚合仅在用户确认后允许，且必须带 `aggregates + aggregation_reason`。
+- 产出后必须校验 `requirements/yaml/schema.json`（若存在）；失败不得进入 S50。
 
 ### 阶段 B：requirements → specs（规格生成）
 
@@ -71,7 +86,11 @@ items:
 2. 读取 `__HARNESS_ROOT__specs/<layer>/schema.json`。
 3. 生成 `__HARNESS_ROOT__specs/<layer>/<module>.<layer>.yaml`，要求：
    - 满足 schema（所有 `required` 字段完备、`enum` 取值合法）
-   - 在本层的语义内回答相关需求条目
+   - 在本层语义内完整回答相关需求条目，禁止仅保留索引占位
+   - `signals`：除 `id` 外须补全 `name`、`direction`、`type`；`type=enum` 时必须有 `enum_values`
+   - `behavior`：`transitions[].guard/action` 应为可执行陈述，禁止「见需求」占位
+   - `ui`：`components[].states[].condition` 必须写出具体触发条件并可追溯到 REQ
+   - `interfaces`：`methods[].description` 需包含参数语义与返回约束，不得仅列方法名
 4. 回填 `traces_to`：在 `requirements` 中把 spec 的路径/锚点记回对应条目。
 5. 校验 YAML 是否通过 schema（优先使用本地校验器；若无，对照 schema 的 `required` 与 `enum` 手动核对）。
 6. 生成 S40 覆盖率报告：`__HARNESS_ROOT__requirements/coverage-report.yaml`，至少包含：
@@ -80,7 +99,8 @@ items:
 extraction_strategy: md_primary
 generated_at: "..."
 sources:
-  - file: "requirements/raw/<file>"
+  - file: "requirements/md/<file>.md"   # 或 requirements/raw/<可读文本文件>
+    source_doc: "requirements/raw/<原始文件>"   # 可选，保留原始资产路径
     anchors_total: 100
     anchors_mapped: 96
     anchors_waived: 4
@@ -91,6 +111,25 @@ waived:
 unmapped: []
 ```
 
+7. 生成 S50 规格覆盖率报告：`__HARNESS_ROOT__specs/coverage-report.yaml`，至少包含：
+
+```yaml
+generated_at: "..."
+module: "<module>"
+requirements_total: 120
+requirements_mapped: 116
+requirements_waived: 4
+mapping_ratio: 0.967
+layers:
+  - name: signals
+    req_mapped: 80
+    quality_flags: []
+  - name: behavior
+    req_mapped: 20
+    quality_flags: []
+critical_gaps: []
+```
+
 ## 状态更新
 
 每完成一个模块后：
@@ -101,8 +140,10 @@ unmapped: []
 
 在 S40 标 DONE 前必须输出表格并经用户确认：
 
-- 列：`源 ID | YAML REQ ID | 状态(mapped/waived/gap)`
+- 列：`源 ID | YAML REQ ID | excerpt_len | desc_len | 缩略风险 | 状态(mapped/waived/gap)`
+- `缩略风险` 判定建议：`desc_len / excerpt_len < 0.5` 记 WARN；`< 0.25` 记 FAIL。
 - 若存在 `gap` 且未完成 waiver，**禁止**标记 `S40_extract_requirements: DONE`。
+- 若存在 `source_excerpt` 缺失、`description` 缩略 FAIL、或 schema 校验失败，**禁止**标记 DONE。
 
 ## 守则（不得违反）
 

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

@@ -100,6 +100,7 @@ __BUILD_MAIN_BRIDGE_HINT__
 |------|------|------|
 | `baseline/wiki/` | 项目知识摘要，优先建立上下文 | 只读 |
 | `baseline/code/` | 权威参考实现 | 只读 |
+| `baseline/repomix/repomix-pack.xml` | 可选：Repomix 整库 XML 快照（仅 build 启用 `--repomix` 时存在；见 `harness.yaml` → `baseline.repomix_pack`） | 只读 |
 | `specs/signals/` | 信号/协议规格 | 只读 |
 | `specs/ui/` | UI 规格 | 只读 |
 | `specs/behavior/` | 行为规格 | 只读 |
@@ -108,6 +109,10 @@ __BUILD_MAIN_BRIDGE_HINT__
 
 > `baseline/code/` 是“参考实现”的权威来源。  
 > 你仍需阅读并修改目标项目业务源码来完成交付，但不得把 `baseline/code/` 之外的路径当作规范样本来源。
+>
+> 若存在 `baseline/repomix/repomix-pack.xml`，清单字段为 `harness.yaml` → `baseline.repomix_pack`；`svharness apply` 会在项目根入口与本 skill 中注入详细用法。
+
+__REPOMIX_APPLY_HINT__
 
 ### 4.3 编码执行
 

package/templates/_shared/meta/harness.yaml.ejs

@@ -23,6 +23,7 @@ requirements:                            # 正式需求（参与条目化）
   raw: requirements/raw/                 #   S20_collect_inputs 用户入口
   md: requirements/md/                   #   convert 产物
   yaml: requirements/yaml/               #   S40 条目化产出
+  schema: requirements/yaml/schema.json  #   requirements 条目结构校验
   # requirements 输入路径（可选）：可记录外部需求文档来源（文件或目录）。
 <% if (requirementsPath) { -%>
   source: "<%= requirementsPath %>"
@@ -42,6 +43,7 @@ references:                              # 参考资料（不参与条目化）
 baseline:
   code: baseline/code/                   # 基线代码快照（参考样本）
   wiki: baseline/wiki/                   # 基线工程 wiki
+  # repomix_pack: baseline/repomix/repomix-pack.xml  # 仅 --repomix 成功后由 CLI 写入
 
 # Agent 运行时环境（规则、技能、工具、记忆）。
 # incoming_* 仅构建期：`svharness build --extra-skills` 将资源暂存于此并生成 manifest，S65 确认后分流写入 rules/skills。

package/templates/_shared/skeleton/requirements/yaml/schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "harness://requirements/yaml/schema.json",
+  "title": "需求条目 Schema",
+  "description": "描述 requirements/yaml 下的结构化需求条目，要求保留原文摘录与完整需求陈述。",
+  "type": "object",
+  "required": ["module", "source_doc", "extracted_at", "intake_profile", "items"],
+  "properties": {
+    "module": { "type": "string", "minLength": 1 },
+    "source_doc": { "type": "string", "minLength": 1 },
+    "extracted_at": { "type": "string", "format": "date-time" },
+    "intake_profile": {
+      "type": "object",
+      "required": ["extraction_strategy"],
+      "properties": {
+        "extraction_strategy": {
+          "type": "string",
+          "enum": ["md_primary", "raw_primary", "hybrid", "manual_assisted"]
+        }
+      },
+      "additionalProperties": true
+    },
+    "items": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "category",
+          "priority",
+          "title",
+          "source_excerpt",
+          "description",
+          "acceptance",
+          "source_anchor",
+          "source_file",
+          "source_section",
+          "aggregates",
+          "waived",
+          "traces_to"
+        ],
+        "properties": {
+          "id": { "type": "string", "pattern": "^REQ-[A-Z0-9_]+-\\d{3,}$" },
+          "category": { "type": "string", "enum": ["functional", "non-functional", "constraint"] },
+          "priority": { "type": "string", "enum": ["must", "should", "may"] },
+          "title": { "type": "string", "minLength": 2 },
+          "source_excerpt": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "acceptance": { "type": "string", "minLength": 1 },
+          "source_anchor": { "type": "string", "minLength": 1 },
+          "source_file": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Agent 可读文本源：requirements/md/<同名>.md（convert 产物）或 requirements/raw/ 下的 md/txt/代码文件；禁止 xlsx/pdf/docx 等"
+          },
+          "source_section": { "type": "string", "minLength": 1 },
+          "aggregates": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "aggregation_reason": { "type": "string" },
+          "waived": { "type": "boolean" },
+          "waived_reason": { "type": "string" },
+          "traces_to": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/templates/_shared/skeleton/specs/behavior/schema.json

@@ -6,7 +6,7 @@
   "type": "object",
   "required": ["module", "version", "states", "transitions"],
   "properties": {
-    "module": { "type": "string" },
+    "module": { "type": "string", "minLength": 1 },
     "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
     "initial_state": { "type": "string" },
     "states": {
@@ -15,8 +15,8 @@
         "type": "object",
         "required": ["name"],
         "properties": {
-          "name": { "type": "string" },
-          "description": { "type": "string" }
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 8 }
         }
       }
     },
@@ -26,11 +26,11 @@
         "type": "object",
         "required": ["from", "to", "trigger"],
         "properties": {
-          "from": { "type": "string" },
-          "to": { "type": "string" },
-          "trigger": { "type": "string" },
-          "guard": { "type": "string" },
-          "action": { "type": "string" }
+          "from": { "type": "string", "minLength": 1 },
+          "to": { "type": "string", "minLength": 1 },
+          "trigger": { "type": "string", "minLength": 1 },
+          "guard": { "type": "string", "minLength": 4 },
+          "action": { "type": "string", "minLength": 4 }
         }
       }
     }

package/templates/_shared/skeleton/specs/interfaces/schema.json

@@ -6,7 +6,7 @@
   "type": "object",
   "required": ["module", "version", "interfaces"],
   "properties": {
-    "module": { "type": "string" },
+    "module": { "type": "string", "minLength": 1 },
     "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
     "interfaces": {
       "type": "array",
@@ -14,7 +14,7 @@
         "type": "object",
         "required": ["name", "kind"],
         "properties": {
-          "name": { "type": "string" },
+          "name": { "type": "string", "minLength": 1 },
           "kind": { "type": "string", "enum": ["aidl", "http", "ipc", "binder", "custom"] },
           "methods": {
             "type": "array",
@@ -22,10 +22,10 @@
               "type": "object",
               "required": ["name"],
               "properties": {
-                "name": { "type": "string" },
+                "name": { "type": "string", "minLength": 1 },
                 "params": { "type": "array", "items": { "type": "object" } },
                 "returns": { "type": "string" },
-                "description": { "type": "string" }
+                "description": { "type": "string", "minLength": 8 }
               }
             }
           }

package/templates/_shared/skeleton/specs/signals/schema.json

@@ -15,13 +15,15 @@
         "required": ["id", "name", "direction", "type"],
         "properties": {
           "id": { "type": "string", "pattern": "^CMDID_[A-Z0-9_]+$" },
-          "name": { "type": "string" },
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 8 },
           "direction": { "type": "string", "enum": ["car2hmi", "hmi2car", "bidirectional"] },
           "type": { "type": "string", "enum": ["int", "bool", "enum", "byte-array", "float"] },
           "length_bytes": { "type": "integer", "minimum": 1 },
           "default": {},
           "enum_values": {
             "type": "array",
+            "minItems": 1,
             "items": { "type": "object", "required": ["value", "meaning"] }
           },
           "traces_to": {
@@ -29,6 +31,15 @@
             "items": { "type": "string" }
           }
         },
+        "allOf": [
+          {
+            "if": {
+              "properties": { "type": { "const": "enum" } },
+              "required": ["type"]
+            },
+            "then": { "required": ["enum_values"] }
+          }
+        ],
         "additionalProperties": true
       }
     }

package/templates/_shared/skeleton/specs/ui/schema.json

@@ -6,7 +6,7 @@
   "type": "object",
   "required": ["module", "version", "components"],
   "properties": {
-    "module": { "type": "string" },
+    "module": { "type": "string", "minLength": 1 },
     "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
     "figma_source": { "type": "string", "format": "uri" },
     "ue_spec_ref": { "type": "string" },
@@ -16,11 +16,12 @@
         "type": "object",
         "required": ["id", "type"],
         "properties": {
-          "id": { "type": "string" },
+          "id": { "type": "string", "minLength": 1 },
           "type": {
             "type": "string",
             "enum": ["Switch", "Slider", "Button", "Tab", "Checkbox", "RadioButton", "Text", "Image", "Custom"]
           },
+          "description": { "type": "string", "minLength": 8 },
           "figma_node_id": { "type": "string" },
           "bound_signal": { "type": "string" },
           "states": {
@@ -29,9 +30,9 @@
               "type": "object",
               "required": ["name"],
               "properties": {
-                "name": { "type": "string" },
+                "name": { "type": "string", "minLength": 1 },
                 "visual": { "type": "string" },
-                "condition": { "type": "string" }
+                "condition": { "type": "string", "minLength": 4 }
               }
             }
           }

package/templates/svharness.config.example.yaml

@@ -20,6 +20,9 @@ build:
   referencesNote: 设计稿与接口文档
   extraSkills:
     - ./team-skills/custom-skill
+  # Repomix：将 baseline/code 打成单文件 baseline/repomix/repomix-pack.xml（默认 false）
+  # 适合：大基线整库鸟瞰、外部单文件上下文工具、封存留档；日常 harness-build 不必开
+  repomix: false
   generateWiki: false
   wikiLang: zh
   force: false