@xulthekl/team-flow 0.68.0 → 0.69.0

package/.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# team-flow v0.68.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.69.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "team-flow",
       "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback + independent business analysis. 28 skills + 17 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.68.0",
+      "version": "0.69.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact) + design-system (design tokens + component contract + AI primer + showcase) + test-strategy (test strategy design) + project-initialize (new service onboarding) + jarvis (team-flow decision agent, opt-in). 28 skills + 17 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

package/.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.68.0"
+    "version": "0.69.0"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "team-flow",
   "displayName": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact) + jarvis (team-flow decision agent, opt-in). 28 skills + 17 agents, one install.",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "author": {
     "name": "LT",
     "url": "https://github.com/LT"

package/.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugins and skills for AI coding agents (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.68.0"
+    "version": "0.69.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, independent business analysis, and local HTML prototyping.",
-      "version": "0.68.0",
+      "version": "0.69.0",
       "source": ".",
       "author": {
         "name": "LT",

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.69.0] - 2026-09-30
+
+### Added（mermaid 语法快速验证：最小闭环——脚本 + 双 reviewer 接入 + 仓库回归；来源 = LT 实测 PRD mermaid 渲染失败）
+
+**验证脚本（唯一实现）**
+- 新增 `scripts/validate-mermaid.mjs`：提取 md 中全部 ```mermaid fence → `mermaid.parse()` 逐个校验（jsdom 提供 DOM，单图 <20ms）。四态契约与 `tf prd check-clarity` 同构 + 用法错误参照其 exit 2 惯例：`STATUS: PASS`（exit 0）/ `FAIL`（exit 1，stdout 必带 `file:line`）/ `SKIP`（exit 0，**仅限**依赖不可用且安装失败——LT 裁定「先尝试安装、装败才降级」）/ `ERROR`（exit 2，用法错误：无参数/路径不存在/传入目录）。顶层异常兜底保证任何场景必有 STATUS 行。
+- **依赖策略**：`mermaid ^12.0.0` + `jsdom ^26.0.0` 入 `dependencies`（用户装插件即带上）；运行时缺依赖 → 先 `npm install`（限时 90s）→ 装败才 WARN 降级 SKIP。
+- **实现陷阱（脚本头注已记）**：Node 同进程内失败的 dynamic import 会缓存为失败（实测安装后重试无效）——必须先 `createRequire` 文件系统级 resolve 探测（不进 ESM 缓存），装完再 import。
+
+**Reviewer 接入（判级：语法错误 = 机械客观缺陷，Critical）**
+- `agents/prd-completeness-reviewer.md`：Phase 1 新增第 3 步 mermaid 机械校验（FAIL=Critical 挂 D6 名下；SKIP=依赖降级不判级；ERROR/无 STATUS=环境错误不判级、不造 Critical）；Phase 2 步骤 3-8 顺延 4-9；6 维清单 D6 行补 (c) mermaid 归属；FAIL 判据扩展；报告模板增 `Mermaid check` Metadata + D6-(c) 占位；「回 Phase 1.3」歧义改写为「回 ce-brainstorm Phase 1.3/Phase 3」。
+- `agents/architecture-reviewer.md`：Phase 1 新增第 4 步 mermaid 机械校验（A1 名下，Critical；路径基于 Inputs 的 `${architecture_dir}`/`${product_snapshot_path}` 拼接，防相对 cwd 假 Critical；domains/ 用 `--dir` 单独跑）；Phase 2 步骤 4-6 顺延 5-7；A1 维度行与报告 Metadata 同步。
+
+**测试（`npm test` 1419 → 1437）**
+- 新增 `tests/lib/validate-mermaid.test.mjs`（18 测试）：fence 提取（含未闭合/非 mermaid fence 不误提）/ ensureDeps 降级路径注入（禁装/装败/装成三态）/ 正负例对照（坏图必须 FAIL、好图必须 PASS）/ CLI 四态 exit code / **skills/ 全量目录扫描回归**（存量 5 fence 基线，新增 fence 文件自动纳管，非硬编码清单）。
+- 评审：plugin-validator PASS（0C+3W）、skill-reviewer PASS_WITH_WARNINGS（0C+3M+7m），全部发现已修复后收口。
+
 ## [0.68.0] - 2026-09-30
 
 ### Added（security-baseline 企业安全基线集成：四层全量落地；设计 = 工作区 `docs/plan/security-baseline-integration-design.md` v1.3 + P3 修正，P1.5 完整档三轮闭合 0 Critical）

package/GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- team-flow-phase-guard-start -->
-# team-flow v0.68.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.69.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.68.0**。
+当前发布版本：**v0.69.0**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.68.0`
+> 当前版本：`v0.69.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，十三套能力协同（详见下文「十三套能力」）。
 

package/agents/architecture-reviewer.md

@@ -50,7 +50,7 @@ If change_brief_path or architecture_dir is missing or unreadable **in change mo
 
 | Dim | Name | Baseline Source | Check Content | Severity |
 |-----|------|----------------|---------------|----------|
-| A1 | 产出完整性 | architecture-design 结构化输出 | `architecture.md` / `database.md` / `api.md` 文件存在且非空 | Critical |
+| A1 | 产出完整性 | architecture-design 结构化输出 | `architecture.md` / `database.md` / `api.md` 文件存在且非空 + 内含 mermaid fence 语法可 parse（Phase 1 第 4 步机械校验） | Critical |
 | A2 | SQL 制品完整性 | `database.md` 中引用的 SQL 路径 | `sql/ddl/*.sql` / `sql/migration/*.sql` 文件存在且语法可检查 | Critical |
 | A3 | 模板合规性 | `architecture-design/templates/` | 产出文件结构与模板一致（YAML frontmatter + 必要章节） | Important |
 | A4 | 需求覆盖 | change-brief + plan | 每个业务需求 → 对应的架构设计覆盖（聚合/BC/API/DB） | Critical |
@@ -84,11 +84,21 @@ Mechanical verification, no LLM semantic judgment needed:
      - api.md → templates/api.md (sections: Command, Read, Query, frontmatter api_contract_manager)
    - Missing required section = Important finding
 
+4. **Mermaid 图语法机械校验（v0.69.0，A1 名下）**:
+   - `node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-mermaid.mjs <文件列表>`（**路径基于 Inputs 传入的目录参数拼接，不是相对 cwd 的字面路径**——传错路径脚本会 `STATUS: ERROR` exit 2，将产生假 Critical/假评审失败）:
+     - change 模式：`${architecture_dir}/architecture.md ${architecture_dir}/database.md ${architecture_dir}/api.md`（三件套逐文件显式传入；**不要**把目录本身传给脚本）
+     - product 模式：`${product_snapshot_path}` 单文件；`domains/` 下多个 .md 用 `--dir <domains目录>` **单独再跑一次**
+     - 脚本自带依赖自愈（缺则先装、装败降级，安装最多阻塞约 90s——依赖装入插件包 node_modules，不触碰审查制品，不违反 Iron Law）
+   - 末行 `STATUS: FAIL`（exit 1）→ 每个 `file:line` 命中 = **Critical finding**（架构图含 mermaid（context map/时序/状态/ER），语法错误渲染必失败；附行号与 parse 错误）。**FAIL 但 stdout 无任何 `file:line` 命中 = 异常输出，按环境错误处理，不得凭空造 Critical。**
+   - 末行 `STATUS: SKIP` → 依赖降级（缺依赖且安装失败），不判级，报告 Metadata 记 `Mermaid check: SKIPPED（依赖不可用）`；不得因 SKIP 判 FAIL
+   - 末行 `STATUS: PASS` → 记 `Mermaid check: PASS (n fences)`
+   - 末行 `STATUS: ERROR`（exit 2，用法错误：路径不对/传了目录）**或无 STATUS 行**（脚本不存在/崩溃）→ **环境错误，不判级**：Metadata 记 `Mermaid check: ERROR (<原因>)`，会话输出通道向派发方提一行（如 `${CLAUDE_PLUGIN_ROOT} 未解析`）；不得记为 SKIPPED，不得判 FAIL
+
 ### Phase 2: Deep-check (LLM Semantic Comparison, A4/A5/A6)
 
 Dimensions requiring semantic understanding, marked as "advisory, false positives can be overridden":
 
-4. **A4 需求覆盖** (v0.29.0 §37 增强：双对照源 + 子实体 CRUD 检查):
+5. **A4 需求覆盖** (v0.29.0 §37 增强：双对照源 + 子实体 CRUD 检查):
    - **对照源 1（现有）**：Read change-brief.md → extract all requirement items (scope, AC, technical direction)
    - **对照源 2（v0.29.0 新增）**：Read `requirement/vN/prd.md` → extract feature list (e.g., F001_P0_P1 ~ P0_PN)
    - Read plan.md → extract relevant technical design sections
@@ -107,7 +117,7 @@ Dimensions requiring semantic understanding, marked as "advisory, false positive
    - Uncovered requirement = Critical finding
    - Build coverage matrix table (MUST include columns for both brief source AND PRD source)
 
-5. **A5 基线一致性**:
+6. **A5 基线一致性**:
    - Read global `ARCHITECTURE.md` → check naming conventions, BC boundaries
    - Read global `PHYSICAL-MODEL.md` → check table naming patterns, field conventions
    - Read global `API-INDEX.md` → check API routing patterns
@@ -118,7 +128,7 @@ Dimensions requiring semantic understanding, marked as "advisory, false positive
      - API endpoint conflicts with API-INDEX → Critical
      - BC boundary contradictions → Critical
 
-6. **A6 conventions 合规**:
+7. **A6 conventions 合规**:
    - Read `team-flow.config.json` → `conventions` section
    - Load applicable convention files:
      - `conventions.database` → check DB naming rules, primary key strategy, audit fields
@@ -156,6 +166,7 @@ Aggregate all findings and determine verdict.
 - **Change Brief**: {change_brief_path}
 - **Architecture Dir**: {architecture_dir}
 - **Global Arch Dir**: {global_arch_dir}
+- **Mermaid check**: {PASS (n fences) | FAIL (n errors) | SKIPPED（依赖不可用） | ERROR (&lt;原因&gt;)}
 - **Review round**: {N}
 - **Reviewer**: architecture-reviewer agent (independent)
 - **Timestamp**: {ISO 8601}

package/agents/prd-completeness-reviewer.md

@@ -41,7 +41,7 @@ If `prd_path` is missing or unreadable, report `FAIL` with reason `INPUT_ERROR`.
 | D3 | 边界与非功能 | 空/错/异常状态、性能/兼容约束 | Important |
 | D4 | 术语一致性 | 与 CONCEPTS.md / §6 业务术语一致 | Minor |
 | D5 | 范围闭环 | in/out scope 明确，无悬空功能 | Important |
-| D6 | §8.4 信息齐备性与业务可读形态 | **（a）信息齐备性**：逐功能模块核对业务信息是否**可定位**（不核对"正文里有没有该维度标题"）；§7↔§8.4 交叉核对无悬空功能。**（b）形态核验（v0.62.0 G7）**：按 6 条判据核验产出形态是否符合规范（见下方 D6 执行细则）。**基准 = `prd-84-authoring-spec.md`（唯一权威，不是模板 §8.4）** | Critical（核心信息缺失 / 悬空功能）/ Important（辅助信息缺失、**形态核验命中**） |
+| D6 | §8.4 信息齐备性与业务可读形态 | **（a）信息齐备性**：逐功能模块核对业务信息是否**可定位**（不核对"正文里有没有该维度标题"）；§7↔§8.4 交叉核对无悬空功能。**（b）形态核验（v0.62.0 G7）**：按 6 条判据核验产出形态是否符合规范（见下方 D6 执行细则）。**（c）mermaid fence 语法机械校验（Phase 1 第 3 步）**：parse 失败 = Critical。**基准 = `prd-84-authoring-spec.md`（唯一权威，不是模板 §8.4）** | Critical（核心信息缺失 / 悬空功能 / mermaid 语法错误）/ Important（辅助信息缺失、**形态核验命中**） |
 
 ## Review Process
 
@@ -49,33 +49,38 @@ If `prd_path` is missing or unreadable, report `FAIL` with reason `INPUT_ERROR`.
 
 1. Read the PRD fully. Locate the functional requirement sections (用户故事 / 功能清单 / 系统功能), acceptance criteria, scope (in/out), and glossary (§6 业务术语).
 2. Use `grep` to enumerate requirement items and check for the presence of AC markers / actor markers / scope markers — this grounds the per-item review.
+3. **Mermaid 语法机械校验（v0.69.0）**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-mermaid.mjs <prd_path>`（脚本自带依赖自愈：缺则先装、装败降级，安装最多阻塞约 90s——依赖装入插件包 node_modules，不触碰任何评审制品，不违反 Iron Law）。
+   - 末行 `STATUS: FAIL`（exit 1）→ 每个 `file:line` 命中记 **Critical**（D6 名下，描述注明「mermaid 语法错误，渲染必失败」，附行号与 parse 错误）——语法失败是机械判定的客观缺陷，非语义裁量，无误报面。**FAIL 但 stdout 无任何 `file:line` 命中 = 异常输出，按下方环境错误处理，不得凭空造 Critical。**
+   - 末行 `STATUS: SKIP` → 依赖降级（缺依赖且安装失败），**不判级**，在报告 Metadata 记 `Mermaid check: SKIPPED（依赖不可用）`；不得因 SKIP 判 FAIL。
+   - 末行 `STATUS: PASS` → 记 `Mermaid check: PASS (n fences)`，无 finding。
+   - 末行 `STATUS: ERROR`（exit 2，用法错误：路径不对/传了目录）**或无 STATUS 行**（脚本不存在/崩溃）→ **环境错误，不判级**：Metadata 记 `Mermaid check: ERROR (<原因>)`，同时在会话输出通道向派发方提一行（如 `${CLAUDE_PLUGIN_ROOT} 未解析`）；不得记为 SKIPPED（依赖问题），不得判 FAIL。
 
 ### Phase 2: Per-Dimension Deep Check（LLM 语义判断）
 
-3. **D1 用户故事完整性**（Critical）：For each functional requirement, check it has:
+4. **D1 用户故事完整性**（Critical）：For each functional requirement, check it has:
    - **actors**（谁触发/谁参与）— explicit or unambiguously inferable
    - **流程**（关键步骤/交互路径）
    - **结果**（完成态/输出/系统响应）
    Missing any of the three for a requirement = Critical finding (cite §X.X + requirement id).
 
-4. **D2 验收标准**（Critical）：For each functional requirement, check there is at least one **verifiable** acceptance criterion or success signal (testable condition, observable outcome, measurable threshold).
+5. **D2 验收标准**（Critical）：For each functional requirement, check there is at least one **verifiable** acceptance criterion or success signal (testable condition, observable outcome, measurable threshold).
    - AC present but vague/unverifiable ("系统应表现良好") = Critical.
    - AC entirely missing = Critical.
 
-5. **D3 边界与非功能**（Important）：Check whether the PRD addresses:
+6. **D3 边界与非功能**（Important）：Check whether the PRD addresses:
    - 边界状态：空态 / 错误态 / 异常 / 并发 / 极值
    - 非功能约束：性能 / 兼容性 / 安全 / 可用性（where relevant to the product）
    Missing edge-state coverage for a core flow, or no non-functional constraints where they clearly matter = Important.
 
-6. **D4 术语一致性**（Minor）：Compare terms used in the PRD against CONCEPTS.md (if provided) and the PRD's own §6 业务术语. Same concept named differently, or undefined jargon used = Minor.
+7. **D4 术语一致性**（Minor）：Compare terms used in the PRD against CONCEPTS.md (if provided) and the PRD's own §6 业务术语. Same concept named differently, or undefined jargon used = Minor.
 
-7. **D5 范围闭环**（Important）：
+8. **D5 范围闭环**（Important）：
    - in scope and out scope explicitly declared?
    - Any "悬空功能" — a feature mentioned in scope but with no actors/AC/implementation path (dangling)?
    - Any out-of-scope item that other requirements implicitly depend on?
    Missing scope declaration or dangling feature = Important.
 
-8. **D6 §8.4 信息齐备性与业务可读形态**：Read the **spec file** FIRST — `spec_path`
+9. **D6 §8.4 信息齐备性与业务可读形态**：Read the **spec file** FIRST — `spec_path`
    （默认 `${CLAUDE_PLUGIN_ROOT}/skills/ce-brainstorm/references/prd-84-authoring-spec.md`）
    is the **single authority**——never judge against your own expectations,
    and never against the template skeleton（模板只承载骨架与槽位）.
@@ -123,9 +128,9 @@ Aggregate findings → final verdict per the Judgment Criteria.
 |---------|-----------|--------|
 | **PASS** | Critical=0 且 Important=0 | 可进入冻结 / 下游 plan |
 | **PASS_WITH_WARNINGS** | Critical=0 且 Important>0 | 警告项交人工裁定，不阻断 |
-| **FAIL** | Critical>0 | 必须回 Phase 1.3/Phase 3 补充后重新评审 |
+| **FAIL** | Critical>0 | 必须回 ce-brainstorm Phase 1.3（澄清）/ Phase 3（撰写）补充后重新评审——注意是 ce-brainstorm 的阶段号，非本 agent 的 Phase 编号 |
 
-**FAIL 仅由 Critical 触发**（D1/D2 缺失；D6 核心维度缺失、D6 悬空功能）。Important（D3/D5/D6 辅助维度）误报不触发 FAIL。Minor（D4/D6 可读性）仅记录。
+**FAIL 仅由 Critical 触发**（D1/D2 缺失；D6 核心维度缺失、D6 悬空功能；D6 mermaid 语法错误——Phase 1 第 3 步机械判定）。Important（D3/D5/D6 辅助维度）误报不触发 FAIL。Minor（D4/D6 可读性）仅记录。
 
 ## Output Format
 
@@ -139,6 +144,7 @@ Aggregate findings → final verdict per the Judgment Criteria.
 ## Metadata
 - **PRD**: {prd_path}
 - **CONCEPTS**: {concepts_path or "N/A"}
+- **Mermaid check**: {PASS (n fences) | FAIL (n errors) | SKIPPED（依赖不可用） | ERROR (&lt;原因&gt;)}
 - **Review round**: {N}
 - **Reviewer**: prd-completeness-reviewer agent (independent)
 - **Timestamp**: {ISO 8601}
@@ -184,6 +190,9 @@ Aggregate findings → final verdict per the Judgment Criteria.
 | 6 维度清单未写入正文 | {是/否} | {Important/—} | |
 [逐功能模块检查：功能形态 | 适用维度覆盖 | NA 标注 | 悬空功能 | 状态]
 
+#### D6-(c) Mermaid 语法机械校验（Phase 1 第 3 步）
+{PASS (n fences) | FAIL (n errors，逐条 file:line + parse 错误) | SKIPPED（依赖不可用） | ERROR (&lt;原因&gt;)}
+
 ## Findings
 | # | Dim | Severity | PRD Source | Requirement | Description | Suggestion |
 |---|-----|----------|-----------|-------------|-------------|------------|

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.68.0`
+- Current: `v0.69.0`
 - v0.9.1 highlights: DP-4 execution-mode recommendations, a portable runtime across 17 platforms, and a raw-package smoke with no plugin-root variable.
 - Self-contained — no OpenSpec or Superpowers runtime required
 - Upstream: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), [obra/superpowers](https://github.com/obra/superpowers)

package/docs/team-flow /344/275/277/347/224/250/350/257/264/346/230/216/357/274/210/347/240/224/345/217/221/345/233/242/351/230/237/347/211/210/357/274/211.md"

@@ -1,6 +1,6 @@
 # team-flow 使用说明（研发团队版）
 
-> 版本锚点：v0.68.0（28 skills + 17 agents）· 更新日期：2026-09-21
+> 版本锚点：v0.69.0（28 skills + 17 agents）· 更新日期：2026-09-21
 > 读者：使用 team-flow 做日常研发的工程师。不需要你懂插件内部实现，只需要照着路径走。
 > 配套文档：安装细节见 [INSTALL.md](../INSTALL.md)；状态机细节见 [state-machine.md](state-machine.md)；决策点细节见 [decision-points.md](decision-points.md)；平台差异见 [platform-matrix.md](platform-matrix.md)。
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML) + business-analysis (independent requirement/scenario artifact) + jarvis (team-flow decision agent, opt-in). 28 skills, one install.",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.68.0: auto-sync CLI version with plugin version
+# v0.69.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.68.0"
+PLUGIN_VERSION="0.69.0"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.68.0.
+Current version: v0.69.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Unified plugin (28 skills + 17 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback, business-analysis for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -50,5 +50,9 @@
   "devDependencies": {
     "js-yaml": "^5.2.3",
     "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "mermaid": "^12.0.0",
+    "jsdom": "^26.0.0"
   }
 }

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact) + design-system (design tokens + component contract + AI primer + showcase) + test-strategy (test strategy design) + project-initialize (new service onboarding) + jarvis (team-flow decision agent, opt-in). 28 skills + 17 agents, one install.",
   "author": {
     "name": "LT"

package/scripts/validate-mermaid.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+// scripts/validate-mermaid.mjs — Markdown 内 ```mermaid 围栏语法快速验证
+//
+// 背景（2026-09-30，LT 提出）：实际用 team-flow 产 PRD 时 mermaid 语法错误导致无法渲染。
+// 仓库此前无任何 mermaid 校验（lint 6 规则 / validate-artifacts / 模板测试均只查存在性正则）。
+//
+// 用法：
+//   node scripts/validate-mermaid.mjs <file.md> [more.md ...]
+//   node scripts/validate-mermaid.mjs --dir <dir>          # 递归扫描目录下全部 .md
+//
+// 输出约定（与 `tf prd check-clarity` 同构 + 用法错误参照其 exit 2 惯例）：
+//   逐 fence 报告 `file:line: <错误>`；末行 `STATUS: PASS | FAIL | SKIP | ERROR`。
+//   PASS   → exit 0（全部 fence 可 parse，或无 fence）；
+//   FAIL   → exit 1（语法错误，stdout 必带 file:line 命中——调用方按行号记 finding）；
+//   SKIP   → exit 0（**仅限**依赖不可用且安装失败——按 LT 裁定降级不阻断，显眼告警）；
+//   ERROR  → exit 2（**调用方用法错误**：无参数 / 路径不存在 / 传入目录 / 脚本自身异常——
+//            不是依赖问题，调用方应报环境错误，不得记为 SKIP 依赖降级）。
+//
+// 依赖策略（LT 2026-09-30 裁定）：
+//   1. mermaid + jsdom 声明在 package.json dependencies（用户装插件即带上）；
+//   2. 运行时缺依赖 → 先尝试 `npm install`（限时）→ 成功则继续；
+//   3. 安装仍失败 → WARN 降级：`STATUS: SKIP` + exit 0，不阻断主流程。
+//
+// 实现要点：
+//   - **先 createRequire resolve 再 import**：Node 同进程内失败的 dynamic import 会被
+//     缓存为失败（实测 ERR_MODULE_NOT_FOUND 重试无效），所以绝不能"先 import 失败再装再
+//     import"——必须用文件系统级 resolve 探测（不进 ESM 缓存），装完后 import 必成功。
+//   - jsdom 提供最小 DOM（mermaid.parse 需要 document/window），实测单图 parse <20ms。
+//   - parse 错误信息含 mermaid 内部行号（相对 fence），输出时换算为 md 文件绝对行号。
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, resolve, dirname, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+const require = createRequire(import.meta.url);
+const INSTALL_TIMEOUT_MS = 90_000;
+
+/**
+ * 提取 md 文本中全部 ```mermaid 围栏。
+ * 返回 [{ startLine (fence 行, 1-based), content, contentStartLine }]。
+ * 不支持嵌套 fence（mermaid 内容本身不含 ```），标准围栏配对即可。
+ */
+export function extractMermaidFences(text) {
+  const lines = text.split(/\r?\n/);
+  const fences = [];
+  let cur = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!cur && /^\s*```mermaid\s*$/.test(line)) {
+      cur = { startLine: i + 1, buf: [], contentStartLine: i + 2 };
+    } else if (cur && /^\s*```\s*$/.test(line)) {
+      fences.push({ startLine: cur.startLine, contentStartLine: cur.contentStartLine, content: cur.buf.join('\n') });
+      cur = null;
+    } else if (cur) {
+      cur.buf.push(line);
+    }
+  }
+  if (cur) {
+    // 未闭合 fence：也算一个待校验项（mermaid.parse 会因缺尾部语法报错，或直接标 ERROR）
+    fences.push({ startLine: cur.startLine, contentStartLine: cur.contentStartLine, content: cur.buf.join('\n'), unclosed: true });
+  }
+  return fences;
+}
+
+/**
+ * 依赖探测 + 按需安装。返回 { ok: true } 或 { ok: false, reason }。
+ * 用 resolve 而非 import 做探测（见文件头注：失败 import 会污染同进程 ESM 缓存）。
+ */
+export function ensureDeps({ allowInstall = true, timeoutMs = INSTALL_TIMEOUT_MS, installer = defaultInstall, resolvelike = defaultResolve } = {}) {
+  if (resolvelike()) return { ok: true };
+  if (!allowInstall) return { ok: false, reason: 'mermaid/jsdom 未安装（安装被禁用）' };
+
+  process.stderr.write('[validate-mermaid] mermaid/jsdom 缺失，尝试安装...\n');
+  const r = installer(timeoutMs);
+  if (r.error || r.status !== 0) {
+    const why = r.error ? r.error.message : `npm exit ${r.status}: ${(r.stderr || '').trim().split('\n').slice(-3).join(' | ')}`;
+    return { ok: false, reason: `依赖安装失败：${why}` };
+  }
+  return resolvelike()
+    ? { ok: true }
+    : { ok: false, reason: 'npm install 完成但依赖仍不可 resolve' };
+}
+
+/** 默认依赖探测：文件系统级 resolve（不进 ESM import 缓存——见文件头注）。 */
+function defaultResolve() {
+  try {
+    require.resolve('mermaid');
+    require.resolve('jsdom');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 默认安装器：在插件包根执行 npm install。 */
+function defaultInstall(timeoutMs) {
+  return spawnSync('npm', ['install', '--no-audit', '--no-fund', '--loglevel=error'], {
+    cwd: PKG_ROOT,
+    timeout: timeoutMs,
+    encoding: 'utf8',
+  });
+}
+
+/** 初始化 mermaid 解析运行时（jsdom DOM + mermaid.initialize）。仅在 ensureDeps ok 后调用。导出供测试复用——进程内 parse 必须先有 DOM，否则恒报错（假绿风险）。 */
+export async function initRuntime() {
+  const { JSDOM } = await import('jsdom');
+  const dom = new JSDOM('<!DOCTYPE html><body></body>', { pretendToBeVisual: true });
+  if (!globalThis.window) globalThis.window = dom.window;
+  if (!globalThis.document) globalThis.document = dom.window.document;
+  try {
+    Object.defineProperty(globalThis, 'navigator', { value: dom.window.navigator, configurable: true });
+  } catch { /* Node >=21 navigator 只读，已有值则忽略 */ }
+  const mermaid = (await import('mermaid')).default;
+  mermaid.initialize({ startOnLoad: false, securityLevel: 'loose' });
+  return mermaid;
+}
+
+/** 把 mermaid parse 错误信息里的相对行号换算为 md 绝对行号。 */
+function reline(msg, contentStartLine) {
+  const m = /on line (\d+)/.exec(msg);
+  if (!m) return contentStartLine;
+  return contentStartLine + (parseInt(m[1], 10) - 1);
+}
+
+/**
+ * 校验单个 md 文件。返回 { file, fenceCount, errors: [{ line, message }], skipped? }。
+ * deps.ok=false 时返回 skipped 态（不读文件不 parse）。
+ */
+export async function validateFile(mdPath, mermaid) {
+  const text = readFileSync(mdPath, 'utf8');
+  const fences = extractMermaidFences(text);
+  const errors = [];
+  for (const f of fences) {
+    if (!f.content.trim()) {
+      if (f.unclosed) errors.push({ line: f.startLine, message: 'mermaid fence 未闭合' });
+      else errors.push({ line: f.startLine, message: 'mermaid fence 为空' });
+      continue;
+    }
+    try {
+      await mermaid.parse(f.content);
+    } catch (e) {
+      const raw = String(e?.message || e).split('\n').filter(Boolean)[0] || 'parse error';
+      errors.push({ line: reline(raw, f.contentStartLine), message: raw, mermaidLine: (/on line (\d+)/.exec(raw)?.[1]) });
+    }
+    if (f.unclosed) errors.push({ line: f.startLine, message: 'mermaid fence 未闭合' });
+  }
+  return { file: mdPath, fenceCount: fences.length, errors };
+}
+
+function collectMdFiles(dir, out = []) {
+  for (const name of readdirSync(dir)) {
+    if (name === 'node_modules' || name.startsWith('.')) continue;
+    const p = join(dir, name);
+    const st = statSync(p);
+    if (st.isDirectory()) collectMdFiles(p, out);
+    else if (name.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const files = [];
+  // 用法错误统一 STATUS: ERROR + exit 2（区别于 SKIP=依赖降级 exit 0——
+  // 混用会让调用方把"路径没传对"误记成"依赖不可用"，门检查不到）
+  const usageError = (msg) => {
+    console.error(msg);
+    console.error('Usage: node scripts/validate-mermaid.mjs <file.md> [...] | --dir <dir>');
+    console.log('STATUS: ERROR');
+    process.exit(2);
+  };
+  if (args.length === 0) usageError('no arguments');
+  if (args[0] === '--dir') {
+    if (!args[1]) usageError('--dir requires a path');
+    if (!existsSync(args[1])) usageError(`dir not found: ${args[1]}`);
+    if (!statSync(args[1]).isDirectory()) usageError(`not a directory: ${args[1]}`);
+    files.push(...collectMdFiles(resolve(args[1])));
+  } else {
+    for (const a of args) {
+      if (!existsSync(a)) usageError(`file not found: ${a}`);
+      if (statSync(a).isDirectory()) usageError(`is a directory (use --dir): ${a}`);
+      files.push(resolve(a));
+    }
+  }
+
+  // 1) 依赖：缺则先装，装不上才降级（LT 裁定）
+  const deps = ensureDeps();
+  if (!deps.ok) {
+    process.stderr.write(`⚠️  [validate-mermaid] ${deps.reason} —— mermaid 校验跳过（WARN 降级，不阻断）\n`);
+    console.log('STATUS: SKIP');
+    process.exit(0);
+  }
+
+  // 2) 运行时（此时尚未 import mermaid/jsdom，ESM 缓存干净）
+  let mermaid;
+  try {
+    mermaid = await initRuntime();
+  } catch (e) {
+    process.stderr.write(`⚠️  [validate-mermaid] 运行时初始化失败：${String(e?.message || e)} —— mermaid 校验跳过\n`);
+    console.log('STATUS: SKIP');
+    process.exit(0);
+  }
+
+  // 3) 逐文件校验（0-fence 文件不逐行打印，防目录扫描刷屏；汇总行给出计数）
+  let fenceTotal = 0;
+  let errorTotal = 0;
+  let filesWithFences = 0;
+  for (const f of files) {
+    const r = await validateFile(f, mermaid);
+    fenceTotal += r.fenceCount;
+    if (r.fenceCount === 0 && r.errors.length === 0) continue;
+    filesWithFences++;
+    const rel = relative(process.cwd(), r.file) || r.file;
+    if (r.errors.length === 0) {
+      console.log(`  ✅ ${rel} (${r.fenceCount} fence)`);
+    } else {
+      errorTotal += r.errors.length;
+      for (const err of r.errors) console.log(`  ❌ ${rel}:${err.line}: ${err.message}`);
+    }
+  }
+  if (filesWithFences === 0) console.log('  (no mermaid fences found)');
+  console.log(`fences: ${fenceTotal} | errors: ${errorTotal} | files: ${files.length} (${filesWithFences} with fences)`);
+  console.log(`STATUS: ${errorTotal > 0 ? 'FAIL' : 'PASS'}`);
+  process.exit(errorTotal > 0 ? 1 : 0);
+}
+
+// 直接执行时跑 main；被 import（测试）时不跑。
+// 顶层兜底：任何未捕获异常也必须输出 STATUS 行——否则调用方（agent）连
+// "出错"都感知不到，只会看到无 STATUS 的裸异常输出（评审 skill-reviewer M3）。
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((e) => {
+    console.error(`unexpected error: ${String(e?.stack || e)}`);
+    console.log('STATUS: ERROR');
+    process.exit(2);
+  });
+}