@xulthekl/team-flow 0.36.2 → 0.36.4

package/skills/architecture-design/chapters/ch06-integration.md

@@ -38,14 +38,14 @@ changes/<name>/              # change 容器
 
 ## 复利回写（借鉴 ce-compound，已正名）
 - **one change per run**：一次回写一个变更 delta，可追溯、不混杂。
-- 全局 ARCHITECTURE.md 维护双视图：`## 当前态`（覆盖式，每 BC/聚合仅留最新有效定义）+ `## 演进日志`（append-only，含 change_id+来源）。
+- 全局 ARCHITECTURE.md 维护双视图（v0.36.0 实现为 marker 区 + 演进日志）：`<!-- arch:current-state:begin/end -->` marker 区（覆盖式，arch-merge 代码独占写 + 成对校验，每 BC/聚合仅留最新有效定义）+ `## 演进日志`（changeName 去重，替代原 append-only 重复标题）。
 - **架构一致性/漂移检查**（独立于 Discoverability）：①结构冲突（重复 BC/聚合 key）②语义冲突（同义异名，如客户vs用户）③跨域一致性门禁（AA≥1 IA 实体，反之亦然）。
 - **Discoverability 正名**：在 AGENTS.md/CLAUDE.md 暴露 `docs/architecture/`，使代理设计前"发现并查阅"（存在/结构/何时检索）——这是 compound 原义，勿与内容冲突检查混淆。
 - 下游检索复用：下一 change 设计前从 `docs/architecture/` 检索相关上下文/聚合（grounding 用 CONCEPTS.md）。
 
 ## 集成纪律（来自 team-flow 源码事实）
 - **design.md 不可变**：原型覆盖层 never mutate design.md/tasks.md。原型结论走 `handoff --type prototype` → 新 requirement delta → 正常 `specifying→closing→spec-merger` 闭环，不得直接改 design.md。
-- **guard 软集成**：三份增量文档为推荐产出、非阻断；全局回写经独立 `arch-compound` skill/overlay，不进状态机硬矩阵；frontmatter 校验仅 advisory 脚本（正则提取 key，不引第三方 YAML 依赖），保全零依赖。
+- **guard 软集成**：三份增量文档为推荐产出、非阻断；全局回写经 `tf arch-merge` 命令（v0.36.0 重构：当前态幂等 upsert + 生成式 PHYSICAL-MODEL/DATABASE/API-INDEX + 冲突预检 + 并发安全，原 arch-compound skill/overlay 概念已由该命令承接）；frontmatter 校验仅 advisory 脚本（正则提取 key，不引第三方 YAML 依赖），保全零依赖。
 - **术语正名**：IA/AA 非"技术架构"（仅 TA 是）；4A 是四域非三层；技术架构对 STRATEGY.md 是"补位 compound 缺位"而非"修正其错误"，且 ARCHITECTURE.md 是 anchor 而非评审巨著。
 
 ## 第二大脑整合（ima「LT的知识库」）

package/skills/architecture-design/references/s3.5-architecture-template.md

@@ -142,7 +142,7 @@ flowchart LR
 | v1 | <date> | 初始设计 |
 
 <!-- arch:current-state:begin -->
-<!-- 此 marker 区由 arch-merge 代码独占写（迭代收尾/change 合并时覆盖），禁止手改 -->
+<!-- 此 marker 区是 arch-merge 全局覆盖写机制的模板约定（v0.36.0）；快照本身不被 arch-merge 写（P1：预测态不进实际态），迭代收尾由 S5 标 snapshot_status=archived -->
 <!-- arch:current-state:end -->
 ````
 

package/skills/architecture-design/references/s3.5-loading-protocol.md

@@ -35,6 +35,6 @@
 
 ## 与既有加载协议的关系
 
-- 本协议**扩展** architecture-design SKILL.md「上下文加载协议」（:166-183），不替代。
+- 本协议**扩展** architecture-design SKILL.md「上下文加载协议」，不替代（引用标题而非行号，防漂移）。
 - 变更级 architecture-design 的输入 = 本协议 ① + ②（产品级）+ ③（变更增量）；语义层（五项检查判定、评审）仍走既有流程。
 - S3.5 产品级评审门（architecture-reviewer product 视角 A1-A6）验证产物结构满足本协议（A1 结构完备 + A2 marker/锚点可解析），保证下游可按域加载。

