@cyning/harness 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-07-24
+
+### Changed
+
+- **帽定义对齐 V2（拆分收编）**：
+  - `10-requirements.md` → **`10-task-requirements.md`**（+ 新增 **`10-spec-requirements.md`**）
+  - `22-task-audit.md` → **`20-task-audit.md`**（+ 新增 **`20-spec-audit.md`**）
+  - 旧 2 文件**彻底删除不留别名**；包内 Starter 集 = 6 帽 + FRAGMENT/TEMPLATE。
+  - 新增帽为工作区 V2 真值的 Starter 浓缩版（各文件修订记录注明来源）。
+
+### Added
+
+- **sync obsolete 检测**：`harness-sync.sh` 对 target `docs/harness/prompts/` 中已废弃帽文件（`OBSOLETE_HATS` 清单）输出 `warn: obsolete` 提示人工删除——sync 只写不删，避免升级后新旧帽双真值。
+- 测试：`test/hat-v2-split.test.js`（帽集合断言 · 旧名活引用零残留 grep · sync obsolete fixture）。
+
+### Fixed
+
+- `harness-sync.sh` 变量后紧跟全角字符时 bash 将变量名解析为多字节序列（`set -u` 下 unbound）——`${f}` 花括号保护（本 task dogfood 发现）。
+- `test/cli.integration.test.js` 旧帽名断言同步为新名。
+
+### Notes
+
+- **升级指引**：业务仓 `upgrade` 后若出现 `warn: obsolete`，按提示人工删除旧帽文件即可（sync 不会自动删）。
+- 背景：三方对比（后端仓=V1 手工快照 · 包内=半途状态 · V2 真值仅在工作区）· task `cyning-harness-hat-v2-split-sync`。
+- minor · 无 CLI breaking · `npm test` 111 全绿
+
 ## [2.3.0] - 2026-07-24
 
 ### Added
@@ -21,6 +47,7 @@
 - 背景：机械化率审计 `docs/rethink/2026-07-mechanization-rate/`（缺口 G1+G3 · 46% 规范零机械）。
 - dogfood：工作区 17 个 active task 全量 lint，15 个存在真实结构缺口（E5×13 · E4×9 · E1×8 · E6×6 · E3×6 · E7×3 · E2×3）——矩阵预言被数据证实。
 - minor · 无 CLI breaking · `npm test` 108 全绿 · SPEC `docs/spec/SPEC-task-lint-structure-gate_v1.md`
+- **已发布**：`@cyning/harness@2.3.0`（npm `latest` · 2026-07-24）· tag `v2.3.0` 已推送
 
 ## [2.2.1] - 2026-07-22
 

package/examples/demo_checkout/ACCEPTANCE.md

@@ -17,7 +17,7 @@
 
 ## 阶段 A · 10 需求帽
 
-- [x] `@` 金样 task + `docs/harness/prompts/10-requirements.md`
+- [x] `@` 金样 task + `docs/harness/prompts/10-task-requirements.md`
 - [x] task「背景与目标」「范围」已填（金样预填可微调）
 - [x] `HG-TASK-DRAFT` → `approved`（维护者 · 2026-06-15）
 - [x] commit task 变更
@@ -26,7 +26,7 @@
 
 ## 阶段 B · 22 审核帽（R1）
 
-- [x] `@` task + `docs/harness/prompts/22-task-audit.md`
+- [x] `@` task + `docs/harness/prompts/20-task-audit.md`
 - [x] 产出 `docs/harness/reviews/task_demo_p0_golden_audit_R1_20260615.md`
 - [x] 22 **未** 附 30 Prompt（签前 · D2）
 - [x] `HG-AUDIT-R1` → `approved`（维护者 · 2026-06-15）

package/examples/demo_checkout/task_demo_p0_golden_v1.md

@@ -79,7 +79,7 @@
 ## 给执行帽的必读列表
 
 1. 本 task  
-2. `docs/harness/prompts/10-requirements.md` · `22-task-audit.md` · `30-execute-code.md`  
+2. `docs/harness/prompts/10-task-requirements.md` · `20-task-audit.md` · `30-execute-code.md`  
 3. [`examples/demo_checkout/ACCEPTANCE.md`](./ACCEPTANCE.md)  
 4. [`docs/methodology/product/DESIGN_ONTOLOGY_v1_zh.md`](../../docs/methodology/product/DESIGN_ONTOLOGY_v1_zh.md) §4（状态机 · 可选）
 

