@cyning/harness 2.0.4 → 2.1.1

package/CHANGELOG.md

@@ -4,6 +4,37 @@
 
 ## [Unreleased]
 
+## [2.1.1] - 2026-06-30
+
+### Fixed
+
+- **task 人工闸解析**：`lib/task-meta.js` 与 `wizard/gate-check.sh` 现在会去除 Markdown 反引号，避免将 `` `approved` `` 误判为 pending。
+- 影响命令：`verify`、`gate-check`。
+
+### Notes
+
+- **HG-RELEASE**：待维护者 publish `@cyning/harness@2.1.1` · tag `v2.1.1`
+- patch · 无 CLI breaking · `npm test` 预期通过
+
+## [2.1.0] - 2026-06-30
+
+### Added
+
+- **YAML-first 图谱模板**：`graph/templates/00_main.graph.yaml`、`10_flow_MAIN.graph.yaml`
+- **编译脚本**：`scripts/graph_yaml_compile.js`（Node.js · `js-yaml`）从 `.graph.yaml` 生成 `.md`
+- **校验脚本**：`scripts/verify-template-compile.sh` — 校验同步、无残留 `.ai.md`、生成物齐全
+- **模板 v0.2**：`graph/templates/README.md` 更新复制流程；`99_mermaid_protocol.md` 升级 v3 YAML-first
+
+### Changed
+
+- **图谱模板**：删除 `graph/templates/00_main.ai.md`、`10_flow_MAIN.ai.md`；`00_main.md`、`10_flow_MAIN.md` 改为生成物
+- **版本**：`package.json` → **2.1.0**
+
+### Notes
+
+- **HG-RELEASE**：待维护者 publish `@cyning/harness@2.1.0` · tag `v2.1.0`
+- docs-only minor · 无 CLI breaking · `npm test` 预期通过
+
 ## [2.0.4] - 2026-06-21
 
 ### Added

package/docs/methodology/AUDIT_doc_consistency_2026-06-15_zh.md

@@ -1,10 +1,12 @@
 # 一致性审计报告 · 2026-06-15
 
-| 项 | 内容 |
-| --- | --- |
-| **状态** | `closed` · 后续任务已落盘 |
-| **触发** | [`prompts/PROMPT_doc_consistency_audit_v1_zh.md`](./prompts/PROMPT_doc_consistency_audit_v1_zh.md) |
-| **真值层** | L2 `docs/methodology/` |
+
+| 项       | 内容                                                                                                 |
+| ------- | -------------------------------------------------------------------------------------------------- |
+| **状态**  | `closed` · 后续任务已落盘                                                                                 |
+| **触发**  | `[prompts/PROMPT_doc_consistency_audit_v1_zh.md](./prompts/PROMPT_doc_consistency_audit_v1_zh.md)` |
+| **真值层** | L2 `docs/methodology/`                                                                             |
+
 
 ---
 
@@ -16,20 +18,22 @@ L2 真值链大体自洽，但存在 semver（v0.5 HGM 晚于 v1.0 闸门）、H
 
 ## 问题清单（按严重程度）
 
-| 级别 | ID | 问题 | 影响读者 | 建议改法 | 涉及文件 | 状态 |
-| --- | --- | --- | --- | --- | --- | --- |
-| P0 | SEM-01 | v0.5.x 在 semver 表位于 v1.0 后，数字易误读 | 以为 HGM 是 v1.0 前产品版 | Track G 子表 + 对外脚注 | `ROADMAP_v1_zh.md` 等 | ✅ → **SEM-02 改 v2.x** |
-| P0 | SEM-02 | SEM-01 脚注仍不足 · v0.5/v0.6 像主轨续号 | 问「0.5 在哪」 | HGM 改 **v2.0+ / v2.1+** · ROADMAP §2.0 | 全 L2 链 | ✅ 2026-06-15 |
-| P0 | ICV-01 | 公众 ICV 三支柱 vs 产品 ICVO 四支柱 | 续篇自相矛盾 | ICVO 升级说明 + 地图 v1.0.3 脚注 | 本体 · README · 公众稿 | ✅ |
-| P0 | IMPL-01 | A0「已完成」vs P0 进行中 | 过度承诺 v0.2 | 拆 A0a/A0b | `STRATEGY_MASTER` | ✅ |
-| P0 | IMPL-02 | HGM/jsonl/npx 未标 proposal | 以为已实现 | 统一 `proposal · 未实现` | HGM · README §5.3 | ✅ |
-| P1 | MIX-01 | HGM §5 写 gate-check --graph @ v0.4 | 与 ROADMAP v1.0 冲突 | 校正为 v1.0 Inform | `HARNESS_GRAPH_MODEL_design_v0_zh.md` | ✅ |
-| P1 | MAP-01 | DOCUMENT_MAP §4 README v1.0 滞后 | 锚点误报 | 更新 §4 | `DOCUMENT_MAP_v1_zh.md` | ✅ |
-| P1 | MAP-02 | README §6 缺 v1.1 修订行 | 版本不一致 | 补修订记录 | `methodology/README.md` | ✅ |
-| P1 | MIX-02 | Harness Engineering vs 纪律包 | 误解为 Runtime | STRATEGY §1.1 澄清 | `STRATEGY_MASTER` | ✅ |
-| P1 | STRAT-01 | §4 无 Track G / ICVO D 轨 | L1 读者漏 G 轨 | 增 §4.9 | `STRATEGY_MASTER` | ✅ |
-| P2 | VER-01 | invoke_index v0.4+ vs v1.0 | 排期歧义 | 统一 v1.0 | `DESIGN_ONTOLOGY` §6 | ✅ |
-| P2 | PILOT-01 | 试点 vs P0 ACCEPTANCE 边界 | 对外泛化 | PILOT 边界句 | `PILOT_kimi_code_fork` | ✅ |
+
+| 级别  | ID       | 问题                                 | 影响读者               | 建议改法                                   | 涉及文件                                  | 状态                    |
+| --- | -------- | ---------------------------------- | ------------------ | -------------------------------------- | ------------------------------------- | --------------------- |
+| P0  | SEM-01   | v0.5.x 在 semver 表位于 v1.0 后，数字易误读   | 以为 HGM 是 v1.0 前产品版 | Track G 子表 + 对外脚注                      | `ROADMAP_v1_zh.md` 等                  | ✅ → **SEM-02 改 v2.x** |
+| P0  | SEM-02   | SEM-01 脚注仍不足 · v0.5/v0.6 像主轨续号     | 问「0.5 在哪」          | HGM 改 **v2.0+ / v2.1+** · ROADMAP §2.0 | 全 L2 链                                | ✅ 2026-06-15          |
+| P0  | ICV-01   | 公众 ICV 三支柱 vs 产品 ICVO 四支柱          | 续篇自相矛盾             | ICVO 升级说明 + 地图 v1.0.3 脚注               | 本体 · README · 公众稿                     | ✅                     |
+| P0  | IMPL-01  | A0「已完成」vs P0 进行中                   | 过度承诺 v0.2          | 拆 A0a/A0b                              | `STRATEGY_MASTER`                     | ✅                     |
+| P0  | IMPL-02  | HGM/jsonl/npx 未标 proposal          | 以为已实现              | 统一 `proposal · 未实现`                    | HGM · README §5.3                     | ✅                     |
+| P1  | MIX-01   | HGM §5 写 gate-check --graph @ v0.4 | 与 ROADMAP v1.0 冲突  | 校正为 v1.0 Inform                        | `HARNESS_GRAPH_MODEL_design_v0_zh.md` | ✅                     |
+| P1  | MAP-01   | DOCUMENT_MAP §4 README v1.0 滞后     | 锚点误报               | 更新 §4                                  | `DOCUMENT_MAP_v1_zh.md`               | ✅                     |
+| P1  | MAP-02   | README §6 缺 v1.1 修订行               | 版本不一致              | 补修订记录                                  | `methodology/README.md`               | ✅                     |
+| P1  | MIX-02   | Harness Engineering vs 纪律包         | 误解为 Runtime        | STRATEGY §1.1 澄清                       | `STRATEGY_MASTER`                     | ✅                     |
+| P1  | STRAT-01 | §4 无 Track G / ICVO D 轨            | L1 读者漏 G 轨         | 增 §4.9                                 | `STRATEGY_MASTER`                     | ✅                     |
+| P2  | VER-01   | invoke_index v0.4+ vs v1.0         | 排期歧义               | 统一 v1.0                                | `DESIGN_ONTOLOGY` §6                  | ✅                     |
+| P2  | PILOT-01 | 试点 vs P0 ACCEPTANCE 边界             | 对外泛化               | PILOT 边界句                              | `PILOT_kimi_code_fork`                | ✅                     |
+
 
 ---
 
