svharness 0.14.2 → 0.14.5

package/README.md

@@ -109,7 +109,7 @@ Harness 是一个 **项目本地的知识层**，由两大部分组成：
 ├── requirements/                   # 正式需求（参与条目化）
 │   ├── raw/                        #   S20_collect_inputs 用户入口
 │   ├── md/                         #   convert 产物
-│   └── yaml/                       #   S40 条目化产出
+│   └── yaml/                       #   S40 条目化产出（含 schema.json）
 ├── references/                     # 参考资料（不参与条目化）
 │   ├── raw/
 │   ├── md/
@@ -185,8 +185,8 @@ harness-build-{skill|rule}-<semantic-name>
 | **S10_wiki** | 构建 baseline wiki（仅当有 baseline 时出现，项目经验底座） | `baseline/wiki/` |
 | **S20_collect_inputs** | 添加相关文件：需求/参考文档 + 额外运行期资源征询（`--extra-skills` 单入口，可混放 skills/rules） | `requirements/raw/` + `references/raw/` + `agent-env/_incoming/skills/` + `task_list.md` |
 | **S30_convert_docs** | 非 Markdown 原始文档转 Markdown | `requirements/md/` + `references/md/` |
-| **S40_extract_requirements** | 条目化需求 + 覆盖率门禁 | `requirements/yaml/*.yaml` + `requirements/coverage-report.yaml` |
-| **S50_generate_specs** | 生成规格 + REQ→spec 覆盖 | `specs/<layer>/<module>.<layer>.yaml` + schema 校验 + 覆盖率结果 |
+| **S40_extract_requirements** | 条目化需求 + 覆盖率门禁 + 保真门禁（`title/source_excerpt/description`） | `requirements/yaml/*.yaml` + `requirements/yaml/schema.json` + `requirements/coverage-report.yaml` |
+| **S50_generate_specs** | 生成规格 + REQ→spec 覆盖 + 深度门禁（非 index-only） | `specs/<layer>/<module>.<layer>.yaml` + schema 校验 + 覆盖率结果 |
 | **S60_process_references** | references 处理（`svharness convert` + 结构化索引 + 用户确认落地） | `references/md/` |
 | **S61_confirm_baseline_extraction** | 确认是否自动从 baseline 提取 skills/rules（表单确认） | `.harness-build-state.yaml`（`phases.S61_confirm_baseline_extraction.baseline_auto_extract`） |
 | **S65_customize_agent_env** | agent-env 定制（extra-skills/extra-rules 冲突建议与重命名建议 → 用户确认 → 写入） | `agent-env/rules/` + `agent-env/skills/` |
@@ -426,6 +426,10 @@ svharness doctor --harness ./my-app-harness --mode pre-seal --format json --repo
 - **门禁**：`overall_score >= 5.0`（C 级）、`critical_count == 0`、报告 frontmatter `gate_pass: true`、用户表单确认
 
 `doctor` 另含 `check-review-report`（warning）：S85 已 DONE 时校验报告 frontmatter 与 state 中 `review_gate_pass` 一致。数量覆盖率阻断仍由 S40/S50 表单门禁负责。
+同时新增：
+
+- `check-requirements-fidelity`：检查 `source_excerpt` 缺失、`description` 缩略与占位语义。
+- `check-specs-depth`：检查 index-only 信号、enum 缺失 `enum_values`、behavior 空 `guard/action`。
 
 ### `convert` —— 文档 → Markdown 预处理（对接 S20_collect_inputs）
 

