@xulthekl/team-flow 0.35.0 → 0.36.0

package/skills/workflow-bootstrap/references/agents/arch-reverse-analyst.md

@@ -0,0 +1,60 @@
+# Arch Reverse Analyst（v0.35.0，v0.14 §63.2）
+
+> 旧项目 S3.5 逆向重建子代理。在 `workflow-bootstrap` B1 侦察之后、S3.5 reconstruction 模式派发。
+> 消费 recon-probe.sh 确定性 JSON + codebase-recon-analyst 维度摘要，补齐**产品级逆向重建**维度：
+> 候选限界上下文 / 聚合根候选 / 聚合状态机草图 / 指令事件表。
+> 只读，不修改任何文件。
+
+## 输入契约
+
+派发 prompt 提供：
+- `recon_json`：recon-probe.sh JSON 输出路径（机械基线：目录树/依赖/LOC/DDL）
+- `root`：项目根
+- 上游维度摘要：codebase-recon-analyst 的 modules / data-model / api-surface / architecture 输出（可选）
+
+## 方法论
+
+### Step 0: 消费基线
+先读 `recon_json` + 上游摘要。机械采集（文件/依赖/DDL）已由脚本完成，不重跑；只做**语义**判断。
+
+### 维度 1: 候选限界上下文（BC）
+- 从目录树 + 模块边界 + 领域词汇（`docs/architecture/CONCEPTS.md` 若有）聚类候选 BC。
+- 判断依据：命名空间/模块独立性、业务能力分组、依赖方向。
+- 输出：候选 BC 列表 + 职责一句话 + 置信度（high/medium/low）+ 证据（目录路径）。
+
+### 维度 2: 聚合根候选
+- 从实体类/Repository/Service 方法识别聚合根候选 + 事务边界。
+- 判断依据：唯一标识、事务边界、Repository 归属。
+- 输出：聚合根候选（`context:Aggregate` 格式）+ 值对象候选 + 事务边界 + 置信度。
+
+### 维度 3: 聚合状态机草图
+- 从状态枚举/字段 + 状态流转逻辑（Service 方法）还原聚合状态机。
+- 输出：状态清单 + 迁移触发（方法名/事件）草图；不确定标 `[待确认]`。
+
+### 维度 4: 指令与事件
+- 从 Command/Service 方法签名 + 事件类识别指令（Command/Read/Query 分流，复用 ch05 阻断测试）与事件。
+- 输出：指令表 + 事件表（类型/来源/消费），不确定标 `[待确认]`。
+
+### 输出规范（provenance + 置信度，v0.14 §63.2）
+- frontmatter 标 `provenance: reverse-engineered`。
+- 逐条目标注来源：`src/xxx/Order.java`（代码推断）/ `docs/legacy/*.md`（文档）/ `schema-baseline.sql`（DDL）/ `user-confirmed`（用户确认）。
+- 置信度判定：代码路径 + DDL 推导 → high；LLM 语义推断 → medium/low。
+- 仅产出 **L0 骨架**（候选 BC + 聚合根候选 + API 表面总览）首轮必做；状态机/指令事件完整深化留 L1 按域渐进（v0.14 §63.3）。
+
+## Tool Guidance
+- Read/Grep/Glob 定位实体/状态/事件；Bash 仅限重新调用 recon-probe.sh（若基线未提供）。
+- 不修改任何文件，只读。
+- 规模阈值：模块<10 且 LOC<2万 可一次性全量；否则 L0+L1 分层渐进。
+
+## Structured Handoff（强制）
+你的 final response 必须是结构化交接：
+```
+{
+  status: "done" | "done_with_questions" | "blocked",
+  deliverable: <候选 BC/聚合根/状态机/指令事件 结构化摘要（含 provenance + 置信度）>,
+  blockers: [ { question, why_blocking, options[] } ],
+  outstanding_questions: [ { question, default_assumption } ],
+  summary: <3-5 行 gist>
+}
+```
+规则：非阻断疑问 → 按 default_assumption 继续 + 记入 outstanding_questions；阻断疑问（recon_json 与 root 均缺失、代码库为空）→ status=blocked + blockers[]，绝不强行猜测。

package/skills/workflow-orchestrator/references/feedback-loops.md

@@ -7,6 +7,8 @@
 | 回退路径 | 触发条件 | 操作 | 制品处置 |
 |---------|---------|------|---------|
 | **S3 → S2** | plan 暴露 PRD scope 问题 | PRD vN 内修订 + 记录变更履历（临时解除 frozen_downstream） | plan.md → plan.md.revN（归档），S3 重入时从零产出 |
+| **ARCH → S3** | 架构设计暴露 plan 拆分问题（v0.35.0 新增） | 调整拆分策略 | plan.md → plan.md.revN（归档）；iterations/vN/ 快照未完成部分丢弃 |
+| **S4 → ARCH** | 架构快照不覆盖 change 触及的 BC / 架构产物缺失（v0.35.0 新增） | 回 ARCH 阶段补快照 | iterations/vN/ 增量调整，change 拆分保留 |
 | **S4 → S3** | 依赖图不可执行/粒度不合理 | 调整拆分策略 | 已创建的 change 目录保留，重新拆分后增量调整 |
 | **S5 → S4** | 跨 change 冲突需要重新拆分 | 重新评估拆分方案 | 见下方「在途 change 处置」 |
 

package/skills/workflow-orchestrator/references/s1-path-router.md

@@ -21,7 +21,7 @@ S1 只做编排动作（需求选择、存在性检查、路径判断、阻塞
 |------|---------|------|------|
 | **全新需求** | 无现有 PRD，需求模糊 | → S2 | 完整流程 |
 | **续版需求** | 有 PRD vN，用户要加功能 | → S2（PRD vN+1） | 新版本迭代 |
-| **重新计划** | PRD 已冻结，plan 需调整 | → S3 | 跳过 brainstorm |
+| **重新计划** | PRD 已冻结，plan 需调整 | → S3 | 跳过 brainstorm；S3 完成后进 ARCH（产品级架构设计，v0.35.0）再拆 change |
 | **继续执行** | changes 已拆分，继续下一个 | → S4/S5 | 先输出状态恢复简报，用户确认后继续 |
 | **单 change 快速通道** | 需求极清晰，无需 PRD（仅限单一功能点、无 UI、无跨模块依赖的极小变更） | → 直接创建 change → workflow-start | 最轻量路径，无 PRD 锚点，**不可触发 S3→S2 回退** |
 | **紧急修复（Hotfix）** | bug/生产问题，需最小范围修复 | → 直接创建 change（type: hotfix，注入 bug 描述替代 PRD）→ workflow-start | closing 时强制补录复利 |

package/skills/workflow-orchestrator/references/s3-plan-pipeline.md

@@ -42,9 +42,10 @@ ce-plan 在 orchestrator pipeline 上下文中减少仪式开销，但**保留
 
 - plan 是否暴露了 PRD 的范围问题？
   - **是** → 回退 S2，触发 PRD vN 内修订（记录变更原因）。详见 feedback-loops.md「S3 → S2」
-  - **否** → 进 S4
+  - **否** → 进 ARCH（architecture 阶段，v0.35.0 产品级架构设计，见 state-model.md「architecture 阶段」）
 
 ## 完成条件
 
 - `prd/vN/plan.md` 已产出，含 change 拆分 + 依赖 DAG + 技术方向
 - `.team-flow/requirements/<req-id>/orchestrator.yaml` 中 S3 状态 = completed
+- 下一步：进入 ARCH 阶段，产出 `docs/architecture/iterations/vN/architecture.md` 后进 S4（v0.35.0）

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

@@ -14,9 +14,19 @@
 
 ## 步骤
 
