@cyning/harness 2.0.1 → 2.0.4

package/docs/methodology/product/README.md

@@ -2,7 +2,8 @@
 
 | 文档 | 说明 |
 | --- | --- |
-| **[`DESIGN_ONTOLOGY_v1_zh.md`](./DESIGN_ONTOLOGY_v1_zh.md)** | **真值** v1.2 · Track / Hat / Sync / P·S·D 公理 / ICVO |
+| **[`DESIGN_ONTOLOGY_v1_zh.md`](./DESIGN_ONTOLOGY_v1_zh.md)** | **真值** v1.3 · Track / Hat / Sync / P·S·D 公理 / ICVO |
+| **[`SDD_HAT_FLOW_v2_zh.md`](./SDD_HAT_FLOW_v2_zh.md)** | **帽链流程** · 人读版 · 30→40 · 打回规则 |
 
 **分层**：回答「产品 **是什么** · 由哪些实体组成 · 允许哪些状态转移」。
 

package/docs/methodology/product/SDD_HAT_FLOW_v2_zh.md

@@ -0,0 +1,78 @@
+# SDD 帽链流程（V2 · 产品仓真值）
+
+| 项 | 内容 |
+|----|------|
+| **版本** | v2.0 |
+| **日期** | 2026-06-21 |
+| **关联** | [`DESIGN_ONTOLOGY_v1_zh.md`](./DESIGN_ONTOLOGY_v1_zh.md) §3.2 · §4.1 · §8 · [`../../../harness/prompts/README.md`](../../../harness/prompts/README.md) |
+
+---
+
+## 1. 标准流程（功能 / Epic）
+
+```text
+人 + 00 chat 生成大纲
+  → 10-spec R0–R9（回填 SPEC · 可多轮）
+  → 20-spec-audit（规格验收 · reviews/）
+       ↔ HG-SPEC-SIGNOFF（人签 · 未过则回到 10-spec 或 20 再审）
+  → 00 起草 P0 task（自 SPEC §13 投影）
+  → 10-task（回填 task §5）
+  → 20-task-audit R1（reviews/ · 可打回 10-task）
+       ↔ HG-AUDIT-R1（人签）
+  → 30 实现
+  → 40 自检（通常由 30 同一 Agent 连续执行 · 失败自修并重跑 40 直至通过 · 无需单独开 40 对话）
+  → 50 独立复检（可选 · 未过打回 30）
+  → CLOSE（关账 · KPI）
+```
+
+**10 / 20 配对**
+
+| 10 | 20 | 人闸 |
+|----|-----|------|
+| 10-spec | 20-spec-audit | HG-SPEC-SIGNOFF |
+| 10-task | 20-task-audit | HG-AUDIT-R1 |
+
+历史别名：`10-requirements`→10-task · `22-task-audit`→20-task-audit。
+
+---
+
+## 2. 打回与关账
+
+| 节点 | 常见打回 | 说明 |
+|------|----------|------|
+| 20-spec-audit | → **10-spec** | 规格缺口 · 人闸 pending / rejected |
+| 20-task-audit | → **10-task** | task 验收 / failure_paths 不可执行 |
+| 50 | → **30** | 独立视角发现实现问题 |
+| CLOSE | → **下一 task / SPEC 增量** | 小问题留后续迭代 |
+| CLOSE | → **10-spec 或 10-task** | 结果与预期相差太远 · 维护者决策重开 |
+
+**30→40**：不强制新对话；30 Agent 跑验证命令、回填 `### 自检结论（执行者）`，不通过则改码再跑，直到 task 所列命令绿。
+
+**00**：编排层 · 不写产品代码 · 起草 SPEC/task · 派下一棒 Prompt。
+
+---
+
+## 3. bugfix 捷径
+
+Issue ≈ mini-SPEC 且已签收时：**跳过 10-spec / 20-spec-audit** · 自 **00 草稿 task → 10-task → 20-task-audit → …**。
+
+---
+
+## 4. Starter 包与用户仓
+
+| 帽 | 产品仓 Starter | 完整 Prompt |
+|----|----------------|-------------|
+| 10-task | `harness/prompts/10-requirements.md` | 工作区 Extended |
+| 20-task-audit | `harness/prompts/22-task-audit.md` | 同上 |
+| 30 / 40 | ✅ Starter | 同上 |
+| 10-spec / 20-spec-audit / 00 / 50 | POINTER | 工作区 `docs/harness/prompts/` |
+
+工作区 Ink 全量库：[`docs/harness/guides/GUIDANCE_harness_hat_v2_chain_v1_zh.md`](../../../../docs/harness/guides/GUIDANCE_harness_hat_v2_chain_v1_zh.md)（POINTER · 私有 monorepo）。
+
+---
+
+## 修订记录
+
+| 版本 | 日期 | 说明 |
+|------|------|------|
+| v2.0 | 2026-06-21 | 与 Ink 工作区 V2 对齐 · 30→40 同 Agent · 50/CLOSE 打回规则 |

