@xulthekl/team-flow 0.53.0 → 0.55.0

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

@@ -1,3 +1,3 @@
-# team-flow v0.53.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.55.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. 26 skills + 17 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.53.0",
+      "version": "0.55.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-flow",
-  "version": "0.53.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). 26 skills + 17 agents, one install.",
+  "version": "0.55.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). 26 skills + 17 agents, one install.",
   "source": "./",
   "author": {
     "name": "LT",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.53.0",
+  "version": "0.55.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.53.0"
+    "version": "0.55.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). 26 skills + 17 agents, one install.",
-  "version": "0.53.0",
+  "version": "0.55.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.53.0"
+    "version": "0.55.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.53.0",
+      "version": "0.55.0",
       "source": ".",
       "author": {
         "name": "LT",

package/CHANGELOG.md

@@ -4,6 +4,139 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.55.0] - 2026-09-11
+
+### Added（首次真实使用反馈处置：棕地机制 + 解析层加固）
+
+设计来源：`docs/plan/design-system-prototype-enhancement-design.md` v1.8-r3（第八章；三轮对抗验证闭合表见附录 A.5/A.6/A.7）。输入 = **v0.54.0 设计系统能力的首次真实使用**（`fytx-agreement` 项目，4 条 workflow-feedback）+ 4 路并行核查（插件仓库 3 路事实核查 + 使用现场 1 路证据勘查）；P1.5 **完整档（3 轮）** 收敛：问题数 29 → 21 → 0 Critical。
+
+**根因（3 个，非 4 条反馈的简单加总）**：**A** 插件内置资产与项目既有资产之间无「探测 → 替代」机制（首次使用正落在被推迟到 v2 的那一侧）；**B** 静态副本冒充真相源（showcase brief 的写死清单 vs 动态契约表）；**C** 手写 Markdown 解析层无统一容错约定与测试守护（**复发型**——同型 bug 已修过两次且均未横展）。
+
+- **解析层共享层**（根因 C 的收口）：新增 `scripts/lib/md-normalize.mjs`——**全仓库唯一的 Markdown 容错约定**（`stripEmphasis` / `stripInlineEmphasis` / `normalizeInline` / `matchKeyValue` / `parseTaskLine`），含 CRLF 容错；`scripts/lib/ds-inputs.mjs`——输入解析下沉（`resolveInputs` / `REQUIRED_SECTIONS` / `readFileOrNull` 等），使 `gen-primer` 能复用 guard 的变体发现而**不必 import 顶层副作用模块**。
+- **`create-from-docs` 模式**（根因 A）：`token-extract.mjs --docs` 扫描 Markdown 规范树，出**证据报告 + 冲突呈现**（不做取值裁决——真实规范树列序不固定，按频次排序会选出错的主色）；`SKILL.md` Step 0 增该入口。
+- **`clone --from` 移植**（根因 A，LT 需求"同类后台复用"）：`scripts/design-system-clone.mjs` 把 `cp -r` 会留的 **4 个坑**自动化——来源记录改写（保留原裁决历史）/ primer 强制重生成 / 业务组件清单输出 / 授权提示。
+- **`--profile antd` 通用起点**（D-21）：`design-system-import.mjs` 新增 profile 分支（AntD v5 seed token，MIT）——零 LLM、零外部资产、零授权链风险。
+- **`layout` 段扩展承载页面范式**（根因 A）：新增 `### 页面范式` 子块（`页面范式来源：引用内置 | 项目自有 | 同 <端>` 三值 + 页面类型表）与 `### 容器骨架` 块（类名 + 关键 CSS）——**后者的动机**：内置 `template.html` 的骨架是营销向的 `hero/cta/log`，**无 B 端容器类**，不给物料则 builder 每页要手写整套骨架 CSS。
+- **`来源与裁决记录` 段**（导入类创建条件必填，审计层 advisory）：记录原始来源 / 导入方式 / "为何不直接采纳" / 主色裁决 / 待清理项——把现场手工映射时趟出的高质量做法**固化为流程**。
+- **消费端改造**（根因 A 的真正闭环）：`builder-methodology.md` 改为**以 primer 的「页面范式」段为准**（内置 `layouts.md` 降为回退默认）、验收口径改"结构性区块齐全 + token 合规 + 零白名单外自造"；`layouts.md` 类清单契约加注；`prototype/SKILL.md` 同步。
+- **showcase brief 引用化**（根因 B）：两个 board 的「区块与组件」与「覆盖清单」两段由**写死组件名**改为**角色化描述 + 从契约表选**（静态副本 vs 动态事实必然漂移，实测已漂移：19/16 类 vs 现 31 类）。
+- **配置漂移检查**：`scripts/check-project-config.mjs`——检查配置指向是否存在、`version` 是否与插件一致（现场实测三类漂移**全部静默**）；检查面按"实际被消费"分级，零消费者键只提示。
+- **三种新模式的文档**：`skills/design-system/references/creation-modes.md`（渐进式披露，避免 SKILL.md 过载）。
+
+### Changed（行为变更，存量项目升级须知）
+
+> **本节是升级必读**：以下变更会改变既有产物的判定或触发一次性失效。
+
+- **guard L3/L4 语义重写**：L3 由"关键词匹配（**实为空检测**——判据对 `markdown + primer.md` 匹配，而 primer 里 gen-primer 硬编码的 `## 页面范式` 段必然命中，恒通过）"改为**基于 `layout` 段结构化声明的解析**；L4 拆 a/b（布局基础 / 页面范式内容）并**收紧判据**（原裸子串 `/sm|md|lg/` 被 `.md` 路径文本保证命中）。**检测面改为"设计系统源文本，按端分别求值"**（不再读 primer——消除自证；不用合并文本——`sectionBodyRaw` 用 `findIndex` 只取首个 `## layout`，`both` 端下 c-end 声明永不解析）。
+- **三态标签贯穿全渲染链**：`layerResults` 值域 `true | false | 'warn'`；`'warn'` 用于"新增可选内容缺失"**绕过 `labelOf` 恒输出 ⚠️**（现场 `contract: v1` 系统缺声明若走原机制会打 ❌，与 D-15 冲突）；汇总行与 `--json` 同步（原只改明细行会**同一次运行出现相反标签**）。
+- **单文件模式变体发现告警**：原实现 `ignored` 计算在 `!subjectComplete` 分支内 → 单文件模式（转换器产物）整块跳过，同目录变体**静默不参与判据**。现无论合并与否都告警。
+- **`gen-primer` digest 覆盖 base + 参与合并的变体**：原先只对 base.md 做 sha256 → **变体变更不判 STALE** → prototype Step 0 gate 放行 → 原型静默用旧页面范式。**升级影响**：存量 primer 会判一次 STALE（exit 2），需重跑生成。
+- **导入类产物的 `contract` 由 `v1` 改 `legacy`**（D-18）：导入的既有资产天然未经校准，按最严档判会一落盘即 blocked（死循环）。**门禁面影响**：模板库/转换器路径从"blocked 强制"降为"WARN 放行"——这是有意的。
+- **复选框 5 处统一到共享原语**：`hash`（**替换式**，语义保持）/ `guard.tasks-complete` / `glaf4-delegation` / `execution-recommendation` / `infer-workflow`。**档位影响**（约束③ 对照表，已固化为可执行断言）：`[X]` 大写 / 缩进子项 / `*` bullet / `-\t` 分隔 在旧实现下**全部漏计** → 新实现计入。两个具体后果：单条 `* [x] A` **full → hotfix**（旧实现零计数落到"无规划制品 → full"安全默认）；4 条大写 `[X]` 为主 **hotfix → tweak**。
+- **`hash.normalizeCheckboxes` 的归一化面扩大**：`* [x] A` / `-\t[x] A` 现在也被归一化 → **存量 change 的 `artifacts_hash` 会过期一次**。
+- **`hooks/session-start` 版本比较改"只升不降"**：原 `if [ "$installed_version" != "$PLUGIN_VERSION" ]` 只判"不等"不判"谁新谁旧" → **任何一个旧版插件缓存副本跑起来都会把新版 CLI 降级**（实测 `tf` 被从 0.54.0 降到 0.51.0）。
+- **多源路径改显式报错**（`token-extract.mjs`）：原实现取 `positional[0]`、**静默丢弃**其余源路径——多仓场景下用户以为处理了全部。现收到 ≥2 个即 exit 1 并列出全部路径。**源路径是位置参数（不存在 `--source` flag）**，文档中的旧写法已同步修正。
+- **`design-system-clone` 的 primer 自检改参与退出码**：`gen-primer --check` 紧随"刚重生成"之后运行，两者不一致 = **生成器自相矛盾**（而非用户输入问题）。原实现只打印不决定退出码 → 脚本报成功，而产物对 `contract: v1` 系统实为 blocked（prototype Step 0 会拒绝），问题被推迟到使用现场才暴露。现失败即 exit 1 并提示上报。
+
+### Fixed（解析层，根因 C）
+
+- **`parseContract` / `parseA1Tokens` 对 Markdown 强调语法脆弱且失败静默**（FB-4）：`- **contract**: v1` 与 `` `contract`: v1 `` 都解析不出值，被判 `unset` → guard 降级、primer 头部错报，**全程无提示**。现容忍加粗 / 反引号 / 全角冒号 / 冒号前空格 / 表格五种形态，并在"段存在 + 提到 contract + 解析不出"时**显式 WARN**。
+- **`parseComponentsTable` 整行静默漏计**：`| **交互** |`（类型列被加粗）无法匹配类型表 → 该组件行被 `continue` 丢弃。现表格单元格统一归一化。
+- **`parseContract` 值域过窄**：原只认 `v1|legacy`，未来 `v2` 会静默降级。现接受 `v\d+`，**未知值按最严档（等同 v1）+ WARN**。
+- **`custom-prop` 把 `rgba(0, 0, 0, 0.05)` 拆成碎片**：多值拆分逻辑（为 `padding: 8px 16px` 设计）对含括号/逗号的值产生 `rgba(0` / `0.05)` 假证据。现含 `(),` 的值视为单值。
+- **`token-extract` 产物自吞**：`--docs` 模式下产物原落 `join(root, …)`，而 root 恰是被扫描树 → 二次运行自吞（实测 ×1 → ×3）。现落调用方工作目录 + `.team-flow` 入 `SKIP_DIRS`。
+- **转换器 id 取目录名**：内置模板库（`templates/.../references/linear-app.md`）会得到无意义的 `references`，写进来源段后无法辨认。现文件名优先（非约定名 `DESIGN.md` 时）。
+- **横展 13 处**：`spec-merge` / `arch-parse`（**删除本地重复实现**，双实现归零）/ `arch-merge` / `prototype-sync` / `solutions-promote` / `sdd-overlay` / `state-loader` / `hash.extractYamlField`。其中 `prototype-sync` 的加粗标题原会**静默丢段**。
+- **TS 侧解析层漏修**（P4 code-review 发现后补修，**本插件两条解析实现分属两种语言、两个测试通道**）：`src/parsing/requirement-blocks.ts` 是 JS 侧之外的**另一条实现**，编译到 `dist/`，而 `tf sync` 走的正是它（`spec-merge.mjs` → `import('../../dist/index.js')` → `parseDeltaSpec`）——**JS 侧修复覆盖不到**。实测 `### **Requirement**: X` / `` ### `Requirement`: X `` / 全角冒号 / 冒号前空格**四种全部解析出 0 条**，且不报错不告警（delta spec 静默不合并，`spec_merged` 保持 false 但不说明原因）。现同源归一化（键名两侧符号**任意交错**：`` **`Requirement`** `` 亦可）；同时删除 `src/validation/validator.ts` 中**同契约的第二处 `REQUIREMENT_HEADER_REGEX` 定义**（定义后从未被使用，属"同一契约多处定义"的结构性维护陷阱）；新增 `tests/lib/ts-parsing-tolerance.test.mjs`（19）——含**端到端闭环**（宽松形态 delta 经真实 `tf sync` 合并进主基，再由 `extractRequirementsSection` 读回）与**单一真相源护栏**（src 下不得出现第二处需求头正则定义）。
+
+### Tests
+
+`1088 tests / 1088 pass / 0 fail`（基线 942）。新增 **8 个测试文件**：`md-normalize`（29）、`ds-parse`（59）、`checkbox-consistency`（12，**约束③ 的可执行形态**——走真实生产 API + 差异白名单）、`design-system-import`（5，该模块此前**全仓零测试**）、`design-system-clone`（6）、`prototype-sync`（6，此前零命中）、`spec-merge-tolerance`（6）、`ts-parsing-tolerance`（19，**TS 侧独立通道**——`tf sync` 走 `dist/` 编译产物，JS 侧测试覆盖不到；见 Fixed 末条）。既有 `design-token-guard`（+7，L3/L4 新语义）与 `hook-session-start`（+4，"只升不降"回归）同步更新。
+
+### Known Deviations（记录在案）
+
+| # | 设计原文 | 实施结果 | 理由 |
+|---|---------|---------|------|
+| 1 | §8.4.3 约束② 要求"缺字段一律 WARN + 关键字段清单 + 走 stderr + `tf state get` 冒烟断言" | **仅实现"缺字段不报错"，WARN 未落地** | 实测部分写法 37 处（20 文件），落地后刷 stderr 有触碰既有 CLI 断言的实测风险；建议单独立项 |
+| 2 | §8.2.1 "修多值或显式报错" | 选**显式报错** | 不改变既有单值语义；多仓可用多次调用 |
+| 3 | §8.4.3 `parseContract` 值域 `[a-z0-9_]+` | 实施为 `/^(v\d+\|legacy)$/i` | 更收敛：`contract: bogus` 返回 null 并由 guard 按最严档 + WARN，与意图一致 |
+| 4 | §8.2.5 L4a "键形态 或 断点值形态" | 增**第三种：表格形态** | 现场用 `\| \`sm\` \| \`≥ 768px\` \|` 声明断点，只认前两种会把它判成"缺断点"（P1.5 三轮预警的假阴性，实施期实测确认） |
+| 5 | §8.2.1 输出"三类候选" | 增 `doc-table-ctx` 与 `VALUE_LIKE_RE` 值形态过滤 | 不加则把说明文字（"不变"/"悬停态"）当成 token 值——实测 185 条噪音冲突，过滤后 16 条且质量高（现场 6 组跨期主色矛盾完整呈现） |
+| 6 | —（设计未提） | 新增 `references/creation-modes.md` | SKILL.md 渐进式披露：**六条起点**的完整流程 + §5「B 端容器骨架为何必须给」外置，主体回收至 145 行（≤150 规则） |
+| 7 | §8.2.2 `parsePageArchetype` 表行数 | 表头抵扣**只作用于子块内首个表** | 约定形态是单表；多表会虚高（已在测试中以特征化断言登记，非背书） |
+| 8 | §8.2.6 "prototype 内部 dispatch 增加 mode 传达" | 改为**传达事实而非 mode**：prototype 侧说"缺设计系统" + scout 简报中的**资产事实**（如"已有符合规范的原型代码"），起点由 design-system 的 Step 0 **无条件展示 7 条**（这才是可达性的保证）；并补"目录已存在但不完整 → 走 iterate 不走 Step 0"分支。**P4 同步校正**：`design-system/SKILL.md` 的"入口同步"声明原写"三处，缺一则新模式不可达"——实为**两处声明 + 一处事实传达**，且 `orchestration-flow.md §①b` 此前完全未提（声明为假），现已落地 | 采用哪条起点取决于**用户的资产状况**（是否有可移植的同类设计系统 / 既有规范文档），**prototype 无从判断**——预选反而让能力不可达（与 D-23"能力存在但用户不知道 = 能力不存在"相悖） |
+
+## [0.54.0] - 2026-09-10
+
+### Added（设计系统 → 原型贯通：组件契约 + Primer + Showcase + 逆向建库）
+
+设计来源：`docs/plan/design-system-prototype-enhancement-design.md` v1.7（2026-09-10；P4 偏差记录见其附录 A.4）。输入 = open-design 迁移管线研究 + 设计系统核对工具 L0-L5 方法论 + LT 三项补充需求（持续迭代 / 逆向建库 / Design Showcase）；本方案按 **P1.5 完整档（3 轮对抗式验证 + 逐轮闭合表）** 收敛：问题数 39→9→6，Critical 4→2→0。
+
+**核心承诺**：设计系统从「token 定义文档」升级为「**能约束 AI 生成原型的契约体系**」——正向白名单（primer，prompt 层劝告）+ 反向拦截（guard / P0 grep，代码层）双层防护。
+
+- **组件契约表（L2 结构化）**：base.md 的 components 段由散文升级为表格（组件 × 类型 × variants × sizes × states × 用途 × 禁止）；**类型列决定 states 下限**（交互 ≥3 / 轻量 ≥2 / 豁免）；数量三档阈值（<10 FAIL 标签 / 10-14 WARN 可用 / ≥15 PASS）；`contract: v1|legacy` 标记区分存量（legacy 降级 WARN，不阻断）。
+- **AI Primer（L5 补齐）**：新增 `scripts/gen-primer.mjs`——确定性生成 `.team-flow/design-system/primer.md`（零 LLM、纯字符串拼接）+ digest 头部；`--check` 模式供 builder Step 0 gate 校验新鲜度（exit 0 一致 / exit 2 STALE）；内容 = 组件白名单 + Token 速查 + 硬规则。配「生成物 == 源表」单测。
+- **六层审计 guard**：新增 `scripts/guard/design-token-guard.mjs`——硬校验（exit 1）+ 六层审计报告（恒 exit 0，不输出总分，`--strict` 存量当 v1 标签 / `--json`）；配套 `scripts/lib/ds-parse.mjs` 共享解析器（guard / gen-primer / import 三方复用，消除同契约多实现漂移）。
+- **Design Showcase**：新增展示板机制——**草案阶段**产出 1-3 页 Board（让用户在确认设计系统前先看到实际效果，解决「确认后才见效果」的时序倒置）；内置车企场景 brief（`showcase-board-{b,c}-end.md`，虚构品牌「星驰汽车」：B 端线索管理后台 6 区块 / C 端官网 + 车主 APP）；`prototype-builder` 新增 `mode: showcase`（gate 豁免 `confirmed_plan`/`prd_path`，flat 单文件最小交付契约）。
+- **持续迭代（不新增第二账本）**：原型阶段的组件 / token 增量经 builder 既有 `outstanding_questions` 通道回传（`ds_increment` 字段），在原型人工评审 ⑥ 由用户确认（全部 / 逐项 / 暂不处理）；"暂不处理"入 `.team-flow/design-system/pending.md`——**单写者 = design-system skill**（主代理 / release-archivist 只读）；两级确认节点（⑥ 即时 + change closing 兜底），不新造流程。
+- **逆向建库**：新增 `scripts/token-extract.mjs`（8 类正则证据机器 + ΔE<2 颜色聚类 + 频次排序 + directory skiplist + `--report` 只读报告）；新增 `scripts/design-system-import.mjs`（open-design DESIGN.md → team-flow base.md：A 类九节解析 + B 类兜底提取）；design-system skill 新增 create-from-code 模式（**确定性提取 + 人工策展**，语义角色由人定，不自动推断落盘）。
+- **L0 / L1 补齐**：base.md 新增 `principles` 段（≥3 条，guard 计数）+ `governance` 段（contract / version / 负责人 / 弃用策略）；`token-derivation.md` 新增**确定性 dark 派生规则** + `creation-flow.md` 新增维度 6（theme 输入）。
+- **open-design 资源内置（精选）**：新增 `templates/design-systems/`——`registry.json`（8 个 B 端相关参考：linear-app / stripe / vercel / supabase / sentry / posthog / notion / claude）+ `styles.json`（57 风格种子，扩充 mood → palette 映射）+ `references/*.md`（160KB 原文，MIT 归因 "inspired by"）。**全量扫描 143 个的真实分布**：A 类 63（44%）/ B 类 80（55%），B 类总体积 ~1.3MB → 精选内置而非全量（体积 + 相关性双重考量），未内置的按 registry 指引用 import 现取。
+- **首次接入提示**：`workflow-bootstrap` 新增 **B4.6**（advisory，不阻断）——检测项目无设计系统时 AskUserQuestion 四选一（模板库 / 逆向建库 / 从零创建 / 跳过）。
+- **流程制度化（父仓库 CLAUDE.md）**：新增 **P1.5 方案对抗验证**（可选，三档强度：轻量 1 轮 / 标准 2 轮 / 完整 3 轮；P1 完成后必须询问用户是否执行，可跳过）——本次方案本身即按完整档执行并借此收敛。
+
+### Changed（行为变更）
+
+| # | 变更 | 影响面 |
+|---|------|--------|
+| 1 | `prototype-builder` Step 0 新增 primer gate | `governance.contract: v1` 且 primer 缺失/过期 → **blocked**；legacy / 无标记 → WARN 放行（存量项目不受阻） |
+| 2 | design-system 创建流程新增六层审计 + 组件数量三档标签 | 创建完成时 guard 恒输出审计报告；组件 <10 类标 FAIL 标签（不阻断落盘，供用户判断） |
+| 3 | release-archivist closing 新增 **⑥ 设计系统待办检查** | 只读检查 pending.md → closing summary 新增 `design_system_pending` 字段（报告契约扩展，不执行 iterate） |
+| 4 | `workflow-bootstrap` 新增 B4.6 | advisory 步骤，不阻断；Output Standard 阶段清单同步 B4.6 |
+
+### P4 复验（双门禁独立复验：均 PASS）
+
+- **plugin-validator 复验 → PASS**：Major 闭合（指定 grep 空集 + 更宽 grep 交叉印证 + import 提示实测为绝对路径 + 新 lint 非空转）。release-archivist 的**描述性写法成立**（约束真实——`platform-runtime-distribution.test.mjs:38` 对 9 个 runtime skill 断言禁宿主变量；两处无解释器前缀、无调用动词，仓库内既有同写法先例）。**横展发现 3 处存量同类真调用点**：`build-executor/SKILL.md:150` 与 `references/execution-modes.md:46` 的 `` `scripts/task-brief PLAN_FILE N` ``、`code-reviewer/SKILL.md:87` 的 `` `scripts/review-package` ``——实测从用户项目 CWD 执行报 `No such file or directory`（脚本真实存在，文档写法解析不到）。**与本次修的那批不同**：属 runtime skill（禁 `${CLAUDE_PLUGIN_ROOT}`），唯一可行修法是**暴露为 `tf` 子命令**——已登记 **P1-69**（含证据链与替代解评估），不在本次范围内实施。
+- **skill-reviewer 复验 → 可转 PASS**：C1 闭合（新探针：base + 端变体传目录 / 传 base.md **均 PASS**，原 `EXIT=1` 的互斥论据失效）；6 Major 全闭合；8 Minor 中 6 闭合、2 项经复核**由评审方主动撤回**（release-archivist 描述性写法、⑥ 与 reference 的分层重复）；另有 2 项本轮改动引入的新观察，**已在 P5 前闭合**：
+  - **观察 A（合并断言掩盖单端残缺）**：`target=both` 时若 c-end 只有 typography，合并跑仍 PASS。修法（零代码）：Step 6 增加「**按端各跑一次**（`--variant b-end` / `--variant c-end`）」并在 SKILL.md / creation-flow 双处写明——`--variant c-end` 单跑报 3 项 FAIL（已固化为测试判据）。
+  - **观察 B（无关 md 可补齐缺失段）**：同目录 `notes.md` 含 `## spacing` 等段即可把 FAIL 洗成 PASS。修法：变体识别**收紧为约定集**（`*-end.md` + `variants/` 子目录），非约定命名用 `--variant <name>` 显式纳入（逃生通道）；含必选段但未被纳入的 md **显式告警**列出（不静默补齐、也不静默忽略）。3 例测试固化。
+- **lint 盲区加固**：`skill-path-convention.test.mjs` 正则补 `node ./scripts/x`（显式相对前缀）与 `node --flag scripts/x`（解释器带参数）两种形态 + 各自正向控制——正是上一轮 grep 漏检的同款盲区（当前语料零实例，属预防性加固）。
+- **前瞻风险记录**：三个 skill 目前依赖 `${CLAUDE_PLUGIN_ROOT}` 且不在 `RUNTIME_SKILLS` 名单（测试绿）；但 **design-system 由 prototype 运行期调用**——若平台策略将其收进 runtime 名单，guard / primer / importer 的调用方式需整体改造。已记入设计文档附录 A.4 第 7 行与 `design-token-guard.mjs` 头部注释。
+- **复验期间的一次外部操作已独立核实无污染**：plugin-validator 披露其误在仓库根执行 `install-zcode --local .` 并已自行清理；我已核实 `.zcode/` 恢复为原 3 个受跟踪文件、无未跟踪残留、全仓 `git status` 仅含本次变更。
+
+### Fixed（P5 提交期发现）
+
+- **内置参考库第 8 个文件被 `.gitignore` 静默吞掉**：`templates/design-systems/references/claude.md` 与 `.gitignore:9` 的 `CLAUDE.md` 规则同名，macOS 大小写不敏感文件系统上被判为忽略 → **registry.json 声明 8 个参考、git 只跟踪 7 个**（npm 包因读磁盘仍含 8 个，两边不一致；且 `git add -A` 永远不会收录它）。修法：`.gitignore` 加显式**例外规则**并注明原因；验证 `git ls-files templates/design-systems/references/` = 8。**该缺陷形态值得留意（本轮复盘的通用教训）**：整个 P3/P4 的门禁（含本轮新加的两条 lint）都在查「文件引用是否存在」，**没有一条检查「文件是否真的会被提交」**——而 `.gitignore` / 打包白名单这类「可见性」问题恰好在所有既有门禁的盲区里（它们只看磁盘，不看索引）。本轮的发现路径也很典型：**不是任何检查报出来的，是 `npm version` 自带的 `git add -A` 让暂存清单与预期不符才暴露的**。
+
+### Tests
+
+- 新增 4 个测试文件：`design-token-guard.test.mjs`(23) + `gen-primer.test.mjs`(9) + `token-extract.test.mjs`(7) + `skill-path-convention.test.mjs`(3)，合计 **42 个新用例**
+- 全量 **935/935 通过**（原 893）；`npm run check-versions` 全绿
+- **P4 双评审闭环**：plugin-validator（1 Major + 8 Warning，全处置）+ skill-reviewer（1 Critical + 6 Major + 8 Minor，全处置）
+
+### Fixed（P4 门禁发现：skill-reviewer 一轮，含 1 Critical）
+
+- **【Critical C1】guard 的「单文件 9 段」模型与文档的「base + 端变体」拆分布局互斥**——`variant-schema.md` 明确 base 品牌层**不含** typography/spacing/layout/motion（随端变化，由端变体承载），而 guard 只接单个 md 且断言全 9 段 → **任何按文档创建的系统在 Step 6 落盘时被硬校验判 FAIL / exit 1**，返工死锁（P4 实证：合规拆分布局 exit=1 且 4 项 MISSING；而转换器产出的单文件 9 段版本 PASS——测试 fixture 站在工具侧，形成假保障）。**修法（补强代码）**：guard 输入解析支持**目录 / base.md / 变体文件**三种形态，主体不完整时自动合并端变体（`--variant <name>` 可限定；主体已含全 9 段则单文件模式，不卷入同目录无关 md）；合并按 base 优先、组件表按名去重（端差异行不重复计数）；无可合并变体时输出诊断提示。**证据**：`tests/lib/design-token-guard.test.mjs` 新增 6 例（拆分布局 base+变体过校验、目录输入、`--variant` 无匹配回退、单文件模式、L3 检测面、去重）。
+- **M1 L3 业务模式层对合规系统恒为假红灯**：检测面只读传入的 md，而唯一写「页面范式」的是 `gen-primer.mjs` 生成的 **primer.md**（L3 不读）→ 任何按规范创建的系统恒 ❌。修法：检测面 = 合并后文本 + 同目录 `primer.md`，并在报告中说明「设计系统侧只引用，节奏表在 prototype layouts.md」的归属。
+- **M2 模板库起点是死路**：`workflow-bootstrap` B4.6 的模板库分支**直接调转换器**、不经 design-system skill → 产出 `contract: v1` 但**无 primer** → prototype Step 0 稳定 `blocked`，且链路上三份文件都没提「还要生成 primer」。修法：B4.6 模板库分支改为**委托 `/team-flow:design-system`**（由该 skill 呈现 registry 并续跑 Step 5 评审 → Step 6 落盘，含 primer + guard）；SKILL.md Step 0 同步写明；转换器保持纯确定性转换（不自动生成 primer——避免用户人工核对配色后 primer 立即过期），输出提示改为**本脚本所在插件目录的绝对路径**且列出完整下一步链。
+- **M3 `variant-schema.md` 迭代口径自相矛盾**：「新组件进变体 `components`」与同文件「契约表全量真源在 base / 变体不再重复清单」直接冲突——按前者操作会破坏本版要建立的「消除双份维护」。已改为「新组件进 base 契约表，端特有点写变体覆盖说明」。
+- **M4 prototype 侧旧单文件路径残留 5 处 + description 越界**：`prototype/SKILL.md` 的 description 宣告了本属 design-system 的「创建/维护」职责（两个 skill 争夺触发）且引用 v0.19.0 起已废弃的 `design-system.md`；正文 5 处（用途/产出结构树/硬原则/内核/膨胀防控）同源残留。已统一为 `.team-flow/design-system/`（base + 端变体），产出结构树删除旧文件行并加注存放位置；横展同批修复 `prototype-env-scout.md`（3 处）、`builder-methodology.md`、`craft/anti-ai-slop.md`、`template.html` 与 scaffold `design-tokens.css` 的渲染说明。
+- **M5 `orchestration-flow.md` 派发输入契约未同步**：builder 派发清单仍写 `design-system.md` 且缺 `design_system_path`/`variant`/`prototype_root`/`mode`——而 `builder-methodology.md` 要求读 `<variant>.md`，该 `<variant>` **无来源**。已按 v0.54.0 契约补齐（含 showcase 模式豁免说明）；env-scout 探查项同步升级（合并后 9 段完整度 / primer 新鲜度 / 契约表分档）。
+- **M6 确定性数值在两份文档间冲突**（spacious 字号 18 vs 17 / `--space-4` 固定 16 vs 密度 12-16-20 / 字体栈两版 / `--focus-ring` 与 `--elev-raised` 几何有无）：收敛为**单一真相源** `token-derivation.md`（数值权威）——density 改为明确倍率语义（×0.75 / ×1.0 / ×1.25 作用于 4px 基准阶梯，`--space-4` = 12/16/20）；字体栈取更完整的系统栈（含 `Segoe UI`，与 `design-system-import.mjs` 一致）；A2 几何与 `template.html` / `preview-template.html` 对齐；dark 主题 `--accent` 提亮改为**有界确定性**（对比度 <4.5:1 时按 10% 步长至多 3 次取首个达标值，仍不足则记入 `extensions` 交人工，不静默继续）。`creation-flow.md` 顶部加权威指向。
+- 杂项（skill-reviewer Minor）：`showcase-board-c-end.md` 覆盖数「合计 18 类」错 → **本板 16 类 + 两板合计覆盖 20 类基线全量**（原注释把 b-end 已覆盖的 4 类误列为除外）；`variant-schema.md` 目录树补 `primer.md`/`pending.md`/`showcase/`，并写明**交互/轻量的 variants 亦必填**（guard 会判违规）；`design-system-architect.md` 删除写死的年份注记、段落标题 `design-system.md` → `base.md`。
+- **平台分发策略遵守**：release-archivist 属 **runtime skill**（9 个 runtime-dependent skill 之一，禁 `${CLAUDE_PLUGIN_ROOT}`——Cursor/ZCODE 等宿主无该变量，由 `platform-runtime-distribution.test.mjs` 守护），故其两处脚本引用改为**描述性写法**（「插件内 `scripts/…`（引用，非调用）」），不用宿主变量。
+
+### Fixed（P4 门禁发现：plugin-validator）
+
+- **【阻断级】插件内脚本/模板调用路径全部裸相对路径**（plugin-validator Major）：4 个新特性的 11 处调用写成 `node scripts/x.mjs` —— Bash 的 CWD 是**用户项目**，而插件零拷贝安装（marketplace，本插件推荐安装方式）时插件位于缓存目录，两者永不相等 → 模板导入 / primer digest 校验 / token 提取 / guard 四件全部不可执行；最严重处 `builder-methodology.md:27` 的 `--check` **exit code 是分支判据**（exit 0 继续 / exit 2 blocked），路径失败把确定性分支退化为猜测。修复：11 处统一改为 `${CLAUDE_PLUGIN_ROOT}/…`（对齐 `workflow-bootstrap` / `install-cursor.mjs` 既有范式与 `$SKILL_DIR` 同类解法）。**机械预防**：新增 `tests/lib/skill-path-convention.test.mjs`（正/负向控制 + 全量语料扫描），把「裸相对路径」从每轮人工审查变成 CI 可拦截的 lint。
+- **plugin.json 描述缺 3 个 first-class skill**（plugin-validator Minor）：`design-system` / `test-strategy` / `project-initialize` 自引入起从未进入 marketplace 描述（`design-system` 为 v0.19.0 起缺失，本轮成为主线能力后更显突兀）→ 两份 manifest 同步补全。
+- `release-archivist/SKILL.md:288` 的设计方案引用改为 workspace 相对写法（`team-flow-workspace/docs/…`），对齐 `workflow-bootstrap/SKILL.md:122`——同一文档两类引用写法并存。
+- `skills/prototype/references/builder-methodology.md:54` 的「8 个 section 骨架」→ **14 个**：`layouts.md` 实际已有 14 个骨架（v0.24.0 扩至 C 端 6 个），该表述自 v0.24.0 起滞后；`prototype/SKILL.md:52` 已正确，横展确认全插件仅此一处残留。
+
+### Known Deviations（记录在案）
+
+- `skills/release-archivist/SKILL.md`（297→305 行，lint 计数）与 `skills/workflow-bootstrap/SKILL.md`（267→280 行，lint 计数）超出 250 行建议线——**存量既存超长**（同批超长另有 `workflow-start` 302 / `ce-brainstorm` 263 / `architecture-design` 260，本次未触碰）；本次新增内容已按渐进式披露做成指针（细节在 `references/closing-procedures.md`），净增 +7/+12 行记录在案，治理待办见 Roadmap。
+
 ## [0.53.0] - 2026-09-10
 
 ### Added（架构台账回写门禁：`arch-merged` 维度 + B' 时序前移）

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.53.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.55.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.53.0**。
+当前发布版本：**v0.55.0**。
 
 ---
 

package/README.md

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

package/agents/prototype-builder.md

@@ -21,12 +21,13 @@ You are a write-focused builder. You read design artifacts (HTML/CSS/JS from the
 
 | Parameter | Description |
 |-----------|-------------|
-| `design_files_dir` | 设计稿目录路径（e.g., `prototype/designs/`） |
-| `design_system_dir` | 设计系统目录路径（e.g., `prototype/design-system/`） |
-| `output_dir` | 原型输出目录路径（e.g., `prototype/runnable/`） |
-| `requirements` | 构建要求（可选：响应式、性能目标、浏览器兼容性） |
+| `design_system_path` | 设计系统 base.md 路径（e.g., `.team-flow/design-system/base.md`） |
+| `confirmed_plan` | 已确认的原型方案（页面清单/组件清单/导航流） |
+| `prd_path` | PRD 路径（页面内容依据） |
+| `prototype_root` | 原型输出根目录（e.g., `prototype/`） |
+| `mode` | （可选）`default` \| `showcase`——showcase 模式用于设计系统展示板（输入换为 showcase-board brief + 设计系统草案，见 references/builder-methodology.md） |
 
-If `design_files_dir` or `design_system_dir` is missing or unreadable, report `BLOCKED` with reason `INPUT_ERROR`.
+If `design_system_path` or `confirmed_plan` or `prd_path` is missing or unreadable, report `BLOCKED` with reason `INPUT_ERROR`（showcase 模式豁免 `confirmed_plan`/`prd_path`）。
 
 ## Output Contract
 

package/agents/prototype-env-scout.md

@@ -1,6 +1,6 @@
 ---
 name: prototype-env-scout
-description: 原型环境探查（prototype skill 内部编排步骤①）。只读探查设计系统现状（9 段 schema 完整度）、原型仓库分支、PRD 版本、已有页面，产出环境简报 + 推荐原型方案设计 + readiness verdict。只读，不写 prototype/，不改 design-system.md。
+description: 原型环境探查（prototype skill 内部编排步骤①）。只读探查设计系统现状（base + 端变体 9 段 schema 完整度 + primer 新鲜度）、原型仓库分支、PRD 版本、已有页面，产出环境简报 + 推荐原型方案设计 + readiness verdict。只读，不写 prototype/，不改 design-system.md。
 
 model: inherit
 color: cyan
@@ -11,13 +11,13 @@ You are a Prototype Environment Scout. You are dispatched by the `prototype` ski
 
 ## The Iron Law
 
-You NEVER write, edit, create, or delete any file. Your only output is the brief in your final response. Writing `prototype/` is `prototype-builder`'s job; writing `design-system.md` is `design-system-architect`'s job.
+You NEVER write, edit, create, or delete any file. Your only output is the brief in your final response. Writing `prototype/` is `prototype-builder`'s job; `.team-flow/design-system/` is the `/team-flow:design-system` skill's job（其内部执行引擎 `design-system-architect` 是唯一写者，但入口是 skill——v0.19.0 起不由原型侧直接派发）。
 
 ## Invocation Contract
 
 The dispatch prompt provides (some may be absent — probe to discover):
 - `prd_path` or a hint to locate the current PRD version (e.g., `requirement/v1/prd.md`).
-- `design_system_path` (from `prototype.designSystem` config) or a hint to find `design-system.md`.
+- `design_system_path` (from `prototype.designSystem` config) or a hint to find `.team-flow/design-system/`.
 - `prototype_root` (default `prototype/`).
 - The intent: new prototype from scratch / iterate on existing / sync after a change.
 
@@ -43,13 +43,13 @@ Turn the probe into a decision-ready brief: what exists, what is missing, and a
 Produce:
 1. **Environment brief**: design-system status (9-段 completeness + palette), branch status, PRD version, existing prototype inventory.
 2. **Recommended prototype design plan（v0.18.0 升级：direction-picker）**: 产出 **2-3 个差异化方向**（反模式：>3 个、互为变体），每个方向含：
-   - 布局策略（section 组合，参照 `references/layouts.md` 页面类型节奏表）
+   - 布局策略（section 组合，参照 `references/layouts.md` 页面类型节奏表；**若设计系统声明 `页面范式来源：项目自有`，改以 primer 的「页面范式」段页面类型表为准**——内置节奏表是回退默认）
    - 视觉侧重（信息密度 / 留白 / 数据可视化程度）
    - 风险权衡（复杂度 / 用户认知负荷 / 实施成本）
    - 方向间必须有**实质差异**（如"数据密集仪表盘" vs "任务流导向" vs "渐进披露"）
    - 附推荐方向 + 理由（1 个）
    通用部分不变：page list (from PRD §4), component list (reuse vs new→sediment), navigation flow (from PRD §8.2), target branch + version.
-3. **Readiness verdict**: `ready`（设计系统完整 + 方案可定）/ `needs_design_system`（缺/不全，需先派 design-system-architect）/ `needs_prd`（PRD 缺页面/功能定义）.
+3. **Readiness verdict**: `ready`（设计系统完整 + 方案可定）/ `needs_design_system`（缺/不全，需主代理先调用 `/team-flow:design-system` skill）/ `needs_prd`（PRD 缺页面/功能定义）.
 
 ## Output Format
 
@@ -105,7 +105,7 @@ Produce:
 ```
 
 ## Red Lines
-- Do NOT write to `prototype/` or edit `design-system.md` — you are read-only.
+- Do NOT write to `prototype/` or edit `.team-flow/design-system/` — you are read-only.
 - Do NOT draw the prototype — that is `prototype-builder`'s job.
 - A missing design system is normally NOT your blocker — flag it via `needs_design_system` verdict for the orchestrator to decide.
 
@@ -128,4 +128,4 @@ Produce:
 阻断疑问（如 PRD 完全缺失无法定方案、无法定位任何原型/PRD 输入）→ 立即停止，返回 status=blocked + blockers[]，绝不强行猜测。你不能调用 AskUserQuestion。
 
 **决策点交互（v0.21.0，§22.1.1 stop-and-resume）**：你无 AskUserQuestion。探查中遇到必须用户/主代理拍板、且 default_assumption 不安全的点（罕见——方向选定由主代理人工评审），可 `SendMessage(to: "main")` 发结构化提问 `{ question, why, options[] }` 后**停止**，主代理代问用户后回传并自动 resume 你续跑；**收到回传须校验对应性**（无主答案/串线 → 拒绝将错就错）。常规非阻断疑问照旧记 `outstanding_questions`，硬阻断照旧 `blocked`。
-注意：设计系统缺失/不全通常**不是**你的 blocker（你只读探查），而是把 Readiness Verdict 标为 needs_design_system 交主代理决定是否先派 design-system-architect。
+注意：设计系统缺失/不全通常**不是**你的 blocker（你只读探查），而是把 Readiness Verdict 标为 needs_design_system，交主代理决定是否先调用 `/team-flow:design-system` skill。若探查中发现与**起点选择**相关的资产事实（如"已有符合规范的原型代码""需求方提到有既有 UI 规范文档""公司另一个后台项目已建过设计系统"），**在简报中如实记录**——主代理会把这些事实传达给 design-system skill 作为起点提示（不预选起点）。

package/agents/release-archivist.md

@@ -43,6 +43,7 @@ writebacks:
   arch_merge: "merged N docs | skipped"
   prototype_sync: "synced N pages | no UX delta | conflicts: N"
   compound_promotion: "promoted N learnings | no learnings"
+  design_system_pending: "N items pending (needs user confirmation) | none"  # v0.54.0 ⑥：只读检查 .team-flow/design-system/pending.md，不执行 iterate
 summary: "..."                       # closing summary + any WARNs needing user acceptance
 ```
 

package/dist/parsing/requirement-blocks.d.ts

@@ -10,7 +10,33 @@ export interface RequirementsSectionParts {
     bodyBlocks: RequirementBlock[];
     after: string;
 }
+/**
+ * 行内强调剥离 + 去反引号（v0.55.0 §8.4.3 横展；与 `scripts/lib/md-normalize.mjs` 同约定）。
+ *
+ * **根因**：解析层对最常见的 Markdown 强调语法脆弱且**失败静默**——手写
+ * `### **Requirement**: X` 或 `` ### `Requirement`: X `` 会让需求块整块漏解析，
+ * 而这条路径在 `tf sync`（→ `spec-merge` → 本模块）上是**活路径**，且
+ * `guard/checks/specs-merged` 会在 delta spec 存在时硬阻断 `executing → closing`。
+ * JS 侧已修（`md-normalize.mjs`），本函数是 TS 侧的对应实现（D-16「全修」）。
+ *
+ * **只剥双符号对**（`**` / `__`）：单 `*` 可能是列表符、单 `_` 可能是 snake_case
+ * 标识符——剥它们是"改语义"而非"容格式"。
+ */
+export declare function stripInlineEmphasis(text: string): string;
+/** 归一化需求名：剥行内强调/反引号（名称本身被包裹时）+ trim。 */
 export declare function normalizeRequirementName(name: string): string;
+/**
+ * 需求块标题：`### Requirement: <name>`。
+ *
+ * v0.55.0 容忍：`Requirement` 键被加粗/反引号包裹（`**Requirement**` /
+ * `` `Requirement` `` / `` **`Requirement`** ``——**两种符号可任意交错、任意顺序**，
+ * 故用字符类而非固定序列）、全角冒号、冒号前后空格。
+ * 名称内的标记由 {@link normalizeRequirementName} 归一。
+ *
+ * 注：单 `*` 包裹（`*Requirement*`）也在容错内——键名两侧的星号无论一个两个
+ * 都是强调写法，剥它不改变语义。**需求名内部**的单符号才是语义边界，
+ * 由 `stripInlineEmphasis` 只剥成对双符号来保证。
+ */
 export declare const REQUIREMENT_HEADER_REGEX: RegExp;
 export declare function extractRequirementsSection(content: string): RequirementsSectionParts;
 export interface DeltaPlan {

package/dist/parsing/requirement-blocks.js

@@ -1,7 +1,35 @@
+/**
+ * 行内强调剥离 + 去反引号（v0.55.0 §8.4.3 横展；与 `scripts/lib/md-normalize.mjs` 同约定）。
+ *
+ * **根因**：解析层对最常见的 Markdown 强调语法脆弱且**失败静默**——手写
+ * `### **Requirement**: X` 或 `` ### `Requirement`: X `` 会让需求块整块漏解析，
+ * 而这条路径在 `tf sync`（→ `spec-merge` → 本模块）上是**活路径**，且
+ * `guard/checks/specs-merged` 会在 delta spec 存在时硬阻断 `executing → closing`。
+ * JS 侧已修（`md-normalize.mjs`），本函数是 TS 侧的对应实现（D-16「全修」）。
+ *
+ * **只剥双符号对**（`**` / `__`）：单 `*` 可能是列表符、单 `_` 可能是 snake_case
+ * 标识符——剥它们是"改语义"而非"容格式"。
+ */
+export function stripInlineEmphasis(text) {
+    return text.replace(/`/g, '').replace(/\*\*(.+?)\*\*/g, '$1').replace(/__(.+?)__/g, '$1');
+}
+/** 归一化需求名：剥行内强调/反引号（名称本身被包裹时）+ trim。 */
 export function normalizeRequirementName(name) {
-    return name.trim();
+    return stripInlineEmphasis(name).trim();
 }
-export const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/i;
+/**
+ * 需求块标题：`### Requirement: <name>`。
+ *
+ * v0.55.0 容忍：`Requirement` 键被加粗/反引号包裹（`**Requirement**` /
+ * `` `Requirement` `` / `` **`Requirement`** ``——**两种符号可任意交错、任意顺序**，
+ * 故用字符类而非固定序列）、全角冒号、冒号前后空格。
+ * 名称内的标记由 {@link normalizeRequirementName} 归一。
+ *
+ * 注：单 `*` 包裹（`*Requirement*`）也在容错内——键名两侧的星号无论一个两个
+ * 都是强调写法，剥它不改变语义。**需求名内部**的单符号才是语义边界，
+ * 由 `stripInlineEmphasis` 只剥成对双符号来保证。
+ */
+export const REQUIREMENT_HEADER_REGEX = /^###\s*[`*]{0,4}\s*Requirement\s*[`*]{0,4}\s*[:：]\s*(.+?)\s*$/i;
 function normalizeLineEndings(content) {
     return content.replace(/\r\n?/g, '\n');
 }
@@ -137,7 +165,7 @@ function parseRemovedNames(sectionBody) {
             names.push(normalizeRequirementName(m[1]));
             continue;
         }
-        const bullet = line.match(/^\s*-\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
+        const bullet = line.match(/^\s*-\s*`?###\s*[`*]{0,4}\s*Requirement\s*[`*]{0,4}\s*[:：]\s*(.+?)\s*$/i);
         if (bullet) {
             names.push(normalizeRequirementName(bullet[1]));
         }
@@ -151,8 +179,8 @@ function parseRenamedPairs(sectionBody) {
     const lines = normalizeLineEndings(sectionBody).split('\n');
     let current = {};
     for (const line of lines) {
-        const fromMatch = line.match(/^\s*-?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
-        const toMatch = line.match(/^\s*-?\s*TO:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
+        const fromMatch = line.match(/^\s*-?\s*FROM\s*[:：]\s*`?###\s*[`*]{0,4}\s*Requirement\s*[`*]{0,4}\s*[:：]\s*(.+?)\s*$/i);
+        const toMatch = line.match(/^\s*-?\s*TO\s*[:：]\s*`?###\s*[`*]{0,4}\s*Requirement\s*[`*]{0,4}\s*[:：]\s*(.+?)\s*$/i);
         if (fromMatch) {
             current.from = normalizeRequirementName(fromMatch[1]);
         }

package/dist/validation/validator.js

@@ -1,7 +1,14 @@
 import { MIN_PURPOSE_LENGTH, MIN_WHY_SECTION_LENGTH, MAX_WHY_SECTION_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, MAX_DELTAS_PER_CHANGE, VALIDATION_MESSAGES, VERIFICATION_MESSAGES, } from './constants.js';
 import { tokenize } from './tokenizer.js';
 import { parseDeltaSpec, normalizeRequirementName, extractRequirementsSection, } from '../parsing/requirement-blocks.js';
-const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/i;
+// v0.55.0 §8.4.3（D-16「全修」横展）：本文件原有第二份 `REQUIREMENT_HEADER_REGEX`
+// 定义（`/^###\s*Requirement:\s*(.+)\s*$/i`）——**定义后从未使用**（本文件的需求头
+// 解析全部经 `parseDeltaSpec` / `extractRequirementsSection` 走解析层），属"同一契约
+// 两处定义"的维护陷阱：改解析层正则时无人知道这里还有一份。已删除，需求头正则的
+// 唯一真相源是 `parsing/requirement-blocks.ts`。
+//
+// ⚠️ 不要再在本文件内定义需求头/场景头以外格式约定的正则——场景头（下方）是
+// 本文件唯一自有的格式契约，其余一律从解析层引入。
 const SCENARIO_HEADER_REGEX = /^####\s+Scenario:/i;
 function normalizeLineEndings(content) {
     return content.replace(/\r\n?/g, '\n');

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.53.0`
+- Current: `v0.55.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/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). 26 skills, one install.",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,16 +1,23 @@
 #!/usr/bin/env bash
-# v0.53.0: auto-sync CLI version with plugin version
+# v0.55.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.53.0"
+PLUGIN_VERSION="0.55.0"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version
 # ═══════════════════════════════════════════════════════════════
 
+# v0.55.0(N1)：取两者中较高的版本号。
+# 按**段的数值**排序（`-k1,1n -k2,2n -k3,3n`），不用 GNU 的 `sort -V`——BSD sort 不保证支持。
+# 数值排序不可退化为字符串排序：`0.6.0` 字符串比 `0.54.0` 大，数值上却更小。
+higher_version() {
+  printf '%s\n%s\n' "$1" "$2" | sort -t. -k1,1n -k2,2n -k3,3n | tail -1
+}
+
 sync_tf_version() {
   # Get installed tf version
   local installed_version=""
@@ -18,6 +25,16 @@ sync_tf_version() {
     installed_version=$(tf --version 2>/dev/null | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1)
   fi
 
+  # v0.55.0(N1)：**只升不降**——同步的语义是"CLI 追上插件"，不是"CLI 随谁启动而震荡"。
+  # 原实现只判 != ，机器上任一旧版插件缓存副本跑起来都会把新版 CLI 降级
+  # （实测 0.54.0 被降到 0.51.0）。故已安装版本 ≥ 插件版本时一律跳过。
+  # 回归守卫：tests/lib/hook-session-start.test.mjs
+  if [ -n "$installed_version" ] && [ "$installed_version" != "$PLUGIN_VERSION" ] \
+    && [ "$(higher_version "$installed_version" "$PLUGIN_VERSION")" = "$installed_version" ]; then
+    echo "⏭️  team-flow CLI ($installed_version) 比插件 ($PLUGIN_VERSION) 新，跳过同步"
+    return 0
+  fi
+
   # Compare versions and sync if needed
   if [ "$installed_version" != "$PLUGIN_VERSION" ]; then
     echo "🔄 team-flow CLI version mismatch: ${installed_version:-not installed} → $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.53.0.
+Current version: v0.55.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.53.0",
+  "version": "0.55.0",
   "description": "Unified plugin (26 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",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-flow",
-  "version": "0.53.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). 26 skills + 17 agents, one install.",
+  "version": "0.55.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). 26 skills + 17 agents, one install.",
   "author": {
     "name": "LT"
   },