+### 0. 架构就绪门禁（arch-readiness，v0.35.0 新增）
+
+> 设计依据：v0.14 §59.4。产品级架构快照必须覆盖 change 拆分触及的限界上下文，拆分审计才有架构依据。
+
+进入拆分前先校验：
+
+- **项目 arch_baseline 缺失（存量/重建未完成）** → WARN 不阻断（reason: 'project architecture baseline not established — S3.5 reconstruction pending'），提示先跑 S3.5 重建产出 L0 骨架。
+- **已建档项目** → 校验 `docs/architecture/iterations/vN/architecture.md` 存在且覆盖 plan.md 各 change 触及的全部 BC。不覆盖 → FAIL，回退 ARCH 阶段补快照（feedback-loops.md「S4 → ARCH」）。
+- **skip 物化**：ARCH 阶段显式跳过（iterations/vN/ 占位含 skipped 标记 + 理由）→ PASS。
+
 ### 1. 拆分质量审计（必选门禁，不可跳过）
 
-调用 `change-split-auditor` agent 对 `plan.md` 做拆分质量审计，输出审计报告（覆盖矩阵 / DAG 无环 / 粒度均衡 / 字段完整 / **拆分维度合规**）。质量自检清单：
+调用 `change-split-auditor` agent 对 `plan.md`（**+ `docs/architecture/iterations/vN/architecture.md` 作为架构依据**，v0.35.0）做拆分质量审计，输出审计报告（覆盖矩阵 / DAG 无环 / 粒度均衡 / 字段完整 / **拆分维度合规**）。质量自检清单：
 
 **必选约束**：审计 verdict = PASS 是 Step 3（创建脚手架）的前置条件。
 verdict = FAIL → 必须回退 S3 调整拆分后重新审计，不可绕过直接创建 change。

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

@@ -16,6 +16,7 @@
 
 - **迁移兼容**：检测到旧 `<root>/.workflow-orchestrator.yaml` 存在时，自动迁移到 `.team-flow/requirements/<req-id>/orchestrator.yaml` 并提示用户（一次性）。
 - **变更级状态**：各 change 的状态文件**当前仍为** `<change>/.team-flow.yaml`，检测逻辑不动；**计划 v1.0.0（P1-6 第二阶段）改名**为 `.team-flow.yaml`（对齐设计增强方案 v0.8 §18.3）。改名落地前，编排层与变更层一律以 `.team-flow.yaml` 为准。
+- **项目级架构状态（v0.35.0 新增）**：`.team-flow/arch-state.json`（架构阶段是产品/迭代级，不放 change 状态）。见下文「architecture 阶段」与「arch_baseline 豁免键」。
 
 ## registry.yaml Schema
 
@@ -42,6 +43,8 @@ phases:                               # 各阶段状态
   - { id: S1, status: completed, started_at: "...", completed_at: "...", artifacts: [...] }
   - { id: S2, status: active, started_at: "...", artifacts: [...] }
   - { id: S3, status: pending }
+  - { id: ARCH, name: 产品级架构设计, status: pending, skip: <迭代无结构性变更|null>, artifacts: [docs/architecture/iterations/vN/architecture.md] }
+  - { id: S4, status: pending }
 custom_phases: []                     # reserved
 replan_log:                           # 重规划履历
   - { seq: 1, trigger: "用户要求跳过原型", before: "S2→S3", after: "S2(skip-proto)→S3", approved_by: user }
@@ -71,6 +74,55 @@ prd_version: v1                       # PRD 版本
 - **阻塞**：active → blocked → active（S5 检测到 change 卡死）或 blocked → aborted
 - **终止**：任何非 completed 状态 → aborted（用户放弃编排）
 