package/skills/architecture-design/references/s3.5-product-architecture.md

@@ -31,6 +31,8 @@
 
 **顺序纪律**：聚合在前、ER 在后（ER 是派生产物，禁止先画 ER 再定聚合）；BC 边界/聚合所有权/全局契约是**产品级唯一事实源**（聚合注册表），变更级只引用。
 
+**按域详细页产出（v0.36.3，domains/ 生产者）**：Step 1 识别 BC 后、Step 2-6 每个触及域细化时，同步产出 `domains/<bc>.md`（职责/聚合明细/指令事件/状态迁移/ER 局部/时序/对外契约）与 `diagrams/`（erd/sequences）——它们是按域分段加载（`s3.5-loading-protocol.md` 第②段）与 reviewer product A1 的审查对象；单文件 ≤1500 token。
+
 **模板**：按 `references/s3.5-architecture-template.md` 骨架产出（6 产物 + 厚锚点 + marker + provenance）。
 
 ## 产品级评审门（Step 8）
@@ -49,6 +51,15 @@
 规则：≤3 轮修复循环 + 收敛检测（连续两轮不一致项不缩小 → 转人工）；PASS 才进 S4。
 **skip 时**：architecture-reviewer 不执行，但 skip 必须物化（iterations/vN/SKIPPED 标记 + 理由）。
 
+### 复利捕获（Step 9，v0.36.3 复利链路修复）
+
+评审 PASS 后，捕获本次架构设计产生的可复用决策经验（advisory 级，捕获失败不阻断）：
+
+- **触发场景**：BC 边界取舍、聚合划分理由、事件/读模型投影设计模式、技术选型决策、逆向重建低置信度修正
+- **命令**：`tf solutions capture --phase architecture --domain <触及BC> --type pitfall|pattern --severity medium --summary "<经验>"`（source: `iterations/vN/architecture.md`）
+- **注入端**：后续架构设计（变更级/产品级）执行时 `tf solutions inject --phase architecture` 自动注入这些经验（architecture-design 加载协议，v0.36.3）
+- **晋升说明**：产品级架构经验直接 capture 写 `docs/solutions/`（不走 change 级 promote——promote 只认 `learnings.md`，是变更级机制）
+
 ## 正向设计 vs 逆向重建
 
 | 维度 | 正向设计（全新/已建档） | 逆向重建（旧项目首轮） |
@@ -59,7 +70,7 @@
 | provenance | forward-designed | reverse-engineered + 置信度（high/medium/low） |
 | 深度 | L0 骨架 + 触及域深化 | 同（首轮强制 L0 骨架，见 v0.14 §63.3） |
 
-逆向重建工具：`workflow-bootstrap` 的 recon-probe.sh（--ddl-out）+ codebase-recon-analyst + 新增 `arch-reverse-analyst`（v0.14 §63.2）。
+逆向重建工具：`workflow-bootstrap` 的 recon-probe.sh（--ddl-out，路径 `${CLAUDE_PLUGIN_ROOT}/skills/workflow-bootstrap/scripts/recon-probe.sh`）+ codebase-recon-analyst + 新增 `arch-reverse-analyst`（v0.14 §63.2）。
 
 ## 完成条件
 
@@ -67,6 +78,7 @@
 - 产品级评审门 verdict = PASS（或 skip 已物化）
 - orchestrator.yaml 中 ARCH 阶段状态 = completed（workflow_phase: architecture）
 - **未触发** arch-merge 全局覆盖写（预测态不进实际态，P1）
+- **架构基线打戳（v0.36.3）**：首轮项目（`arch_baseline` 缺失）评审 PASS 后执行 `tf arch init --mode reconstruction --baseline-ref prd/vN/`（旧项目逆向重建）或 `--mode design`（全新项目正向设计）——arch-readiness/arch-snapshot 门禁的豁免键在此建立，项目进入「已建档」正轨
 
 ## 常见陷阱
 

package/skills/ce-compound/references/v0.5-upgrade.md

