@cyning/harness 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@
 
 ## [Unreleased]
 
+## [2.9.0] - 2026-07-25
+
+### Changed
+
+- **⚠ 行为变更 · 裸 `verify`（无 `--task`/`--spec`）纳入 reviews 留档闸（N4 · G2 residual）**：gate-check 通过后对每个 active 跑 `findReview`；任一缺失 → `VERIFY: BLOCKED · missing R<n> review（n/m tasks · basename…）` exit 2。豁免：`--allow-no-review`（WARN 放行）。
+- **active 发现双路径**：`listActiveTasks` 与 `gate-check.sh` 同步扫描 `docs/tasks/active` ∪ `docs/harness/tasks/active`（同 basename 优先 Starter）。
+- 全量 `--json`：每 task 的 `may_start_30` / `verify_ok` 纳入 `review_found`（与 `--task` 同构）。
+- `lifecycle.yaml` `to_30` / `reviews_retention`：描述覆盖「`--task` 与全量」。
+
+### Notes
+
+- 全量模式仍**不**跑 task lint / audit D5（维持 N2）。
+- SPEC：`docs/spec/SPEC-verify-full-reviews-gate_v1.md`
+- minor · 行为更严 · 存量「闸表可 30 但无审查文」将被挡（可补审或 `--allow-no-review`）
+
+## [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 · 行为新增（新模式）
+- **已发布**：`@cyning/harness@2.8.0`（npm `latest` · 2026-07-25）· tag `v2.8.0` 已推送
+
 ## [2.7.0] - 2026-07-24
 
 ### Added
@@ -17,6 +48,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

@@ -45,13 +45,20 @@ cd your-project
 `npx @cyning/harness verify` 在 30 执行前聚合扫描人工闸与测试声明，确保 ICVO 公理可机械检查：
 
 ```bash
-# 30 前聚合验证（gate-check + audit D5 + reviews + S5 warn + 可选 --graph）
+# 30 前聚合验证（gate-check + reviews + S5 warn + 可选 --graph）
+# 无 --task：双路径 active（docs/tasks/active ∪ docs/harness/tasks/active）+ 全量 reviews（v2.9+）
 npx @cyning/harness verify --target /path/to/your-repo
+# 缺审查文豁免：--allow-no-review
 npx @cyning/harness verify --target /path/to/your-repo \
   --task docs/tasks/active/task_xxx.md
-# --task 另跑 task lint（v2.7+ · E 级仅 WARN，不挡 may_start_30）
+# --task 另跑 audit D5 + 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
@@ -71,7 +78,9 @@ npx @cyning/harness sync index --target /path/to/your-repo
 | 公理 | 检查项 | 行为 |
 |------|--------|------|
 | **D3** | 30 前置人闸 | 复用 `gate-check.sh`，HG-AUDIT-R1 非 approved 时 verify 非 0 |
-| **D5** | 改码任务测试声明 | `test_strategy=required` 但无测试/CI 引用时 verify 非 0 |
+| **D5** | 改码任务测试声明 | 仅 `--task`：`test_strategy=required` 但无测试/CI 引用时 verify 非 0 |
+| **reviews** | R<n> 审查文存在 | `--task` 与全量（v2.9+）· 缺文 BLOCKED · `--allow-no-review` |
+| **active** | 任务发现 | 双路径 `docs/tasks/active` ∪ `docs/harness/tasks/active`（v2.9+） |
 | **S5** | Git 工作区干净 | dirty 时 warn（不直接 fail verify，但 apply 须 `--force`） |
 | **lint** | task 结构（仅 `--task`） | v2.7+ E 级 → `WARN: task lint`（不改 exit / `may_start_30`） |
 

package/docs/USER_GUIDE_v1.0_zh.md

@@ -111,10 +111,19 @@ npx @cyning/harness@1.0.1 init --preset harness-only --ide cursor,agents --yes
 **原则**：Agent 可以写 task 和 review，**人工闸只有维护者能签**。
 
 ```bash
-# 30 前聚合验证（gate-check + audit D5 + reviews + task lint WARN + S5 · 可选 --graph）
+# 全量（无 --task）：双路径 active + 闸表 + reviews（v2.9+ · 不跑 lint/D5）
+npx @cyning/harness verify --target .
+# 缺审查文豁免：--allow-no-review
+
+# 单 task：gate-check + audit D5 + reviews + task lint WARN + S5 · 可选 --graph
 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 \
