@cyning/harness 2.11.1 → 2.12.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@
 
 ## [Unreleased]
 
+## [2.12.0] - 2026-07-26
+
+### Added
+
+- **多帽 invoke 留档硬闸**：task 元信息 `required_invoke_hats` / `invoke_retention_profile`（`default`=`10,30,40` · `minimal`=`30` · `full`=`00,10,20,30,40,CLOSE`）。
+- `task close` 检查 1 按集合覆盖校验；文件名 `30_40` 可同时满足 30 与 40；`--allow-invoke-gap` 豁免留痕。
+- `verify --task` 对 invoke hats 缺口 **WARN**（不挡 30）；`task lint` **W6** 提醒未设字段。
+- `lib/task-meta.js`：`resolveRequiredInvokeHats` · `scanInvokeHats` · `evaluateInvokeHatsRetention` · `extractHatsFromInvokeFilename`。
+
+### Changed
+
+- `lifecycle.yaml` close 守卫登记 `invoke_hats_retention`；`discipline-coverage.yaml` `as_of` → **2.12.0** · gaps `INVOKE-HATS`。
+- TASK_TEMPLATE / TEMPLATE_invoke / 10·20·30 帽文同步字段与纪律。
+
+### Notes
+
+- SPEC：`docs/spec/SPEC-invoke-hats-retention-gate_v1.md`
+- **破坏性（close）**：无字段时按 default 要求 10+30+40；存量仅 30 的 active 须补档、改 `minimal` 或 `--allow-invoke-gap`
+- minor · 建议业务仓 upgrade 后按 RUNBOOK 勾选 invoke 集合
+
 ## [2.11.1] - 2026-07-25
 
 ### Fixed
@@ -15,6 +35,7 @@
 
 - 摩擦报告：`Projects/docs/harness/guides/ANALYSIS_upgrade_wizard_friction_20260725_v1_zh.md`
 - patch · 2.3+ manifest 仅五字段：`version` / `preset` / `ide` / `from_version` / `upgraded_at`（`name` / `tech_graph_dir` / `tasks_dir` / `hooks` 等已废弃）
+- **已发布**：`@cyning/harness@2.11.1`（npm `latest` · 2026-07-26）· tag `v2.11.1` 已推送
 
 ## [2.11.0] - 2026-07-25
 

package/docs/USER_GUIDE_v1.0_zh.md