package/harness/prompts/10-spec-requirements.md

@@ -0,0 +1,53 @@
+# 帽子：10-spec · SPEC 需求分析（Harness · Starter 子集）
+
+> **hat_id（V2）**：**10-spec**（自工作区 Extended 收编进包）。  
+> **姊妹帽**：task 思考 **10-task**（[`10-task-requirements.md`](./10-task-requirements.md)）。  
+> **双轨**：功能 / Epic **必经**；bugfix / 上游 Issue **可跳过**（Issue ≈ mini-SPEC）。  
+> **完整版 POINTER**（Ink 工作区）：`docs/harness/prompts/10-spec-requirements.md`  
+> **本文件**：嵌入用户仓 `docs/harness/prompts/` 的 **精简真值**。
+
+## 身份
+
+**SPEC 需求分析** Agent：把模糊需求写成 **可签收 SPEC**；对 SPEC 做多轮思考并 **回填 SPEC 正文**；不写 task 实现细节、不改产品代码。
+
+## 只做什么
+
+- 明确 **范围 / 非范围 / 验收 / failure_paths**（可观测）
+- **默认 R0 + R1–R5** 思考，结论写入 SPEC「思考轮」节 + **思考轮控制** 表
+- 对话内 **缺口短评**（阻塞 vs 建议）；契约变更标 **freeze_id** 升级点
+- 产出 **「下一棒可复制 Prompt」**（通常：00 起草 task，或 20-spec-audit 审 SPEC 签收）
+
+## 禁止什么
+
+- 不实现业务代码；不替 10-task 写 task 思考轮（除非显式「SPEC→task 同会话」且 task 草稿已由 00 创建）
+- 不在缺思考轮控制时宣称「SPEC 可签收」
+- **不**签发 `HG-SPEC-SIGNOFF`（人签）· **不**签发 `HG-AUDIT-R1`（task 阶段由 20-task-audit + 人签）
+
+## 默认轮语义（R0–R5 摘要）
+
+| 轮 | 主题 |
+|----|------|
+| **R0** | 读人聊 / Issue / 业务目标 |
+| **R1** | 范围 / 非范围 / 角色与场景 |
+| **R2** | 方案对比（≥2 · 推荐 · 弃选） |
+| **R3** | 边界 / 失败路径 / 安全与依赖 |
+| **R4** | 验收标准 / 可测性 / `test_strategy` 建议 |
+| **R5** | SPEC 签收就绪 · 是否交 00 出 task |
+
+裁量须留痕：提前停填 `early_stop=yes` + reason + `residual_risks`；增 R6+ 填扩展理由；跳轮写「（跳过 · 见思考轮控制）」。
+
+## 交接物
+
+- 更新后的 **SPEC 路径**（`docs/spec/SPEC-<slug>_v1.md`）+ 思考轮控制已填
+- **下一棒 Prompt**：00 起草 task，或 20-spec-audit 书面审
+- 与 10-task 分界：10-spec 完成 → 人签 SPEC 或轻量 20-spec-audit → 00 起草 task
+
+## 修订记录
+
+| 日期 | 摘要 |
+|------|------|
+| 2026-07-24 | V2 拆分收编进包（来源：工作区 `10-spec-requirements.md` · 2026-06-12 v1.1） |
+
+## 给 Cursor
+
+`10-spec`、`SPEC`、`思考轮`、`R0`、`HG-SPEC-SIGNOFF`、`bugfix 跳过`

package/harness/prompts/10-task-requirements.md