@@ -65,7 +69,10 @@ L2 真值链大体自洽，但存在 semver（v0.5 HGM 晚于 v1.0 闸门）、H
 
 ## 修订记录
 
-| 日期 | 说明 |
-| --- | --- |
-| 2026-06-15 | 初版审计 · 同日落盘修复 |
+
+| 日期         | 说明                              |
+| ---------- | ------------------------------- |
+| 2026-06-15 | 初版审计 · 同日落盘修复                   |
 | 2026-06-15 | SEM-02：HGM semver **v2.x** 全链回填 |
+
+

package/docs/methodology/README.md

@@ -80,6 +80,7 @@ HGM = 结构化对象 + 显式带类型的边 + 不可变事件历史 + 可推
 | ----------------------------------------------------------- | ------------------------------------ |
 | `[HARNESS_V2_PLAN.md](./pointers/HARNESS_V2_PLAN_v1_zh.md)` | Ink 工作区 Harness 规划 · task 字段 · CI 批次 |
 | `[SDD_HAT_FLOW.md](./pointers/SDD_HAT_FLOW_v1_zh.md)`       | 历史帽编号 · Starter 以产品仓 prompts 为准      |
+| `[HARNESS_HAT_CHAIN_V2_ONEPAGER_v1_zh.md](./pointers/HARNESS_HAT_CHAIN_V2_ONEPAGER_v1_zh.md)` | 帽子链 V2 对外摘要 · 双 20 · 人闸 · 50 可选 |
 | 工作区 `docs/harness/prompts/`                                 | **Extended** 全量帽 · 不默认复制进产品包         |
 
 

package/docs/methodology/execution/POSTMORTEM_backtick_gate_parsing_v1_zh.md

@@ -0,0 +1,96 @@
+# Postmortem · 人工闸 status 反引号解析事故
+
+| 项 | 内容 |
+| --- | --- |
+| 日期 | 2026-06-30 |
+| 产品包 | `@cyning/harness` |
+| 版本 | 2.1.0 → 2.1.1 |
+| 类型 | bugfix / 回归风险 |
+| 触发任务 | `task_fix_harness_verify_status_parsing_v1` |
+
+## 现象
+
+`npx @cyning/harness verify` 在 task 表的 `### 人工闸` 中，将 status 字段的 Markdown 反引号一并解析，导致：
+
+- task 表写 `HG-AUDIT-R1 | approved` 时，内部状态为 `` `approved` ``
+- `evaluateMayStart30` 判断 `audit?.status !== 'approved'`，返回阻塞
+- CLI 输出「HG-AUDIT-R1 非 approved（须维护者签 task 表）」，即使 task 表已明确 approved
+
+## 根因
+
+### 1. `lib/task-meta.js` 的 `normalizeCell` 只去星号没去反引号
+
+```javascript
+// 修复前
+function normalizeCell(cell) {
+  return cell.replace(/\*/g, '').trim();
+}
+```
+
+### 2. `wizard/gate-check.sh` 的 `gate_status` / `gate_blocks` 同样只去星号
+
+```bash
+# 修复前
+awk -F'|' -v g="$gate" '
+  ...
+  gsub(/\*/, "", $3)
+  ...
+'
+```
+
+### 3. 测试用例未覆盖带反引号的 status
+
+现有 `test/verify.test.js` 的 `writeTaskWithGate` 直接写 `approved`（无反引号），未模拟真实 task 表中 `` `approved` `` 的格式。
+
+## 修复
+
+### `lib/task-meta.js`
+
+```javascript
+function normalizeCell(cell) {
+  return cell.replace(/[`\*]/g, '').trim();
+}
+```
+
+### `wizard/gate-check.sh`
+
+```bash
+awk -F'|' -v g="$gate" '
+  ...
+  gsub(/[`*]/, "", $3)
+  ...
+'
+```
+
+> **注意**：awk 字符类中写 `` [`\*] `` 会导致正则语法错误（`illegal primary in regular expression`），因为 awk 中反斜杠在字符类内有特殊处理。应使用 `` [`*] ``。
+
+## 教训
+
+1. **Markdown 表格的格式化符号必须被 normalize**
+   - status 字段常见写法：`` `approved` ``、`*approved*`、`` **`approved`** ``
+   - 解析时必须统一去除：反引号、星号、首尾空白
+
+2. **测试用例必须覆盖真实 task 表格式**
+   - 不要只测裸字符串 `approved`
+   - 必须测 `` `approved` ``、`` **`approved`** ``、`*approved*` 等变体
+
+3. **awk 与 JavaScript 正则差异**
+   - JS：`/[`\\*]/g` 正确
+   - awk：`` [`\*] `` 报错，应写 `` [`*] ``
+   - 修改 shell 脚本后必须用 `bash -n` 或实际运行验证
+
+4. **发布前必须跑完整测试**
+   - `npm test` 在修复前是 62/72 失败，修复后是 72/72 通过
+   - 若发布前未跑测试，此 bug 会进入 2.1.0
+
+## 预防措施
+
+- [ ] 在 `test/verify.test.js` 中增加带反引号的 gate 状态测试
+- [ ] 在 `test/audit.test.js` 中同样增加反引号覆盖
+- [ ] 将 `normalizeCell` 的测试独立为一个单元测试
+- [ ] 后续修改 `wizard/*.sh` 时，先用 `bash -n` 检查语法
+
+## 关联提交
+
+- `9f5761c` fix(verify): strip backticks from gate status cells
+- tag: `v2.1.1`

package/docs/methodology/pointers/HARNESS_HAT_CHAIN_V2_ONEPAGER_v1_zh.md

@@ -0,0 +1,31 @@
+# POINTER · 帽子链 V2 一页纸
+
+| 项 | 内容 |
+| --- | --- |
+| **状态** | `active` |
+| **版本** | v1.0 |
+| **日期** | 2026-06-29 |
+| **真值** | 工作区 `Projects/docs/harness/guides/POINTER_hat_chain_v2_onepager_v1_zh.md` |
+| **修正测评** | 工作区 `Projects/docs/harness/guides/ASSESSMENT_hat_chain_00_50_corrected_v1_zh.md` |
+| **三方原文（只读）** | 工作区 `Projects/docs/harness/guides/ASSESSMENT_third_party_hat_chain_00_50_archive_v1_zh.md` |
+
+> **本文件为 POINTER · 禁止复制全文**。对外/面试摘要请打开上方「真值」链接。
+
+---
+
+## 一句话
+
+工作区 Harness V2 帽链 = **00 编排 + 10 双轨思考 + 20 双类型书面审 + 人闸 + 30–40–可选 50**，目标是把 AI 编码做成 **有规格冻结点、有书面签收、有命令证据、有独立复检、有 CI 终审** 的 PR 级交付。
+
+## 关键纪律
+
+- **双 20**：`20-spec-audit` 审 SPEC，`20-task-audit` 审 task；**不可合并为单审**。  
+- **人闸**：`HG-AUDIT-R1` 必须在 30 执行前书面 approved；00/Agent **禁止代签**。  
+- **50 可选**：非每个 task 都须 50，但 40 自检证据必须可复核。  
+- **invoke ≠ cache**：invoke 是 **开帽快照**，不是 prompt 缓存。  
+
+## 阅读顺序
+
+1. 真值 one-pager：[`POINTER_hat_chain_v2_onepager_v1_zh.md`](../../../../Projects/docs/harness/guides/POINTER_hat_chain_v2_onepager_v1_zh.md)  
+2. 修正测评：[`ASSESSMENT_hat_chain_00_50_corrected_v1_zh.md`](../../../../Projects/docs/harness/guides/ASSESSMENT_hat_chain_00_50_corrected_v1_zh.md)  
+3. V2 链指南：[`GUIDANCE_harness_hat_v2_chain_v1_zh.md`](../../../../Projects/docs/harness/guides/GUIDANCE_harness_hat_v2_chain_v1_zh.md)

package/docs/methodology/pointers/README.md

@@ -16,6 +16,7 @@
 | [`PILOT_kimi_code_fork_v1_zh.md`](./PILOT_kimi_code_fork_v1_zh.md) | `docs/harness/guides/PILOT_kimi_code_fork_adoption_v1_zh.md` |
 | [`GUIDANCE_distribution_v1_zh.md`](./GUIDANCE_distribution_v1_zh.md) | `docs/harness/guides/GUIDANCE_harness_distribution_v1_zh.md` |
 | [`ASSESSMENT_etclovg_v1_zh.md`](./ASSESSMENT_etclovg_v1_zh.md) | `docs/harness/guides/ASSESSMENT_cyning_harness_etclovg_industry_v1_zh.md` |
+| [`HARNESS_HAT_CHAIN_V2_ONEPAGER_v1_zh.md`](./HARNESS_HAT_CHAIN_V2_ONEPAGER_v1_zh.md) | `docs/harness/guides/POINTER_hat_chain_v2_onepager_v1_zh.md` |
 
 **工作区索引**：`docs/harness/README.md`
 

package/graph/templates/00_main.graph.yaml

@@ -0,0 +1,72 @@
+graph_id: "00_main"
+title: "顶层流程总图"
+description: "模板包主入口分发与典型子流程路由"
+version: "2026-06-30"
+
+nodes:
+  - id: "Q"
+    label: "用户 / 客户端请求"
+  - id: "E"
+    label: "应用入口"
+  - id: "M1"
+    label: "核心业务处理"
+  - id: "M2"
+    label: "次要路径"
+  - id: "ADM"
+    label: "Admin / Job"
+  - id: "FLOW_MAIN"
+    label: "主路径子流程"
+  - id: "FLOW_DOC"
+    label: ">10_flow_MAIN.md"
+  - id: "DB"
+    label: "持久化"
+  - id: "STRUCT_DOC"
+    label: ">01_struct.md"
+
+edges:
+  - from: "Q"
+    to: "E"
+    label: "->"
+    anchors:
+      - path: "src/main.py"
+        line: 1
+      - path: "app/router/index.ts"
+        line: 1
+  - from: "E"
+    to: "M1"
+    label: "主路径 A"
+    anchors:
+      - path: "handlers/resource.py"
+        symbol: "handle_create"
+  - from: "E"
+    to: "M2"
+    label: "主路径 B"
+    anchors:
+      - path: "handlers/health.py"
+        symbol: "health_check"
+  - from: "E"
+    to: "ADM"
+    label: "管理/批处理"
+    anchors:
+      - path: "jobs/ingest.py"
+        symbol: "run_sync"
+  - from: "M1"
+    to: "FLOW_MAIN"
+    mark: "::triggers"
+    type: "triggers"
+  - from: "FLOW_MAIN"
+    to: "FLOW_DOC"
+    label: "加载"
+  - from: "M1"
+    to: "DB"
+    label: "->"
+    anchors:
+      - path: "db/repository.py"
+  - from: "ADM"
+    to: "DB"
+    label: "->"
+    anchors:
+      - path: "db/repository.py"
+  - from: "E"
+    to: "STRUCT_DOC"
+    label: "加载"

package/graph/templates/00_main.md

@@ -1,52 +1,65 @@
-# 顶层流程总图（人类友好版）
+---
+graph_id: 00_main
+title: 顶层流程总图
+description: 模板包主入口分发与典型子流程路由
+version: '2026-06-30'
+generated_from: 00_main.graph.yaml
+generator: scripts/graph_yaml_compile.js
+---
 
-> **用途**：`docs/_tech_graph/00_main.md` — 本仓 **Happy Path** 主干；子流程折叠为 `10_flow_*.md` 链接。  
-> **双轨**：须与 [`00_main.ai.md`](./00_main.ai.md) 语义等价；flowchart 改 `.ai.md` 优先，再同步本文件。  
-> **协议**：[`99_mermaid_protocol.md`](./99_mermaid_protocol.md)
+# 顶层流程总图
 
-## 维护说明
+> 模板包主入口分发与典型子流程路由
 
-1. 替换下方占位节点为你的 **真实入口**（HTTP 路由 / CLI / 事件总线等）。
-2. 子图节点 > 7 时折叠为 `[[Phase]]`，链至独立 `10_flow_*.md`。
-3. 异常分支可挂侧链；主干保持可读。
+> **源文件**：`00_main.graph.yaml` · 由 `scripts/graph_yaml_compile.js` 生成 · 请勿直接手写本文件
 
 ```mermaid
 flowchart TD
-    %% version: YYYY-MM-DD — 替换为首次人签日期
-
-    %% === 入口 ===
-    Q[用户 / 客户端请求] --> E{应用入口<br/>例：src/main.py 或 app/router}
-
-    %% === 主业务分支（示例 · 按栈裁剪）===
-    E -->|主路径 A| M1[核心业务处理<br/>例：/api/v1/resource]
-    E -->|主路径 B| M2[次要路径<br/>例：/health 或 /metrics]
-    E -->|管理/批处理| ADM[Admin / Job<br/>例：ingest / sync]
-
-    %% === 子流程折叠 ===
-    M1 --> FLOW_MAIN[主路径子流程]
-    FLOW_MAIN --> FLOW_DOC[> 10_flow_MAIN.md]
-
-    M1 --> DB[(持久化<br/>例：PostgreSQL / 文件)]
+    Q[[用户 / 客户端请求]]
+    E[[应用入口]]
+    M1[[核心业务处理]]
+    M2[[次要路径]]
+    ADM[[Admin / Job]]
+    FLOW_MAIN[[主路径子流程]]
+    FLOW_DOC[>10_flow_MAIN.md]
+    DB[(持久化)]
+    STRUCT_DOC[>01_struct.md]
+    Q --> E
+    E --"主路径 A"--> M1
+    E --"主路径 B"--> M2
+    E --"管理/批处理"--> ADM
+    M1 --"::triggers"--> FLOW_MAIN
+    FLOW_MAIN --"加载"--> FLOW_DOC
+    M1 --> DB
     ADM --> DB
-
-    %% === 样式（可选）===
-    classDef start fill:#e1f5fe,stroke:#01579b,stroke-width:2px
-    classDef main fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
-    classDef infra fill:#fff8e1,stroke:#ff6f00,stroke-width:1px
-
-    class Q,E start
-    class M1,M2,ADM main
-    class FLOW_MAIN,DB infra
+    E --"加载"--> STRUCT_DOC
+    %% 锚点：见 YAML 源 edges[].anchors
 ```
 
-## 待补 flow 清单（存量 S2+ 可用）
+## Nodes
 
-| flow 文件 | 状态 | 说明 |
-|-----------|------|------|
-| `10_flow_MAIN.md` | 示例已提供 | 主请求路径；嵌入后替换为真实 API/页面流 |
-| `10_flow_*.md` | 待增量 | 每 Epic 或跨模块改动时补 1 张 |
+| ID | Label |
+|----|-------|
+| Q | 用户 / 客户端请求 |
+| E | 应用入口 |
+| M1 | 核心业务处理 |
+| M2 | 次要路径 |
+| ADM | Admin / Job |
+| FLOW_MAIN | 主路径子流程 |
+| FLOW_DOC | >10_flow_MAIN.md |
+| DB | 持久化 |
+| STRUCT_DOC | >01_struct.md |
 
-## 关联
+## Edges
 
-- 模块边界：[`01_struct.md`](./01_struct.md)（**HG-GRAPH-MODULES** 人签真值）
-- 拓扑协议：[`99_mermaid_protocol.md`](./99_mermaid_protocol.md)
+| From | To | Label | Type | Anchors |
+|------|----|-------|------|---------|
+| Q | E | -> |  | src/main.py#L1, app/router/index.ts#L1 |
+| E | M1 | 主路径 A |  | handlers/resource.py::handle_create |
+| E | M2 | 主路径 B |  | handlers/health.py::health_check |
+| E | ADM | 管理/批处理 |  | jobs/ingest.py::run_sync |
+| M1 | FLOW_MAIN | ::triggers | triggers |  |
+| FLOW_MAIN | FLOW_DOC | 加载 |  |  |
+| M1 | DB | -> |  | db/repository.py |
+| ADM | DB | -> |  | db/repository.py |
+| E | STRUCT_DOC | 加载 |  |  |

package/graph/templates/02_version.md

@@ -0,0 +1,6 @@
+# 图谱版本时间线
+
+| 日期 | 版本 | 事件 |
+|------|------|------|
+| YYYY-MM-DD | v0.1 | 首次嵌入用户仓（请替换为真实日期） |
+| 2026-06-30 | v0.2 | 模板包迁移至 YAML-first：`00_main.graph.yaml`、`10_flow_MAIN.graph.yaml` 成为唯一编辑源；`.ai.md` 双轨文件弃用并删除；`scripts/graph_yaml_compile.js` + `scripts/verify-template-compile.sh` 上线 |

package/graph/templates/10_flow_MAIN.graph.yaml

@@ -0,0 +1,105 @@
+graph_id: "10_flow_MAIN"
+title: "主路径 Flow 示例"
+description: "典型 HTTP 请求从入口到响应的主干流程"
+version: "2026-06-30"
+
+nodes:
+  - id: "IN"
+    label: "HTTP 请求"
+  - id: "AUTH"
+    label: "鉴权 / 会话校验"
+  - id: "VAL"
+    label: "参数校验"
+  - id: "SVC"
+    label: "业务服务层"
+  - id: "ERR_AUTH"
+    label: "Auth Failed"
+  - id: "ERR_VAL"
+    label: "Validation Failed"
+  - id: "REPO"
+    label: "仓储 / ORM"
+  - id: "DB"
+    label: "数据库 / 存储"
+  - id: "HIT"
+    label: "record exists?"
+  - id: "NOTFOUND"
+    label: "404 / 空结果"
+  - id: "BIZERR"
+    label: "4xx 业务错误"
+  - id: "RESP"
+    label: "组装响应 DTO"
+  - id: "OUT"
+    label: "返回 JSON / 页面"
+  - id: "LOG"
+    label: "结构化日志"
+  - id: "MAIN_DOC"
+    label: ">00_main.md"
+
+edges:
+  - from: "IN"
+    to: "AUTH"
+    label: "->"
+    anchors:
+      - path: "middleware/auth.py"
+        symbol: "require_user"
+  - from: "AUTH"
+    to: "VAL"
+    label: "[ok]"
+  - from: "AUTH"
+    to: "ERR_AUTH"
+    label: "[err]"
+    anchors:
+      - path: "middleware/auth.py"
+        line: 42
+  - from: "VAL"
+    to: "SVC"
+    label: "[ok]"
+    anchors:
+      - path: "services/resource_service.py"
+        symbol: "handle"
+  - from: "VAL"
+    to: "ERR_VAL"
+    label: "[err]"
+  - from: "SVC"
+    to: "REPO"
+    label: "->"
+    anchors:
+      - path: "repositories/resource_repo.py"
+        symbol: "find_by_id"
+  - from: "REPO"
+    to: "DB"
+    label: "->"
+    anchors:
+      - path: "db/session.py"
+  - from: "REPO"
+    to: "HIT"
+    label: "?>"
+  - from: "HIT"
+    to: "NOTFOUND"
+    label: "[no]"
+  - from: "HIT"
+    to: "SVC"
+    label: "[yes]"
+  - from: "SVC"
+    to: "BIZERR"
+    label: "[err]"
+    anchors:
+      - path: "services/resource_service.py"
+  - from: "SVC"
+    to: "RESP"
+    label: "->"
+  - from: "RESP"
+    to: "OUT"
+    label: "->"
+    anchors:
+      - path: "handlers/resource.py"
+        symbol: "to_response"
+  - from: "OUT"
+    to: "LOG"
+    mark: "::archives"
+    type: "archives"
+    anchors:
+      - path: "observability/logger.py"
+  - from: "IN"
+    to: "MAIN_DOC"
+    label: "加载"

package/graph/templates/10_flow_MAIN.md

@@ -1,47 +1,89 @@
-# 主路径 Flow 示例（人类友好版）
+---
+graph_id: 10_flow_MAIN
+title: 主路径 Flow 示例
+description: 典型 HTTP 请求从入口到响应的主干流程
+version: '2026-06-30'
+generated_from: 10_flow_MAIN.graph.yaml
+generator: scripts/graph_yaml_compile.js
+---
 
-> **用途**：`docs/_tech_graph/10_flow_MAIN.md` — **至少 1 条**主业务流（新仓 / S0 必做）。  
-> **双轨**：须与 [`10_flow_MAIN.ai.md`](./10_flow_MAIN.ai.md) 语义等价。  
-> **嵌入后**：将占位路径替换为真实 handler / 路由 / 页面流。
+# 主路径 Flow 示例
 
-```mermaid
-flowchart TD
-    %% Entry: 例 GET/POST /api/v1/resource — 替换为真实入口
-
-    %% === 请求阶段 ===
-    IN[HTTP 请求] --> AUTH[鉴权 / 会话校验]
-    AUTH --> VAL[参数校验<br/>schema / DTO]
-    VAL --> SVC[业务服务层<br/>例：ResourceService]
-
-    %% === 数据阶段 ===
-    SVC --> REPO[仓储 / ORM<br/>例：ResourceRepository]
-    REPO --> DB[(数据库 / 存储)]
-
-    REPO -->|无记录| NOTFOUND[404 / 空结果]
-    SVC -->|业务规则失败| BIZERR[4xx 业务错误]
+> 典型 HTTP 请求从入口到响应的主干流程
 
-    %% === 响应阶段 ===
-    SVC --> RESP[组装响应 DTO]
-    RESP --> OUT[返回 JSON / 页面]
+> **源文件**：`10_flow_MAIN.graph.yaml` · 由 `scripts/graph_yaml_compile.js` 生成 · 请勿直接手写本文件
 
-    %% === 可观测（可选）===
-    OUT --> LOG[结构化日志 / trace]
-
-    %% 样式
-    classDef request fill:#e1f5fe,stroke:#01579b,stroke-width:2px
-    classDef domain fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
-    classDef data fill:#fff8e1,stroke:#ff6f00,stroke-width:1px
-
-    class IN,AUTH,VAL request
-    class SVC,RESP,OUT domain
-    class REPO,DB,LOG data
+```mermaid
+flowchart TD
+    IN[[HTTP 请求]]
+    AUTH[[鉴权 / 会话校验]]
+    VAL[[参数校验]]
+    SVC[[业务服务层]]
+    ERR_AUTH[[Auth Failed]]
+    ERR_VAL[[Validation Failed]]
+    REPO[[仓储 / ORM]]
+    DB[(数据库 / 存储)]
+    HIT{record exists?}
+    NOTFOUND[[404 / 空结果]]
+    BIZERR[[4xx 业务错误]]
+    RESP[[组装响应 DTO]]
+    OUT[[返回 JSON / 页面]]
+    LOG(( 结构化日志 ))
+    MAIN_DOC[>00_main.md]
+    IN --> AUTH
+    AUTH --"[ok]"--> VAL
+    AUTH --"[err]"--> ERR_AUTH
+    VAL --"[ok]"--> SVC
+    VAL --"[err]"--> ERR_VAL
+    SVC --> REPO
+    REPO --> DB
+    REPO --"?>"--> HIT
+    HIT --"[no]"--> NOTFOUND
+    HIT --"[yes]"--> SVC
+    SVC --"[err]"--> BIZERR
+    SVC --> RESP
+    RESP --> OUT
+    OUT --"::archives"--> LOG
+    IN --"加载"--> MAIN_DOC
+    %% 锚点：见 YAML 源 edges[].anchors
 ```
 
-## 与顶层图关系
+## Nodes
 
-- 在 [`00_main.md`](./00_main.md) 中由 `M1` 或等价节点 **加载** 本文件。
-- 模块归属见 [`01_struct.md`](./01_struct.md) 中 `api` / `core` 等行。
+| ID | Label |
+|----|-------|
+| IN | HTTP 请求 |
+| AUTH | 鉴权 / 会话校验 |
+| VAL | 参数校验 |
+| SVC | 业务服务层 |
+| ERR_AUTH | Auth Failed |
+| ERR_VAL | Validation Failed |
+| REPO | 仓储 / ORM |
+| DB | 数据库 / 存储 |
+| HIT | record exists? |
+| NOTFOUND | 404 / 空结果 |
+| BIZERR | 4xx 业务错误 |
+| RESP | 组装响应 DTO |
+| OUT | 返回 JSON / 页面 |
+| LOG | 结构化日志 |
+| MAIN_DOC | >00_main.md |
 
-## 增量维护
+## Edges
 
-改 BFF / API 契约时：**同 task** 更新本 flow 或另开图谱子 task；Harness 关账 ≠ 图谱关账。
+| From | To | Label | Type | Anchors |
+|------|----|-------|------|---------|
+| IN | AUTH | -> |  | middleware/auth.py::require_user |
+| AUTH | VAL | [ok] |  |  |
+| AUTH | ERR_AUTH | [err] |  | middleware/auth.py#L42 |
+| VAL | SVC | [ok] |  | services/resource_service.py::handle |
+| VAL | ERR_VAL | [err] |  |  |
+| SVC | REPO | -> |  | repositories/resource_repo.py::find_by_id |
+| REPO | DB | -> |  | db/session.py |
+| REPO | HIT | ?> |  |  |
+| HIT | NOTFOUND | [no] |  |  |
+| HIT | SVC | [yes] |  |  |
+| SVC | BIZERR | [err] |  | services/resource_service.py |
+| SVC | RESP | -> |  |  |
+| RESP | OUT | -> |  | handlers/resource.py::to_response |
+| OUT | LOG | ::archives | archives | observability/logger.py |
+| IN | MAIN_DOC | 加载 |  |  |

package/graph/templates/99_mermaid_protocol.md

@@ -1,14 +1,13 @@
-# Mermaid 拓扑协议（通用 · v2）
+# Mermaid 拓扑协议（通用 · v3）
 
-> **用途**：`docs/_tech_graph/99_mermaid_protocol.md` — flowchart **双轨** 与边标记真值。  
-> **双轨制**：`.md` 人类友好；`.ai.md` AI / 脚本协议版；**语义等价**。
+> **用途**：`docs/_tech_graph/99_mermaid_protocol.md` — flowchart 边标记、节点形状与 YAML-first 生成真值。
 
-| 后缀 | 维护者 | 特点 |
-|------|--------|------|
-| `.md` | 开发者 | 简洁可读；少量裸边可接受 |
-| `.ai.md` | LLM / 脚本 | 结构化标记、锚点分离、**零裸边** |
+## 0. YAML-first 工作流
 
-**转换方向**：人写 `.md` → 按本协议生成/同步 `.ai.md` → 渲染审阅。
+- **唯一人工编辑源**：`*.graph.yaml`（本目录下如 `00_main.graph.yaml`、`10_flow_MAIN.graph.yaml`）。
+- **生成物**：同名 `*.md` 由 `scripts/graph_yaml_compile.js` 自动生成，包含 YAML frontmatter、Mermaid flowchart、Nodes/Edges 表。
+- **禁止手写 `.md`**：如需改图，改 YAML 源后重新运行编译脚本；`--check` 模式可检测 `.md` 与 `.graph.yaml` 是否同步。
+- **历史 `.ai.md` 双轨已弃用**：Post-G0 后不再维护 `.md` + `.ai.md` 两份文件；所有结构化信息（锚点、边类型）集中在 YAML 源中。
 
 ---
 
@@ -59,19 +58,23 @@
 
 ---
 
-## 3. 锚点规则（`.ai.md` 强制）
+## 3. 锚点规则（YAML 源强制）
 
-每条 **硬边** 须可追溯到代码或文档：
+每条 **硬边** 须可追溯到代码或文档，写在 YAML `edges[].anchors` 中：
 
-```text
-// → src/handlers/foo.py#L42
-// → src/handlers/foo.py::handle_request
-// → migrations/001_init.sql#L12
-// → docs/_tech_graph/10_flow_MAIN.md
+```yaml
+edges:
+  - from: "Q"
+    to: "E"
+    anchors:
+      - path: "src/main.py"
+        line: 1
+      - path: "app/router/index.ts"
+        symbol: "Router"
 ```
 
-- 锚点用 **独立注释行** `// → path#Ln`，不塞进节点标签。
-- 跨模块调用：虚线或 `::triggers`，**不**展开对方内部。
+- 跨模块调用：使用 `::triggers` 或虚线，**不**展开对方内部。
+- 未知锚点：保留 `path: TBD` 并开 task 补全。
 
 ---
 
@@ -87,14 +90,30 @@
 
 ## 5. 禁止项
 
-- `.ai.md` 中 **禁止裸边**（须带 `"->"` 等标记）。
-- 禁止虚构文件路径；未知处用 `// → TBD` 并开 task 补锚点。
+- **禁止**维护 `.ai.md` 双轨文件。
+- **禁止**在生成的 `.md` 中直接手写 flowchart（会被下次编译覆盖）。
+- 禁止虚构文件路径；未知处用 `path: TBD` 并开 task 补锚点。
 - **禁止** onboarding 默认「全仓扫描生图」。
 
 ---
 
-## 6. 修订记录
+## 6. YAML 字段到 Mermaid 映射
+
+| YAML 字段 | Mermaid 输出 | 说明 |
+|-----------|--------------|------|
+| `nodes[].id` | 节点 ID | 必须唯一 |
+| `nodes[].label` | 节点显示文本 | 决定节点形状 |
+| `edges[].from` / `to` | 边两端 | 必须引用存在的节点 |
+| `edges[].label` | 边标签 | `"->"` 表示裸执行边 |
+| `edges[].mark` | 元关系标记 | 如 `::triggers`、`::branches` |
+| `edges[].type` | 边类型 | 与 `mark` 命名空间对应 |
+| `edges[].anchors` | 不渲染，写入 table | 代码追溯 |
+
+---
+
+## 7. 修订记录
 
 | 日期 | 说明 |
 |------|------|
+| 2026-06-30 | v3：YAML-first，删除 `.ai.md` 双轨，新增 YAML → Mermaid 映射 |
 | YYYY-MM-DD | 嵌入用户仓时填写首次版本 |

package/graph/templates/README.md

@@ -2,16 +2,16 @@
 
 复制到用户仓 **`docs/_tech_graph/`**。
 
-## v0.1 已交付模板（T1 · M2）
+## v0.2 已交付模板（T2 · YAML-first）
 
 | 文件 | 状态 | 说明 |
 |------|------|------|
-| [`00_main.md`](./00_main.md) | ✅ | 顶层流程（人类友好版） |
-| [`00_main.ai.md`](./00_main.ai.md) | ✅ | 顶层流程（AI 协议版 · 双轨） |
+| [`00_main.graph.yaml`](./00_main.graph.yaml) | ✅ | 顶层流程（唯一编辑源） |
+| [`00_main.md`](./00_main.md) | ✅ | 顶层流程（编译生成物） |
 | [`01_struct.md`](./01_struct.md) | ✅ | **模块边界表**（D4-a · **HG-GRAPH-MODULES** 人签真值） |
-| [`99_mermaid_protocol.md`](./99_mermaid_protocol.md) | ✅ | Mermaid 拓扑协议 |
-| [`10_flow_MAIN.md`](./10_flow_MAIN.md) | ✅ | 主路径 flow 示例（人类版） |
-| [`10_flow_MAIN.ai.md`](./10_flow_MAIN.ai.md) | ✅ | 主路径 flow 示例（AI 版） |
+| [`10_flow_MAIN.graph.yaml`](./10_flow_MAIN.graph.yaml) | ✅ | 主路径 flow 示例（唯一编辑源） |
+| [`10_flow_MAIN.md`](./10_flow_MAIN.md) | ✅ | 主路径 flow 示例（编译生成物） |
+| [`99_mermaid_protocol.md`](./99_mermaid_protocol.md) | ✅ | Mermaid 拓扑协议（YAML-first） |
 
 ## 仍可选补（非 T1 硬门槛）
 
@@ -19,16 +19,41 @@
 |------|------|
 | `02_version.md` | 版本时间线；新仓建议嵌入后首周补 |
 
+## 编辑与复制流程
+
+1. **改图**：只改 `.graph.yaml`，不要手写 `.md`。
+2. **编译**：在 `cyning-harness/` 根运行：
+   ```bash
+   node scripts/graph_yaml_compile.js
+   ```
+3. **校验**：
+   ```bash
+   bash scripts/verify-template-compile.sh
+   ```
+4. **复制到业务仓**：
+   ```bash
+   mkdir -p docs/_tech_graph
+   cp -R cyning-harness/graph/templates/* docs/_tech_graph/
+   # 按需删除 README 或本说明段
+   ```
+
+## 业务仓专属产物
+
+以下文件是业务仓运行时 artifact，**不在模板包中生成空壳**：
+
+- `_manifest.json`
+- `_contract_manifest.json`
+- `_test_manifest.json`
+
+业务仓应基于真实 endpoint / RPC / 表 / 事件契约，通过自身 CI（如 `tech-graph.yml`、`tech-graph-contract.yml`）生成并校验这些 manifest。模板包仅提供 `.graph.yaml` → `.md` 的简化编译流。
+
 ## 嵌入后
 
 - **新仓**：骨架 + 模块表人签 + 至少 1 主 flow（见 [`docs/ONBOARDING.md`](../../docs/ONBOARDING.md) §3）
 - **存量**：按 ONBOARDING 档位 S0～S3；**禁止**首次全 flow 构图
 - **人签**：`01_struct` 模块表 → **HG-GRAPH-MODULES** approved → 允许 30 改码
 
-## 复制命令
+## 历史说明
 
-```bash
-mkdir -p docs/_tech_graph
-cp -R cyning-harness/graph/templates/* docs/_tech_graph/
-# 按需删除 README 或本说明段
-```
+- v0.1 使用 `.md` + `.ai.md` 双轨；v0.2 起改为 YAML-first，`.ai.md` 已弃用。
+- 复杂业务仓应采用 `.graph.yaml` 源 + manifest/contract CI；`cyning-harness` 模板包维持简化编译流。

package/lib/task-meta.js

@@ -219,5 +219,5 @@ function extractSection(content, startMarker, endMarker) {
 }
 
 function normalizeCell(cell) {
-  return cell.replace(/\*/g, '').trim();
+  return cell.replace(/[`\\*]/g, '').trim();
 }

package/package.json

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

package/wizard/ONBOARDING_wizard_v1_zh.md

@@ -2,7 +2,8 @@
 
 > **状态**：`active`（M2 v0.1）  
 > **形态**：**脚本优先**（[`wizard/README.md`](./README.md)）；本文档为 preset 说明备查  
-> **关联**：[`docs/ONBOARDING.md`](../docs/ONBOARDING.md) · GUIDANCE D3 IDE 轨
+> **关联**：[`docs/ONBOARDING.md`](../docs/ONBOARDING.md) · GUIDANCE D3 IDE 轨  
+> **新建项目引导**：[`wizard/guides/GUIDE_new_project_bootstrap_v1_zh.md`](./guides/GUIDE_new_project_bootstrap_v1_zh.md) — 从零接入的 6 步操作手册
 
 ---
 

package/wizard/gate-check.sh

@@ -30,7 +30,7 @@ gate_status() {
   awk -F'|' -v g="$gate" '
     $0 ~ /^[[:space:]]*\|/ && index($0, g) > 0 {
       gsub(/^[[:space:]]+|[[:space:]]+$/, "", $3)
-      gsub(/\*/, "", $3)
+      gsub(/[`*]/, "", $3)
       print $3
       exit
     }