@@ -187,7 +187,8 @@ 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`）；v2.11.1+：`local.json` 在 apply 后写入；manifest 重写前 WARN 非标准字段（2.3+ 仅五字段） |
 | `npx @cyning/harness check` | 检查是否有新版本 |
-| `npx @cyning/harness verify` | 全量：双路径 + reviews（v2.9+）；`--task`：30 前聚合；`--spec`：SPEC→00（v2.8+ · 互斥） |
+| `npx @cyning/harness verify` | 全量：双路径 + reviews（v2.9+）；`--task`：30 前聚合 + invoke hats WARN（v2.12+）；`--spec`：SPEC→00（v2.8+ · 互斥） |
+| `npx @cyning/harness task close` | 受闸归档；v2.12+ 按 `required_invoke_hats` / `invoke_retention_profile` 校验多帽 invoke（缺省 `10,30,40`；`--allow-invoke-gap`） |
 | `npx @cyning/harness lifecycle show` | 只读展示 `harness/lifecycle.yaml`（登记 · v2.7+） |
 | `npx @cyning/harness lifecycle dry-run` | 转移资格判定（引擎消费 yaml · v2.10+ · 旁路 · 非 G7） |
 | `npx @cyning/harness discipline show` | 只读展示 `harness/discipline-coverage.yaml`（v2.11+ · 非 audit UI） |

package/docs/methodology/graph/README.md

@@ -2,7 +2,7 @@
 
 > **对外名**：PIP（过程实例投影）。对内历史文件名可含 `HGM` / `hgm_*`（路径兼容，正文不用曾称括注）。
 
-> **Track G · G1 / v2.0+**：PIP（过程实例投影）为 **v1.0 公理稳定后的可选增强**（proposal · 未实现）· 详见 [`../ROADMAP_v1_zh.md`](../ROADMAP_v1_zh.md) §2.0 · §2.2。
+> **Track G · G1 / v2.0+**：PIP（过程实例投影）本地 JSONL + `graph ingest|snapshot|axioms` **已实现**；Neo4j / 远端同步仍提案 · 详见 [`../ROADMAP_v1_zh.md`](../ROADMAP_v1_zh.md) §2.0 · §2.2。
 
 | 文档 | 状态 | 说明 |
 | --- | --- | --- |

package/docs/spec/SPEC-invoke-hats-retention-gate_v1.md

@@ -0,0 +1,59 @@
+# SPEC：多帽 invoke 留档硬闸（可配置）（v1）
+
+> **状态**：`signed`  
+> **track**：`feature`  
+> **关联图谱**：无（纯 Harness 工具链）  
+> **下游**：30 实现 → 40 → close  
+
+---
+
+## Harness 元信息
+
+| 字段 | 值 |
+|------|-----|
+| **spec_slug** | `invoke-hats-retention-gate` |
+| **test_strategy** | `required` |
+| **test_strategy_note** | close/lint/verify 集合校验与 profile 展开须可失败测试驱动 |
+| **skip_spec_audit** | `true` |
+
+---
+
+## 1. 背景与目标
+
+close 检查 1 仅要求 `by-task/<slug>/` ≥1 个 `.md`，业务仓理性只交 30。  
+目标：按 task 元信息 `required_invoke_hats` / `invoke_retention_profile` 做**集合覆盖**硬闸；默认 `10,30,40`；40 允许与 30 合并文件名。
+
+## 2. 范围
+
+- `lib/task-meta.js`：profile 预置、解析、文件名 hat 扫描、缺口计算
+- `lib/task-close.js`：检查 1 升级；`--allow-invoke-gap`
+- `lib/task-lint.js`：缺字段 WARN
+- `lib/verify.js`：缺口 WARN（不挡 30）
+- lifecycle / discipline / 模板 / CHANGELOG · **v2.12.0**
+
+## 3. 非范围
+
+- 强制 CLOSE invoke 文件（关账= close 命令）
+- 默认要求 20 invoke（reviews 已硬闸）
+- 同步 Ink 全套 TEMPLATE-*-invoke.md
+- 历史 done invoke 补录
+
+## 4. 验收标准
+
+- [x] 无字段 → 默认要求 `10,30,40`；仅有 30 → CLOSE BLOCKED
+- [x] `invoke_retention_profile: minimal` → 仅需 30
+- [x] `required_invoke_hats` 优先于 profile
+- [x] `invoke_*_30_40_*.md` 同时满足 30 与 40
+- [x] `--allow-invoke-gap` 豁免并留痕
+- [x] verify --task 对缺口 WARN、不挡 may_start_30
+- [x] `npm test` 全绿
+
+> **复检**（2026-07-26 · cyning-harness `task/invoke-hats-retention-gate`）：`npm test` **187/187** 绿；行为与上表一致。非阻塞备注见对话复检报告。
+
+## 5. 预置
+
+| profile | hats |
+|---------|------|
+| default | 10,30,40 |
+| minimal | 30 |
+| full | 00,10,20,30,40,CLOSE |

package/harness/discipline-coverage.yaml

@@ -6,7 +6,7 @@
 # 禁止：把本文件当「每周全量重盘」流程；不做 audit --discipline UI（本波）
 
 version: "1"
-as_of_package_version: "2.11.0"
+as_of_package_version: "2.12.0"
 scope: "Starter · harness/prompts （10/22/30/40 + FRAGMENT）+ TEMPLATE_invoke"
 source_audit: "rethink/2026-07-mechanization-rate · 02 转录 + 03 聚合 · 状态已按 G1–G4/N1–N4 刷新（非第二轮通读盘点）"
 
@@ -61,6 +61,11 @@ gaps:
     status: closed
     closed_in: "2.10.0"
     note: "Epic T2 · 旁路报告"
+  - id: INVOKE-HATS
+    title: 多帽 invoke 留档集合闸
+    status: closed
+    closed_in: "2.12.0"
+    note: "close evaluateInvokeHatsRetention · default 10,30,40"
 
 statements:
   - id: A1
@@ -105,11 +110,11 @@ statements:
     mechanism_quality: null
   - id: A6
     source: 30-execute-code.md
-    summary: invoke 快照落盘 by-task/<slug>/
+    summary: invoke 快照落盘 by-task/<slug>/（按 required_invoke_hats 集合）
     status: mechanical
-    mechanism: "M5 close + M6 lint-done"
+    mechanism: "M5 close evaluateInvokeHatsRetention + M6 lint-done"
     gap: null
-    notes: null
+    notes: "v2.12.0 默认 10,30,40；profile minimal/full；--allow-invoke-gap"
     mechanism_quality: null
   - id: A7
     source: 30-execute-code.md
@@ -265,11 +270,11 @@ statements:
     mechanism_quality: null
   - id: F1
     source: TEMPLATE_invoke.md
-    summary: 落盘路径 by-task/<task_slug>/
+    summary: 落盘路径 by-task/<task_slug>/ 且帽子集合覆盖
     status: mechanical
-    mechanism: "M5/M6"
+    mechanism: "M5 evaluateInvokeHatsRetention / M6"
     gap: null
-    notes: null
+    notes: "v2.12.0 文件名 hat token · 合并 30_40 可双计"
     mechanism_quality: null
   - id: F2
     source: TEMPLATE_invoke.md

package/harness/invokes/TEMPLATE_invoke.md

@@ -9,7 +9,7 @@
 
 | 字段 | 值 |
 |------|-----|
-| hat_id | 10 / 22 / 30 / 40 / 50 / 00 / CLOSE |
+| hat_id | 10 / 22 / 30 / 40 / 50 / 00 / CLOSE（合并可写 `30（含 40）`） |
 | task_slug | `<slug>` |
 | freeze_id | （可选） |
 | task_paths | `docs/tasks/active/task_….md` |
@@ -44,7 +44,8 @@
 | 同帽追问 | **不** 新增 invoke；沿用本节路径 |
 | 打回重开 | 新文件或 `_r2` 后缀 |
 | 与 reviews 分工 | reviews = 结论；invoke = **当时指令** |
-| close 机械闸 | `harness task close` 归档前校验 `by-task/<task_slug>/` 存在且含 ≥1 个 `.md`（v2.2+） |
+| close 机械闸 | `harness task close` 按 task 元信息 `required_invoke_hats` / `invoke_retention_profile` 校验帽集合覆盖（v2.12+；缺省 `10,30,40`；文件名含 `30_40` 可双计；`--allow-invoke-gap` 豁免） |
+| 命名 | `invoke_YYYYMMDD_<hat>_<slug>.md` 或 `invoke_YYYYMMDD_30_40_<slug>.md` |
 | commit | 落盘 + task 回填后再 commit（见 HANDOFF） |
 
 ---

package/harness/lifecycle.yaml

@@ -66,8 +66,14 @@ transitions:
     description: "task close · active→done 归档"
     guards:
       - id: close_invoke
-        command_or_check: "task close 检查1 · invoke 快照存在"
+        command_or_check: "task close 检查1 · invoke hats 集合覆盖（required_invoke_hats / profile · v2.12+）"
         severity: block
+        allow_flag: "--allow-invoke-gap"
+        note: "缺省 default=10,30,40；minimal=30；full 含 CLOSE；40 可与 30 合并文件名"
+      - id: invoke_hats_retention
+        command_or_check: "evaluateInvokeHatsRetention · 同 close_invoke（登记别名）"
+        severity: block
+        allow_flag: "--allow-invoke-gap"
       - id: close_self_check
         command_or_check: "task close 检查2 · 自检结论已回填"
         severity: block

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

@@ -15,6 +15,7 @@
 - 补齐 **`failure_paths`**（触发 → 行为 → 可重试 → 用户可见）
 - 写清 **非范围**、**依赖**（相对路径链接）
 - 建议 `test_strategy` + `code_quality_bar`
+- **选定 invoke 留档集合**（v2.12+）：写 `invoke_retention_profile`（`default`=`10,30,40` / `minimal`=`30` / `full`）或显式 `required_invoke_hats`；并落盘本帽 `invoke_*_10_*.md`
 - 承接 **20-task-audit 审查**：按 `docs/harness/reviews/*_audit_*.md` 回填 task
 
 ## 禁止什么
@@ -48,7 +49,8 @@
 |------|------|
 | 2026-07-24 | V2 拆分收编：自 `10-requirements.md` 改名为 `10-task-requirements.md`（来源：工作区 `10-task-requirements.md` · 2026-06-12 v2） |
 | 2026-07-24 | G4：思考轮摘要节补 v2.6+ `task lint` 条件触发结构检查 |
+| 2026-07-26 | v2.12：起草时选定 `required_invoke_hats` / `invoke_retention_profile` |
 
 ## 给 Cursor
 
-`Harness`、`10-task`、`验收`、`failure_paths`、`test_strategy`、`task lint`、`拒开工`
+`Harness`、`10-task`、`验收`、`failure_paths`、`test_strategy`、`task lint`、`required_invoke_hats`、`拒开工`

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

@@ -62,7 +62,8 @@
 
 ## 交接物
 
-- 审查 md 路径 + invoke 快照（可选）
+- 审查 md 路径（**必须** · `docs/harness/reviews/`）
+- invoke 快照：仅当 task `required_invoke_hats` / profile **含 20** 时必须落盘；默认 default 集合不含 20（与 reviews 硬闸分工）
 - 按 HANDOFF 分仓 commit
 
 ## 修订记录
@@ -70,6 +71,7 @@
 | 日期 | 摘要 |
 |------|------|
 | 2026-07-24 | V2 拆分收编：自 `22-task-audit.md` 改名为 `20-task-audit.md`（来源：工作区 `20-task-audit.md` · 2026-06-21 v3 + 原包内人工闸联动节保留） |
+| 2026-07-26 | v2.12：澄清 20 invoke 仅在 required 集合含 20 时强制；默认靠 reviews |
 
 ## 给 Cursor
 

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

@@ -20,8 +20,8 @@
 - 读 task **必读列表** + `AGENTS.md` + `_tech_graph/` + L2（涉码）
 - `test_strategy: required` → **先** 可失败测试再改实现
 - 闸扫描通过后：运行 task **验证命令**；回填 `### 自检结论（执行者）`
-- invoke 快照落盘 `docs/harness/invokes/by-task/<task_slug>/`
-- 归档（active→done）**只能**走 `npx @cyning/harness task close --file <task> --yes`：`CLOSE: PASS` 后方可归档；机械校验 invoke 留档 / 自检结论 / 验收勾选 / slug / 状态，任一不过 **不执行** mv（v2.2+）
+- invoke 快照落盘 `docs/harness/invokes/by-task/<task_slug>/`（须覆盖 task 要求的 hats；40 可与 30 合并为 `invoke_*_30_40_*.md`）
+- 归档（active→done）**只能**走 `npx @cyning/harness task close --file <task> --yes`：`CLOSE: PASS` 后方可归档；机械校验 **invoke hats 集合** / 自检结论 / 验收勾选 / slug / 状态 / R1 review，任一不过 **不执行** mv（v2.2+ · hats 集合 v2.12+）
 
 ## 禁止什么
 

package/harness/templates/TASK_TEMPLATE.md

@@ -19,6 +19,8 @@
 | **chain_prompt** | `docs/harness/prompts/PROMPT_cursor_task_chain_serial_v1.md`（嵌入后路径） |
 | **semi_auto** | **`false`**（禁止作总闸） |
 | **audit_profile** | `full` / `post_close` / `human_only` |
+| **invoke_retention_profile** | `default` / `minimal` / `full`（10 起草时选定） |
+| **required_invoke_hats** | `10,30,40`（显式列表优先于 profile；缺省=default） |
 | **git_branch** | `task/<slug>` |
 | **worktree_root** | （并行时填独立 worktree 目录） |
 | **experience_capture** | `required` / `recommended` / `not_applicable` |

package/lib/cli.js

@@ -404,11 +404,11 @@ async function cmdVerify(args) {
     formatAgentHint,
   } = await import('./verify.js');
   if (args.includes('--help') || args.includes('-h')) {
-    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]
+    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] [--allow-invoke-gap]
 
 无 --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。
+--task：30 前聚合（gate + audit + reviews + lint WARN + invoke hats WARN）· --allow-no-review / --allow-lint-fail / --allow-invoke-gap。
 --spec：SPEC→00 前查审查文存在性（v2.8+ · 与 --task 互斥）· --allow-no-spec-review。
   推荐：--spec <产品仓 SPEC> --workspace-root <含 docs/harness/reviews 的工作区根>
 --json / --agent-hint：Agent handoff。
@@ -431,6 +431,7 @@ async function cmdVerify(args) {
   const allowNoReview = rest.includes('--allow-no-review');
   const allowLintFail = rest.includes('--allow-lint-fail');
   const allowNoSpecReview = rest.includes('--allow-no-spec-review');
+  const allowInvokeGap = rest.includes('--allow-invoke-gap');
   rest = rest.filter(
     (a) =>
       a !== '--graph' &&
@@ -438,7 +439,8 @@ async function cmdVerify(args) {
       a !== '--agent-hint' &&
       a !== '--allow-no-review' &&
       a !== '--allow-lint-fail' &&
-      a !== '--allow-no-spec-review',
+      a !== '--allow-no-spec-review' &&
+      a !== '--allow-invoke-gap',
   );
 
   if (rest.length > 0) {
@@ -469,7 +471,13 @@ async function cmdVerify(args) {
     });
     label = path.basename(specFile);
   } else {
-    result = verifyTarget(target, { taskFile, graph, allowNoReview, allowLintFail });
+    result = verifyTarget(target, {
+      taskFile,
+      graph,
+      allowNoReview,
+      allowLintFail,
+      allowInvokeGap,
+    });
     handoff = buildVerifyHandoff(target, {
       taskFile,
       workspaceRoot: ws,
@@ -709,13 +717,16 @@ async function cmdTask(args) {
 
 async function cmdTaskClose(args) {
   if (args.includes('--help') || args.includes('-h')) {
-    console.log(`用法: npx @cyning/harness task close --file PATH [--target PATH] [--yes] [--allow-unchecked]
+    console.log(`用法: npx @cyning/harness task close --file PATH [--target PATH] [--yes] [--allow-unchecked] [--allow-no-review] [--allow-invoke-gap]
 
-受闸归档（方案 A · invoke 留档机械闸）：
-  5 项机械校验：invoke 留档 · 自检结论回填 · 验收标准勾选 · task_slug 一致 · 状态 done/completed
+受闸归档（方案 A · invoke 留档机械闸 · v2.12+ 多帽集合）：
+  机械校验：invoke hats 覆盖（required_invoke_hats / profile）· 自检结论 · 验收勾选 · slug · 状态 · R1 review
   默认 dry-run（只检不 mv）；--yes 才执行 mv 到 active/ 同级 done/（basename 保留）
-  --target PATH    显式覆盖归档目标完整路径
-  --allow-unchecked  验收标准未勾选项 warn 放行
+  --target PATH         显式覆盖归档目标完整路径
+  --allow-unchecked     验收标准未勾选项 warn 放行
+  --allow-no-review     缺 R<n> 审查文 warn 放行
+  --allow-invoke-gap    缺 required invoke hats warn 放行（v2.12+）
+  缺省 required hats：10,30,40（可用 invoke_retention_profile=minimal|full 或显式列表覆盖）
 任一校验失败 → exit 2 + CLOSE: BLOCKED · 不执行 mv。末行协议：CLOSE: PASS · <slug>。
 `);
     return;
@@ -724,7 +735,14 @@ async function cmdTaskClose(args) {
   const yes = args.includes('--yes');
   const allowUnchecked = args.includes('--allow-unchecked');
   const allowNoReview = args.includes('--allow-no-review');
-  let rest = args.filter((a) => a !== '--yes' && a !== '--allow-unchecked' && a !== '--allow-no-review');
+  const allowInvokeGap = args.includes('--allow-invoke-gap');
+  let rest = args.filter(
+    (a) =>
+      a !== '--yes' &&
+      a !== '--allow-unchecked' &&
+      a !== '--allow-no-review' &&
+      a !== '--allow-invoke-gap',
+  );
   const { value: fileArg, rest: r1 } = takeOption(rest, '--file');
   rest = r1;
   const { value: targetArg, rest: r2 } = takeOption(rest, '--target');
@@ -746,6 +764,7 @@ async function cmdTaskClose(args) {
     target: targetArg,
     allowUnchecked,
     allowNoReview,
+    allowInvokeGap,
     cwd: process.cwd(),
   });
 

package/lib/task-close.js

@@ -5,6 +5,7 @@ import {
   PLACEHOLDER_RE,
   STATUS_RE,
   UNCHECKED_RE,
+  evaluateInvokeHatsRetention,
   extractSection,
   extractTaskSlug,
   findReview,
@@ -23,6 +24,7 @@ export function closeTaskFile(filePath, options = {}) {
     target: targetArg,
     allowUnchecked = false,
     allowNoReview = false,
+    allowInvokeGap = false,
     cwd = process.cwd(),
   } = options;
 
@@ -60,7 +62,8 @@ export function closeTaskFile(filePath, options = {}) {
   const inActive = path.basename(activeDir) === 'active';
   const repoRoot = findRepoRoot(activeDir);
 
-  // 检查 1 · invoke 留档
+  // 检查 1 · invoke 留档（v2.12+：按 required_invoke_hats / profile 集合覆盖）
+  let invokeHatsEval = null;
   if (!repoRoot) {
     blockers.push(`无法定位 repo root（${activeDir} 无 docs 祖先）`);
   } else if (slug) {
@@ -69,12 +72,29 @@ export function closeTaskFile(filePath, options = {}) {
       'docs/harness/invokes/by-task',
       slug,
     );
-    const hasMd =
-      fs.existsSync(invokeDir) &&
-      fs.readdirSync(invokeDir).some((f) => f.endsWith('.md'));
-    if (!hasMd) {
-      blockers.push(
-        `missing invoke snapshots: ${path.relative(repoRoot, invokeDir)} 不存在或无 .md`,
+    invokeHatsEval = evaluateInvokeHatsRetention(meta, invokeDir);
+    const relDir = path.relative(repoRoot, invokeDir).replace(/\\/g, '/');
+    if (invokeHatsEval.missingDir || invokeHatsEval.files.length === 0) {
+      const msg = `missing invoke snapshots: ${relDir} 不存在或无 .md（要求 hats: ${invokeHatsEval.required.join(',')})`;
+      if (allowInvokeGap) {
+        warnings.push(`warn: ${msg}（--allow-invoke-gap 豁免 · 留痕）`);
+      } else {
+        blockers.push(msg);
+      }
+    } else if (invokeHatsEval.missing.length > 0) {
+      const msg =
+        `missing invoke hats: ${invokeHatsEval.missing.join(',')} ` +
+        `（要求 ${invokeHatsEval.required.join(',')} · 已有 ${invokeHatsEval.covered.join(',') || '∅'} · ` +
+        `source=${invokeHatsEval.resolution.source}` +
+        `${invokeHatsEval.resolution.unknown_profile ? ` · unknown_profile=${invokeHatsEval.resolution.unknown_profile}` : ''}）`;
+      if (allowInvokeGap) {
+        warnings.push(`warn: ${msg}（--allow-invoke-gap 豁免 · 留痕）`);
+      } else {
+        blockers.push(msg);
+      }
+    } else if (invokeHatsEval.resolution.unknown_profile) {
+      warnings.push(
+        `warn: unknown invoke_retention_profile '${invokeHatsEval.resolution.unknown_profile}' · 已回退 default`,
       );
     }
   }
@@ -167,6 +187,14 @@ export function closeTaskFile(filePath, options = {}) {
     dest,
     dryRun: !yes,
     moved,
+    invoke_hats: invokeHatsEval
+      ? {
+          required: invokeHatsEval.required,
+          covered: invokeHatsEval.covered,
+          missing: invokeHatsEval.missing,
+          source: invokeHatsEval.resolution.source,
+        }
+      : null,
   };
 }
 

package/lib/task-lint.js

@@ -193,6 +193,33 @@ export function lintTaskFile(filePath, options = {}) {
     warnings.push(warn('W2', '缺 ### 人工闸 节（轻量 task 可忽略本提醒）'));
   }
 
+  // W6 · invoke 留档集合字段（v2.12+ · 缺则 close 按 default=10,30,40）
+  if (
+    meta.task_slug &&
+    !meta.required_invoke_hats &&
+    !meta.invoke_retention_profile
+  ) {
+    warnings.push(
+      warn(
+        'W6',
+        '未设 required_invoke_hats / invoke_retention_profile · close 将按 default=10,30,40（紧急 fix 可写 minimal）',
+      ),
+    );
+  } else if (
+    meta.invoke_retention_profile &&
+    !['default', 'minimal', 'full'].includes(
+      String(meta.invoke_retention_profile).trim().toLowerCase(),
+    ) &&
+    !meta.required_invoke_hats
+  ) {
+    warnings.push(
+      warn(
+        'W6',
+        `未知 invoke_retention_profile '${meta.invoke_retention_profile}' · 将回退 default`,
+      ),
+    );
+  }
+
   // G4 · 思考轮结构（条件触发）
   lintThinkingRounds(content, lines, errors, warnings);
 

package/lib/task-meta.js

@@ -396,6 +396,158 @@ export function normalizeSlug(slug) {
   return String(slug).replace(/_/g, '-');
 }
 
+/**
+ * invoke 留档 profile → 帽集合（v2.12+）。
+ * default=10,30,40 · minimal=30 · full=00,10,20,30,40,CLOSE
+ */
+export const INVOKE_RETENTION_PROFILES = Object.freeze({
+  default: Object.freeze(['10', '30', '40']),
+  minimal: Object.freeze(['30']),
+  full: Object.freeze(['00', '10', '20', '30', '40', 'CLOSE']),
+});
+
+/** 已知 hat token（文件名扫描白名单） */
+export const KNOWN_INVOKE_HAT_TOKENS = Object.freeze(
+  new Set([
+    '00',
+    '10',
+    '20',
+    '22',
+    '30',
+    '40',
+    '50',
+    'CLOSE',
+    'close',
+  ]),
+);
+
+/**
+ * 解析 required_invoke_hats / invoke_retention_profile。
+ * 显式列表优先；皆无 → default。
+ * @returns {{ hats: string[], profile: string|null, source: 'explicit'|'profile'|'default', unknown_profile?: string }}
+ */
+export function resolveRequiredInvokeHats(meta = {}) {
+  const explicit = meta.required_invoke_hats;
+  if (explicit != null && String(explicit).trim() !== '') {
+    const hats = parseHatList(explicit);
+    return { hats, profile: meta.invoke_retention_profile ?? null, source: 'explicit' };
+  }
+
+  const profileRaw = meta.invoke_retention_profile;
+  if (profileRaw != null && String(profileRaw).trim() !== '') {
+    const key = String(profileRaw).trim().toLowerCase();
+    const preset = INVOKE_RETENTION_PROFILES[key];
+    if (preset) {
+      return { hats: [...preset], profile: key, source: 'profile' };
+    }
+    return {
+      hats: [...INVOKE_RETENTION_PROFILES.default],
+      profile: key,
+      source: 'default',
+      unknown_profile: key,
+    };
+  }
+
+  return {
+    hats: [...INVOKE_RETENTION_PROFILES.default],
+    profile: 'default',
+    source: 'default',
+  };
+}
+
+/**
+ * 从 invoke 文件名提取 hat token 集合。
+ * 兼容：invoke_YYYYMMDD_30_slug.md · invoke_YYYYMMDD_30_40_slug.md · invoke_*_CLOSE_*.md
+ * 亦认 22→20（V2 改名等价，计为 20）。
+ */
+export function extractHatsFromInvokeFilename(fileName) {
+  const base = path.basename(fileName, '.md');
+  const hats = new Set();
+
+  if (/CLOSE/i.test(base)) {
+    hats.add('CLOSE');
+  }
+
+  // 去 invoke_ 前缀与可选日期段
+  let rest = base.replace(/^invoke[_-]?/i, '');
+  rest = rest.replace(/^\d{8}[_-]?/, '');
+  rest = rest.replace(/^\d{4}-\d{2}-\d{2}[_-]?/, '');
+
+  const parts = rest.split(/[_-]+/).filter(Boolean);
+  for (const p of parts) {
+    const upper = p.toUpperCase();
+    if (upper === 'CLOSE') {
+      hats.add('CLOSE');
+      continue;
+    }
+    if (KNOWN_INVOKE_HAT_TOKENS.has(p)) {
+      hats.add(normalizeHatToken(p));
+    }
+  }
+
+  // V2：22 与 20 等价（审 task）
+  if (hats.has('22')) {
+    hats.add('20');
+  }
+
+  return hats;
+}
+
+/**
+ * 扫描 by-task/<slug>/ 目录，聚合已覆盖 hat。
+ * @returns {{ covered: Set<string>, files: string[], missingDir: boolean }}
+ */
+export function scanInvokeHats(invokeDir) {
+  if (!invokeDir || !fs.existsSync(invokeDir)) {
+    return { covered: new Set(), files: [], missingDir: true };
+  }
+  const files = fs
+    .readdirSync(invokeDir)
+    .filter((f) => f.endsWith('.md'));
+  const covered = new Set();
+  for (const f of files) {
+    for (const h of extractHatsFromInvokeFilename(f)) {
+      covered.add(h);
+    }
+  }
+  return { covered, files, missingDir: false };
+}
+
+/**
+ * 计算 required vs covered 缺口。
+ * @returns {{ required: string[], covered: string[], missing: string[], ok: boolean, resolution }}
+ */
+export function evaluateInvokeHatsRetention(meta, invokeDir) {
+  const resolution = resolveRequiredInvokeHats(meta);
+  const { covered, files, missingDir } = scanInvokeHats(invokeDir);
+  const required = resolution.hats.map(normalizeHatToken);
+  const missing = required.filter((h) => !covered.has(h));
+  return {
+    required,
+    covered: [...covered].sort(),
+    missing,
+    ok: missing.length === 0 && !missingDir && files.length > 0,
+    missingDir,
+    files,
+    resolution,
+  };
+}
+
+function parseHatList(raw) {
+  return String(raw)
+    .split(/[,，\s]+/)
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map(normalizeHatToken);
+}
+
+function normalizeHatToken(token) {
+  const t = String(token).trim();
+  if (/^close$/i.test(t)) return 'CLOSE';
+  if (t === '22') return '22';
+  return t;
+}
+
 function normalizeCell(cell) {
   return cell.replace(/[`\\*]/g, '').trim();
 }

package/lib/verify.js

@@ -5,10 +5,12 @@ import { resolveHarnessRootForTarget, wizardScript } from './paths.js';
 import { auditTarget } from './audit.js';
 import {
   buildTaskHandoff,
+  evaluateInvokeHatsRetention,
   extractSpecSlug,
   findReview,
   findSpecReview,
   listActiveTasks,
+  parseHarnessMeta,
   shouldSkipSpecAudit,
 } from './task-meta.js';
 import { lintTaskFile } from './task-lint.js';
@@ -16,10 +18,17 @@ import { lintTaskFile } from './task-lint.js';
 /**
  * 30 前聚合验证：gate-check + audit D5（仅 --task）+ reviews 留档闸
  *（--task 与全量 · N4/v2.9+）+ task lint WARN（仅 --task · v2.7+）
+ * + invoke hats 缺口 WARN（仅 --task · v2.12+ · 不挡 30）
  * + S5 git-clean warn + 可选 --graph
  */
 export function verifyTarget(target, options = {}) {
-  const { taskFile, graph, allowNoReview = false, allowLintFail = false } = options;
+  const {
+    taskFile,
+    graph,
+    allowNoReview = false,
+    allowLintFail = false,
+    allowInvokeGap = false,
+  } = options;
   const harnessRoot = resolveHarnessRootForTarget(target);
 
   // 1. gate-check（含 --graph）
@@ -70,6 +79,35 @@ export function verifyTarget(target, options = {}) {
         gateResult.stdout += `WARN: task lint FAIL · ${rules || 'errors'}（不挡 may_start_30 · 修结构或 --allow-lint-fail）\n`;
       }
     }
+
+    // 3d. invoke hats 缺口（v2.12+）：WARN 不挡 30 · close 才 block
+    const absTask = path.isAbsolute(taskFile)
+      ? taskFile
+      : path.join(target, taskFile);
+    if (fs.existsSync(absTask)) {
+      const content = fs.readFileSync(absTask, 'utf8');
+      const meta = parseHarnessMeta(content);
+      const slug = meta.task_slug;
+      if (slug) {
+        const invokeDir = path.join(
+          target,
+          'docs/harness/invokes/by-task',
+          slug,
+        );
+        const hatsEval = evaluateInvokeHatsRetention(meta, invokeDir);
+        if (hatsEval.missing.length > 0 || hatsEval.missingDir || hatsEval.files.length === 0) {
+          const detail =
+            hatsEval.missingDir || hatsEval.files.length === 0
+              ? `目录缺失/空 · 要求 ${hatsEval.required.join(',')}`
+              : `缺 ${hatsEval.missing.join(',')}（要求 ${hatsEval.required.join(',')} · 已有 ${hatsEval.covered.join(',') || '∅'}）`;
+          if (allowInvokeGap) {
+            gateResult.stdout += `WARN: invoke hats gap suppressed（--allow-invoke-gap · 留痕）· ${detail}\n`;
+          } else {
+            gateResult.stdout += `WARN: invoke hats gap · ${detail}（不挡 may_start_30 · close 前须补齐或 --allow-invoke-gap）\n`;
+          }
+        }
+      }
+    }
   } else {
     // 3c. 全量 reviews 闸（N4 · v2.9+）：不跑 lint / D5
     const taskFiles = listActiveTasks(target);

package/package.json

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