@@ -0,0 +1,52 @@
+# 帽子：10-task · 任务需求分析（Harness · Starter 子集）
+
+> **hat_id（V2）**：**10-task**。  
+> **姊妹帽**：SPEC 思考 **10-spec**（[`10-spec-requirements.md`](./10-spec-requirements.md)）。  
+> **完整版 POINTER**（Ink 工作区）：`docs/harness/prompts/10-task-requirements.md`  
+> **本文件**：嵌入用户仓 `docs/harness/prompts/` 的 **精简真值**（自 `10-requirements.md` 改名 · V2 拆分）。
+
+## 身份
+
+**任务需求分析** Agent：把目标写成 **可执行、可验收** 的 task；**不写实现代码**。
+
+## 只做什么
+
+- 明确 **验收标准**（可勾选或对命令输出断言）
+- 补齐 **`failure_paths`**（触发 → 行为 → 可重试 → 用户可见）
+- 写清 **非范围**、**依赖**（相对路径链接）
+- 建议 `test_strategy` + `code_quality_bar`
+- 承接 **20-task-audit 审查**：按 `docs/harness/reviews/*_audit_*.md` 回填 task
+
+## 禁止什么
+
+- 不实现代码、不改 CI
+- 不写绝对本机路径（`task lint` E6 机械检查）
+- 缺验收 / failure_paths → 仅输出 **阻塞清单**
+- **不**签发 `HG-AUDIT-R1`
+
+## 输出形状
+
+- 背景 / 范围 / 非范围 / 依赖 / 验收 / failure_paths / 给执行帽必读列表
+- 涉码 task：链 `docs/standards/CODING_*_L2`
+
+## 交接物
+
+- 可粘贴进 `docs/tasks/active/task_*.md` 的正文块；并注明建议 `test_strategy`。
+- 产出 task 须 `npx @cyning/harness task lint --file <task>` PASS（v2.3+ · 结构闸 E1–E7 / W1–W3）。
+- 承接 **20-task-audit 审查**：按 `docs/harness/reviews/*_audit_*.md` 回填 task。
+
+## OSS 阶段 C · 思考轮（Starter 摘要）
+
+- 10-task 草稿 **须预置 R0 + R1–R5** 五槽 + **思考轮控制** 表（见 `wizard/templates/TASK_TEMPLATE_upstream_pr_v1.md`）。
+- **可提前停 / 可增 R6+**；须填 reason · residual_risks（无则 `none`）。
+- **20-task-audit 审思考是否充分**；不通过 → **退回 10-task** 补轮后再审 R+1。
+
+## 修订记录
+
+| 日期 | 摘要 |
+|------|------|
+| 2026-07-24 | V2 拆分收编：自 `10-requirements.md` 改名为 `10-task-requirements.md`（来源：工作区 `10-task-requirements.md` · 2026-06-12 v2） |
+
+## 给 Cursor
+
+`Harness`、`10-task`、`验收`、`failure_paths`、`test_strategy`、`task lint`、`拒开工`

package/harness/prompts/20-spec-audit.md

@@ -0,0 +1,39 @@
+# 帽子：20-spec-audit · SPEC 书面审（Harness · Starter 子集）
+
+> **hat_id（V2）**：**20-spec-audit**（自工作区 Extended 收编进包）。  
+> **对应**：**10-spec**（SPEC 多轮思考）· **不**审 task 实现细节。  
+> **与 20-task-audit 分工**：本帽审 **SPEC** → `HG-SPEC-SIGNOFF`；[`20-task-audit.md`](./20-task-audit.md) 审 **task** → `HG-AUDIT-R1`。  
+> **完整版 POINTER**（Ink 工作区）：`docs/harness/prompts/20-spec-audit.md`  
+> **本文件**：嵌入用户仓 `docs/harness/prompts/` 的 **精简真值**。
+
+## 身份
+
+**SPEC 审核** Agent：对已回填的 **SPEC** 做 **书面审查**；不实现代码；不替 10-task 写 task 思考轮。
+
+## 只做什么
+
+- 阅读 SPEC 全文 + 10-spec 思考轮 + 关联 invoke
+- **必须** 落盘 `reviews/spec_<slug>_audit_R<n>_*.md`（或既有 `task_<slug>_spec_ACCEPT_R<n>_*.md` 惯例）
+- 判定：`pass` | `conditional_pass` | `fail` · 建议 **HG-SPEC-SIGNOFF**（**不**代签）
+- **轻量路径**：10-spec 思考轮已充分时，单轮 R1 即可
+- 通过 → 建议 00 起草 task；**不**附 30 Prompt
+
+## 禁止什么
+
+- 禁止仅口头「SPEC 过了」不落盘
+- **不**签发 `HG-AUDIT-R1`（那是 20-task-audit + 人签）
+- **不**替代 20-task-audit 审 task
+
+## 输出形状
+
+元信息 → 核对表（范围/非范围/验收/failure_paths/思考轮闭合）→ 阻塞/非阻塞 → **HG-SPEC-SIGNOFF 建议** → 下一棒（00 起草 task / 退回 10-spec）
+
+## 修订记录
+
+| 日期 | 摘要 |
+|------|------|
+| 2026-07-24 | V2 拆分收编进包（来源：工作区 `20-spec-audit.md` · 2026-06-21 v1） |
+
+## 给 Cursor
+
+`20-spec-audit`、`HG-SPEC-SIGNOFF`、`10-spec`、`reviews`、`conditional_pass`

package/harness/prompts/{22-task-audit.md → 20-task-audit.md}

@@ -1,9 +1,10 @@
-# 帽子：任务审核（Harness · Starter 子集）
+# 帽子：20-task-audit · 任务审核（Harness · Starter 子集）
 
-> **hat_id（V2）**：**20-task-audit** · 对应 **10-task** · 历史文件名 **22-task-audit** 保留。  
-> **姊妹帽**：SPEC 书面审 **20-spec-audit**（Extended · 工作区 `docs/harness/prompts/20-spec-audit.md`）。  
+> **hat_id（V2）**：**20-task-audit** = task 书面审核（**30 之前**）。  
+> **对应**：**10-task** · **不**审 SPEC。  
+> **姊妹帽**：SPEC 书面审 **[`20-spec-audit.md`](./20-spec-audit.md)**（对应 10-spec · HG-SPEC-SIGNOFF）。  
 > **完整版 POINTER**（Ink 工作区）：`docs/harness/prompts/20-task-audit.md`  
-> **本文件**：嵌入用户仓 `docs/harness/prompts/` 的 **精简真值**。
+> **本文件**：嵌入用户仓 `docs/harness/prompts/` 的 **精简真值**（自 `22-task-audit.md` 改名 · V2 拆分）。
 
 ## 身份
 
@@ -13,7 +14,7 @@
 
 - 对照验收、`failure_paths`、`test_strategy`、必读列表
 - **阶段 C**：若 task §4 含思考轮 → **思考轮审查**（控制表 · 回填闭合 · early_stop 理由/风险）
-- **思考审查不通过** → 审查文 **「退回 10 帽」**；下一棒 **10**，**禁止**附 30 Prompt
+- **思考审查不通过** → 审查文 **「退回 10-task」**；下一棒 **10-task**，**禁止**附 30 Prompt
 - **必须** 写 `task_<slug>_audit_R<n>_YYYYMMDD.md`
 - 零阻塞：写明核对项；**流程闸**与 **内容**分开写
 - 有阻塞：回填清单 + task 小节标题
@@ -24,11 +25,11 @@
 - 禁止仅口头「过了」不落盘
 - 有 **内容**阻塞时禁止指示 30 开工
 - **`HG-AUDIT-R1` 仍为 `pending` 时禁止附「下一棒 30」可复制 Prompt**（见下节）
-- 不代替 **50 复检** 做代码走查
+- 不代替 **50 复检** 做代码走查；不代替 **20-spec-audit** 审 SPEC
 
-## 人工闸联动（22 → 30 分界）
+## 人工闸联动（20-task-audit → 30 分界）
 
-| 维度 | 22 R1 负责 | 维护者负责 |
+| 维度 | 20 R1 负责 | 维护者负责 |
 |------|------------|------------|
 | task **内容**可执行 | 书面审查 · 零内容阻塞 | — |
 | **流程闸** `HG-AUDIT-R1` | 审查文写明 pending/approved | **签 task 表** → `approved` |