@@ -20,6 +20,9 @@ ce-compound 从"手动触发的记录工具"升级为"复利贯穿引擎的执
 - change 执行中超出原始 scope（phase=build, type=pitfall）
 - re-bridge 触发（phase=spec, type=pitfall）
 - mandatory rewind 触发（phase=cross-phase, type=pitfall）
+- 架构评审 FAIL 反复修正（phase=architecture, type=pitfall，v0.36.3 新增）
+- 架构修订决策门触发（phase=architecture, type=pattern，v0.36.3 新增）
+- 逆向重建低置信度决策（phase=architecture, type=pattern，v0.36.3 新增）
 
 ## 被流程自动调用
 

package/skills/release-archivist/SKILL.md

@@ -125,6 +125,8 @@ If implementation diverged from the contract, return to `bridging` before closur
 
 Run `tf state transition <change-dir> closing`. If delta specs exist, route to `spec-merger`.
 
+**架构快照门禁（arch-snapshot，v0.36.0 / v0.36.3）**：`executing→closing` 挂 `arch-snapshot` 维度——本轮迭代产品级架构快照 `iterations/vN/architecture.md` 必须已落盘（"先快照后回写"强制化）。**FAIL 升级路径**：回 orchestrator 的 ARCH 阶段补快照；存量升级在途 change（快照缺失但 change 有增量产物）→ WARN 兜底放行；`arch_baseline` 缺失 → WARN 不阻断。hotfix/tweak 豁免（不挂该维度）。判定逻辑见 `scripts/guard/checks/arch-gate-exemptions.mjs`。
+
 ### Architecture Merge (v0.10 §28-§31) — MUST run first
 
 Merge change-level architecture artifacts to the global `docs/architecture/` baseline **before** any other post-verification step:

package/skills/workflow-bootstrap/SKILL.md

@@ -56,7 +56,7 @@ Do NOT invoke for:
 > **硬原则**：主代理只编排（派发 + 汇总 + 写 baseline.md），侦察执行下沉子代理（§18.1 交接协议）。先跑确定性脚本固定化采集基底，再派子代理做语义增强——**可复现、可横展对比**。
 
 - **模式**（询问用户）：Quick（默认，技术栈+模块+架构模式+测试文档，~2 分钟）/ Deep（+数据模型+API 表面，~10 分钟）。
-- **B1.1 脚本采集**：`bash scripts/recon-probe.sh --root <根> --out /tmp/recon-<slug>.json`（固定化，两次接入结果一致）。
+- **B1.1 脚本采集**：`bash ${CLAUDE_PLUGIN_ROOT}/skills/workflow-bootstrap/scripts/recon-probe.sh --root <根> --out /tmp/recon-<slug>.json`（固定化，两次接入结果一致）。
 - **B1.2 并行子代理**：读 `references/agents/codebase-recon-analyst.md`，把 JSON 路径作 `recon_json` 入参，按维度并行派发（§18.1 返回）。
 - **B1.3 主代理汇总**：只汇总不重新侦察，整合已有文档（合并而非覆盖，标注来源），写 `docs/architecture/baseline.md`。
 
@@ -124,7 +124,7 @@ Step 1: 询问用户是否有既有成果物
 
 Step 2: 确定性提取（兜底）
   ├── recon-probe.sh DDL 提取能力（v0.24.0 已实现：SQL 文件 / Java Entity / 占位）
-  │   bash scripts/recon-probe.sh --root <根> --ddl-out docs/architecture/schema-baseline.sql
+  │   bash ${CLAUDE_PLUGIN_ROOT}/skills/workflow-bootstrap/scripts/recon-probe.sh --root <根> --ddl-out docs/architecture/schema-baseline.sql
   ├── 从 schema-baseline.sql 反向生成 PHYSICAL-MODEL.md
   └── 扫描 Controller/Router 类 → 生成 API-INDEX.md
 
@@ -142,8 +142,8 @@ Step 2: 确定性提取（兜底）
 
 **轻量 vs 完整**：
 - bootstrap 产出的是**基线快照**（As-Is 当前态），不是完整的 4A+DDD 设计