+## architecture 阶段（S3.5，v0.35.0 新增）
+
+> 产品级架构设计阶段，位于 S3 计划之后、S4 拆分之前。设计依据：设计增强方案 v0.14 §59。
+
+**phase id**：`ARCH`；顶层 `workflow_phase: architecture`（语义 kebab-case）。
+**命名约定**：新阶段一律用 kebab-case 语义名（历史值保留不迁移，避免无价值 churn）。
+
+```yaml
+phases:
+  - { id: S3, status: completed }
+  - { id: ARCH, name: 产品级架构设计, workflow_phase: architecture,
+      status: completed, skip: null,
+      artifacts: [docs/architecture/iterations/vN/architecture.md] }
+  - { id: S4, status: pending }
+```
+
+**场景判定（入口三态）**：
+| 场景 | 判定输入 | S3.5 模式 |
+|------|---------|----------|
+| S0 全新项目 | 无代码库 | 正向设计（首轮不可跳过） |
+| S1 存量代码+无基线 | 有 src/，无 baseline.md | 先 workflow-bootstrap → 逆向重建 |
+| S2 存量+瘦锚点 | baseline.md + ARCHITECTURE 无 BC/聚合层 | 逆向重建（深化） |
+| S3 存量+跑过迭代 | baseline + changes/ + prd/vN/，无 arch_baseline | 逆向重建（首轮强制） |
+| S4 已有产品级架构 | arch_baseline 已打戳 + iterations/ | 正向设计（正轨） |
+
+**skip 条件（须物化）**：迭代无结构性变更（纯 bugfix/重构/不新增 BC 或聚合/不改变聚合边界或全局契约）。判定者 = **编排器 + 用户确认**（非 LLM 自判，防 v0.13 §54 绕过教训）。**skip 必须物化**：写入 `docs/architecture/iterations/vN/` 占位（含 skipped 标记 + 理由），guard 才放行——否则 hotfix/快速通道 change 会卡在 arch-readiness 上（v0.32.2 C1 死锁链同类）。
+
+**时间盒 + 深度分层**：时间盒 ≤1 天；非触及 BC 只维护锚点行，触及 BC 才做按域深化（v0.14 §60.4）。
+
+**输入输出契约**：
+- 输入：prd/vN/prd.md（frozen_downstream）+ plan.md + prototype/ + baseline.md + CONCEPTS.md + 现有全局基线（旧项目）
+- 输出：`docs/architecture/iterations/vN/architecture.md`（6 产物权威快照，预测态，provenance 标注）+ 产品级评审 verdict；**不触发全局覆盖写**（P1：预测态不进实际态）
+
+**门禁**（v0.14 §59.4）：
+| 门禁 | 挂点 | 校验 | 豁免 |
+|------|------|------|------|
+| 产品级评审门 | ARCH→S4 | architecture-reviewer product 视角 PASS | skip 时仍要物化标记 |
+| arch-readiness | S4 拆分 | iterations/vN/ 快照覆盖 change 触及的 BC | arch_baseline 缺失 → WARN 不 FAIL |
+| arch-snapshot | executing→closing | 本轮快照已落盘 | 在途 change legacy 豁免 |
+
+## arch_baseline 豁免键（v0.35.0 新增）
+
+完全复刻 v0.13 §48.1 schema_version 防污染模式（设计增强方案 v0.14 §59.4/§63.1）：
+
+- **位置**：`.team-flow/arch-state.json`（项目级状态；架构阶段是产品/迭代级，不放 change 的 `.team-flow.yaml`）
+- **内容**：`{ arch_baseline: "v0", established_at: "<date>", mode: "reconstruction" | "design", snapshot_root: "iterations/", baseline_prd_ref: "prd/vN/" }`
+- **防污染**：仅 `tf arch init` 写入；`tf state set`/rebuild/doctor 一律不得追加（缺失 = 存量信号）
+- **判定**：`arch_baseline == null` → arch-readiness/arch-snapshot 均 PASS + WARN（reason: 'project architecture baseline not established — S3.5 reconstruction pending'）
+
 ## 双层冻结语义（解决 §17.3 与 §17.9.1 矛盾）
 
 - **`frozen_downstream`**（S2 完成时设置）：下游阶段（S3/S4/S5）不可直接修改 PRD，只能通过回退到 S2 修改。**S3→S2 回退 = 临时解除 frozen_downstream**，S2 重新完成后恢复。