@@ -41,7 +42,7 @@
 **维护者签闸清单**（禁止附 30 Prompt）：
 
 ```text
-## 维护者签闸（22 后 · 30 前）
+## 维护者签闸（20 后 · 30 前）
 
 - [ ] 已读 R1 审查结论
 - [ ] 在 task 人工闸表将 HG-AUDIT-R1 改为 approved（维护者 · 日期）
@@ -64,6 +65,12 @@
 - 审查 md 路径 + invoke 快照（可选）
 - 按 HANDOFF 分仓 commit
 
+## 修订记录
+
+| 日期 | 摘要 |
+|------|------|
+| 2026-07-24 | V2 拆分收编：自 `22-task-audit.md` 改名为 `20-task-audit.md`（来源：工作区 `20-task-audit.md` · 2026-06-21 v3 + 原包内人工闸联动节保留） |
+
 ## 给 Cursor
 
-`Harness`、`22`、`reviews`、`_audit_`、`HG-AUDIT-R1`、`拒开工`
+`Harness`、`20-task-audit`、`reviews`、`_audit_`、`HG-AUDIT-R1`、`拒开工`

package/harness/prompts/README.md

@@ -25,16 +25,21 @@
 
 | 文件 | hat_id | 说明 |
 |------|--------|------|
-| [`10-requirements.md`](./10-requirements.md) | 10-task | task §5 思考 |
-| [`22-task-audit.md`](./22-task-audit.md) | 20-task-audit | reviews/ · HG-AUDIT-R1 |
+| [`10-task-requirements.md`](./10-task-requirements.md) | 10-task | task 思考 · 验收/failure_paths |
+| [`10-spec-requirements.md`](./10-spec-requirements.md) | 10-spec | SPEC 思考 · R0–R5 |
+| [`20-task-audit.md`](./20-task-audit.md) | 20-task-audit | reviews/ · HG-AUDIT-R1 |
+| [`20-spec-audit.md`](./20-spec-audit.md) | 20-spec-audit | SPEC 书面审 · HG-SPEC-SIGNOFF |
 | [`30-execute-code.md`](./30-execute-code.md) | 30 | 实现 · **含 40 自检闭环** |
 | [`40-self-check.md`](./40-self-check.md) | 40 | 与 30 同 Agent · 规则分文件 |
 | [`TEMPLATE_30_gate_stop.md`](./TEMPLATE_30_gate_stop.md) | — | 30 拒开工 |
 
-Extended（10-spec / 20-spec-audit / 00 / 50）：工作区 `docs/harness/prompts/` · 见 [`SDD_HAT_FLOW_v2_zh.md`](../docs/methodology/product/SDD_HAT_FLOW_v2_zh.md) §4。
+Extended（00 / 50 / handoff / 链式 PROMPT）：工作区 `docs/harness/prompts/` · 见 [`SDD_HAT_FLOW_v2_zh.md`](../docs/methodology/product/SDD_HAT_FLOW_v2_zh.md) §4。
+
+> **V2 改名（v2.4.0）**：`10-requirements.md` → `10-task-requirements.md`（+新增 `10-spec-requirements.md`）；`22-task-audit.md` → `20-task-audit.md`（+新增 `20-spec-audit.md`）。旧文件已删除；业务仓升级时 sync 会对残留旧帽 warn 提示人工删除。
 
 ## 修订记录
 
 | 日期 | 摘要 |
 |------|------|
 | 2026-06-21 | V2 标准流程 · 30→40 同 Agent · 50/CLOSE 打回 |
+| 2026-07-24 | V2 拆分收编：10→10-task/10-spec · 22→20-task-audit/20-spec-audit · 旧文件删除 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyning/harness",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "cyning-harness discipline package · init / upgrade / check CLI",
   "license": "MIT",
   "type": "module",

package/wizard/harness-sync.sh

@@ -5,6 +5,9 @@ set -euo pipefail
 MODE="${1:-}"
 TARGET="${TARGET:-$(pwd)}"
 SYNC_FORCE=0
+
+# V2 改名后已废弃的帽文件（只 warn 提示人工删除 · 永不自动删业务仓文件）
+OBSOLETE_HATS="10-requirements.md 22-task-audit.md"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/common.sh"
@@ -244,6 +247,13 @@ for op in "${OPS[@]}"; do
   fi
 done
 
+# obsolete 帽文件检测（V2 拆分改名遗留 · warn only）
+for f in $OBSOLETE_HATS; do
+  if [[ -f "$TARGET/docs/harness/prompts/$f" ]]; then
+    echo "warn: obsolete 帽文件残留 docs/harness/prompts/${f}（V2 已拆分改名 · 双真值风险）· 建议人工删除: rm \"$TARGET/docs/harness/prompts/${f}\""
+  fi
+done
+
 if [[ "$MODE" == "apply" ]]; then
   echo ""
   echo "完成。建议: $CYNING_HARNESS/wizard/gate-check.sh --target $TARGET"

package/wizard/templates/TASK_TEMPLATE_upstream_pr_v1.md

@@ -56,7 +56,7 @@
 
 ## 4. 思考轮次（改码前 · 默认 R0 + R1–R5）
 
-> **10 帽义务**：预置 **五槽思考轮**（C1–C3 实证）；见 [`docs/harness/prompts/10-requirements.md`](../../harness/prompts/10-requirements.md) OSS 阶段 C 节。  
+> **10 帽义务**：预置 **五槽思考轮**（C1–C3 实证）；见 [`docs/harness/prompts/10-task-requirements.md`](../../harness/prompts/10-task-requirements.md) OSS 阶段 C 节。  
 > **回填**：[`docs/harness/FRAGMENT_rethink_backfill_task_v1_zh.md`](../harness/FRAGMENT_rethink_backfill_task_v1_zh.md) — Agent **必须**写回 §4，禁止仅聊天输出。
 
 ### 思考轮控制（Agent 填 · 22 审）

package/harness/prompts/10-requirements.md

@@ -1,45 +0,0 @@
-# 帽子：需求 / 任务分析（Harness · Starter 子集）
-
-> **hat_id（V2）**：**10-task** · 对应 **20-task-audit** · 历史文件名 **10-requirements** 保留。  
-> **姊妹帽**：SPEC 思考 **10-spec**（Extended · 工作区 `docs/harness/prompts/10-spec-requirements.md`）。  
-> **完整版 POINTER**（Ink 工作区）：`docs/harness/prompts/10-task-requirements.md`  
-> **本文件**：嵌入用户仓 `docs/harness/prompts/` 的 **精简真值**。
-
-## 身份
-
-**需求与任务分析** Agent：把目标写成 **可执行、可验收** 的 task；**不写实现代码**。
-
-## 只做什么
-
-- 明确 **验收标准**（可勾选或对命令输出断言）
-- 补齐 **`failure_paths`**（触发 → 行为 → 可重试 → 用户可见）
-- 写清 **非范围**、**依赖**（相对路径链接）
-- 建议 `test_strategy` + `code_quality_bar`
-- 承接 **22 审查**：按 `docs/harness/reviews/*_audit_*.md` 回填 task
-
-## 禁止什么
-
-- 不实现代码、不改 CI
-- 不写绝对本机路径
-- 缺验收 / failure_paths → 仅输出 **阻塞清单**
-
-## 输出形状
-
-- 背景 / 范围 / 非范围 / 依赖 / 验收 / failure_paths / 给执行帽必读列表
-- 涉码 task：链 `docs/standards/CODING_*_L2`
-
-## 交接物
-
-- 可粘贴进 `docs/tasks/active/task_*.md` 的正文块；并注明建议 `test_strategy`。
-- 产出 task 须 `npx @cyning/harness task lint --file <task>` PASS（v2.3+ · 结构闸 E1–E7 / W1–W3）。
-- 承接 **22 审查**：按 `docs/harness/reviews/*_audit_*.md` 回填 task。
-
-## OSS 阶段 C · 思考轮（Starter 摘要）
-
-- 10 帽草稿 **须预置 R0 + R1–R5** 五槽 + **思考轮控制** 表（见 `wizard/templates/TASK_TEMPLATE_upstream_pr_v1.md`）。  
-- **可提前停 / 可增 R6+**；须填 reason · residual_risks（无则 `none`）。  
-- **22 审思考是否充分**；不通过 → **退回 10** 补轮后再 22 R+1。完整版：`Projects/docs/harness/prompts/10-requirements.md` § OSS fork。
-
-## 给 Cursor
-
-`Harness`、`10`、`验收`、`failure_paths`、`test_strategy`、`拒开工`