-- 完整的架构演进仍走 `/architecture-design` 的标准增量流程
-- 如果用户需要完整架构设计，B2 结束后建议："基线已建立。如需完整架构设计，请运行 `/architecture-design`"
+- 完整的架构演进：既有代码库的**逆向重建**走 workflow-orchestrator 的 ARCH 阶段（S3.5 reconstruction 模式，`arch-reverse-analyst`，v0.36.0）；全新架构设计走 ARCH 正向设计
+- 如果用户需要完整架构设计，B2 结束后建议："基线已建立。如需完整架构设计（逆向重建或正向设计），请进入 workflow-orchestrator 的 ARCH 阶段"（v0.36.3 修正——原指引导向 change 级 skill 已过时）
 
 **已有架构文档处理**：
 - 如果 `docs/architecture/ARCHITECTURE.md` 已存在 → 读取并整合，不覆盖
@@ -190,9 +190,12 @@ Step 2: 确定性提取（兜底）
 询问用户：
 
 > 您希望从哪个需求开始使用 team-flow？
-> - A) 我有一个具体的功能需求（→ 进入 workflow-orchestrator S1）
+> - A) 我有一个具体的功能需求（→ 进入 workflow-orchestrator S1，S3 后进 ARCH 产品级架构设计）
 > - B) 我有一个模糊的产品方向（→ ce-brainstorm）
 > - C) 我只是想建立架构基线，暂不开发新需求（→ 结束）
+> - D) 我想从既有代码逆向重建完整架构（→ 进入 workflow-orchestrator ARCH 阶段 reconstruction 模式，arch-reverse-analyst，v0.36.0；重建 PASS 后 `tf arch init` 打戳）
+
+**逆向重建衔接（v0.36.3）**：ARCH 阶段 reconstruction 模式复用本 bootstrap 的 recon-probe.sh（--ddl-out）+ codebase-recon-analyst，并派发 `arch-reverse-analyst` 补 BC/状态/指令事件维度（见 `references/agents/arch-reverse-analyst.md`）。
 
 **上下文传递**：
 - 将 `docs/architecture/baseline.md` 和 `docs/architecture/CONCEPTS.md` 的路径传递给 workflow-orchestrator S1

package/skills/workflow-bootstrap/references/b1-reconnaissance.md

@@ -10,7 +10,7 @@
 ## B1.1 确定性脚本采集（先跑，固定化探查）
 
 ```bash
-bash scripts/recon-probe.sh --root <项目根> --out /tmp/recon-<slug>.json
+bash ${CLAUDE_PLUGIN_ROOT}/skills/workflow-bootstrap/scripts/recon-probe.sh --root <项目根> --out /tmp/recon-<slug>.json
 ```
 
 固定采集（不依赖 LLM，两次接入结果一致）：目录树（限深 4 层）、依赖清单（pom/package.json/requirements/go.mod/build.gradle）、LOC 与文件类型分布、测试文件计数（含 `.test.mjs`/`.spec.mjs`）、DB 迁移文件清单、README/docs 探测。输出结构化 JSON 供子代理消费。脚本只做确定性机械采集（§17.8 第四类载体），语义判断交给子代理 LLM。
@@ -25,7 +25,7 @@ bash scripts/recon-probe.sh --root <项目根> --out /tmp/recon-<slug>.json
 
 **用法**：
 ```bash
-bash scripts/recon-probe.sh --root <根> --ddl-out docs/architecture/schema-baseline.sql --out /tmp/recon-<slug>.json
+bash ${CLAUDE_PLUGIN_ROOT}/skills/workflow-bootstrap/scripts/recon-probe.sh --root <根> --ddl-out docs/architecture/schema-baseline.sql --out /tmp/recon-<slug>.json
 ```
 
 **JSON 输出字段**：`ddl_extraction.source`（sql_files / java_entity / none）、`ddl_extraction.table_count`、`ddl_extraction.tables[]`、`ddl_extraction.ddl_statements`

package/skills/workflow-orchestrator/SKILL.md

@@ -83,7 +83,7 @@ prd_draft → user_review → prototype_loop → prd_frozen → completed
 
 **评审门**：产出经 architecture-reviewer product 视角（`review_mode: product`，A1-A6）评审，**PASS 才进 S4**。
 