@@ -42,7 +42,7 @@ gate_blocks() {
   awk -F'|' -v g="$gate" '
     $0 ~ /^[[:space:]]*\|/ && index($0, g) > 0 {
       gsub(/^[[:space:]]+|[[:space:]]+$/, "", $4)
-      gsub(/\*/, "", $4)
+      gsub(/[`*]/, "", $4)
       print $4
       exit
     }

package/wizard/guides/GUIDE_new_project_bootstrap_v1_zh.md

@@ -0,0 +1,158 @@
+# GUIDE · 新建项目 Harness 引导（v1）
+
+| 项 | 内容 |
+| --- | --- |
+| **状态** | `active` |
+| **版本** | v1 |
+| **日期** | 2026-06-29 |
+| **触发** | harness-probe bootstrapping 实录 → 抽象为通用模式 |
+| **读者** | 维护者在新项目中接入 Harness 时的操作手册 |
+
+> **用途**：从零开始给一个新项目（单仓、Python、无前端）接入 cyning-harness 纪律体系。存量项目见 [`ONBOARDING_wizard_v1_zh.md`](../ONBOARDING_wizard_v1_zh.md)。
+
+---
+
+## 1. 判断：你的项目需要什么
+
+| 条件 | 推荐 profile | 说明 |
+| --- | --- | --- |
+| 纯文档/小工具 | `harness-only` | 只给 prompts + invoke 模板 |
+| 有业务代码 + CI | `harness-only` + 手动补图谱和 CI | **本指南覆盖** |
+| 全栈 Ink 类（前端+后端） | `fullstack-node-py` | 带 Wiki、standards、task bootstrap |
+
+**关键原则**：宁可先用 `harness-only` 打底，再按需补。fullstack profile 多出来的 Wiki + standards 对小项目是噪音。
+
+---
+
+## 2. 引导 6 步（通用模板）
+
+### Step 1：种子 prompts + invoke 模板
+
+```bash
+cd <project-root>
+npx @cyning/harness init --preset harness-only --ide cursor
+```
+
+产物：
+- `docs/harness/prompts/`：10/22/30/40 + FRAGMENT + TEMPLATE
+- `docs/harness/invokes/TEMPLATE_invoke.md`
+- `.cursor/rules/06-harness-pointer.mdc`
+
+**注意**：`.cyning-harness/` 加到 `.gitignore`。
+
+### Step 2：AGENTS.md + CLAUDE.md
+
+模板源：`cyning-harness/ide/adapters/`
+
+```bash
+cp <path-to-cyning-harness>/ide/adapters/CLAUDE.md.fragment.example <project-root>/CLAUDE.md
+cp <path-to-cyning-harness>/ide/adapters/AGENTS.md.fragment.example <project-root>/AGENTS.md
+```
+
+**CLAUDE.md**：薄层，基本不用改。替换 Verify 表里的技术栈（前端→删掉、后端→`pytest tests/ -q`）。
+
+**AGENTS.md**：片段末尾追加项目专属段（~20 行）：
+- **读序**：README → 架构文档 → 图谱
+- **命令**：项目专属 vitest/pytest/build 命令
+- **边界**：不改什么、不碰什么
+- **关键词**：项目专属关键词
+
+### Step 3：Agent 定义 + 权限
+
+创建 `.claude/agents/<project>-agent.md`：
+
+```markdown
+---
+name: <project>
+description: <项目描述> · spawn by Lead
+tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+你是 **<project> agent**。
+
+## 必读
+- `docs/harness/prompts/30-execute-code.md`
+- `docs/harness/prompts/40-self-check.md`
+- `docs/_tech_graph/graph.json`
+- 当前 task：`docs/harness/tasks/active/task_*.md`
+
+## Open Folder
+- **`<project>/`**
+
+## 边界
+- 列出项目专属禁止项
+
+## Verify
+- `pytest tests/ -q`
+
+## 回报（≤10 行）
+Status / Deliverables / Blockers / Judgment
+```
+
+`.claude/settings.json`：最小权限基线（Read/Bash 白名单）。
+
+### Step 4：技术图谱
+
+**模块 ≤ 10 个 → 手写 graph.json**。模块多了再引入导出工具链。
+
+1. 创建 `docs/_tech_graph/` 目录
+2. 为每个模块写一个 `.ai.md`（node id + label + depends_on + entry_points）
+3. 手写 `graph.json`（`schema_version: graph_v2`）
+4. `README.md` + `99_mermaid_protocol.md`
+
+**验证**：
+
+```bash
+python -m src.probe graph-query --graph docs/_tech_graph/graph.json --node <entry> --depth 2
+```
+
+### Step 5：CI 门禁
+
+复制 `task_validate.py` 并定制：
+
+```bash
+cp <source-repo>/tools/harness_task_validate.py <project-root>/tools/
+```
+
+修改：
+- `ACTIVE_TASKS` 路径 → `<project>/docs/harness/tasks/active/`
+- `_section_body` 用子串匹配（`title not in ...`），不精确匹配
+
+CI workflow（`.github/workflows/tech-graph.yml`）：
+- `task_validate` job：扫描 PR diff 中的 `docs/harness/tasks/` 变更
+- `pytest` job：跑全量测试
+
+### Step 6：验证链路
+
+```bash
+pytest tests/ -q                                      # 单测全绿
+python -m src.probe verify --task <path>              # probe 自带 verify
+npx @cyning/harness verify --target . --task <path>   # cyning-harness verify
+python tools/harness_task_validate.py <path>           # task 门禁
+```
+
+全部 exit 0 则引导完成。
+
+---
+
+## 3. 常见问题
+
+### Q: 为什么不直接用 fullstack profile？
+
+fullstack 带了 Wiki、standards L1/L2、task bootstrap——小项目用不上，反而增加 Agent 读取负担。
+
+### Q: task_validate.py 的 `_section_body` 为什么要子串匹配？
+
+因为 task 文件常用编号标题（`## 3. 失败路径`），精确匹配会遗漏。用 `title in heading` 替代 `title == heading`。
+
+### Q: GATE_ROW regex 为什么要接受反引号？
+
+因为 human_gate 表的状态列可能写 `approved` 或 `` `approved` ``，正则加 `?` 做可选反引号匹配。
+
+---
+
+## 4. 修订记录
+
+| 版本 | 日期 | 说明 |
+| --- | --- | --- |
+| v1 | 2026-06-29 | 初版 · 从 harness-probe 引导实录抽象 |

package/graph/templates/00_main.ai.md

@@ -1,28 +0,0 @@
-```mermaid
-flowchart TD
-  %% version: YYYY-MM-DD — AI 协议版 · 须与 00_main.md 语义等价
-  %% 拓扑：见 99_mermaid_protocol.md
-
-  %% === 入口阶段 ===
-  Q[[用户 / 客户端请求]] --"->"--> E{"应用入口"}
-  // → src/main.py#L1 或 app/router/index.ts#L1（替换为真实锚点）
-
-  %% === 主业务分支 ===
-  E --"主路径 A"--> M1[[核心业务处理]]
-  // → 例：handlers/resource.py::handle_create
-  E --"主路径 B"--> M2[[次要路径]]
-  // → 例：handlers/health.py::health_check
-  E --"管理/批处理"--> ADM[[Admin / Job]]
-  // → 例：jobs/ingest.py::run_sync
-
-  %% === 子流程折叠 ===
-  M1 --"::triggers"--> FLOW_MAIN[[主路径子流程]]
-  FLOW_MAIN --"加载"--> FLOW_DOC[>10_flow_MAIN.md]
-
-  M1 --"->"--> DB[(持久化)]
-  // → 例：db/repository.py 或 ORM 层
-  ADM --"->"--> DB
-
-  %% === 按需加载（可选）===
-  E --"加载"--> STRUCT_DOC[>01_struct.md]
-```

package/graph/templates/10_flow_MAIN.ai.md

@@ -1,43 +0,0 @@
-```mermaid
-flowchart TD
-  %% Entry: 例 POST /api/v1/resource — 替换锚点为真实代码
-  %% 拓扑协议：见 99_mermaid_protocol.md
-
-  %% === 请求阶段 ===
-  IN[[HTTP 请求]] --"->"--> AUTH[[鉴权 / 会话校验]]
-  // → middleware/auth.py::require_user 或 src/auth/guard.ts
-
-  AUTH --"[ok]"--> VAL[[参数校验]]
-  AUTH --"[err]"--> ERR_AUTH[>Auth Failed]
-  // → middleware/auth.py#L42
-
-  VAL --"[ok]"--> SVC[[业务服务层]]
-  // → services/resource_service.py::handle
-  VAL --"[err]"--> ERR_VAL[>Validation Failed]
-
-  %% === 数据阶段 ===
-  SVC --"->"--> REPO[[仓储 / ORM]]
-  // → repositories/resource_repo.py::find_by_id
-
-  REPO --"->"--> DB[(数据库 / 存储)]
-  // → db/session.py 或 ORM model
-
-  REPO --"?>"--> HIT{record exists?}
-  HIT --"[no]"--> NOTFOUND[[404 / 空结果]]
-  HIT --"[yes]"--> SVC
-
-  SVC --"[err]"--> BIZERR[[4xx 业务错误]]
-  // → services/resource_service.py 业务规则分支
-
-  %% === 响应阶段 ===
-  SVC --"->"--> RESP[[组装响应 DTO]]
-  RESP --"->"--> OUT[[返回 JSON / 页面]]
-  // → handlers/resource.py::to_response
-
-  %% === 归档 ===
-  OUT --"::archives"--> LOG[[结构化日志]]
-  // → observability/logger.py
-
-  %% === 顶层链接 ===
-  IN --"加载"--> MAIN_DOC[>00_main.md]
-```