@cyning/harness 2.0.3 → 2.1.0

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/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/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/ontology.yaml

@@ -2,8 +2,8 @@
 # 人类真值：docs/methodology/product/DESIGN_ONTOLOGY_v1_zh.md
 # 冲突时以 Markdown 为准 · 供未来 harness ontology-check 使用
 
-version: "1.2"
-product_semver: "2.0.0"
+version: "1.3"
+product_semver: "2.0.4"
 license: MIT
 
 classes:
@@ -64,24 +64,44 @@ axioms:
     text: "禁止 sync 覆盖 docs/tasks、reviews、invokes/by-task"
   - id: S5
     text: "harness-sync apply 前须 git-clean（可 --force 跳过）"
+  - id: D1
+    text: "每次 20-task-audit 必须产出 AuditReview（零阻塞须写明）"
   - id: D2
-    text: "HG-AUDIT-R1 pending 时 22 不得附 30 Prompt"
+    text: "HG-AUDIT-R1 pending 时 20-task-audit 不得附 30 Prompt（别名 22-task-audit）"
   - id: D7
     text: "public push 须 HG-RELEASE 人闸 checklist 全勾"
 
+# V2 hat_id · Starter 闭包 + Extended POINTER（见 DESIGN_ONTOLOGY §3.2）
 starter_hats:
-  - hat_id: "10-requirements"
-    role: RequirementsHat
-  - hat_id: "22-task-audit"
+  - hat_id: "10-task"
+    role: TaskRequirementsHat
+    alias: "10-requirements"
+  - hat_id: "20-task-audit"
     role: TaskAuditHat
+    alias: "22-task-audit"
   - hat_id: "30-execute-code"
     role: ExecuteHat
   - hat_id: "40-self-check"
     role: SelfCheckHat
 
+extended_hats:
+  - hat_id: "10-spec"
+    role: SpecRequirementsHat
+    pointer: "工作区 docs/harness/prompts/10-spec-requirements.md"
+  - hat_id: "20-spec-audit"
+    role: SpecAuditHat
+    pointer: "工作区 docs/harness/prompts/20-spec-audit.md"
+  - hat_id: "00-orchestrator"
+    role: OrchestratorHat
+  - hat_id: "50-independent-reinspect"
+    role: ReinspectHat
+
 human_gates:
   - id: HG-TASK-DRAFT
-    blocks_hats: ["22-task-audit", "30-execute-code"]
+    blocks_hats: ["20-task-audit", "30-execute-code"]
+  - id: HG-SPEC-SIGNOFF
+    blocks_hats: ["30-execute-code"]
+    note: "Epic 级 · SPEC approved 后 00 方可派实现链至 30"
   - id: HG-AUDIT-R1
     blocks_hats: ["30-execute-code"]
   - id: HG-RELEASE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyning/harness",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "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/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 引导实录抽象 |