-**输出契约**：`docs/architecture/iterations/vN/architecture.md` + 评审 verdict；`orchestrator.yaml` 中 ARCH phase 状态 = completed（`workflow_phase: architecture`）。
+**输出契约**：`docs/architecture/iterations/vN/architecture.md` + 评审 verdict；`orchestrator.yaml` 中 ARCH phase 状态 = completed（`workflow_phase: architecture`）。**首轮项目（`arch_baseline` 缺失）评审 PASS 后执行 `tf arch init --mode reconstruction|design --baseline-ref prd/vN/` 打戳**（v0.36.3）——arch 门禁豁免键由此建立，项目进入「已建档」正轨。
 
 ### S4: 拆分验证与分发
 

package/skills/workflow-orchestrator/references/s4-split-validate.md

@@ -84,6 +84,7 @@ tf state init changes/v1-C2-policy-management
 upstream_source: orchestrator          # orchestrator | manual | null
 upstream_req_id: <req-id>              # 对应 .team-flow/requirements/<req-id>/
 upstream_plan_ref: prd/vN/plan.md      # hotfix/快速通道为 null
+upstream_arch_ref: docs/architecture/iterations/vN/architecture.md  # 产品级架构快照（v0.36.3）；ARCH skip 或 hotfix 为 null
 upstream_change_id: C2                 # 对应 change_dag.id
 plan_hash: sha256:<plan.md 内容摘要>    # 检测产品层改动后变更层未同步
 ---
@@ -99,7 +100,7 @@ plan_hash: sha256:<plan.md 内容摘要>    # 检测产品层改动后变更层
 <取自 auditor 报告 Dim1 覆盖矩阵中映射到本 change 的 AC，逐条列出>
 
 ## 全局技术方向
-<取自 plan.md 高阶技术设计段的要点指针：模块边界/技术选型/数据流方向，供 spec-writer 作 design.md 约束>
+<取自 plan.md 高阶技术设计段的要点指针：模块边界/技术选型/数据流方向，供 spec-writer 作 design.md 约束；**BC 边界/聚合所有权以 `upstream_arch_ref` 产品级快照为准**（v0.36.3），plan.md 仅高阶方向>
 
 ## PRD & plan 引用
 - PRD: prd/vN/prd.md §<相关章节>

package/skills/workflow-orchestrator/references/s5-monitoring.md

@@ -58,4 +58,5 @@ S5 是动态重规划的主要触发点。当检测到需要重新拆分（跨 c
 - 所有 change closed
 - 复利晋升已完成
 - 跨 change 一致性已确认（无未解决冲突）
+- **架构迭代收尾（v0.36.3，快照生命周期）**：本轮迭代 `docs/architecture/iterations/vN/architecture.md` 的 `snapshot_status` 标 `archived`（预测态退役，全局当前态 = 唯一权威，P1）——已建档项目的迭代收尾动作
 - S5 状态 = completed

package/skills/workflow-orchestrator/references/state-model.md

@@ -111,7 +111,7 @@ phases:
 | 门禁 | 挂点 | 校验 | 豁免 |
 |------|------|------|------|
 | 产品级评审门 | ARCH→S4 | architecture-reviewer product 视角 PASS | skip 时仍要物化标记 |
-| arch-readiness | S4 拆分 | iterations/vN/ 快照覆盖 change 触及的 BC | arch_baseline 缺失 → WARN 不 FAIL |
+| arch-readiness | exploring:specifying（guard 存在性）+ S4 拆分（LLM 覆盖校验） | iterations/vN/ 快照覆盖 change 触及的 BC | arch_baseline 缺失 → WARN 不 FAIL |
 | arch-snapshot | executing→closing | 本轮快照已落盘 | 在途 change legacy 豁免 |
 
 ## arch_baseline 豁免键（v0.35.0 新增）

package/skills/workflow-start/SKILL.md