package/examples/compliance_bench/S6_agent_handoff/.cyning-harness/manifest.json

@@ -0,0 +1 @@
+{"version":"2.0.2","preset":"harness-only"}

package/examples/compliance_bench/S6_agent_handoff/docs/harness/invokes/by-task/s6/PROMPT_START_30_v1.md

@@ -0,0 +1,3 @@
+# PROMPT_START_30 · S6 fixture
+
+Static invoke path for compliance bench S6.

package/examples/compliance_bench/S6_agent_handoff/docs/harness/reviews/task_s6_agent_handoff_audit_R1_20260618.md

@@ -0,0 +1,3 @@
+# 任务审核 · cyning-harness A6 · R1 fixture
+
+S6 compliance bench · static review path.

package/examples/compliance_bench/S6_agent_handoff/task_s6_agent_handoff.md

@@ -0,0 +1,31 @@
+# Task fixture · S6 · Agent handoff · verify --json
+
+> 用途：SDD-Compliance micro-bench S6 · approved + entry_invoke_30 → may_start_30 true
+
+---
+
+## Harness 元信息
+
+| 字段 | 值 |
+| --- | --- |
+| **task_slug** | `s6_agent_handoff` |
+| **test_strategy** | `not_applicable` |
+| **test_strategy_note** | compliance bench 静态夹具 |
+| **entry_invoke_30** | `docs/harness/invokes/by-task/s6/PROMPT_START_30_v1.md` |
+
+### 人工闸
+
+| human_gate_id | status | blocks_hats | 说明 |
+| --- | --- | --- | --- |
+| HG-TASK-DRAFT | approved | 20, 30 | ok |
+| HG-AUDIT-R1 | approved | 30 | R1 已签 |
+
+---
+
+## 背景与目标
+
+验证 A6 Agent handoff：`verify --json` 输出 `may_start_30: true` 且 `entry_invoke_30` 非空。
+
+## 验收标准
+
+- `verify --json --task task_s6_agent_handoff.md` · `may_start_30` = true · `entry_invoke_30` 非空

package/harness/prompts/10-requirements.md

@@ -1,6 +1,8 @@
 # 帽子：需求 / 任务分析（Harness · Starter 子集）
 
-> **完整版 POINTER**（Ink 工作区）：`docs/harness/prompts/10-requirements.md`  
+> **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/` 的 **精简真值**。
 
 ## 身份

package/harness/prompts/22-task-audit.md

@@ -1,6 +1,8 @@
 # 帽子：任务审核（Harness · Starter 子集）
 
-> **完整版 POINTER**（Ink 工作区）：`docs/harness/prompts/22-task-audit.md`  
+> **hat_id（V2）**：**20-task-audit** · 对应 **10-task** · 历史文件名 **22-task-audit** 保留。  
+> **姊妹帽**：SPEC 书面审 **20-spec-audit**（Extended · 工作区 `docs/harness/prompts/20-spec-audit.md`）。  
+> **完整版 POINTER**（Ink 工作区）：`docs/harness/prompts/20-task-audit.md`  
 > **本文件**：嵌入用户仓 `docs/harness/prompts/` 的 **精简真值**。
 
 ## 身份

package/harness/prompts/30-execute-code.md

@@ -38,7 +38,8 @@
 ## 输出形状
 
 - （拒开工）仅闸扫描 STOP 模板
-- （通过）diff + PR 验证说明 + invoke + task 自检回填 + 下一棒 40 Prompt
+- （通过）diff + 验证说明 + invoke + **40 自检闭环**（同上下文跑命令 · 不通过则改码重跑 · 回填 `### 自检结论`）
+- **40 不强制新开对话**；须 task 验证命令全绿后再交 50 / CLOSE
 
 ## 交接物
 

package/harness/prompts/40-self-check.md

@@ -5,7 +5,9 @@
 
 ## 身份
 
-**执行者自检**：与 30 执行帽 **可同上下文连续**；把「声称完成」变成 **可核对证据**。
+**执行者自检**：默认由 **30 同一 Agent** 在本轮连续完成；把「声称完成」变成 **可核对证据**。
+
+> **纪律**：不通过则 30 改码并重跑本帽步骤，直至 task 验证命令绿；**无需**维护者单独开 40 对话澄清。
 
 ## 只做什么
 
@@ -36,8 +38,9 @@
 
 ## 交接物
 
-- 给 50 复检 / 00 统筹：**diff + 日志摘要 + 自检验收表**  
-- task 内 **`### 自检结论（执行者）`** 相对路径引用
+- 给 50 复检 / 00 统筹 / **CLOSE**：diff + 日志 + 自检验收表  
+- task 内 **`### 自检结论（执行者）`** 须已回填  
+- 50 未过 → 打回 **30**；CLOSE 偏差过大 → 维护者决策 ↺ **10-task** 或 **10-spec**
 
 ---
 
@@ -45,4 +48,4 @@
 
 | 日期 | 摘要 |
 |------|------|
-| 2026-06-15 | A2 Starter 初版 · 与 Ink 完整库 POINTER 对齐 |
+| 2026-06-21 | 30 同 Agent 闭环 · 50/CLOSE 打回规则 |

package/harness/prompts/FRAGMENT_30_gate_verify_v1_zh.md

@@ -20,7 +20,7 @@ reviews：task_*_audit_R1_*.md 存在且 R1 通过？ {是/否}
 
 结论：{STOP · 签闸指引 | 可进入读码/改码}
 
-机械辅助（推荐）：`npx @cyning/harness verify --target <meta> --task docs/tasks/active/task_*.md`
+机械辅助（30 改码前必须）：`npx @cyning/harness verify --target <meta> --task docs/tasks/active/task_*.md [--json] [--agent-hint] [--workspace-root <Projects>]`
 ```
 
 ## Agent 纪律

package/harness/prompts/README.md

@@ -1,31 +1,40 @@
 # harness/prompts
 
-从本目录向用户仓 **`docs/harness/prompts/`** 复制 **Starter 子集**（非 Ink 全量帽子库）。
-
-## v0.1 已交付（T3 · M2）
-
-| 文件 | 状态 | 说明 |
-|------|------|------|
-| [`10-requirements.md`](./10-requirements.md) | ✅ | 需求 / 任务分析 · 精简 + POINTER |
-| [`22-task-audit.md`](./22-task-audit.md) | ✅ | 任务审核 · 落盘 reviews · HG-AUDIT-R1 |
-| [`30-execute-code.md`](./30-execute-code.md) | ✅ v0.1.1 | 执行编码 · 强制闸扫描 · AUDIT approved |
-| [`40-self-check.md`](./40-self-check.md) | ✅ v0.3.2 | 自检 · 命令证据 · 回填 task |
-| [`TEMPLATE_30_gate_stop.md`](./TEMPLATE_30_gate_stop.md) | ✅ v0.1.1 | 30 拒开工输出模板 |
+从本目录向用户仓 **`docs/harness/prompts/`** 复制 **Starter 子集**。
+
+## 标准流程（V2）
+
+```text
+人 + 00 chat 大纲
+  → 10-spec R0–R9
+  → 20-spec-audit + HG-SPEC-SIGNOFF（人签 · 可多轮）
+  → 00 起草 P0 task
+  → 10-task → 20-task-audit R1（↺ 10-task）→ HG-AUDIT-R1
+  → 30 → 40（同 Agent · 自修重跑直至通过）
+  → 50（↺ 30 · 可选）→ CLOSE
+```
 
-**Starter 闭包**：10 / 22 / 30 / **40**（A2 · v0.3.x）
+详述：[`../docs/methodology/product/SDD_HAT_FLOW_v2_zh.md`](../docs/methodology/product/SDD_HAT_FLOW_v2_zh.md)
 
-## 完整库（POINTER · 不复制全文）
+| 10 | 20 | 人闸 |
+|----|-----|------|
+| 10-spec | 20-spec-audit | HG-SPEC-SIGNOFF |
+| 10-task | 20-task-audit | HG-AUDIT-R1 |
 
-Extended 帽（00/20/40/50、链式 PROMPT）由维护者在 **私有工作区或签约伙伴仓** 维护 · **不**默认复制进用户仓。
+## Starter（本目录）
 
-嵌入用户仓后可在 README 追加（示例）：
+| 文件 | 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 |
+| [`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 拒开工 |
 
-```markdown
-## 完整 Harness 库
-- 上游：你的组织/monorepo `docs/harness/prompts/`（只读对照 · 非 Starter 默认）
-```
+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。
 
-## 链式执行
+## 修订记录
 
-- 串行 Task 链：维护者工作区链式 PROMPT（M3 `harness ctx` 前手工 `@` 引用）
-- 每帽 invoke：[`../invokes/TEMPLATE_invoke.md`](../invokes/TEMPLATE_invoke.md)
+| 日期 | 摘要 |
+|------|------|
+| 2026-06-21 | V2 标准流程 · 30→40 同 Agent · 50/CLOSE 打回 |

package/harness/templates/QUICKREF_v1_zh.md

@@ -8,7 +8,7 @@
 
 ```bash
 # 30 前聚合验证（gate-check + audit D5 + S5 warn + 可选 --graph）
-npx @cyning/harness verify [--target .] [--task docs/tasks/active/task_xxx.md] [--graph]
+npx @cyning/harness verify [--target .] [--task docs/tasks/active/task_xxx.md] [--graph] [--json] [--agent-hint] [--workspace-root PATH]
 
 # 仅人工闸	npx @cyning/harness gate-check [--target .] [--task ...] [--graph] [--json]
 

package/lib/cli.js

@@ -38,7 +38,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]
+  npx @cyning/harness verify [--target PATH] [--task FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH]
   npx @cyning/harness sync index [--target PATH]
   npx @cyning/harness task check --file PATH [--no-circular] [--registry DIR]...
   npx @cyning/harness graph yaml compile --graph-id ID [--input DIR] [--output FILE]
@@ -375,12 +375,15 @@ async function cmdGateCheck(args) {
 
 async function cmdVerify(args) {
   // D3 · implemented in lib/verify.js
-  const { verifyTarget } = await import('./verify.js');
+  const { verifyTarget, buildVerifyHandoff, formatAgentHint } = await import('./verify.js');
   if (args.includes('--help') || args.includes('-h')) {
-    console.log(`用法: npx @cyning/harness verify [--target PATH] [--task FILE] [--graph]
+    console.log(`用法: npx @cyning/harness verify [--target PATH] [--task FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH]
 
 无 --task 时：扫描 docs/tasks/active/task_*.md 并逐项列出闸表（同 gate-check）。
 任一 task 阻塞则 VERIFY: BLOCKED · exit 2；全部可 30 则 VERIFY: PASS。
+--json：输出 Agent handoff JSON（may_start_30 · entry_invoke_30 · review_path 等）。
+--agent-hint：人类可读 handoff 摘要（可与 --json 同用）。
+--workspace-root：解析 task 中 Projects/ 前缀的 entry_invoke 路径。
 `);
     return;
   }
@@ -390,8 +393,12 @@ 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');
+  rest = r3;
   const graph = rest.includes('--graph');
-  rest = rest.filter((a) => a !== '--graph');
+  const json = rest.includes('--json');
+  const agentHint = rest.includes('--agent-hint');
+  rest = rest.filter((a) => a !== '--graph' && a !== '--json' && a !== '--agent-hint');
 
   if (rest.length > 0) {
     const err = new Error(`verify 未知参数: ${rest.join(' ')}`);
@@ -402,15 +409,37 @@ async function cmdVerify(args) {
   const target = resolveTarget(process.cwd(), targetArg);
   const result = verifyTarget(target, { taskFile, graph });
 
-  // forward gate-check/audit/graph stdout if any
-  if (result.stdout) {
+  // forward gate-check/audit/graph stdout if any（--json 时仍透传机械闸表）
+  if (result.stdout && !json) {
     process.stdout.write(result.stdout);
+  } else if (result.stdout && json) {
+    // JSON 模式：闸表走 stderr 避免污染 stdout JSON
+    process.stderr.write(result.stdout);
   }
 
-  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);
+  const handoff = buildVerifyHandoff(target, {
+    taskFile,
+    workspaceRoot: workspaceRoot ? path.resolve(workspaceRoot) : undefined,
+  });
+
+  if (json) {
+    console.log(JSON.stringify(handoff, null, 2));
+  }
+  if (agentHint) {
+    console.log(formatAgentHint(handoff));
+  }
+
+  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);
+  }
 
   if (!result.ok) {
     process.exitCode = result.exitCode ?? 2;

package/lib/task-meta.js

@@ -0,0 +1,223 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const META_FIELD_RE = /\|\s*\*\*([^*]+)\*\*\s*\|\s*`([^`]+)`/;
+const GATE_ROW_RE = /^\|\s*(?:\*\*)?([^*|]+?)(?:\*\*)?\s*\|\s*([^|]+)\|\s*([^|]+)\|\s*([^|]*)\|/;
+
+/**
+ * 从 task Markdown 解析 Harness 元信息表（反引号包裹的值）。
+ */
+export function parseHarnessMeta(content) {
+  const meta = {};
+  const section = extractSection(content, '## Harness 元信息', '###');
+  if (!section) return meta;
+
+  for (const line of section.split('\n')) {
+    const match = line.match(META_FIELD_RE);
+    if (!match) continue;
+    const key = match[1].trim();
+    meta[key] = match[2].trim();
+  }
+  return meta;
+}
+
+/**
+ * 解析 ### 人工闸 表。
+ */
+export function parseHumanGates(content) {
+  const section = extractSection(content, '### 人工闸', '##');
+  if (!section) return [];
+
+  const gates = [];
+  for (const line of section.split('\n')) {
+    const match = line.match(GATE_ROW_RE);
+    if (!match) continue;
+    const id = match[1].trim();
+    if (!id.startsWith('HG-') || id.includes('human_gate')) continue;
+    gates.push({
+      id,
+      status: normalizeCell(match[2]),
+      blocks_hats: normalizeCell(match[3]),
+      note: normalizeCell(match[4]),
+    });
+  }
+  return gates;
+}
+
+/**
+ * 机械判定 may_start_30（与 gate-check.sh 一致）。
+ */
+export function evaluateMayStart30(gates) {
+  const byId = Object.fromEntries(gates.map((g) => [g.id, g]));
+  const draft = byId['HG-TASK-DRAFT'];
+  const audit = byId['HG-AUDIT-R1'];
+  const graph = byId['HG-GRAPH-MODULES'];
+
+  if (audit?.status !== 'approved') {
+    return {
+      may_start_30: false,
+      blocked_reason: 'HG-AUDIT-R1 非 approved（须维护者签 task 表）',
+    };
+  }
+
+  if (
+    draft?.status !== 'approved' &&
+    draft?.blocks_hats?.includes('30')
+  ) {
+    return {
+      may_start_30: false,
+      blocked_reason: 'HG-TASK-DRAFT pending 且 blocks 30',
+    };
+  }
+
+  if (graph?.status === 'pending') {
+    return {
+      may_start_30: false,
+      blocked_reason: 'HG-GRAPH-MODULES pending',
+    };
+  }
+
+  return { may_start_30: true, blocked_reason: null };
+}
+
+/**
+ * 解析 Projects/ 前缀路径；需 workspaceRoot 才 resolve。
+ */
+export function resolveInvokePath(rawPath, { target, workspaceRoot } = {}) {
+  if (!rawPath) {
+    return { resolved: null, warnings: [] };
+  }
+
+  const warnings = [];
+
+  if (rawPath.startsWith('Projects/')) {
+    if (!workspaceRoot) {
+      warnings.push(
+        `entry_invoke 路径以 Projects/ 开头但未提供 --workspace-root：${rawPath}`,
+      );
+      return { resolved: null, warnings };
+    }
+    const abs = path.join(workspaceRoot, rawPath.replace(/^Projects\//, ''));
+    if (!fs.existsSync(abs)) {
+      warnings.push(`entry_invoke 路径不存在：${rawPath}`);
+    }
+    return { resolved: abs, warnings };
+  }
+
+  if (path.isAbsolute(rawPath)) {
+    if (!fs.existsSync(rawPath)) {
+      warnings.push(`entry_invoke 路径不存在：${rawPath}`);
+    }
+    return { resolved: rawPath, warnings };
+  }
+
+  const abs = path.resolve(target ?? process.cwd(), rawPath);
+  if (!fs.existsSync(abs)) {
+    warnings.push(`entry_invoke 路径不存在（相对 target）：${rawPath}`);
+  }
+  return { resolved: abs, warnings };
+}
+
+/**
+ * 查找最新 R1 审查文（相对 target）。
+ */
+export function findReviewPath(target, taskFile) {
+  const reviewsDir = path.join(target, 'docs/harness/reviews');
+  if (!fs.existsSync(reviewsDir)) return null;
+
+  const taskBase = path.basename(taskFile, '.md');
+  const prefix = `${taskBase}_audit_R1_`;
+
+  let best = null;
+  let bestMtime = 0;
+
+  for (const name of fs.readdirSync(reviewsDir)) {
+    if (!name.startsWith(prefix) || !name.endsWith('.md')) continue;
+    const full = path.join(reviewsDir, name);
+    const mtime = fs.statSync(full).mtimeMs;
+    if (mtime > bestMtime) {
+      bestMtime = mtime;
+      best = path.relative(target, full).replace(/\\/g, '/');
+    }
+  }
+
+  return best;
+}
+
+/**
+ * 聚合单 task 的 Agent handoff 结果。
+ */
+export function buildTaskHandoff(target, taskFile, options = {}) {
+  const { workspaceRoot } = options;
+  const absTask = path.isAbsolute(taskFile)
+    ? taskFile
+    : path.join(target, taskFile);
+
+  const content = fs.readFileSync(absTask, 'utf8');
+  const meta = parseHarnessMeta(content);
+  const gates = parseHumanGates(content);
+  const gateEval = evaluateMayStart30(gates);
+
+  const warnings = [];
+  const entry30Raw = meta.entry_invoke_30 ?? null;
+  const entry20Raw = meta.entry_invoke_20 ?? null;
+
+  const entry30 = resolveInvokePath(entry30Raw, { target, workspaceRoot });
+  const entry20 = resolveInvokePath(entry20Raw, { target, workspaceRoot });
+  warnings.push(...entry30.warnings, ...entry20.warnings);
+
+  const reviewPath = findReviewPath(target, taskFile);
+
+  return {
+    task: path.basename(taskFile),
+    task_path: taskFile.replace(/\\/g, '/'),
+    task_slug: meta.task_slug ?? null,
+    may_start_30: gateEval.may_start_30,
+    blocked_reason: gateEval.blocked_reason,
+    review_path: reviewPath,
+    entry_invoke_20: entry20Raw,
+    entry_invoke_20_resolved: entry20.resolved,
+    entry_invoke_30: entry30Raw,
+    entry_invoke_30_resolved: entry30.resolved,
+    next_hat: gateEval.may_start_30 ? '30' : null,
+    agent_preamble: gateEval.may_start_30
+      ? '首输出 GATE_VERIFY 闸扫描表，再读 entry_invoke_30 开 30 帽。'
+      : null,
+    warnings,
+    gates: gates.map((g) => ({
+      id: g.id,
+      status: g.status,
+      blocks_hats: g.blocks_hats,
+    })),
+  };
+}
+
+/**
+ * 扫描 target 下 active task 列表。
+ */
+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();
+}
+
+function extractSection(content, startMarker, endMarker) {
+  const start = content.indexOf(startMarker);
+  if (start === -1) return null;
+
+  let end = content.length;
+  if (endMarker) {
+    const next = content.indexOf(endMarker, start + startMarker.length);
+    if (next !== -1) end = next;
+  }
+  return content.slice(start, end);
+}
+
+function normalizeCell(cell) {
+  return cell.replace(/\*/g, '').trim();
+}

package/lib/verify.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { resolveHarnessRootForTarget, wizardScript } from './paths.js';
 import { auditTarget } from './audit.js';
+import { buildTaskHandoff, listActiveTasks } from './task-meta.js';
 
 /**
  * 30 前聚合验证：gate-check + audit D5（仅 --task）+ S5 git-clean warn + 可选 --graph
@@ -150,3 +151,71 @@ function runGitCleanCheck(target) {
   const dirty = result.status === 0 && result.stdout.trim().length > 0;
   return { dirty };
 }
+
+/**
+ * 构建 verify --json / --agent-hint 的 Agent handoff 载荷。
+ */
+export function buildVerifyHandoff(target, options = {}) {
+  const { taskFile, workspaceRoot } = options;
+  const handoffOpts = { workspaceRoot };
+
+  if (taskFile) {
+    const handoff = buildTaskHandoff(target, taskFile, handoffOpts);
+    return {
+      schema_version: '1',
+      verify_ok: handoff.may_start_30,
+      ...handoff,
+    };
+  }
+
+  const taskFiles = listActiveTasks(target);
+  const tasks = taskFiles.map((tf) => {
+    const handoff = buildTaskHandoff(target, tf, handoffOpts);
+    return {
+      schema_version: '1',
+      verify_ok: handoff.may_start_30,
+      ...handoff,
+    };
+  });
+
+  const verifyOk = tasks.length > 0 && tasks.every((t) => t.may_start_30);
+  return {
+    schema_version: '1',
+    verify_ok: verifyOk,
+    tasks,
+  };
+}
+
+/**
+ * 人类可读的 --agent-hint（5–10 行）。
+ */
+export function formatAgentHint(payload) {
+  const lines = ['=== Harness verify · agent-hint ==='];
+
+  const items = payload.tasks ?? [payload];
+  for (const item of items) {
+    lines.push(`task: ${item.task}`);
+    lines.push(`  may_start_30: ${item.may_start_30}`);
+    if (item.blocked_reason) {
+      lines.push(`  blocked: ${item.blocked_reason}`);
+    }
+    if (item.review_path) {
+      lines.push(`  review: ${item.review_path}`);
+    }
+    if (item.entry_invoke_30) {
+      lines.push(`  entry_invoke_30: ${item.entry_invoke_30}`);
+      if (item.entry_invoke_30_resolved) {
+        lines.push(`  resolved: ${item.entry_invoke_30_resolved}`);
+      }
+    }
+    if (item.next_hat) {
+      lines.push(`  next_hat: ${item.next_hat}`);
+    }
+    for (const w of item.warnings ?? []) {
+      lines.push(`  warn: ${w}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n').trimEnd();
+}