@cyning/harness 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@
 
 ## [Unreleased]
 
+## [2.8.0] - 2026-07-25
+
+### Added
+
+- **SPEC 审查文留档闸（N3 · G2 姊妹）**：`verify --spec FILE` 检查 `docs/harness/reviews/` 下 SPEC 审查文存在性（推荐 `spec_<slug>_audit_R*` · 兼容 `*_ACCEPT_*` / `task_*_spec_ACCEPT_*`）。缺失 → `VERIFY: BLOCKED · missing SPEC R<n> review` exit 2。
+- 豁免：`--allow-no-spec-review`；元信息 `track: bugfix` / `skip_spec_audit: true`。
+- `findSpecReview`（支持 `--workspace-root` 分仓）；handoff：`may_start_00` · `spec_review_found` · `spec_review_latest`。
+- `lifecycle.yaml` 转移 `to_00` + guard `spec_reviews_retention`（只登记）。
+
+### Notes
+
+- 与 `--task` 互斥；**不**改 task 侧 verify/close。
+- SPEC：`docs/spec/SPEC-spec-reviews-retention-gate_v1.md`
+- minor · 行为新增（新模式）
+
 ## [2.7.0] - 2026-07-24
 
 ### Added
@@ -17,6 +32,7 @@
 - 背景：Post-G4 方案 N1+N2 · rethink 方向二骨架；dogfood active lint FAIL 率高故本波不做 block。
 - SPEC：`docs/spec/SPEC-lifecycle-and-verify-lint_v1.md`
 - minor · `npm test` 含 lifecycle + verify-lint-warn
+- **已发布**：`@cyning/harness@2.7.0`（npm `latest` · 2026-07-24）· tag `v2.7.0`
 
 ## [2.6.0] - 2026-07-24
 

package/docs/ONBOARDING.md

@@ -52,6 +52,11 @@ npx @cyning/harness verify --target /path/to/your-repo \
 # --task 另跑 task lint（v2.7+ · E 级仅 WARN，不挡 may_start_30）
 # 抑制 lint WARN：加 --allow-lint-fail
 
+# SPEC→00 前：审查文存在性（v2.8+ · 与 --task 互斥）
+npx @cyning/harness verify --spec docs/spec/SPEC-xxx_v1.md \
+  --workspace-root /path/to/Projects
+# 豁免：--allow-no-spec-review · 或 SPEC track=bugfix / skip_spec_audit
+
 # 只读生命周期登记（方向二 · 非引擎）
 npx @cyning/harness lifecycle show
 npx @cyning/harness lifecycle show --json

package/docs/USER_GUIDE_v1.0_zh.md

@@ -115,6 +115,11 @@ npx @cyning/harness@1.0.1 init --preset harness-only --ide cursor,agents --yes
 npx @cyning/harness verify --target . --task docs/tasks/active/task_xxx.md
 # lint FAIL 仅 WARN（v2.7+ · 不挡 30）；抑制：--allow-lint-fail
 
+# SPEC→00：审查文存在性（v2.8+ · 与 --task 互斥）
+npx @cyning/harness verify --spec docs/spec/SPEC-xxx_v1.md \
+  --workspace-root /path/to/Projects
+# 豁免：--allow-no-spec-review
+
 # Agent handoff（v2.0.2+）：JSON 路由 + 下一帽提示
 npx @cyning/harness verify --target . \
   --task docs/tasks/active/task_xxx.md \