@@ -62,6 +62,7 @@ Validate mode against artifact content. If hotfix/tweak criteria not met → upg
 
 - **记录 agentId**：dispatch 后立即记录子代理 ID；修复一律 SendMessage 恢复原子代理（禁启动新子代理，见 v0.29.0 §37）
   - **上下文水位例外（v0.35.0）**：当原子代理 transcript 超过 2MB 或累计 token 消耗超过 200 万时，主代理可以启动新代理替代恢复。新代理必须接收完整交接文档（当前进度、已完成 wave 列表、未解决问题、artifact 位置、已知 blocker），以保证连续性。此为 SendMessage 恢复原则的唯一补充例外
+  - **build-executor 交互轮次轮转（v0.36.4）**：主代理通过 SendMessage 恢复 build-executor 时，累计交互轮次。当累计 ≥6 轮（~3 wave 的典型交互量：放行→实施→审查→FAIL→修→复评）时，checkpoint 当前进度并启动新 build-executor 子代理。交接文档必须包含：已完成 waves 及 receipt 状态、累积技术决策（如命名约定、架构选型）、worktree commit SHA、剩余 waves 及依赖关系。此规则独立于上下文水位例外——两者取先触发者
 - **返回即验证（validation gate）**：子代理返回产物后**立即** `tf validate <change-dir>`；FAIL → SendMessage 回**原**子代理修复，通过后才能继续/转换。把格式失败拦截在返回时，而非状态转换时（避免浪费整次执行后再失败）。**build-executor 附加验证（v0.13 §52 B3，SDD/full 模式）**：返回的 diff 中必须包含测试文件（src/test/ 或项目测试目录）；零测试文件的实现返回一律 BLOCK，SendMessage 回原子代理按 test-matrix.md / TDD Iron Law 补齐——不得以"手动验证"替代（C1-domain-policy 事件教训）。例外：已显式记录 `test_matrix_skipped=true` + 理由的 change（纯文档/配置类）不要求测试文件
 - **结果协议**：子代理终态须标注 `FINAL VERDICT: <DONE|BLOCKED|FAIL>`（审查类用 PASS/PASS_WITH_WARNINGS/FAIL）；**SendMessage 报告为权威结果**，task-notification.result 仅内部元数据
 - **子代理状态边界**：子代理 MUST NOT 修改 `.team-flow.yaml` 的 `state`/`workflow` 核心字段（状态转换是主代理专有职责，经 `tf state transition` 执行），只写自己的 `dp_N_*` 决策字段
@@ -98,6 +99,8 @@ Execution hit blockage: test failure, unexpected behavior, build error, task can
 ### Route to code-reviewer
 The current planned wave is implemented and ready for spec-compliance + code-quality verification. A reviewer must write an `tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>` receipt before any dependent wave or closing transition.
 
+**逐 wave 审查纪律（v0.36.4）**：每次 code-reviewer dispatch 只审查**一个** wave。禁止将多个 wave 合并为一次审查（vrm4teamflow C1 事件：W1-W4 合并审查导致设计约定类问题在 W4 才发现，修复范围扩大到 8 个 batch）。parallel wave 内的多个 task 作为整体审查一次（receipt 是 wave 级别），但审查 prompt 必须包含每个 task 的独立 diff。
+
 ### Route to release-archivist (dispatch sub-agent)
 Guard: `... check <dir> executing closing --json` → fail = BLOCK. Implementation complete, verification complete/nearly complete. Include `DP-7: 归档确认`.
 

package/skills/workflow-start/references/routing-rules.md

@@ -9,6 +9,8 @@ Change is fuzzy, scope unclear, comparing options, no stable change name.
 
 Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before spec-writer.
 
+**架构门禁（v0.36.0 / v0.36.3）**：`exploring→specifying` 还挂 `arch-readiness` 维度（产品级架构快照 `iterations/vN/architecture.md` 存在 或 ARCH skip 物化 或 在途兜底）。**FAIL 升级路径**：回 orchestrator 的 ARCH 阶段补快照（或确认 ARCH skip 物化）；`arch_baseline` 缺失（存量项目）→ WARN 不阻断。判定逻辑见 `scripts/guard/checks/arch-gate-exemptions.mjs`。
+
 ### Step 1: Dispatch architecture-design sub-agent
 
 Dispatch `architecture-design` as sub-agent with inputs: