spec-wave 2.1.1

package/assets/graph/templates/01_struct.md

@@ -0,0 +1,38 @@
+# 模块边界登记表（L0-b · D4-a 人签真值）
+
+> **用途**：`docs/_tech_graph/01_struct.md` — **一级模块** 边界；**HG-GRAPH-MODULES** approved 后方可 **30 执行改码**。  
+> **不是**：全仓 flow 一次画完；flow 按 task **增量** 维护。  
+> **嵌入后**：删除示例行，填真实模块；维护者人签后更新 task 内 `HG-GRAPH-MODULES` → `approved`。
+
+## 模块表（必填）
+
+| module_id | 名称 | 路径 glob | 依赖方向（仅指向谁） | 负责人/备注 |
+|-----------|------|-----------|----------------------|-------------|
+| `core` | 核心业务 | `src/core/**` 或 `app/**` | → `infra` | 示例 · **替换** |
+| `api` | HTTP / RPC 入口 | `src/api/**` 或 `routes/**` | → `core` | 示例 · **替换** |
+| `infra` | DB / 缓存 / 外部 SDK | `src/infra/**` | —（被依赖） | 示例 · **替换** |
+| `_TODO_` | （待填） | `（glob）` | → | 新增行 |
+
+### 填写规则
+
+1. **module_id**：小写 snake_case；全仓唯一。
+2. **路径 glob**：能覆盖该模块源码根； monorepo 按 **子包** 分行。
+3. **依赖方向**：只写 **出边**（本模块允许 import / 调用谁）；禁止循环 unless 文档化。
+4. **一级模块**：通常 3～12 行；更细粒度放 Wiki 或子 task，不膨胀本表。
+
+## 跨模块契约（可选）
+
+| 契约 | 提供方 module_id | 消费方 | 说明 |
+|------|------------------|--------|------|
+| `（例：UserDTO）` | `core` | `api` | 共享类型 / OpenAPI schema |
+
+## 人签记录（嵌入后填写）
+
+| human_gate_id | status | 签核人 | 日期 | 说明 |
+|---------------|--------|--------|------|------|
+| HG-GRAPH-MODULES | pending | | | `01_struct` 模块表覆盖一级模块 |
+
+## 关联
+
+- 顶层图：[`00_main.md`](./00_main.md) · [`00_main.ai.md`](./00_main.ai.md)
+- 主 flow 示例：[`10_flow_MAIN.md`](./10_flow_MAIN.md)

package/assets/graph/templates/02_version.md

@@ -0,0 +1,7 @@
+# 图谱版本时间线
+
+| 日期 | 版本 | 事件 |
+|------|------|------|
+| YYYY-MM-DD | v0.1 | 首次嵌入用户仓（请替换为真实日期） |
+| 2026-06-30 | v0.2 | 模板包迁移至 YAML-first：`00_main.graph.yaml`、`10_flow_MAIN.graph.yaml` 成为唯一编辑源；`.ai.md` 双轨文件弃用并删除；旧包脚本编译/校验流程上线 |
+| 2026-08-24 | v1.2.4 | DEF-006：编译/校验命令面迁移至本包 `npx spec-wave graph yaml compile|export|check`；生成物 md 以本包编译器重生成 |

package/assets/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/assets/graph/templates/10_flow_MAIN.md

@@ -0,0 +1,103 @@
+---
+graph_id: 10_flow_MAIN
+version: 2026-06-30
+generated_at: sha256-eb7519dfb81b42a1
+source: 10_flow_MAIN.graph.yaml
+---
+
+# 主路径 Flow 示例
+
+典型 HTTP 请求从入口到响应的主干流程
+
+## Mermaid
+
+```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
+    %% → middleware/auth.py::require_user
+    AUTH -->|"[ok]"| VAL
+    AUTH -->|"[err]"| ERR_AUTH
+    %% → middleware/auth.py#L42
+    VAL -->|"[ok]"| SVC
+    %% → services/resource_service.py::handle
+    VAL -->|"[err]"| ERR_VAL
+    SVC --> REPO
+    %% → repositories/resource_repo.py::find_by_id
+    REPO --> DB
+    %% → db/session.py
+    REPO -->|"?>"| HIT
+    HIT -->|"[no]"| NOTFOUND
+    HIT -->|"[yes]"| SVC
+    SVC -->|"[err]"| BIZERR
+    %% → services/resource_service.py
+    SVC --> RESP
+    RESP --> OUT
+    %% → handlers/resource.py::to_response
+    OUT -->|"::archives"| LOG
+    %% → observability/logger.py
+    IN -->|"加载"| MAIN_DOC
+
+    classDef phase fill:#e1f5fe,stroke:#01579b,stroke-width:2px
+    classDef doc fill:#fff8e1,stroke:#ff6f00,stroke-width:1px
+    classDef infra fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px
+    class MAIN_DOC doc
+    class AUTH infra
+```
+
+## Structured Data
+
+### Nodes
+
+| ID | Label | Kind |
+|----|-------|------|
+| 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
+
+| From | To | Mark | Type | Label | Anchors |
+|------|----|------|------|-------|---------|
+| IN | AUTH | -> | depends_on | -> | 1 anchor(s) |
+| AUTH | VAL | -> | depends_on | [ok] |  |
+| AUTH | ERR_AUTH | -> | depends_on | [err] | 1 anchor(s) |
+| VAL | SVC | -> | depends_on | [ok] | 1 anchor(s) |
+| VAL | ERR_VAL | -> | depends_on | [err] |  |
+| SVC | REPO | -> | depends_on | -> | 1 anchor(s) |
+| REPO | DB | -> | depends_on | -> | 1 anchor(s) |
+| REPO | HIT | ?> | condition | ?> |  |
+| HIT | NOTFOUND | -> | depends_on | [no] |  |
+| HIT | SVC | -> | depends_on | [yes] |  |
+| SVC | BIZERR | -> | depends_on | [err] | 1 anchor(s) |
+| SVC | RESP | -> | depends_on | -> |  |
+| RESP | OUT | -> | depends_on | -> | 1 anchor(s) |
+| OUT | LOG | ::archives | archives |  | 1 anchor(s) |
+| IN | MAIN_DOC | -> | depends_on | 加载 |  |