@@ -141,6 +150,7 @@ npx @cyning/harness gate-check --graph --target .    # Inform 图谱闸
 | `HG-GRAPH-MODULES` | 架构模块表人签 | pending → 拒改码 30 |
 | `HG-RELEASE` | 发版闸（产品仓） | 一般业务仓不涉及 |
 | `task_lint`（v2.7+） | `verify --task` 结构检查 | **仅 WARN** · 不改 `may_start_30` |
+| `reviews`（全量 v2.9+） | 裸 verify 亦查 R<n> 文 | 缺文 → BLOCKED · `--allow-no-review` |
 
 ### 5.1 Agent handoff（v2.0.2+）
 
@@ -148,7 +158,8 @@ npx @cyning/harness gate-check --graph --target .    # Inform 图谱闸
 
 | JSON 字段 | 含义 |
 | --- | --- |
-| `may_start_30` | 等价 gate-check「可 30」 |
+| `may_start_30` | 闸表可 30 **且** `review_found`（或豁免） |
+| `review_found` | R<n> 审查文是否存在（全量与 `--task` 同构 · v2.9+） |
 | `blocked_reason` | 阻塞时 D2/D3 文案 |
 | `review_path` | 最新 `*_audit_R1_*.md`（相对 target） |
 | `entry_invoke_30` | task 表原始路径 |
@@ -172,7 +183,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` | 全量：双路径 + reviews（v2.9+）；`--task`：30 前聚合；`--spec`：SPEC→00（v2.8+ · 互斥） |
 | `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/docs/spec/SPEC-verify-full-reviews-gate_v1.md