package/dist/commands/doctor/check-requirements-fidelity.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkRequirementsFidelity = checkRequirementsFidelity;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const utils_1 = require("./utils");
+const TRUNCATION_HINT_RE = /(详见原文|见上文|同前|tbd|placeholder|…|\.{3,})/i;
+const MIN_EXCERPT_LEN = 20;
+const WARN_RATIO = 0.5;
+const ERROR_RATIO = 0.25;
+function normalizeLength(v) {
+    if (typeof v !== 'string')
+        return 0;
+    return v.replace(/\s+/g, '').length;
+}
+async function checkRequirementsFidelity(ctx) {
+    const id = 'requirements-fidelity';
+    const findings = [];
+    const yamlDir = node_path_1.default.join(ctx.harnessRoot, 'requirements', 'yaml');
+    const reqYamlFiles = (await (0, utils_1.listRealFilesRecursive)(yamlDir, { extensions: ['.yaml', '.yml'] })).filter((f) => !f.endsWith('schema.json'));
+    for (const yamlFile of reqYamlFiles) {
+        let parsed;
+        try {
+            parsed = js_yaml_1.default.load(await fs_extra_1.default.readFile(yamlFile, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const items = parsed?.items;
+        if (!Array.isArray(items))
+            continue;
+        for (const [idx, item] of items.entries()) {
+            const obj = (item ?? {});
+            const itemId = typeof obj.id === 'string' ? obj.id : `#${idx + 1}`;
+            const excerpt = typeof obj.source_excerpt === 'string' ? obj.source_excerpt : '';
+            const desc = typeof obj.description === 'string' ? obj.description : '';
+            const excerptLen = normalizeLength(excerpt);
+            const descLen = normalizeLength(desc);
+            const ratio = excerptLen > 0 ? descLen / excerptLen : 1;
+            const itemPath = `${(0, utils_1.rel)(ctx.harnessRoot, yamlFile)}:${itemId}`;
+            if (excerptLen === 0) {
+                findings.push({
+                    checkId: id,
+                    severity: 'error',
+                    message: 'source_excerpt 为空，无法证明需求保留了源文档信息',
+                    path: itemPath,
+                });
+            }
+            else if (excerptLen < MIN_EXCERPT_LEN) {
+                findings.push({
+                    checkId: id,
+                    severity: 'warning',
+                    message: `source_excerpt 过短（${excerptLen}），建议补充完整原文摘录`,
+                    path: itemPath,
+                });
+            }
+            if (!desc.trim()) {
+                findings.push({
+                    checkId: id,
+                    severity: 'error',
+                    message: 'description 为空，缺少完整需求陈述',
+                    path: itemPath,
+                });
+            }
+            else if (ratio < ERROR_RATIO) {
+                findings.push({
+                    checkId: id,
+                    severity: ctx.mode === 'pre-seal' ? 'error' : 'warning',
+                    message: `description 相对 source_excerpt 明显缩略（ratio=${ratio.toFixed(2)}）`,
+                    path: itemPath,
+                });
+            }
+            else if (ratio < WARN_RATIO) {
+                findings.push({
+                    checkId: id,
+                    severity: 'warning',
+                    message: `description 可能缩略 source_excerpt（ratio=${ratio.toFixed(2)}）`,
+                    path: itemPath,
+                });
+            }
+            if (TRUNCATION_HINT_RE.test(excerpt) || TRUNCATION_HINT_RE.test(desc)) {
+                findings.push({
+                    checkId: id,
+                    severity: 'warning',
+                    message: '检测到截断/占位语义（如 详见原文、TBD、placeholder）',
+                    path: itemPath,
+                });
+            }
+        }
+    }
+    return { id, title: '需求保真度', findings };
+}

package/dist/commands/doctor/check-requirements.js

@@ -7,6 +7,8 @@ exports.checkRequirements = checkRequirements;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const node_path_1 = __importDefault(require("node:path"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
+const ajv_1 = __importDefault(require("ajv"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
 const utils_1 = require("./utils");
 async function checkRequirements(ctx) {
     const id = 'requirements';
@@ -35,6 +37,24 @@ async function checkRequirements(ctx) {
         }
     }
     else {
+        const schemaPath = node_path_1.default.join(yamlDir, 'schema.json');
+        let validate;
+        if (await fs_extra_1.default.pathExists(schemaPath)) {
+            try {
+                const schema = JSON.parse(await fs_extra_1.default.readFile(schemaPath, 'utf8'));
+                const ajv = new ajv_1.default({ allErrors: true, strict: false });
+                (0, ajv_formats_1.default)(ajv);
+                validate = ajv.compile(schema);
+            }
+            catch (err) {
+                findings.push({
+                    checkId: id,
+                    severity: 'error',
+                    message: `requirements/yaml/schema.json 无效：${err.message}`,
+                    path: 'requirements/yaml/schema.json',
+                });
+            }
+        }
         for (const file of yamlFiles) {
             try {
                 const raw = await fs_extra_1.default.readFile(file, 'utf8');
@@ -47,7 +67,19 @@ async function checkRequirements(ctx) {
                     });
                     continue;
                 }
-                js_yaml_1.default.load(raw);
+                const parsed = js_yaml_1.default.load(raw);
+                if (validate && !validate(parsed)) {
+                    const detail = (validate.errors ?? [])
+                        .slice(0, 3)
+                        .map((e) => `${e.instancePath || '/'} ${e.message}`)
+                        .join('; ');
+                    findings.push({
+                        checkId: id,
+                        severity: 'error',
+                        message: `requirements schema 校验失败：${detail}`,
+                        path: (0, utils_1.rel)(ctx.harnessRoot, file),
+                    });
+                }
             }
             catch (err) {
                 findings.push({

package/dist/commands/doctor/check-specs-depth.js

@@ -0,0 +1,165 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSpecsDepth = checkSpecsDepth;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const utils_1 = require("./utils");
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+async function getEnabledLayers(harnessRoot) {
+    const { doc } = await (0, utils_1.readHarnessYaml)(harnessRoot);
+    const layers = asArray(doc?.specs?.layers);
+    const enabled = new Set();
+    for (const l of layers) {
+        const name = l?.name;
+        if (name === 'signals' || name === 'behavior' || name === 'interfaces' || name === 'ui') {
+            enabled.add(name);
+        }
+    }
+    if (enabled.size === 0) {
+        enabled.add('signals');
+        enabled.add('behavior');
+        enabled.add('interfaces');
+        enabled.add('ui');
+    }
+    return enabled;
+}
+async function getDepthThresholds(harnessRoot) {
+    const defaults = {
+        warnThreshold: 0.5,
+        failThreshold: 0.8,
+    };
+    const { doc } = await (0, utils_1.readHarnessYaml)(harnessRoot);
+    const arch = doc?.arch?.trim();
+    const candidates = [
+        arch ? node_path_1.default.join(harnessRoot, 'agent-env', 'review-profiles', `${arch}.yaml`) : '',
+        node_path_1.default.join(harnessRoot, 'agent-env', 'review-profiles', '_default.yaml'),
+    ].filter(Boolean);
+    for (const file of candidates) {
+        if (!(await fs_extra_1.default.pathExists(file)))
+            continue;
+        try {
+            const parsed = js_yaml_1.default.load(await fs_extra_1.default.readFile(file, 'utf8'));
+            const heuristics = (parsed?.heuristics ?? {});
+            const fail = Number(heuristics.index_signal_id_ratio_threshold);
+            if (!Number.isNaN(fail) && fail > 0 && fail <= 1) {
+                return {
+                    warnThreshold: Math.max(0.1, Math.min(0.95, fail * 0.7)),
+                    failThreshold: fail,
+                };
+            }
+        }
+        catch {
+            // ignore invalid profile and fall back
+        }
+    }
+    return defaults;
+}
+async function scanSignalsDepth(ctx, findings, warnThreshold, failThreshold) {
+    const signalsDir = node_path_1.default.join(ctx.harnessRoot, 'specs', 'signals');
+    const files = (await (0, utils_1.listRealFilesRecursive)(signalsDir, { extensions: ['.yaml', '.yml'] })).filter((f) => !f.endsWith('schema.json'));
+    let totalSignals = 0;
+    let indexOnlySignals = 0;
+    for (const file of files) {
+        let parsed;
+        try {
+            parsed = js_yaml_1.default.load(await fs_extra_1.default.readFile(file, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const signals = asArray(parsed?.signals);
+        for (const sig of signals) {
+            totalSignals++;
+            const id = typeof sig.id === 'string' ? sig.id : '';
+            const hasDescription = typeof sig.description === 'string' && sig.description.trim().length >= 8;
+            const hasEnumValues = Array.isArray(sig.enum_values) && sig.enum_values.length > 0;
+            const hasLength = typeof sig.length_bytes === 'number';
+            const isEnum = sig.type === 'enum';
+            const maybeIndexOnly = /^CMDID_[A-Z0-9_]+$/.test(id) && !hasDescription && !hasLength && (!isEnum || !hasEnumValues);
+            if (maybeIndexOnly) {
+                indexOnlySignals++;
+            }
+            if (isEnum && !hasEnumValues) {
+                findings.push({
+                    checkId: 'specs-depth',
+                    severity: 'warning',
+                    message: `enum 信号缺少 enum_values（${id || 'unknown-id'}）`,
+                    path: (0, utils_1.rel)(ctx.harnessRoot, file),
+                });
+            }
+        }
+    }
+    if (totalSignals === 0)
+        return;
+    const ratio = indexOnlySignals / totalSignals;
+    if (ratio >= failThreshold) {
+        findings.push({
+            checkId: 'specs-depth',
+            severity: 'error',
+            message: `signals 索引式占比过高（${indexOnlySignals}/${totalSignals}=${ratio.toFixed(2)}）`,
+            path: 'specs/signals',
+        });
+    }
+    else if (ratio >= warnThreshold) {
+        findings.push({
+            checkId: 'specs-depth',
+            severity: 'warning',
+            message: `signals 索引式占比偏高（${indexOnlySignals}/${totalSignals}=${ratio.toFixed(2)}）`,
+            path: 'specs/signals',
+        });
+    }
+}
+async function scanBehaviorDepth(ctx, findings) {
+    const behaviorDir = node_path_1.default.join(ctx.harnessRoot, 'specs', 'behavior');
+    const files = (await (0, utils_1.listRealFilesRecursive)(behaviorDir, { extensions: ['.yaml', '.yml'] })).filter((f) => !f.endsWith('schema.json'));
+    for (const file of files) {
+        let parsed;
+        try {
+            parsed = js_yaml_1.default.load(await fs_extra_1.default.readFile(file, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const transitions = asArray(parsed?.transitions);
+        for (const t of transitions) {
+            const trigger = typeof t.trigger === 'string' ? t.trigger : 'unknown-trigger';
+            const guard = typeof t.guard === 'string' ? t.guard.trim() : '';
+            const action = typeof t.action === 'string' ? t.action.trim() : '';
+            if (!guard || /^见需求|^tbd|placeholder/i.test(guard)) {
+                findings.push({
+                    checkId: 'specs-depth',
+                    severity: 'warning',
+                    message: `transition.guard 为空或占位（${trigger}）`,
+                    path: (0, utils_1.rel)(ctx.harnessRoot, file),
+                });
+            }
+            if (!action || /^见需求|^tbd|placeholder/i.test(action)) {
+                findings.push({
+                    checkId: 'specs-depth',
+                    severity: 'warning',
+                    message: `transition.action 为空或占位（${trigger}）`,
+                    path: (0, utils_1.rel)(ctx.harnessRoot, file),
+                });
+            }
+        }
+    }
+}
+async function checkSpecsDepth(ctx) {
+    const id = 'specs-depth';
+    const findings = [];
+    const enabledLayers = await getEnabledLayers(ctx.harnessRoot);
+    const { warnThreshold, failThreshold } = await getDepthThresholds(ctx.harnessRoot);
+    if (enabledLayers.has('signals')) {
+        await scanSignalsDepth(ctx, findings, warnThreshold, failThreshold);
+    }
+    if (enabledLayers.has('behavior')) {
+        await scanBehaviorDepth(ctx, findings);
+    }
+    return { id, title: 'Specs 深度启发式', findings };
+}

package/dist/commands/doctor/index.js

@@ -45,7 +45,9 @@ const check_empty_dirs_1 = require("./check-empty-dirs");
 const check_convert_pairing_1 = require("./check-convert-pairing");
 const check_requirements_1 = require("./check-requirements");
 const check_requirements_coverage_1 = require("./check-requirements-coverage");
+const check_requirements_fidelity_1 = require("./check-requirements-fidelity");
 const check_specs_1 = require("./check-specs");
+const check_specs_depth_1 = require("./check-specs-depth");
 const check_references_1 = require("./check-references");
 const check_skills_tasks_1 = require("./check-skills-tasks");
 const check_memory_1 = require("./check-memory");
@@ -74,7 +76,9 @@ async function runDoctorChecks(input) {
         check_convert_pairing_1.checkConvertPairing,
         check_requirements_1.checkRequirements,
         check_requirements_coverage_1.checkRequirementsCoverage,
+        check_requirements_fidelity_1.checkRequirementsFidelity,
         check_specs_1.checkSpecs,
+        check_specs_depth_1.checkSpecsDepth,
         check_references_1.checkReferences,
         check_skills_tasks_1.checkSkillsTasks,
         check_memory_1.checkMemory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svharness",
-  "version": "0.14.2",
+  "version": "0.14.5",
   "description": "CLI scaffolder for SDD-Driven Agent-Agnostic Coding Framework (harness)",
   "bin": {
     "svharness": "./bin/cli.js",

package/templates/_shared/build-rules/harness-build-rule-chinese-only.md

@@ -6,7 +6,7 @@
 
 以下产出**必须**使用中文撰写：
 
-- `requirements/yaml/*.requirements.yaml` 中 `description`、`acceptance` 字段
+- `requirements/yaml/*.requirements.yaml` 中 `title`、`source_excerpt`、`description`、`acceptance` 字段
 - `specs/**/*.yaml` 中所有描述性字段（如 `description`、`note`、`summary`、`purpose`）
 - `agent-env/rules/**/*.md` 或 `*.mdc` 中正文段落、正反例注释、检测说明
 - `agent-env/skills/*/SKILL.md` 正文及 description
@@ -32,7 +32,7 @@
 ## 正反例
 
 正例：
-> `description: "根据 P_TMRAVA 信号显示或隐藏预约充电设置入口"`
+> `description: "当 P_TMRAVA=1 且车辆处于驻车状态时显示预约充电入口；当 P_TMRAVA=0 或车速>0 时隐藏入口。"`
 
 反例（严禁）：
 > `description: "Show or hide the scheduled charging settings entry based on P_TMRAVA signal"`

package/templates/_shared/build-rules/harness-build-rule-orchestrator-flow.md

@@ -14,12 +14,15 @@
 3. **S30_convert_docs** — 将 `requirements/raw/` 和 `references/raw/` 中的非 Markdown 原始文档统一转为 Markdown，产物落到对应 `md/` 目录。准入：S20_collect_inputs DONE；退出：每份源文档在对应 `md/` 目录中有同基名的 `.md` 文件。
 4. **S40_extract_requirements** — 由 `harness-build-skill-spec-builder` 将 raw 条目化到 `requirements/yaml/`。退出：
    - 已生成 `requirements/coverage-report.yaml`；
+   - `requirements/yaml/schema.json`（若存在）校验通过；
    - `unmapped` 为空，或已全部完成 waiver 与用户确认；
-   - 每条需求具备稳定 id 与可追溯锚点（允许有备案聚合，但不得无依据粗化）。
+   - 每条需求具备稳定 id 与可追溯锚点（允许有备案聚合，但不得无依据粗化）；
+   - 每条需求包含 `title`、`source_excerpt`、`description`，且不存在明显缩略风险（门禁策略可由 doctor/审查报告提供证据）。
 5. **S50_generate_specs** — 生成 `specs/{signals,ui,behavior,interfaces}/*.yaml`。退出：
    - 全部通过 `specs/*/schema.json` 校验；
    - 已产出 spec 覆盖率结果（建议 `specs/coverage-report.yaml`）；
-   - 每条 REQ 有 spec 映射或显式 N/A 理由。
+   - 每条 REQ 有 spec 映射或显式 N/A 理由；
+   - 深度启发式无 Critical（如 index-only signals、空 guard、断裂 bound_* 引用）。
 6. **S60_process_references**（阶段叙事：**references 处理**）— 对 S20 中的 references 执行处理与结构化：
    - 必须执行 `svharness convert`，不得跳过转换直接抽取；
    - 必须产出结构化索引（规制约束 / skills 候选 / signals / manuals，缺项需显式标注）；

package/templates/_shared/build-rules/harness-build-rule-pre-seal-review.md

@@ -21,10 +21,16 @@
 
 1. **需求可追溯**（若存在 requirements/yaml）：每条在已声明 spec 层有映射或 waiver。
 2. **覆盖率完整**：`requirements/coverage-report.yaml` 与（若存在）`specs/coverage-report.yaml` 可解析；`unmapped` 闭环。
-3. **描述完整性**：无 TBD/placeholder 占位语义。
+3. **描述完整性**：无 TBD/placeholder 占位语义，且 `description` 不得明显弱于 `source_excerpt`。
 4. **references / wiki / agent-env**（若目录存在）：与 S60、baseline 策略一致。
 5. **流程合规**、**中文与 agent-agnostic** 扫尾。
 
+补充抽检要求（至少随机 N=5 条或按项目规模调整）：
+
+- 抽检 `requirements/yaml`：确认 `source_excerpt` 保留原文约束（条件/数值/枚举），`description` 未删减关键语义。
+- 抽检 `specs/signals`：识别 index-only 信号（仅 id/name/type 且缺少协议/枚举语义）。
+- 抽检 `specs/behavior`：`transitions[].guard`/`action` 为空或占位语义应计入风险。
+
 ### Part B — 深度质量（按 specs.layers 启用）
 
 - 加载 `agent-env/review-profiles/<arch>.yaml` 或 `_default.yaml`。

package/templates/_shared/build-rules/harness-build-rule-requirements-extraction.md

@@ -23,7 +23,13 @@
      - `aggregation_reason`
      - 用户表单确认
 
-4. **覆盖率报告是 S40 必备产物**
+4. **原文优先，禁止缩略**
+   - `source_excerpt` 必须是可追溯锚点对应的原文摘录，禁止写成「见上文」「同前」「TBD」。
+   - `description` 必须覆盖 `source_excerpt` 里的条件、数值、枚举、时序，不得退化为标题短语。
+   - 推荐使用长度启发式审查：`description` 明显短于 `source_excerpt`（如 < 50%）时标记风险并复核。
+   - `title` 仅用于索引，禁止用 `title` 替代完整需求描述。
+
+5. **覆盖率报告是 S40 必备产物**
    - 必须生成 `requirements/coverage-report.yaml`。
    - 报告至少包含：
      - `extraction_strategy`
@@ -41,3 +47,5 @@
 - 禁止跳过源清点（inventory）直接写 `requirements/yaml`。
 - 禁止仅凭少量摘要条目宣称「提取完成」。
 - 禁止在未说明依据的情况下选择提取策略。
+- 禁止 `source_excerpt` 留空或使用占位语。
+- 禁止将多行表格仅提取第一列后声称完成条目化。

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

@@ -20,10 +20,13 @@ 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_section`: 源章节或表格区域
@@ -32,12 +35,13 @@ specs/
 - `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,7 +44,13 @@ 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>"
@@ -58,10 +64,13 @@ items:
 规则：
 - 条目 id **稳定**：一旦产出不得改写，新条目追加。
 - 有可追踪锚点时默认 1:1 条目化（细不能粗）。
-- 每条 `description` 必须是一句清晰陈述，不得写成聚合摘要。
+- `title` 仅作索引；不得把 `title` 充当完整需求描述。
+- `source_excerpt` 必须来自源文档原文；禁止写成「见上文」「同前」等替代语。
+- `description` 必须覆盖 `source_excerpt` 的关键约束；不得删减条件、数值、枚举、时序。
 - `traces_to` 初始可为空，阶段 B 生成 specs 后回填。
 - `source_doc` 与 `source_file` 必须引用真实源文件。
 - 聚合仅在用户确认后允许，且必须带 `aggregates + aggregation_reason`。
+- 产出后必须校验 `requirements/yaml/schema.json`（若存在）；失败不得进入 S50。
 
 ### 阶段 B：requirements → specs（规格生成）
 
@@ -71,7 +80,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`，至少包含：
@@ -91,6 +104,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 +133,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/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 %>"

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

@@ -0,0 +1,71 @@
+{
+  "$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 },
+          "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 }
               }
             }
           }