@@ -172,7 +177,7 @@ Schema：[`schema/verify_result.v1.schema.json`](../schema/verify_result.v1.sche
 | `npx @cyning/harness init` | 首次安装模板与 manifest（可选 `--with-scripts`） |
 | `npx @cyning/harness upgrade` | 同步产品包更新（可加 `--gate-check` 先 audit） |
 | `npx @cyning/harness check` | 检查是否有新版本 |
-| `npx @cyning/harness verify` | 30 前聚合：gate-check + audit D5 + reviews +（`--task`）lint WARN + S5 · 可选 `--graph` / `--json` / `--allow-lint-fail` |
+| `npx @cyning/harness verify` | `--task`：30 前聚合；`--spec`：SPEC→00 审查文闸（v2.8+ · 互斥）· `--allow-no-spec-review` |
 | `npx @cyning/harness lifecycle show` | 只读展示 `harness/lifecycle.yaml`（状态/转移/守卫 · v2.7+ · 非引擎） |
 | `npx @cyning/harness gate-check` | 仅人工闸（`--graph` / `--json`） |
 | `npx @cyning/harness audit` | ICVO 机械审计（D3/D5/S5） |

package/docs/spec/SPEC-spec-reviews-retention-gate_v1.md

@@ -0,0 +1,192 @@
+# SPEC：SPEC 审查文留档闸（20-spec-audit / HG-SPEC-SIGNOFF 存在性检查）（v1）
+
+> **状态**：`signed`（维护者签收 2026-07-25 · 对话「签收」）  
+> **track**：`feature`  
+> **关联图谱**：无（纯 Harness 工具链）  
+> **上游**：[`PLAN_post_g4_next_mechanization_v1_zh.md`](../../../docs/harness/guides/PLAN_post_g4_next_mechanization_v1_zh.md) · N3 · G2 姊妹  
+> **前置**：G2 `@cyning/harness@2.5.0`（`findReview`）· N1 `@2.7.0`（`lifecycle.yaml`）  
+> **下游**：00 已起草 task → 20-task-audit → HG-AUDIT-R1 → 30（目标版本 **v2.8.0**）
+
+---
+
+## Harness 元信息
+
+| 字段 | 值 |
+|------|-----|
+| **spec_slug** | `spec-reviews-retention-gate` |
+| **test_strategy** | `required` |
+| **test_strategy_note** | `findSpecReview` 命名变体 + `verify --spec` 三态（pass/block/豁免）+ bugfix 豁免；既有 `verify --task` 回归不改 |
+| **entry_invoke_10_spec** | `Projects/docs/harness/invokes/by-task/cyning-harness-spec-reviews-retention-gate/invoke_20260725_10_spec_spec_reviews_retention_gate.md` |
+| **entry_invoke_00_draft** | 工作区 `docs/harness/prompts/PROMPT_00_draft_spec_or_task_v1_zh.md` |
+
+---
+
+## 1. 背景与目标
+
+G2（v2.5.0）已把 **task** 侧「R<n> 审查文存在」机械化为 `verify --task` / `task close` 检查 6。功能轨上游对称缺口仍在：
+
+- [`20-spec-audit.md`](../../harness/prompts/20-spec-audit.md) 要求落盘 `reviews/spec_<slug>_audit_R<n>_*.md`（或既有 `*_spec_ACCEPT_R*` 惯例）；
+- **`HG-SPEC-SIGNOFF` 可由对话「签收」完成，签署依据（SPEC 审查文）存在性零机械**——与 G2 补闸前的 task 侧同构。
+
+**dogfood（2026-07-25）**：产品仓 `docs/spec/SPEC-*.md` **5** 份近期 SPEC（含 G1–G4 / N1+N2）**均无**对应 `spec_*_audit_R*` / `*_spec_ACCEPT_R*` 文；工作区仅有少量历史 `spec_*_ACCEPT_*` / `*_spec_ACCEPT_*`。说明当前主流是「对话签收 + 跳过 20-spec-audit 落盘」。
+
+**目标**：补上 SPEC→task 纸链的对称闸——机器只查**审查文存在性**；审查结论仍由人签 `HG-SPEC-SIGNOFF` 覆盖。
+
+**职责切分（同 G2）**：机器 = 形式（文件在）；人 = 实质（通过/条件通过）。
+
+---
+
+## 2. 范围
+
+### D1 · `findSpecReview`（`lib/task-meta.js` 或邻近模块）
+
+- 输入：`specFile` + `target`（reviews 根所在仓）+ 可选 `workspaceRoot`（SPEC 在产品仓、reviews 在工作区时）
+- 匹配（任一命中即 `found`；取最新轮）：
+  1. **推荐**：`spec_<slug>_audit_R<n>_*.md`
+  2. **兼容**：`spec_<slug>_ACCEPT_R<n>_*.md`
+  3. **兼容**：`task_<slug>_spec_ACCEPT_R<n>_*.md`（工作区历史惯例）
+- slug 来源：优先 SPEC 表 `spec_slug`；否则自文件名剥离 `SPEC-` / `_v\d+` / 扩展名后 `normalizeSlug`
+- 文件名与 slug：**两侧**下划线/连字符等价；版本后缀 `_v\d+` 双侧剥离（复用 G2 R1-B1 思路）
+- 返回：`{ found, latest, rounds[], matched_pattern? }`
+
+### D2 · CLI 挂点：`verify --spec FILE`
+
+- **新模式**（与 `--task` 互斥）：`npx @cyning/harness verify --spec PATH [--target PATH] [--workspace-root PATH] [--json] [--allow-no-spec-review]`
+- 行为：
+  - 审查文存在 → `VERIFY: PASS`（或等价摘要）· exit 0
+  - 缺失 → `VERIFY: BLOCKED · missing SPEC R<n> review` · exit 2
+  - `--allow-no-spec-review` → warn 放行 · 留痕
+- `--json`：`may_start_00`（或 `spec_review_ok`）· `spec_review_found` · `spec_review_latest` · `blocked_reason`
+- **不**改动既有 `verify --task` / 无参全量模式语义（N4 仍另议）
+- **不**把本闸挂进 `verify --task`（挂点错误：30 查的是 task 审查文，不是 SPEC）
+
+### D3 · bugfix / 跳过 10-spec 豁免
+
+满足任一则 **不**要求 SPEC 审查文（exit 0 + 可选 info 行）：
+
+- SPEC / 元信息显式：`track: bugfix` 或 `skip_spec_audit: true`（字段名以实现为准 · 文档冻结）
+- CLI：`--allow-no-spec-review`（通用泄压，含历史对话签收存量）
+
+### D4 · lifecycle 登记
+
+- `harness/lifecycle.yaml` 新增转移（建议 id：`to_00` 或 `spec_signoff`）：
+  - from：spec draft / signed 相关状态（可用注释说明别名；本波允许最小 states 扩展或仅在 transitions 注释）
+  - to：可起草 task
+  - guard：`spec_reviews_retention` · severity=`block` · `allow_flag: --allow-no-spec-review`
+- **只登记 · 不实现引擎**（同 N1）
+
+### D5 · 文档 / 版本
+
+- `20-spec-audit.md` / ONBOARDING 或 USER_GUIDE：注明 v2.8+ `verify --spec` 机械强制存在性
+- CHANGELOG **v2.8.0**（行为新增 · minor；醒目说明 + 豁免指引）
+- PLAN / rethink 矩阵回链本 SPEC
+
+### D6 · 测试
+
+- 命名三变体命中；slug 连字符/下划线；版本后缀
+- verify `--spec` 三态 + bugfix 豁免 + 与 `--task` 互斥用法
+- 既有 verify/close/lifecycle 回归绿
+
+---
+
+## 3. 非范围
+
+- 审查文**内容**判定（pass / conditional_pass / fail）——人/20-spec-audit 职责
+- 强制给**存量** 5 份已对话签收的产品 SPEC 补审（可用豁免；另开 hygiene 可选）
+- 把 SPEC 审查闸挂进 `verify --task` 或 `task close`
+- N4：verify 无 `--task` 全量模式纳入 task reviews
+- 自动代签 `HG-SPEC-SIGNOFF`；状态机引擎执行 `to_00`
+- 统一历史所有命名为单一范式（本波只兼容读取）
+
+---
+
+## 4. 验收标准
+
+- [ ] `findSpecReview`：推荐名 / `ACCEPT` / `task_*_spec_ACCEPT_*` 均可 `found`；多轮取最新
+- [ ] `verify --spec`：有文 → PASS；无文 → BLOCKED exit 2；`--allow-no-spec-review` → warn 放行
+- [ ] bugfix / `skip_spec_audit` → 不要求审查文
+- [ ] `--json` 含 `spec_review_found`（或等价）且 **不**破坏 `--task` handoff 字段
+- [ ] lifecycle.yaml 已登记 `to_00`（或等价）+ `spec_reviews_retention` guard
+- [ ] `npm test` 全绿；CHANGELOG v2.8.0；文档可链到
+- [ ] dogfood：对本 SPEC 走通「20-spec-audit 落盘 → `verify --spec` PASS」（实现波自检）
+
+---
+
+## 5. failure_paths
+
+| 触发条件 | 系统行为 | 可重试 |
+|----------|----------|--------|
+| 00 前无 SPEC 审查文 | `VERIFY: BLOCKED · missing SPEC R<n> review` | 跑 20-spec-audit 落盘；或 `--allow-no-spec-review` |
+| SPEC 在产品仓、reviews 在工作区 | 未传 `--workspace-root` / 错 `--target` → 误报缺失 | 按文档传参后重跑 |
+| 命名不在兼容列表 | 视为缺失 | 按推荐名重命名或补一份推荐名 |
+| bugfix 轨被误挡 | 应走 D3 豁免；若未标 track → 用 allow 旗 | 补元信息 |
+| 业务仓未升级 2.8.0 | 无 `--spec` 模式 · 行为不变 | upgrade |
+
+---
+
+## 6. 依赖与引用
+
+- G2：`findReview` / `--allow-no-review` 模式；本波 **独立** flag `--allow-no-spec-review`（审计痕迹不混）
+- N1：`lifecycle.yaml` 挂点登记
+- 纪律：`harness/prompts/20-spec-audit.md` · `10-spec-requirements.md`（bugfix 跳过）
+- PLAN N3；G2 SPEC 非范围「SPEC 审查文——下一轮」本 SPEC 关闭该句
+
+---
+
+## 7. 思考轮（10-spec 回填 · R0–R5）
+
+### R0 · 读入与约束
+
+读入：PLAN N3；G2 SPEC（非范围点名本缺口）；`20-spec-audit` 命名双惯例；`findReview` 实现；lifecycle.yaml 仅有 task 转移；dogfood：5/5 产品 SPEC 无 spec 审查文。约束：挂点时刻须晚于审查文应存在时刻；不误伤 bugfix；不把闸错挂到 `--task`。
+
+### R1 · 范围 / 非范围 / 场景
+
+**场景**：① 维护者/Agent 在 00 起草 task 前跑 `verify --spec`，挡「对话签了但无审查文」；② 20-spec-audit 多轮 R1→R2 取最新；③ 历史 `*_ACCEPT_*` 命名仍认；④ bugfix 无 10-spec 不挡。  
+**同构 G2、异挂点**：共享「存在性闸」模式，但消费者是 **SPEC→00**，不是 **task→30**。  
+**非范围**：内容判定、存量强制补审、挂进 task verify/close——避免双重计费与挂点错位。
+
+### R2 · 方案对比
+
+| 决策点 | 选项 | 裁定 | 理由 |
+|---|---|---|---|
+| 严格度 | warn 起步 / block+allow | **block + `--allow-no-spec-review`** | 与 G2 同构；warn 等于再留自觉层。dogfood 存量用豁免，不降级整闸 |
+| CLI 形态 | 独立 `spec check` / 并入 `verify --spec` | **`verify --spec`** | 与 G2 叙事一致（「verify = 下一转移前置」）；少一个动词 |
+| 挂点 | `--task` 附带查 SPEC / 仅 `--spec` / close | **仅 `--spec`** | `--task` 时 SPEC 链路可能已结束；close 查 SPEC 无审计价值 |
+| 命名 | 只认推荐 / 兼容 ACCEPT | **推荐 + 两兼容** | 20-spec-audit 已写双惯例；工作区有 ACCEPT 实档 |
+| reviews 根 | 仅 SPEC 所在仓 / 可 workspace-root | **支持 `--workspace-root`（或 `--target` 指 reviews 仓）** | 产品 SPEC × 工作区 reviews 是本仓常态 |
+| 豁免旗 | 复用 `--allow-no-review` / 独立 | **独立 `--allow-no-spec-review`** | 与 task 审查豁免分迹 |
+| 版本 | 2.7.x patch / 2.8.0 | **2.8.0** | 新 blocking 模式 · minor |
+
+### R3 · 边界 / 失败语义 / 安全
+
+- **存量**：5 份已对话签收 SPEC 不自动被扫；仅在有人执行 `verify --spec` 时暴露 → 豁免或补 20-spec-audit。
+- **误报**：形式宽容止于「slug 匹配 + 兼容模式名」；不接受任意含 spec 字样的文件。
+- **安全**：只读检查；不写盘、不代签人闸。
+- **兼容**：无 `--spec` 的旧调用链行为不变。
+
+### R4 · 验收 / 可测性 / test_strategy
+
+`test_strategy: required`。fixture：三命名 · 互斥参数 · block/pass/allow · bugfix 跳过；回归 verify-task / lifecycle show。实现波 dogfood：本 SPEC 的 20-spec-audit 文 + `verify --spec` PASS。
+
+### R5 · SPEC 签收就绪 · 是否可交 00 出 task
+
+自足：挂点、命名、豁免、lifecycle 登记、版本均已裁定。**可交 00**：建议单 task `cyning-harness-spec-reviews-retention-gate`。图谱无需 bootstrap。
+
+### 思考轮控制
+
+| 字段 | 值 |
+|------|-----|
+| `actual_last_round` | `R5` |
+| `early_stop` | `no` |
+| `early_stop_reason` | — |
+| `residual_risks` | ① 对话签收文化可能继续依赖豁免旗——须文档把「00 前 verify --spec」写成默认；② SPEC 路径与 reviews 仓分裂时 Agent 漏传 workspace-root → 误 BLOCKED；③ 是否在 00 帽 Prompt 增加「开工前 GATE_VERIFY_SPEC」句，属文档同步，实现时对照 10-spec/00 模板 |
+| `round_extension_note` | — |
+
+---
+
+## 修订记录
+
+| 日期 | 摘要 |
+|------|------|
+| 2026-07-25 | 10-spec R0–R5（维护者点菜「继续 N3」）· dogfood 5/5 无 spec 审查文 |
+| 2026-07-25 | 维护者签收（对话「签收」）· → 00 起草 task |

package/harness/lifecycle.yaml

@@ -8,7 +8,9 @@ version: "1"
 
 states:
   - id: draft
-    note: "含 pending / active 等词表别名 · 见 KNOWN_STATUS_TOKENS"
+    note: "含 pending / active 等词表别名 · 见 KNOWN_STATUS_TOKENS；SPEC 侧亦用 draft"
+  - id: signed
+    note: "SPEC 人签 HG-SPEC-SIGNOFF 后 · 可起草 task"
   - id: in_progress
   - id: done
     note: "close 可接受 completed 别名"
@@ -16,6 +18,18 @@ states:
     note: "task close 归档后 · 物理上在 done/ 目录"
 
 transitions:
+  - id: to_00
+    from: ["draft", "signed"]
+    to: signed
+    hat: "00"
+    description: "SPEC 签收后起草 task（verify --spec 聚合 · v2.8+）"
+    guards:
+      - id: spec_reviews_retention
+        command_or_check: "verify --spec · findSpecReview（v2.8+）"
+        severity: block
+        allow_flag: "--allow-no-spec-review"
+        note: "bugfix / skip_spec_audit 元信息豁免 · 不挂 verify --task"
+
   - id: to_30
     from: ["draft", "in_progress"]
     to: in_progress

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

@@ -17,6 +17,7 @@
 - 判定：`pass` | `conditional_pass` | `fail` · 建议 **HG-SPEC-SIGNOFF**（**不**代签）
 - **轻量路径**：10-spec 思考轮已充分时，单轮 R1 即可
 - 通过 → 建议 00 起草 task；**不**附 30 Prompt
+- **v2.8+ 机械闸**：00 前跑 `npx @cyning/harness verify --spec <SPEC路径> [--workspace-root <Projects>]`——机器只查审查文**存在性**；缺失 exit 2。豁免：`--allow-no-spec-review` · bugfix / `skip_spec_audit`
 
 ## 禁止什么
 

package/lib/cli.js

@@ -41,7 +41,7 @@ function usage(version = 'unknown') {
   npx @cyning/harness check [--target PATH]
   npx @cyning/harness audit [--target PATH] [--task FILE]
   npx @cyning/harness gate-check [--target PATH] [--task FILE] [--graph] [--json]
-  npx @cyning/harness verify [--target PATH] [--task FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH]
+  npx @cyning/harness verify [--target PATH] [--task FILE | --spec FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH]
   npx @cyning/harness lifecycle show [--json]
   npx @cyning/harness sync index [--target PATH]
   npx @cyning/harness task check --file PATH [--no-circular] [--registry DIR]...
@@ -62,7 +62,7 @@ function usage(version = 'unknown') {
   check       读 manifest.json · 对比当前包版本是否有可升级版本
   audit       ICVO 机械审计：复用 gate-check · D5 测试声明检查 · S5 git-clean 提醒
   gate-check  调用 wizard/gate-check.sh（业务仓无需 clone 即可用）
-  verify      30 前聚合：gate-check + audit D5 + reviews + task lint WARN（v2.7+）+ S5 warn + 可选 --graph
+  verify      30 前聚合（--task）或 SPEC→00 审查文闸（--spec · v2.8+）
   lifecycle   只读展示 harness/lifecycle.yaml（状态/转移/守卫 · v2.7+）
   sync index  生成 .cyning-harness/invoke_index.json
   task check  校验 task.harness.v1.json sidecar · --no-circular 检测 depends_on 环
@@ -390,16 +390,21 @@ async function cmdGateCheck(args) {
 
 async function cmdVerify(args) {
   // D3 · implemented in lib/verify.js
-  const { verifyTarget, buildVerifyHandoff, formatAgentHint } = await import('./verify.js');
+  const {
+    verifyTarget,
+    verifySpecTarget,
+    buildVerifyHandoff,
+    buildSpecVerifyHandoff,
+    formatAgentHint,
+  } = await import('./verify.js');
   if (args.includes('--help') || args.includes('-h')) {
-    console.log(`用法: npx @cyning/harness verify [--target PATH] [--task FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH] [--allow-no-review] [--allow-lint-fail]
-
-无 --task 时：扫描 docs/tasks/active/task_*.md 并逐项列出闸表（同 gate-check）；本波不跑 task lint。
-任一 task 阻塞则 VERIFY: BLOCKED · exit 2；全部可 30 则 VERIFY: PASS。
---task：另跑 task lint；E 级仅 WARN（v2.7+ · 不改 may_start_30）；--allow-lint-fail 抑制 WARN。
---json：输出 Agent handoff JSON（may_start_30 · entry_invoke_30 · review_path · lint 等）。
---agent-hint：人类可读 handoff 摘要（可与 --json 同用）。
---workspace-root：解析 task 中 Projects/ 前缀的 entry_invoke 路径。
+    console.log(`用法: npx @cyning/harness verify [--target PATH] [--task FILE | --spec FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH] [--allow-no-review] [--allow-lint-fail] [--allow-no-spec-review]
+
+无 --task/--spec：扫描 docs/tasks/active/task_*.md 并逐项列出闸表（同 gate-check）；不跑 task lint。
+--task：30 前聚合（gate + audit + reviews + lint WARN）· --allow-no-review / --allow-lint-fail。
+--spec：SPEC→00 前查审查文存在性（v2.8+ · 与 --task 互斥）· --allow-no-spec-review。
+  推荐：--spec <产品仓 SPEC> --workspace-root <含 docs/harness/reviews 的工作区根>
+--json / --agent-hint：Agent handoff。
 `);
     return;
   }
@@ -409,20 +414,24 @@ async function cmdVerify(args) {
   rest = r1;
   const { value: taskFile, rest: r2 } = takeOption(rest, '--task');
   rest = r2;
-  const { value: workspaceRoot, rest: r3 } = takeOption(rest, '--workspace-root');
+  const { value: specFile, rest: r3 } = takeOption(rest, '--spec');
   rest = r3;
+  const { value: workspaceRoot, rest: r4 } = takeOption(rest, '--workspace-root');
+  rest = r4;
   const graph = rest.includes('--graph');
   const json = rest.includes('--json');
   const agentHint = rest.includes('--agent-hint');
   const allowNoReview = rest.includes('--allow-no-review');
   const allowLintFail = rest.includes('--allow-lint-fail');
+  const allowNoSpecReview = rest.includes('--allow-no-spec-review');
   rest = rest.filter(
     (a) =>
       a !== '--graph' &&
       a !== '--json' &&
       a !== '--agent-hint' &&
       a !== '--allow-no-review' &&
-      a !== '--allow-lint-fail',
+      a !== '--allow-lint-fail' &&
+      a !== '--allow-no-spec-review',
   );
 
   if (rest.length > 0) {
@@ -431,8 +440,37 @@ async function cmdVerify(args) {
     throw err;
   }
 
+  if (taskFile && specFile) {
+    const err = new Error('verify：--task 与 --spec 互斥');
+    err.exitCode = 1;
+    throw err;
+  }
+
   const target = resolveTarget(process.cwd(), targetArg);
-  const result = verifyTarget(target, { taskFile, graph, allowNoReview, allowLintFail });
+  const ws = workspaceRoot ? path.resolve(workspaceRoot) : undefined;
+
+  let result;
+  let handoff;
+  let label;
+
+  if (specFile) {
+    result = verifySpecTarget(target, { specFile, workspaceRoot: ws, allowNoSpecReview });
+    handoff = buildSpecVerifyHandoff(target, {
+      specFile,
+      workspaceRoot: ws,
+      allowNoSpecReview,
+    });
+    label = path.basename(specFile);
+  } else {
+    result = verifyTarget(target, { taskFile, graph, allowNoReview, allowLintFail });
+    handoff = buildVerifyHandoff(target, {
+      taskFile,
+      workspaceRoot: ws,
+      allowNoReview,
+      allowLintFail,
+    });
+    label = taskFile ? path.basename(taskFile) : null;
+  }
 
   // forward gate-check/audit/graph stdout if any（--json 时仍透传机械闸表）
   if (result.stdout && !json) {
@@ -442,13 +480,6 @@ async function cmdVerify(args) {
     process.stderr.write(result.stdout);
   }
 
-  const handoff = buildVerifyHandoff(target, {
-    taskFile,
-    workspaceRoot: workspaceRoot ? path.resolve(workspaceRoot) : undefined,
-    allowNoReview,
-    allowLintFail,
-  });
-
   if (json) {
     console.log(JSON.stringify(handoff, null, 2));
   }
@@ -456,15 +487,13 @@ async function cmdVerify(args) {
     console.log(formatAgentHint(handoff));
   }
 
+  const summary = label
+    ? `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''} · ${label}`
+    : `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''}`;
+
   if (!json && !agentHint) {
-    const summary = taskFile
-      ? `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''} · ${path.basename(taskFile)}`
-      : `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''}`;
     console.log(summary);
   } else if (json || agentHint) {
-    const summary = taskFile
-      ? `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''} · ${path.basename(taskFile)}`
-      : `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''}`;
     console.error(summary);
   }
 

package/lib/task-meta.js

@@ -157,6 +157,107 @@ export function findReviewPath(target, taskFile) {
   return findReview(target, taskFile).latest;
 }
 
+/** 剥离文件名末尾 `_v\d+` */
+function stripVerSuffix(s) {
+  return String(s).replace(/_v\d+$/, '');
+}
+
+/**
+ * 自 SPEC 路径/正文解析 slug（优先表 `spec_slug`）。
+ */
+export function extractSpecSlug(specFile, content) {
+  const meta = content ? parseHarnessMeta(content) : {};
+  if (meta.spec_slug) return meta.spec_slug;
+
+  let base = path.basename(specFile, '.md');
+  base = base.replace(/^SPEC[-_]/i, '');
+  base = stripVerSuffix(base);
+  return base;
+}
+
+/**
+ * bugfix / 显式跳过 10-spec 审计：不要求 SPEC 审查文。
+ * 只认元信息表 / 文首 track 行——避免命中正文里对规则的说明文字。
+ */
+export function shouldSkipSpecAudit(content) {
+  if (!content) return false;
+  const meta = parseHarnessMeta(content);
+  if (String(meta.skip_spec_audit || '').toLowerCase() === 'true') return true;
+  if (String(meta.track || '').toLowerCase() === 'bugfix') return true;
+  if (/^>\s*\*\*track\*\*[：:]\s*`?bugfix\b/im.test(content)) return true;
+  return false;
+}
+
+/**
+ * 查找 SPEC 的 R<n> 审查文（verify --spec · N3）。
+ * 兼容命名：
+ * 1. spec_<slug>_audit_R<n>_*.md（推荐）
+ * 2. spec_<slug>_ACCEPT_R<n>_*.md
+ * 3. task_<slug>_spec_ACCEPT_R<n>_*.md
+ * 在 target 与可选 workspaceRoot 的 docs/harness/reviews/ 下搜索。
+ */
+export function findSpecReview(specFile, options = {}) {
+  const { target = process.cwd(), workspaceRoot } = options;
+  const empty = { found: false, latest: null, rounds: [], matched_pattern: null };
+
+  const absSpec = path.isAbsolute(specFile)
+    ? specFile
+    : path.resolve(target, specFile);
+  if (!fs.existsSync(absSpec)) return empty;
+
+  const content = fs.readFileSync(absSpec, 'utf8');
+  const slugNorm = normalizeSlug(stripVerSuffix(extractSpecSlug(absSpec, content)));
+
+  const roots = [];
+  const pushRoot = (root) => {
+    if (!root) return;
+    const abs = path.resolve(root);
+    if (!roots.includes(abs)) roots.push(abs);
+  };
+  pushRoot(target);
+  pushRoot(workspaceRoot);
+
+  const PATTERNS = [
+    { id: 'spec_audit', re: /^spec_(.+?)_audit_R(\d+)_.*\.md$/i },
+    { id: 'spec_ACCEPT', re: /^spec_(.+?)_ACCEPT_R(\d+)_.*\.md$/i },
+    { id: 'task_spec_ACCEPT', re: /^task_(.+?)_spec_ACCEPT_R(\d+)_.*\.md$/i },
+  ];
+
+  const matches = [];
+  for (const root of roots) {
+    const reviewsDir = path.join(root, 'docs/harness/reviews');
+    if (!fs.existsSync(reviewsDir)) continue;
+    for (const name of fs.readdirSync(reviewsDir)) {
+      for (const pat of PATTERNS) {
+        const m = name.match(pat.re);
+        if (!m) continue;
+        if (normalizeSlug(stripVerSuffix(m[1])) !== slugNorm) continue;
+        matches.push({
+          name,
+          round: parseInt(m[2], 10),
+          mtime: fs.statSync(path.join(reviewsDir, name)).mtimeMs,
+          pattern: pat.id,
+          root,
+          rel: path.join('docs/harness/reviews', name).replace(/\\/g, '/'),
+        });
+        break;
+      }
+    }
+  }
+
+  if (matches.length === 0) return empty;
+
+  matches.sort((a, b) => b.round - a.round || b.mtime - a.mtime);
+  const latest = matches[0];
+  return {
+    found: true,
+    latest: latest.rel,
+    rounds: [...new Set(matches.map((x) => x.round))].sort((a, b) => a - b),
+    matched_pattern: latest.pattern,
+    reviews_root: latest.root,
+  };
+}
+
 /**
  * 聚合单 task 的 Agent handoff 结果。
  */

package/lib/verify.js

@@ -1,8 +1,16 @@
 import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import { resolveHarnessRootForTarget, wizardScript } from './paths.js';
 import { auditTarget } from './audit.js';
-import { buildTaskHandoff, findReview, listActiveTasks } from './task-meta.js';
+import {
+  buildTaskHandoff,
+  extractSpecSlug,
+  findReview,
+  findSpecReview,
+  listActiveTasks,
+  shouldSkipSpecAudit,
+} from './task-meta.js';
 import { lintTaskFile } from './task-lint.js';
 
 /**
@@ -89,6 +97,96 @@ function runTaskLintForVerify(target, taskFile) {
   }
 }
 
+/**
+ * SPEC→00 前验证（N3 · v2.8+）：仅查 SPEC 审查文存在性。
+ * 不跑 gate-check / audit D5 / task lint（与 --task 模式分离）。
+ */
+export function verifySpecTarget(target, options = {}) {
+  const { specFile, workspaceRoot, allowNoSpecReview = false } = options;
+  let stdout = '';
+
+  if (!specFile) {
+    return {
+      ok: false,
+      exitCode: 1,
+      reason: 'verify --spec 须指定 SPEC 文件路径',
+      stdout,
+    };
+  }
+
+  const absSpec = path.isAbsolute(specFile)
+    ? specFile
+    : path.resolve(target, specFile);
+  if (!fs.existsSync(absSpec)) {
+    return {
+      ok: false,
+      exitCode: 1,
+      reason: `SPEC 文件不存在: ${specFile}`,
+      stdout,
+    };
+  }
+
+  const content = fs.readFileSync(absSpec, 'utf8');
+  if (shouldSkipSpecAudit(content)) {
+    stdout += `INFO: skip SPEC review gate（bugfix / skip_spec_audit）\n`;
+    return { ok: true, exitCode: 0, stdout, skipped: true };
+  }
+
+  const review = findSpecReview(absSpec, { target, workspaceRoot });
+  if (!review.found) {
+    if (allowNoSpecReview) {
+      stdout += `WARN: missing SPEC R<n> review（--allow-no-spec-review 豁免 · 留痕）\n`;
+      return { ok: true, exitCode: 0, stdout, skipped: false };
+    }
+    return {
+      ok: false,
+      exitCode: 2,
+      reason:
+        'missing SPEC R<n> review（docs/harness/reviews/ 无 spec_*_audit_R / *_ACCEPT_R · 20-spec-audit 或 --allow-no-spec-review）',
+      stdout,
+    };
+  }
+
+  return { ok: true, exitCode: 0, stdout, skipped: false };
+}
+
+/** SPEC 模式 handoff（verify --spec --json） */
+export function buildSpecVerifyHandoff(target, options = {}) {
+  const { specFile, workspaceRoot, allowNoSpecReview = false } = options;
+  const absSpec = path.isAbsolute(specFile)
+    ? specFile
+    : path.resolve(target, specFile);
+  const content = fs.existsSync(absSpec) ? fs.readFileSync(absSpec, 'utf8') : '';
+  const skipped = shouldSkipSpecAudit(content);
+  const review = skipped
+    ? { found: false, latest: null, rounds: [], matched_pattern: null }
+    : findSpecReview(absSpec, { target, workspaceRoot });
+
+  const reviewOk = skipped || review.found || allowNoSpecReview;
+  let blocked_reason = null;
+  if (!reviewOk) {
+    blocked_reason = 'missing SPEC R<n> review';
+  }
+
+  return {
+    schema_version: '1',
+    mode: 'spec',
+    verify_ok: reviewOk,
+    may_start_00: reviewOk,
+    spec: path.basename(specFile),
+    spec_path: specFile.replace(/\\/g, '/'),
+    spec_slug: content ? extractSpecSlug(absSpec, content) : null,
+    spec_review_found: Boolean(review.found),
+    spec_review_latest: review.latest,
+    spec_review_rounds: review.rounds ?? [],
+    spec_review_skipped: skipped,
+    spec_review_suppressed: Boolean(allowNoSpecReview && !review.found && !skipped),
+    matched_pattern: review.matched_pattern ?? null,
+    blocked_reason,
+    next_hat: reviewOk ? '00' : null,
+  };
+}
+
 /** 规范化 lint 结果供 handoff */
 export function lintSnapshotForHandoff(target, taskFile, { allowLintFail = false } = {}) {
   if (!taskFile) return null;
@@ -258,6 +356,16 @@ export function buildVerifyHandoff(target, options = {}) {
 export function formatAgentHint(payload) {
   const lines = ['=== Harness verify · agent-hint ==='];
 
+  if (payload.mode === 'spec') {
+    lines.push(`spec: ${payload.spec}`);
+    lines.push(`  may_start_00: ${payload.may_start_00}`);
+    if (payload.blocked_reason) lines.push(`  blocked: ${payload.blocked_reason}`);
+    if (payload.spec_review_latest) lines.push(`  review: ${payload.spec_review_latest}`);
+    if (payload.spec_review_skipped) lines.push(`  review: skipped`);
+    if (payload.next_hat) lines.push(`  next_hat: ${payload.next_hat}`);
+    return lines.join('\n').trimEnd();
+  }
+
   const items = payload.tasks ?? [payload];
   for (const item of items) {
     lines.push(`task: ${item.task}`);

package/package.json

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