@@ -0,0 +1,183 @@
+# SPEC：verify 全量模式纳入 reviews 留档闸（N4）（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) · N4 · G2 residual  
+> **前置**：G2 `@cyning/harness@2.5.0`（`--task` 已查 reviews）· N3 `@2.8.0`  
+> **下游**：30/40 已完成（分支 `task/cyning-harness-verify-full-reviews-gate` · package **2.9.0** · 待 publish）
+
+---
+
+## Harness 元信息
+
+| 字段 | 值 |
+|------|-----|
+| **spec_slug** | `verify-full-reviews-gate` |
+| **test_strategy** | `required` |
+| **test_strategy_note** | 全量模式：有文 PASS / 缺文 BLOCKED / `--allow-no-review`；双路径发现；既有 `--task` 回归不变 |
+| **entry_invoke_10_spec** | `Projects/docs/harness/invokes/by-task/cyning-harness-verify-full-reviews-gate/invoke_20260725_10_spec_verify_full_reviews_gate.md` |
+| **entry_invoke_00_draft** | 工作区 `docs/harness/prompts/PROMPT_00_draft_spec_or_task_v1_zh.md` |
+
+---
+
+## 1. 背景与目标
+
+G2（v2.5.0）把「R<n> 审查文存在」挂在 **`verify --task`** 与 `task close`，但 R2 明确：**无 `--task` 全量模式本波只查闸表**。后果：
+
+1. **语义裂缝**：`verify --task X` 会因缺审查文 BLOCKED，但裸 `verify`（全量）在闸表全 approved 时仍可能 **PASS**——「仓库可否 30」答案因是否传 `--task` 而分裂。
+2. **发现路径裂缝**：`gate-check` / `listActiveTasks` 只扫 `docs/tasks/active`；工作区 Extended 真值在 `docs/harness/tasks/active`。对 Projects 根跑裸 `verify` →「无 active」vacuous PASS，与人工闸表现实脱节。
+
+**dogfood（2026-07-25 · `findReview` + `evaluateMayStart30`）**：`docs/harness/tasks/active` **15** 个 task：
+
+| 指标 | 值 |
+|------|-----|
+| `may_start_30=true` | **4** |
+| 其中缺 R<n> 审查文 | **3**（`a5_cli_verify` · `hat_chain_pointer_sync` · `task_validate_human_gate_ci_gate`） |
+| 有审查文且可 30 | **1**（`ops_clarify_single_run_resume`） |
+
+→ 若仅扩展 reviews 检查而不扩路径，N4 对工作区几乎无效果；若扩路径 + 查 reviews，裸 `verify` 将暴露上述 3 个「闸表可 30 但无审查文」任务（预期拦截 · 可用 `--allow-no-review`）。
+
+**目标**：闭合 G2 residual——全量模式与 `--task` 在 **reviews 存在性** 上同构；并让全量发现覆盖 Starter（`docs/tasks/active`）与 Extended（`docs/harness/tasks/active`）。
+
+**职责切分（同 G2）**：机器 = 存在性；人 = `HG-AUDIT-R1` 结论。
+
+---
+
+## 2. 范围
+
+### D1 · 全量模式 reviews 闸（`lib/verify.js`）
+
+- 当**无** `--task` 且**无** `--spec`：在 gate-check 通过后，对发现的每个 active task 调用 `findReview`：
+  - 任一缺失 → `VERIFY: BLOCKED · missing R<n> review`（reason 列出 basename，如 `3/15 tasks · a.md, b.md, …`）· exit 2
+  - `--allow-no-review` → 对缺失者 WARN 放行（与 `--task` 同旗）
+- **不**在全量模式跑 task lint（维持 N2：仅 `--task`）
+- **不**在全量模式跑 audit D5 逐 task（本波不变；另议）
+
+### D2 · active 发现双路径
+
+- `listActiveTasks(target)`：返回  
+  `docs/tasks/active/task_*.md` ∪ `docs/harness/tasks/active/task_*.md`  
+  （去重：同 basename 优先 Starter 路径；排序稳定）
+- `wizard/gate-check.sh`：**同步**双路径扫描（无 `--task` 时），避免闸表集合 ≠ reviews 集合
+- 文档：ONBOARDING/USER_GUIDE 注明双路径
+
+### D3 · handoff 对齐
+
+- 全量 `--json`：每个 task 的 `may_start_30` / `verify_ok` **纳入** `review_found`（与单 `--task` 一致）；根级 `verify_ok` = 全部可 30（含审查文）
+- `--agent-hint` 可显示缺审查文的 blocked 行
+
+### D4 · lifecycle 登记
+
+- `harness/lifecycle.yaml`：`to_30` 的 `reviews_retention` 注释/描述改为覆盖「`--task` 与全量模式」；不新增转移 id（同守卫 · 两入口）
+
+### D5 · 测试 / 文档 / 版本
+
+- 测试：全量三态（全有文 PASS / 一缺 BLOCKED / allow 豁免）+ 双路径夹具（仅 harness 路径也能被扫到）+ 既有 `--task` 回归
+- CHANGELOG **v2.9.0**（⚠ 行为变更：裸 verify 更严）+ 豁免指引
+- PLAN / G2 SPEC residual 回链关闭
+
+### D6 · dogfood（实现波）
+
+- 对工作区根或含 `docs/harness/tasks/active` 的 target 跑裸 `verify`，报告 BLOCKED 列表与豁免后结果；落自检结论（可修审查文或 `--allow-no-review`，不强制本波修齐 3 个存量）
+
+---
+
+## 3. 非范围
+
+- 全量模式接入 **task lint**（N2-C / 另 SPEC）
+- 全量模式逐 task **audit D5**
+- SPEC 侧全量扫描（已有 `verify --spec` 单文件）
+- 强制补齐 dogfood 3 个缺审查文的存量 task
+- 审查文内容判定；状态机引擎
+
+---
+
+## 4. 验收标准
+
+- [ ] 无 `--task`：active 均有 R&lt;n&gt; 文 → PASS（闸表亦过）
+- [ ] 无 `--task`：至少一 task 缺审查文 → BLOCKED exit 2 · reason 含该 basename
+- [ ] `--allow-no-review`：全量缺失 → WARN + PASS
+- [ ] 仅存在 `docs/harness/tasks/active` 时，gate-check / listActiveTasks 仍能发现 task
+- [ ] `--task` 行为与 v2.8 一致（回归）
+- [ ] 全量 `--json`：`may_start_30` 含审查文条件
+- [ ] `npm test` 全绿；CHANGELOG v2.9.0 行为变更醒目
+- [ ] dogfood 分布落自检结论
+
+---
+
+## 5. failure_paths
+
+| 触发条件 | 系统行为 | 可重试 |
+|----------|----------|--------|
+| 全量扫描发现缺审查文 | BLOCKED · 列出 task | 补 20 审 / `--allow-no-review` |
+| 双路径同 basename 重复 | 去重后只检一次 | — |
+| 业务仓只有 Starter 路径 | 行为 = 只扫 `docs/tasks/active`（与今同构 + reviews） | — |
+| 未升级 2.9.0 | 全量仍不查 reviews | upgrade |
+| 存量 3 个可 30 无审查文被挡 | **预期** | 补审或豁免 |
+
+---
+
+## 6. 依赖与引用
+
+- G2：`findReview` · `--allow-no-review` · SPEC residual ③  
+- N2：全量不跑 lint（本 SPEC 维持）  
+- `listActiveTasks` · `gate-check.sh` ACTIVE_DIR  
+- PLAN N4
+
+---
+
+## 7. 思考轮（10-spec 回填 · R0–R5）
+
+### R0 · 读入与约束
+
+读入：PLAN N4；G2 R2「全量本波不变」+ residual ③；`verify.js` 仅 `taskFile` 分支查 reviews；`listActiveTasks` / gate-check 仅 `docs/tasks/active`；dogfood 15/4/3。约束：行为变更须豁免阀 + CHANGELOG；挂点须与检查物同时刻（审查文应在 R1 后已存在）。
+
+### R1 · 范围 / 非范围 / 场景
+
+**场景**：① 维护者/Agent 裸 `verify` 做仓库健康检查，应与逐 task `--task` 对「可 30」同答案；② Extended 工作区 active 在 harness 路径下也要被扫到；③ 存量缺文用豁免，不强制本波修齐。  
+**非范围**：lint/D5 全量化、SPEC 全量、内容判定——避免 N4 膨胀成「verify 大一统」。
+
+### R2 · 方案对比
+
+| 决策点 | 选项 | 裁定 | 理由 |
+|---|---|---|---|
+| 是否纳入 reviews | 否（关账 N4）/ warn / block | **block + `--allow-no-review`** | 与 G2 `--task` 同构；warn 再留自觉层；dogfood 已能量化误伤面（3 task） |
+| 检查哪些 task | 全部 active / 仅 may_start_30 | **全部发现的 active**（与 gate-check 集合对齐） | 闸表未 approved 者 gate-check 已挡；对已过闸者补审查文洞；实现简单 |
+| 双路径 | 仅 Starter / Starter∪Extended | **∪ 双路径**（listActiveTasks + gate-check 同步） | 否则 N4 对 Projects dogfood 无效 |
+| 全量 lint | 顺带做 / 不做 | **不做** | N2 已拒；FAIL 率仍高 |
+| 版本 | 2.8.x / 2.9.0 | **2.9.0** | 裸 verify 行为变更 · minor |
+
+### R3 · 边界 / 失败语义 / 安全
+
+- **误伤**：主要是「闸表可 30 且无审查文」——正是 G2 要抓的类；豁免旗复用。  
+- **空 active**：两路径皆无 → 维持现状（gate-check 提示无 active · exit 0）。  
+- **安全**：只读。  
+- **兼容**：`--task` / `--spec` 不变。
+
+### R4 · 验收 / 可测性 / test_strategy
+
+`test_strategy: required`。夹具：双路径目录、全量缺一文、allow 豁免；回归 verify-review-gate / verify-lint-warn。dogfood 命令写进 40 自检。
+
+### R5 · SPEC 签收就绪 · 是否可交 00 出 task
+
+自足：裁定、路径、豁免、版本清晰。**可交 00**：单 task `cyning-harness-verify-full-reviews-gate`。图谱无需。关闭 G2 residual ③。
+
+### 思考轮控制
+
+| 字段 | 值 |
+|------|-----|
+| `actual_last_round` | `R5` |
+| `early_stop` | `no` |
+| `early_stop_reason` | — |
+| `residual_risks` | ① gate-check 双路径改 bash 须防破既有单测路径假设；② 去重规则若两目录同 slug 不同内容属数据错误——本波只去重不深比较；③ 全量 D5 仍空缺，健康检查仍非「可 30」充分条件 |
+| `round_extension_note` | — |
+
+---
+
+## 修订记录
+
+| 日期 | 摘要 |
+|------|------|
+| 2026-07-25 | 10-spec R0–R5（维护者点菜「继续 N4」）· dogfood 15/4/3 |
+| 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,11 +18,23 @@ 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
     hat: "30"