package/assets/graph/templates/99_mermaid_protocol.md

@@ -0,0 +1,156 @@
+# Mermaid 拓扑协议（通用 · v3）
+
+> **用途**：`docs/_tech_graph/99_mermaid_protocol.md` — flowchart 边标记、节点形状与 YAML-first 生成真值。
+
+## 0. YAML-first 工作流
+
+- **唯一人工编辑源**：`*.graph.yaml`（本目录下如 `00_main.graph.yaml`、`10_flow_MAIN.graph.yaml`）。
+- **生成物**：同名 `*.md` 由本包 CLI `npx spec-wave graph yaml compile`（`--graph-id ID` 或 `--all`）自动生成，包含 YAML frontmatter、Mermaid flowchart、Nodes/Edges 表。frontmatter / `graph.json` 的 `generated_at` 为 yaml 源内容戳 `sha256-<16hex>`（同字节重编译 / export 幂等），不是 wall-clock。
+- **禁止手写 `.md`**：如需改图，改 YAML 源后重新运行 `graph yaml compile`；手改生成物会被下次编译覆盖。
+- **一致性校验**：`graph yaml check` 比对的是 YAML 源与 `graph.json` 切片（按 graph_id 过滤节点/边），需先 `graph yaml export` 生成 `shared/graph.json`；本包不校验 `.md` 与 `.graph.yaml` 的同步（md 由编译单一来源生成，见 §7）。
+- **历史 `.ai.md` 双轨已弃用**：Post-G0 后不再维护 `.md` + `.ai.md` 两份文件；所有结构化信息（锚点、边类型）集中在 YAML 源中。
+
+---
+
+## 1. 边标记
+
+### 1.1 执行流
+
+| 标记 | 语义 | 何时用 |
+|------|------|--------|
+| `->` | 同步顺序执行 | 普通调用 |
+| `~>` | 异步 / await | 非阻塞 I/O |
+| `=>` | 赋值 / 映射 | 数据转换 |
+| `?>` | 条件分支 | if / switch / 路由 |
+
+### 1.2 状态与可靠性
+
+| 标记 | 语义 | 示例 |
+|------|------|------|
+| `[ok]` | 成功路径 | `validate() -->|"[ok]"| save()` |
+| `[err]` | 失败 / 异常 | `parse() -->|"[err]"| fallback()` |
+| `[retry=N]` | 重试 | `call_api() -->|"[retry=3]"| call_api()` |
+| `[timeout]` | 超时降级 | `fetch() -->|"[timeout]"| cache_get()` |
+
+> 示例采用官方边上文字形态 `A-->|text|B`（见 §7 输出契约）；旧形态 `--"[ok]"-->` 已弃用，IDE 预览不保证可渲染。
+
+### 1.3 元关系（`::` 命名空间）
+
+| 标记 | 语义 |
+|------|------|
+| `::yields` | 流式 / 生成器产出 |
+| `::triggers` | 触发子流程或后台任务 |
+| `::gates` | 门禁 / 鉴权 / 依赖注入 |
+| `::branches` | 并行分支 |
+| `::merges` | 多路归并 |
+| `::signoff` | 持久化确认 / 事务提交 |
+| `::archives` | 日志 / 审计归档 |
+
+---
+
+## 2. 节点形状（flowchart）
+
+| 形状 | 含义 | 示例 |
+|------|------|------|
+| `[["..."]]` | 阶段 / 流程块 | `Q[["Query Phase"]]` |
+| `["..."]` | 函数 / 操作（编译器默认，文本一律加引号） | `step["process_request"]` |
+| `[">..."]` | 文档指针（`>` 前缀保留在引号文本内） | `FLOW_DOC[">10_flow_MAIN.md"]` |
+| `[(...)]` | 数据 / 模型（手写图可用） | `db[(UserRecord)]` |
+| `{...}` | 判断 / 路由（手写图可用） | `gw{authorized?}` |
+| `((...))` | 循环 / 归档（手写图可用） | `log((write_log))` |
+
+---
+
+## 3. 锚点规则（YAML 源强制）
+
+每条 **硬边** 须可追溯到代码或文档，写在 YAML `edges[].anchors` 中：
+
+```yaml
+edges:
+  - from: "Q"
+    to: "E"
+    anchors:
+      - path: "src/main.py"
+        line: 1
+      - path: "app/router/index.ts"
+        symbol: "Router"
+```
+
+- 跨模块调用：使用 `::triggers` 或虚线，**不**展开对方内部。
+- 未知锚点：保留 `path: TBD` 并开 task 补全。
+
+---
+
+## 4. 分层与折叠
+
+| 条件 | 操作 |
+|------|------|
+| 子图节点 ≤ 7 | 可在主图展开 |
+| 子图节点 > 7 | 折叠为 `[[Phase]]`，链独立 `10_flow_*.md` |
+| 异常分支 | 挂侧链；Happy Path 走主干 |
+
+---
+
+## 5. 禁止项
+
+- **禁止**维护 `.ai.md` 双轨文件。
+- **禁止**在生成的 `.md` 中直接手写 flowchart（会被下次编译覆盖）。
+- 禁止虚构文件路径；未知处用 `path: TBD` 并开 task 补锚点。
+- **禁止** onboarding 默认「全仓扫描生图」。
+
+---
+
+## 6. YAML 字段到 Mermaid 映射
+
+| YAML 字段 | Mermaid 输出 | 说明 |
+|-----------|--------------|------|
+| `nodes[].id` | 节点 ID | 必须唯一 |
+| `nodes[].label` | 节点显示文本 | 决定节点形状 |
+| `edges[].from` / `to` | 边两端 | 必须引用存在的节点 |
+| `edges[].label` | 边标签 | `"->"` 表示裸执行边 |
+| `edges[].mark` | 元关系标记 | 如 `::triggers`、`::branches` |
+| `edges[].type` | 边类型 | 与 `mark` 命名空间对应 |
+| `edges[].anchors` | `%% → path[#Ln|::symbol]` 独立注释行；Edges 表 Anchors 列渲染为 `N anchor(s)` 摘要 | 代码追溯 |
+
+> 编译器 Edges 表列序固定为 `From | To | Mark | Type | Label | Anchors`（与 §7 输出契约同源）。
+
+---
+
+## 7. IDE 预览兼容 · 编译器输出契约
+
+> 语法真值（改编译器 emit 前必读，禁止凭记忆）：
+> 官网 [Diagram Syntax](https://mermaid.js.org/intro/syntax-reference.html)（注释只认 `%%`）·
+> [Flowchart](https://mermaid.js.org/syntax/flowchart.html)；
+> 本地对照 `mermaid/packages/mermaid/src/docs/syntax/flowchart.md`
+>（§ Links between nodes · § Text on links · § A link with arrow head and text · § Special characters that break syntax · § Comments）。
+
+`graph yaml compile` 生成物 **默认 emit 形态**（Cursor / IDE Markdown 预览与 mermaid-cli 均可渲染）：
+
+| 元素 | 默认输出 | 依据 |
+|------|----------|------|
+| 锚点注释 | `%% → path#Ln`（独立行） | flowchart.md § Comments：注释仅 `%%` 前缀 |
+| 带标签边 | `src -->|"label"| dst` | flowchart.md § A link with arrow head and text：`A-->|text|B` |
+| 裸边 | `src --> dst`（yaml `label: "->"` 或无 label） | flowchart.md § A link with arrow head |
+| 节点 | `id["label"]`（文本一律双引号包裹） | flowchart.md § Special characters that break syntax |
+| 子流程节点 | `id[["label"]]`（文本同样加引号） | 同上 |
+| label 转义 | `"` → `#quot;` · `|` → `#124;` · `#` → `#35;` | flowchart.md § Entity codes to escape characters |
+
+**禁止作为编译器默认输出**（IDE 预览会静默解析失败：节点横排一行、边丢失）：
+
+- `--"label"-->`（旧边形态，非官方推荐）
+- `//` 行注释（非 Mermaid 语法）
+- 含空格 / `()` / `/` / `+` / `>` 等字符却未加引号的节点标签
+
+**消费者升级指引**：升级 dsh-coding-kit 后须重跑 `graph yaml compile`（或 `graph yaml compile --all`）重新生成 `*.md`；手改生成物会被下次编译覆盖。
+
+---
+
+## 8. 修订记录
+
+| 日期 | 说明 |
+|------|------|
+| 2026-06-30 | v3：YAML-first，删除 `.ai.md` 双轨，新增 YAML → Mermaid 映射 |
+| 2026-08-24 | DEF-023：新增 §7 IDE 预览兼容输出契约；§1.2/§2 示例改官方 `-->|"…"|` 与引号节点形态；锚点注释改 `%%` |
+| 2026-08-24 | DEF-006：§0 编译器名改本包 `npx spec-wave graph yaml compile`；`check` 语义如实改写为 YAML↔graph.json 切片比对（需先 `export`）；§6 补 Edges 表列序与锚点摘要化说明 |
+| 2026-08-28 | §0：`generated_at` 改为 yaml 源内容戳（幂等），不是 wall-clock |
+| YYYY-MM-DD | 嵌入用户仓时填写首次版本 |

package/assets/graph/templates/README.md

@@ -0,0 +1,66 @@
+# graph/templates
+
+复制到用户仓 **`docs/_tech_graph/`**。
+
+## v0.2 已交付模板（T2 · YAML-first）
+
+| 文件 | 状态 | 说明 |
+|------|------|------|
+| [`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** 人签真值） |
+| [`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 硬门槛）
+
+| 文件 | 说明 |
+|------|------|
+| `02_version.md` | 版本时间线；新仓建议嵌入后首周补 |
+
+## 编辑与复制流程
+
+1. **改图**：只改 `.graph.yaml`，不要手写 `.md`。
+2. **编译**（业务仓根，本包作为依赖安装后）：
+   ```bash
+   npx spec-wave graph yaml compile --all --input docs/_tech_graph
+   ```
+3. **校验**（两步：先 `export` 生成 `shared/graph.json`，再 `check` 做 YAML ↔ graph.json 切片比对）：
+   ```bash
+   npx spec-wave graph yaml export --input docs/_tech_graph
+   npx spec-wave graph yaml check --all --input docs/_tech_graph
+   ```
+4. **复制到业务仓**（模板源在本包 assets 内）：
+   ```bash
+   mkdir -p docs/_tech_graph
+   cp -R node_modules/spec-wave/assets/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（见薄指针页 [`POINTER_ONBOARDING.md`](../../docs/POINTER_ONBOARDING.md) · 原文 §3）
+- **存量**：按 ONBOARDING 档位 S0～S3；**禁止**首次全 flow 构图
+- **人签**：`01_struct` 模块表 → **HG-GRAPH-MODULES** approved → 允许 30 改码
+
+## 本包 dogfood
+
+kit **源码仓**自图在 `docs/_tech_graph/`（L0 `00_main` · L1 `01_struct` · L2 四条 `10_flow_*`）；CI 为 `.github/workflows/tech-graph.yml`（本仓 bin compile/check）。
+**`docs/` 不随 npm 包发布**；请到源码仓查看：https://github.com/Cyning12/SpecGate/tree/main/docs/_tech_graph
+
+## 历史说明
+
+- v0.1 使用 `.md` + `.ai.md` 双轨；v0.2 起改为 YAML-first，`.ai.md` 已弃用。
+- 复杂业务仓应采用 `.graph.yaml` 源 + manifest/contract CI；本模板包（dsh-coding-kit）维持简化编译流。
+- v1.2.4（DEF-006）：编译/校验命令面迁移至本包 `npx spec-wave graph yaml compile|export|check`；`00_main.md`/`10_flow_MAIN.md` 以本包编译器重生成（输出契约见 `99_mermaid_protocol.md` §7）。

package/assets/harness/README.md

@@ -0,0 +1,18 @@
+# harness · 过程轨
+
+| 子目录 | 内容 | T3 状态 |
+|--------|------|---------|
+| [`templates/`](templates/) | task、Epic、graph_bootstrap | ✅ v0.1 |
+| [`prompts/`](prompts/) | 10/22/30 Starter 子集 | ✅ v0.1 |
+| [`invokes/`](invokes/) | invoke 落盘约定 + TEMPLATE | ✅ v0.1 |
+
+用户仓对应路径建议：`docs/tasks/`、`docs/harness/prompts/`、`docs/harness/invokes/`。
+
+## 嵌入一键清单
+
+```bash
+mkdir -p docs/tasks/active docs/harness/prompts docs/harness/invokes/by-task docs/harness/reviews
+cp -R harness/templates/* docs/tasks/   # 或按需单文件复制并重命名
+cp harness/prompts/*.md docs/harness/prompts/
+cp harness/invokes/TEMPLATE_invoke.md docs/harness/invokes/
+```