-    description: "执行帽开工（verify --task 聚合）"
+    description: "执行帽开工（verify --task 与全量模式聚合 · v2.9+）"
     guards:
       - id: HG-AUDIT-R1
         command_or_check: "gate-check · human_gate HG-AUDIT-R1=approved"
@@ -32,9 +46,10 @@ transitions:
         command_or_check: "verify/audit · test_strategy vs 测试文件存在"
         severity: block
       - id: reviews_retention
-        command_or_check: "verify · findReview R<n> 存在性（v2.5+）"
+        command_or_check: "verify --task 与全量 · findReview R<n> 存在性（v2.5+ · 全量 v2.9+）"
         severity: block
         allow_flag: "--allow-no-review"
+        note: "全量模式扫描双路径 active；不跑 lint / D5"
       - id: task_lint
         command_or_check: "verify --task · lintTaskFile（v2.7+）"
         severity: warn

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,22 @@ 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 ∪ docs/harness/tasks/active（同 basename 优先 Starter）；
+  闸表 + 全量 reviews 存在性（v2.9+）· 不跑 task lint / D5 · --allow-no-review。
+--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 +415,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 +441,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 +481,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 +488,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 结果。
  */
@@ -209,17 +310,25 @@ export function buildTaskHandoff(target, taskFile, options = {}) {
 }
 
 /**
- * 扫描 target 下 active task 列表。
+ * 扫描 target 下 active task 列表（N4 · v2.9+）。
+ * 双路径：docs/tasks/active ∪ docs/harness/tasks/active；
+ * 同 basename 优先 Starter；排序稳定。
  */
 export function listActiveTasks(target) {
-  const activeDir = path.join(target, 'docs/tasks/active');
-  if (!fs.existsSync(activeDir)) return [];
-
-  return fs
-    .readdirSync(activeDir)
-    .filter((f) => f.startsWith('task_') && f.endsWith('.md'))
-    .map((f) => path.join('docs/tasks/active', f).replace(/\\/g, '/'))
-    .sort();
+  const dirs = ['docs/tasks/active', 'docs/harness/tasks/active'];
+  const byBasename = new Map();
+
+  for (const dir of dirs) {
+    const abs = path.join(target, dir);
+    if (!fs.existsSync(abs)) continue;
+    for (const f of fs.readdirSync(abs)) {
+      if (!f.startsWith('task_') || !f.endsWith('.md')) continue;
+      if (byBasename.has(f)) continue;
+      byBasename.set(f, path.join(dir, f).replace(/\\/g, '/'));
+    }
+  }
+
+  return [...byBasename.values()].sort();
 }
 
 function escapeRegExp(s) {

package/lib/verify.js

@@ -1,13 +1,22 @@
 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';
 
 /**
- * 30 前聚合验证：gate-check + audit D5（仅 --task）+ reviews 留档闸（仅 --task）
- * + task lint WARN（仅 --task · v2.7+）+ S5 git-clean warn + 可选 --graph
+ * 30 前聚合验证：gate-check + audit D5（仅 --task）+ reviews 留档闸
+ *（--task 与全量 · N4/v2.9+）+ task lint WARN（仅 --task · v2.7+）
+ * + S5 git-clean warn + 可选 --graph
  */
 export function verifyTarget(target, options = {}) {
   const { taskFile, graph, allowNoReview = false, allowLintFail = false } = options;
@@ -61,6 +70,26 @@ export function verifyTarget(target, options = {}) {
         gateResult.stdout += `WARN: task lint FAIL · ${rules || 'errors'}（不挡 may_start_30 · 修结构或 --allow-lint-fail）\n`;
       }
     }
+  } else {
+    // 3c. 全量 reviews 闸（N4 · v2.9+）：不跑 lint / D5
+    const taskFiles = listActiveTasks(target);
+    const missing = [];
+    for (const tf of taskFiles) {
+      if (!findReview(target, tf).found) missing.push(path.basename(tf));
+    }
+    if (missing.length > 0) {
+      const detail = `${missing.length}/${taskFiles.length} tasks · ${missing.join(', ')}`;
+      if (allowNoReview) {
+        gateResult.stdout += `WARN: missing R<n> review（--allow-no-review 豁免 · 留痕）· ${detail}\n`;
+      } else {
+        return {
+          ok: false,
+          exitCode: 2,
+          reason: `missing R<n> review（${detail}）`,
+          stdout: gateResult.stdout,
+        };
+      }
+    }
   }
 
   // 4. S5 git-clean：warn 不挡
@@ -89,6 +118,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;
@@ -237,14 +356,19 @@ export function buildVerifyHandoff(target, options = {}) {
   const taskFiles = listActiveTasks(target);
   const tasks = taskFiles.map((tf) => {
     const handoff = buildTaskHandoff(target, tf, handoffOpts);
+    const reviewOk = handoff.review_found || allowNoReview;
+    const verifyOk = handoff.may_start_30 && reviewOk;
     return {
       schema_version: '1',
-      verify_ok: handoff.may_start_30,
+      verify_ok: verifyOk,
       ...handoff,
+      may_start_30: verifyOk,
+      blocked_reason: handoff.blocked_reason ?? (reviewOk ? null : 'missing R<n> review'),
+      next_hat: verifyOk ? '30' : null,
     };
   });
 
-  const verifyOk = tasks.length > 0 && tasks.every((t) => t.may_start_30);
+  const verifyOk = tasks.length > 0 && tasks.every((t) => t.verify_ok);
   return {
     schema_version: '1',
     verify_ok: verifyOk,
@@ -258,6 +382,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.9.0",
   "description": "cyning-harness discipline package · init / upgrade / check CLI",
   "license": "MIT",
   "type": "module",

package/wizard/gate-check.sh

@@ -174,6 +174,29 @@ if [[ "$JSON_MODE" != "1" ]]; then
   echo ""
 fi
 
+# N4 · v2.9+：双路径发现（Starter ∪ Extended）；同 basename 优先 Starter
+# 输出绝对路径列表到 TASK_LIST（bash 3.2 兼容 · 无关联数组）
+collect_active_tasks() {
+  TASK_LIST=()
+  local dir tf base existing already
+  for dir in "$TARGET/docs/tasks/active" "$TARGET/docs/harness/tasks/active"; do
+    [[ -d "$dir" ]] || continue
+    for tf in "$dir"/task_*.md; do
+      [[ -f "$tf" ]] || continue
+      base="$(basename "$tf")"
+      already=0
+      for existing in "${TASK_LIST[@]+"${TASK_LIST[@]}"}"; do
+        if [[ "$(basename "$existing")" == "$base" ]]; then
+          already=1
+          break
+        fi
+      done
+      [[ "$already" == "1" ]] && continue
+      TASK_LIST+=("$tf")
+    done
+  done
+}
+
 BLOCKED=0
 
 if [[ "$GRAPH_MODE" == "1" ]]; then
@@ -191,26 +214,16 @@ if [[ "$GRAPH_MODE" == "1" ]]; then
     fi
     graph_for_task "$TASK_FILE"
   else
-    ACTIVE_DIR="$TARGET/docs/tasks/active"
-    if [[ ! -d "$ACTIVE_DIR" ]]; then
+    collect_active_tasks
+    if [[ ${#TASK_LIST[@]} -eq 0 ]]; then
       if [[ "$JSON_MODE" == "1" ]]; then
         printf ']\n'
       else
-        echo "⚠️  无 $ACTIVE_DIR" >&2
+        echo "无 active task_*.md（docs/tasks/active ∪ docs/harness/tasks/active）"
       fi
       exit 0
     fi
-    TASK_FILES=("$ACTIVE_DIR"/task_*.md)
-    if [[ ! -e "${TASK_FILES[0]}" ]]; then
-      if [[ "$JSON_MODE" == "1" ]]; then
-        printf ']\n'
-      else
-        echo "无 active task_*.md"
-      fi
-      exit 0
-    fi
-    for tf in "$ACTIVE_DIR"/task_*.md; do
-      [[ -f "$tf" ]] || continue
+    for tf in "${TASK_LIST[@]}"; do
       if [[ "$JSON_MODE" == "1" ]]; then
         [[ "$local_first" == "1" ]] || printf ','
         local_first=0
@@ -234,15 +247,16 @@ if [[ -n "$TASK_FILE" ]]; then
   fi
   check_one_task "$TASK_FILE" || BLOCKED=1
 else
-  ACTIVE_DIR="$TARGET/docs/tasks/active"
-  [[ -d "$ACTIVE_DIR" ]] || { echo "无 $ACTIVE_DIR" >&2; exit 1; }
-  TASK_FILES=("$ACTIVE_DIR"/task_*.md)
-  if [[ ! -e "${TASK_FILES[0]}" ]]; then
+  collect_active_tasks
+  if [[ ${#TASK_LIST[@]} -eq 0 ]]; then
+    if [[ ! -d "$TARGET/docs/tasks/active" && ! -d "$TARGET/docs/harness/tasks/active" ]]; then
+      echo "无 docs/tasks/active 且无 docs/harness/tasks/active" >&2
+      exit 1
+    fi
     echo "无 active task_*.md"
     exit 0
   fi
-  for tf in "$ACTIVE_DIR"/task_*.md; do
-    [[ -f "$tf" ]] || continue
+  for tf in "${TASK_LIST[@]}"; do
     check_one_task "$tf" || BLOCKED=1
   done
 fi