@xulthekl/team-flow 0.28.0 → 0.29.0

package/scripts/lib/cmd-state.mjs

@@ -26,6 +26,10 @@ const SETTABLE_FIELDS = [
   // Architecture design gate (v0.9 §26, v0.22.5 评审修复 F02)
   'arch_design_decision', 'arch_design_reason',
   'arch_design_timestamp', 'arch_design_artifacts',
+  // Architecture review (v0.28.1 §36 审查增强)
+  'arch_review_verdict', 'arch_review_rounds', 'arch_review_report',
+  // DP-A user confirmation gate (v0.29.0 §37)
+  'dp_a_result', 'dp_a_timestamp', 'dp_a_adjustments',
   // Compound engineering capture gate (v0.24.0 复利贯穿强制化)
   'compound_skipped',
 ];

package/scripts/lib/state-loader.mjs

@@ -43,6 +43,14 @@ const BUILTIN_DEFAULTS = {
   arch_design_reason: null,
   arch_design_timestamp: null,
   arch_design_artifacts: null,
+  // Architecture review (v0.28.1 §36 审查增强)
+  arch_review_verdict: null,
+  arch_review_rounds: null,
+  arch_review_report: null,
+  // DP-A user confirmation gate (v0.29.0 §37)
+  dp_a_result: null,
+  dp_a_timestamp: null,
+  dp_a_adjustments: null,
   // Compound engineering capture gate (v0.24.0 复利贯穿强制化)
   compound_skipped: null,
 };
@@ -120,6 +128,16 @@ export function writeState(changeDir, state) {
   lines.push(`arch_design_timestamp: ${state.arch_design_timestamp ?? 'null'}`);
   lines.push(`arch_design_artifacts: ${state.arch_design_artifacts ?? 'null'}`);
   lines.push('');
+  lines.push('# === Architecture review (v0.28.1 §36) ===');
+  lines.push(`arch_review_verdict: ${state.arch_review_verdict ?? 'null'}`);
+  lines.push(`arch_review_rounds: ${state.arch_review_rounds ?? 'null'}`);
+  lines.push(`arch_review_report: ${state.arch_review_report ?? 'null'}`);
+  lines.push('');
+  lines.push('# === DP-A user confirmation gate (v0.29.0 §37) ===');
+  lines.push(`dp_a_result: ${state.dp_a_result ?? 'null'}`);
+  lines.push(`dp_a_timestamp: ${state.dp_a_timestamp ?? 'null'}`);
+  lines.push(`dp_a_adjustments: ${state.dp_a_adjustments ?? 'null'}`);
+  lines.push('');
   lines.push('# === Compound engineering capture gate (v0.24.0) ===');
   lines.push(`compound_skipped: ${state.compound_skipped ?? 'null'}`);
 

package/skills/architecture-design/SKILL.md

@@ -136,6 +136,7 @@ changes/<name>/
 - **不**重复 Swagger 管理的内容：请求/响应 schema、错误码定义、参数明细等由 Swagger/OpenAPI 规范承载
 - frontmatter 须声明 `api_contract_manager: swagger`，表明详细契约由 Swagger 工具链管理
 - sql/ 目录中的 DDL 和 migration 脚本为独立可执行 `.sql` 文件，不嵌入 markdown 文档
+- **PRD 功能清单 → API 端点映射表（v0.29.0 §37 新增）**：在 api.md 中增加独立章节，逐条对照 `prd/vN/prd.md` 功能清单（如 F001_P0_P1 ~ P0_PN），映射每个功能点到对应的 API 端点。对于涉及子实体（明细/子项）的功能，必须确保独立 CRUD 端点存在——仅查询端点不覆盖"新增/编辑"功能。此映射表供 architecture-reviewer A4 交叉验证使用
 
 **下游消费**：
 - `architecture/architecture.md` → spec-writer：design.md Decisions 约束

package/skills/bug-investigator/SKILL.md

@@ -51,6 +51,66 @@ Scientific method: form a single hypothesis ("I think X is the root cause becaus
 
 3+ failed fixes = architectural problem. Each fix revealing new problems elsewhere = wrong architecture. Record: `tf state set <change-dir> dp_5_result <decision>`. Discuss with user before attempting more fixes.
 
+## Report Format
+
+Write the investigation report with this structure:
+
+```markdown
+# Bug Investigation Report
+
+## Summary
+[One-paragraph description of the bug and investigation outcome]
+
+## Symptom
+- **What happens:** [Exact observed behavior]
+- **Expected behavior:** [What should happen]
+- **Reproduction:** [Exact steps, commands, or conditions]
+- **Frequency:** [Always / intermittent / specific conditions]
+
+## Investigation Trail
+[Chronological record of what you investigated, in order]
+
+### Phase 1: Root Cause Investigation
+- Error messages analyzed: [details]
+- Recent changes checked: [git log summary, relevant commits]
+- Data flow traced: [path from symptom to source]
+- Component boundaries tested: [if applicable]
+
+### Phase 2: Pattern Analysis
+- Working examples found: [file references]
+- Key differences identified: [list]
+
+### Phase 3: Hypotheses Tested
+| # | Hypothesis | Test | Result |
+|---|-----------|------|--------|
+| 1 | [hypothesis] | [what you did] | Confirmed / Rejected |
+| 2 | ... | ... | ... |
+
+## Root Cause
+[Clear, specific statement of the root cause with evidence]
+- **Location:** [file:line]
+- **Mechanism:** [How the bug works, step by step]
+- **Evidence:** [What proves this is the cause]
+
+## Recommended Fix
+[Suggested approach — describe what to change and why, but do NOT implement it]
+- **Fix location:** [where to change]
+- **Fix approach:** [what to change]
+- **Test to add:** [regression test suggestion]
+- **Risk assessment:** [what could go wrong with this fix]
+
+## DP-5 Escalation
+[Only if 3+ hypotheses failed — architectural concern details]
+```
+
+## Writing Investigation Notes
+
+During investigation, you may write intermediate notes to track your progress:
+- Use a working file (e.g., `investigation-notes.md`) for scratch work
+- Record each hypothesis, test, and result as you go
+- This protects against losing your train of thought on complex investigations
+- Clean up or consolidate into the final report when done
+
 ## Red Flags — Return to Phase 1
 
 "Quick fix, investigate later" / "Just try changing X" / "Skip the test, I'll verify manually" / "It's probably X, let me fix that" / "I don't fully understand but this might work" / "One more fix attempt" (after 2+) / Proposing solutions before tracing data flow.
@@ -75,3 +135,18 @@ If truly environmental/timing-dependent/external: document what you investigated
 - **Parse failures**: Report raw output, ask for clarification — don't guess
 - **Missing files**: Escalate immediately — not a normal debugging scenario
 - **User interruption**: Re-read investigation report on resume, continue from last completed phase
+
+## Quality Standards
+
+1. **Evidence over intuition**: Every claim in your report must be backed by observable evidence (test output, code path, git history)
+2. **Specificity**: Name exact files, line numbers, functions, and values — not "somewhere in the auth module"
+3. **Completeness**: Document what you ruled OUT, not just what you found. Negative results are valuable.
+4. **Actionability**: Your recommended fix should be specific enough that an implementer can act on it without re-investigating
+5. **Honesty**: If you cannot determine root cause, say so explicitly and document what you DID investigate. 95% of "no root cause found" cases are incomplete investigation — but the remaining 5% are genuinely environmental/timing/external.
+
+## Edge Cases
+
+- **Environmental issues**: If the bug is environment-specific, document the environment differences and suggest environment normalization
+- **Timing/race conditions**: Document the timing window, suggest synchronization or defensive handling
+- **External dependencies**: If the root cause is in a third-party library, document the version, the specific behavior, and suggest workarounds or upstream issues
+- **Cannot reproduce**: Document everything you tried. Suggest monitoring/instrumentation for the next occurrence. Do NOT guess at a cause you cannot verify.

package/skills/code-reviewer/SKILL.md

@@ -86,3 +86,98 @@ Suggestion breaks existing functionality, reviewer lacks context, violates YAGNI
 - **Parse failures**: Report specific file, request regenerated review package
 - **Missing files**: Regenerate via `scripts/review-package`. Empty diff = nothing to review
 - **User interruption**: Re-read review report on resume, continue from next unreviewed batch
+
+---
+
+## Review Process (Agent Methodology)
+
+The code-reviewer agent follows this 6-step process:
+
+### Step 1: Gather Context
+
+1. Read `change-brief.md` to understand scope and constraints
+2. Read `specs/*.md` to understand requirements
+3. Read `design.md` to understand architectural decisions
+4. Get the list of changed files: `git diff --name-only BASE..HEAD` or from the change directory
+
+### Step 2: Spec Compliance Check
+
+For each requirement in specs/:
+1. Locate the corresponding implementation
+2. Check if the implementation faithfully reflects the spec
+3. Note any deviations (with justification or flag as Critical)
+4. Build a compliance matrix: spec requirement → implementation status
+
+### Step 3: Code Quality Review
+
+Check for:
+- **Readability**: Clear naming, appropriate comments, logical structure
+- **Maintainability**: DRY principles, appropriate abstraction, no code smells
+- **Error handling**: Proper exception handling, meaningful error messages
+- **Performance**: No obvious N+1 queries, no unnecessary loops, appropriate caching
+- **Security**: Input validation, SQL injection prevention, XSS prevention, auth checks
+
+### Step 4: Architecture Review
+
+Check for:
+- **Separation of concerns**: Each module/class has a single responsibility
+- **Dependency direction**: Dependencies flow inward (domain ← application ← infrastructure)
+- **Interface design**: Clean APIs, appropriate abstraction layers
+- **Scalability**: No obvious bottlenecks, appropriate use of async/queue for heavy operations
+- **Consistency**: Follows established patterns in the codebase
+
+### Step 5: Test Coverage Review
+
+Check for:
+- **Unit tests**: Each function/method has corresponding unit tests
+- **Integration tests**: API endpoints have integration tests
+- **Edge cases**: Tests cover boundary conditions, error cases
+- **Test quality**: Tests are meaningful (not just "it works"), assertions are specific
+
+### Step 6: Documentation Review
+
+Check for:
+- **Code comments**: Complex logic is explained
+- **API documentation**: Endpoints are documented (Swagger/OpenAPI)
+- **README updates**: User-facing changes are documented
+- **Change log**: Significant changes are noted
+
+## Severity Levels
+
+| Level | Meaning | Examples |
+|-------|---------|----------|
+| **Critical** | Must fix before merge | Spec violations, bugs, security issues, data loss risks |
+| **Important** | Should fix before next batch | Architecture problems, poor error handling, missing tests |
+| **Minor** | Nice to have, note for later | Code style, optimization opportunities, documentation polish |
+
+## Verdict Criteria
+
+| Verdict | Condition |
+|---------|-----------|
+| **PASS** | No Critical or Important findings |
+| **PASS_WITH_WARNINGS** | No Critical, but Important findings exist |
+| **FAIL** | Any Critical finding |
+
+## Calibration Rules
+
+1. **Evidence-based**: Every finding must cite specific file:line
+2. **Severity-appropriate**: Don't mark style issues as Critical
+3. **Constructive**: Provide actionable suggestions, not just complaints
+4. **Context-aware**: Consider the change scope and constraints
+5. **Spec-grounded**: Spec violations are always Critical (unless explicitly justified)
+
+## Critical Rules
+
+**DO:**
+- Read specs and design BEFORE reading implementation
+- Build an explicit spec compliance matrix
+- Cite file:line for every finding
+- Distinguish Critical (spec violation/bug) from Important (architecture/quality)
+- Give a clear, unambiguous verdict
+
+**DON'T:**
+- Guess at spec requirements not explicitly stated
+- Mark style issues as Critical (they're Minor)
+- Produce vague findings without file:line references
+- Skip the spec compliance check (it's the core deliverable)
+- Implement fixes (that's the implementer's job after your review)

package/skills/prototype/SKILL.md

@@ -103,6 +103,10 @@ prototype/
 ## 脚手架
 新建项目：`cp -r references/prototype-scaffold/ <project>/prototype/`，再按 `.team-flow/design-system/` 的设计系统填 token（缺设计系统先用 `/team-flow:design-system` 创建）。
 
+## prototype-builder agent 方法论（v0.28.1 §37，Agent/Skill 职责分离）
+
+`prototype-builder` agent 通过 `skills: [prototype]` 预加载本 SKILL.md。其详细构建方法论（Hard Constraints / Build Process Steps 0-4 / Seed Composition / P0-P2 Quality Self-Check / Structured Handoff / Deliverable Hard Gate / Decision-Point Interaction）已迁移至 `references/builder-methodology.md`，由 agent 在执行中按需 Read。
+
 ## 方法论参考与归因
 
 > ⚠️ **命名区分**：本 skill 负向清单中排除的「Open Design 桌面应用」（nexu-io/open-design 出品的 Electron 桌面设计工作台产品）与 `references/craft/anti-ai-slop.md` 借鉴的「nexu-io/open-design 开源设计方法论」**同名不同义**：

package/skills/prototype/references/builder-methodology.md

@@ -0,0 +1,138 @@
+# Builder Methodology（prototype-builder agent 详细方法论）
+
+> 从 agents/prototype-builder.md 提取的详细构建方法论（v0.28.1 §37 Agent/Skill 职责分离）。
+> Agent prompt 只保留 WHO/WHAT，详细 HOW 在此 reference 中。
+
+## Hard Constraints（零依赖 + 防漂移）
+
+1. **零外部依赖、可离线**：
+   - 无 CDN、无外部字体、无外部脚本/样式表。
+   - CSS 一律进 `<style>`，JS 一律进 `<script>`，页面内 `<div id="tweaks">` 控件替代云端工具栏。
+   - 资源仅来自 `prototype/assets/`（本地）。
+2. **复用设计系统 token，禁止内联样式漂移**：
+   - 渲染 `design-system.md` 的 token 到 `assets/design-tokens.css`（CSS 变量），所有页面/组件通过 `var(--token)` 引用。
+   - 颜色/间距/字号/圆角等一律走 token，**禁止**在页面里写死 `#hex` / `padding: 13px` 之类非 token 值。
+   - 复用 `components/` 已有组件；新增组件**先沉淀进 design-system 再引用**（如发现 design-system 缺组件，记入 outstanding_questions，不擅自新建漂移组件）。
+3. **遵循 confirmed_plan**：页面清单、组件清单、导航流以确认方案为准，不自行增删页面。
+
+## Build Process
+
+### Step 0: Precondition Gate（阻断检查）
+
+Before writing anything, verify:
+- `design_system_path` exists and is readable → if missing/unreadable, return `status: blocked` (blocker: 设计系统缺失，需先派 design-system-architect).
+- `confirmed_plan` is present and marked confirmed → if absent or explicitly unconfirmed, return `status: blocked` (blocker: 原型方案未确认，需主代理先完成方案评审 + 人工确认).
+- `prd_path` readable → if missing, `status: blocked` (blocker: PRD 缺失).
+
+Do NOT proceed past a failed gate.
+
+### Step 1: Render Design Tokens
+
+1. Read `.team-flow/design-system/<variant>.md` + `base.md`（合并 base 品牌层 + 变体端特有层：9 段 schema + palette 5 方向调色板 + aliases 别名层 + extensions 待提升清单）.
+2. Generate/refresh `assets/design-tokens.css` with CSS custom properties for every token (colors incl. palette 50–900 steps, spacing scale, font scale, radii, shadows, durations, A2 派生状态色, B-slot 别名).
+3. **完整性约束**：design-tokens.css 必须声明全部 A1+A2+B-slot token——agent 把单份 `:root` 块粘进单个 `<style>`，无全局级联，缺一个 token 规则悄悄失效。可运行 `node scripts/guard/design-token-guard.mjs <design-system.md> <design-tokens.css>` 自检。
+
+### Step 1.5: Seed Composition（种子优先，v0.18.0）
+
+**不从零写 CSS——从种子模板 + 骨架库组合。**
+
+1. 读 `references/template.html`（至少到 `</style>` 结尾）+ 读 `references/layouts.md`（8 个 section 骨架 + 类清单契约 + 页面类型节奏表）。
+2. **先选 section 列表再写文案**：按页面类型查节奏表（管理后台列表页 / 表单页 / 仪表盘 / Landing / 文档索引），为每个页面选定 section 组合。选定后**用一句话向主代理报出 section 列表**（写入 `outstanding_questions`，question = "页面 X 计划用 section 组合：hero → log → stats，此刻改向便宜，而不是 200 行 HTML 之后"，default_assumption = 按此组合继续）。
+3. 从 `layouts.md` 粘贴对应骨架到 `<main id="content">`，替换 `[REPLACE]` 槽为 PRD 中的真实、具体文案。
+   - **"槽位空着说明选错了布局，换一个，不许编文案。"**
+   - 类清单契约：只用 template.html `<style>` 中已定义的类；够不到的类先在页面 `<style>` 定义，绝不凭空发明全局类。
+4. 纪律约束（来自 layouts.md 各骨架）：stats ≤3 个且不编造指标；quote 每页 ≤1 个；accent 每屏 ≤2 处；section 节奏交替（禁止连续同类型）。
+
+### Step 2: Build Structure
+
+```
+prototype/
+├── index.html          # 入口 / 全局导航（列出所有页面，可达）
+├── pages/              # 每个 confirmed_plan 页面一个 HTML
+├── components/         # 可复用组件（统一设计系统 token）
+├── assets/             # design-tokens.css / design-tokens.js
+└── flow.md             # 页面跳转 / 用户流（与 PRD 导航一致）
+```
+
+For each page in `confirmed_plan`:
+- Create `pages/<slug>.html`, self-contained (inline `<style>`/`<script>` referencing `var(--token)`).
+- Wire navigation links so every page is reachable from `index.html`.
+- Reflect PRD §4 画面 / §7 功能清单 / §8.4 字段 / §8.2 交互 in the page content.
+
+**大产出分片纪律（v0.20.0，防输出预算耗尽/单次 Write 截断）**：规划要**克制**——数据模型/改善方向等推演够用即可，不要把大量输出预算耗在 thinking 阶段的详尽规划上，留足预算给真正 Write 产物。对超大文件（经验阈值 ~800 行，如带完整数据层的 `index.html`）**默认分片写**：
+
+1. 先 `Write` 主体骨架（HTML 结构 + `<style>` token 引用 + 导航 + 空的 `<script>` 数据/渲染占位），落盘一个**可运行的最小入口**；
+2. 再 `Edit` 分段追加：数据层 → 渲染层 → 各页面/组件，每段追加后文件保持完整；
+3. **任何一刻被中断，已落盘的骨架都构成有效进展**——配合下方 Deliverable Hard Gate，绝不出现"规划完、产物没写、却报 done"。
+
+### Step 3: Flow + Consistency
+
+1. Write/refresh `flow.md` describing page transitions / user flows, consistent with PRD navigation.
+2. Self-check (Bash): grep for hardcoded colors/spacing outside tokens; grep for any `http://`/`https://`/CDN/`@import` external references — if found, remove and replace with tokens/local.
+3. Verify every confirmed page file exists and is linked from `index.html`.
+
+### Step 3.5: P0/P1/P2 Quality Self-Check（v0.18.0）
+
+逐项过 `references/checklist.md`。**P0 用 Bash grep 机械验证**，任一失败 → 自行修正后再提交：
+
+- 裸 hex 检查：grep `#[0-9a-fA-F]{3,8}` 在 `:root{}` 块外 = 0 命中
+- 靛蓝黑名单：grep `#6366f1\|#4f46e5\|#4338ca\|#3730a3\|#8b5cf6\|#7c3aed\|#a855f7` = 0 命中
+- emoji 图标：grep `✨\|🚀\|🎯\|⚡\|🔥\|💡` 在 h*/button/li 中 = 0 命中
+- 填充文案：grep `lorem\|功能一\|功能二\|功能三\|placeholder\|示例文本` = 0 命中
+- scrollIntoView：grep `scrollIntoView` = 0 命中（用 `scrollTo({...})` 替代）
+- data-testid：每个顶层 `<section>` 有 `data-testid` 属性
+- accent 超限：每屏 `var(--accent)` 使用 ≤2 处
+
+P1 逐项自查（节奏交替 / 标题 ≤14 词 / CTA 说明动作 / hover 态）；P2 酌情加分。
+**Anti-slop 两秒直觉检查**：截图后外人能认出是哪个产品？看不出 → 把一个特性格换成只有这个产品才有的东西，去掉一个 accent。
+
+### Step 4: 修正轮（when review_findings provided）
+
+- Address each finding on the specific page/component cited.
+- Keep token reuse; do not introduce new inline drift while fixing.
+- Do not touch unrelated pages.
+
+## data-testid Discipline（可选，config 驱动）
+
+When the project enables E2E (`prototype.e2e: true` or stated in the plan):
+- 场景级 `S-{nn}-{slug}` / 页面级 `P-{xx}-{slug}` 必带；元素级仅关键交互锚点（提交/主操作/状态切换）。
+- `data-testid` 是纯 HTML 属性，零依赖，守离线约束。
+When not enabled, do not over-tag.
+
+## Structured Handoff（强制，主代理据此编排）
+
+你的 final response 必须是如下结构化交接（JSON 风格描述即可，主代理据此编排）：
+```
+{
+  status: "done" | "done_with_questions" | "blocked",
+  deliverable: <prototype 入口绝对路径 + 页面/组件清单>,
+  blockers: [ { question, why_blocking, options[] } ],          # 阻断项：无法继续、必须主代理裁决
+  outstanding_questions: [ { question, default_assumption } ],  # 非阻断：已按默认假设继续，回主代理批量确认
+  summary: <3-5 行 gist>
+}
+```
+
+### Deliverable Hard Gate（v0.20.0，修订设计 §18.1.1——禁止谎报完成）
+
+**返回 `status: done` 的硬前置：你声明的 `deliverable`（`<abs>/prototype/index.html`）必须已 `Write` 落盘且非空。** 终态交接前**必须**自检（Bash）：
+
+```bash
+test -f <prototype_root>/index.html && test -s <prototype_root>/index.html && echo OK
+```
+
+- 自检 **OK** 才可返回 `done` / `done_with_questions`。
+- 若核心产物（index.html / confirmed_plan 要求的页面）**尚未落盘或非空**——无论原因是输出预算将尽、单次 Write 担心截断、还是规划过重——**禁止返回 `done`**。改为返回 `status: blocked`，blocker 写明：「核心产物 `<文件>` 未落盘/未完成，原因 `<输出预算不足 | 单次 Write 过大>`，请 resume 续写」，由主代理裁决续跑。
+- **绝不把中间状态汇报（如 "Scaffold is ready… Next I'll write index.html…"）当作终态交接返回 done**——那只是进度，不是产物。
+
+规则：非阻断疑问（如某页面状态展示方式未明确→按合理默认实现）→ 按 default_assumption 继续跑完，记入 outstanding_questions（status=done_with_questions）；
+阻断疑问（Precondition Gate 任一输入缺失：设计系统/confirmed_plan/PRD，**或核心产物未落盘**）→ 立即停止，返回 status=blocked + blockers[]，绝不臆造 token 或臆测页面，**绝不谎报 done**。你不能调用 AskUserQuestion。
+
+## Decision-Point Interaction（v0.21.0，设计 §22.1.1 stop-and-resume）
+
+你**没有 AskUserQuestion**。绘制中遇到**无法用 default_assumption 化解、必须用户/主代理拍板**的决策点（如：某关键交互/布局有两个合理走向需用户选、方案暴露 PRD 歧义需澄清），**不要猜、也不要直接 terminate 丢上下文**，走中继：
+
+1. **发问即停**：`SendMessage(to: "main")` 发结构化提问 `{ question, why, options[] }`，随后**停止**（任务 completed）。末条消息明示「已发问、等待主代理回传后续跑」——让主代理识别为中继请求，**不是终态交接**（区别于上面的 `done/blocked`）。
+2. **被唤醒续跑**：主代理代问用户后会 `SendMessage` 回传答案并**自动 resume 你**，你带答案从断点继续绘制（上下文经 transcript 保留）。
+3. **应答校验（正确优先）**：收到回传时核对「这是否对应我实际发出的提问」；**不匹配（无主答案/串线）→ 拒绝将错就错**，按 default_assumption 继续或重新发问，并在 summary 标注。
+
+**边界**：能用 `default_assumption` 化解的非阻断疑问 → 照旧跑完记入 `outstanding_questions`（不必发问）；Precondition Gate 输入缺失等硬阻断 → 照旧 `blocked` 终态返回。stop-and-resume **仅用于"需真实用户决策、且默认假设不安全"的中途点**。harness 不支持 resume 时，降级为 `blocked` + 主代理携答案重派。

package/skills/workflow-orchestrator/SKILL.md

@@ -176,6 +176,7 @@ plan_hash: sha256:<plan.md 内容摘要>    # 检测产品层改动后变更层
 - **路由是建议非决定**：S1 路由判断必须用户确认；重规划必须 DP-R 阻塞确认
 - **回退必写 replan_log**：active → pending 回退必须记录；受影响制品归档为 .revN，重入不读旧制品
 - **不阻断流程**：所有复利操作为 advisory 级，INDEX.md 读取失败时静默跳过
+- **Artifact Ownership — 主代理不得直接修改子代理产物** (v0.29.0 §37)：子代理是其产物的唯一负责人（architecture-design → `architecture/` 目录，spec-writer → `proposal.md`/`specs/`/`design.md`/`tasks.md`，contract-builder → `execution-contract.md`，prototype-builder → `prototype/` 目录）。主代理（workflow-orchestrator）不得通过 Read + Edit/Write 直接修改子代理的产物文件。修改必须通过 `SendMessage` 恢复原子代理（优先）或启动新子代理执行。例外：仅当子代理无法启动且用户明确授权时，主代理可直接修改，但必须在修改后重新触发对应的 review 验证。编排层自己负责的产物（change-brief.md、orchestrator.yaml、审计报告落盘）不受此限制
 
 ## Output Standard
 

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

@@ -1,7 +1,8 @@
-# S4 拆分验证与分发（v0.7 重写，v0.17.0 审计必选）
+# S4 拆分验证与分发（v0.7 重写，v0.17.0 审计必选，v0.29.0 命名规范）
 
 > 原 v0.5「拆分与分发」。v0.7 新增拆分质量审计与并行策略。设计依据：设计增强方案 v0.7 §17.2 / §17.8。
 > v0.17.0 变更：change-split-auditor 审计由隐含步骤升级为「必选门禁」，PASS 前不可创建 change 脚手架。change_dag 字段 `spec_dir` 更名为 `change_dir`，路径修正为 `changes/<change-name>/`。
+> v0.29.0 变更：change 目录命名增加 PRD 版本号前缀（`changes/v1-C1-domain-policy/`），change_dag 增加 `prd_version` 字段，S5 按版本分组展示。
 
 ## 编排层 vs 执行层
 
@@ -36,11 +37,24 @@ verdict = FAIL → 必须回退 S3 调整拆分后重新审计，不可绕过直
 
 按 plan 中的 change 拆分方案，为每个 change 创建目录并初始化状态文件：
 
+**命名规范（v0.29.0）**：`changes/<prd-version>-<C-ID>-<kebab-name>/`
+
 ```bash
-mkdir -p changes/<change-name>
-tf state init changes/<change-name>
+# 格式：changes/v{N}-C{n}-{kebab-name}/
+# 示例：
+mkdir -p changes/v1-C1-domain-policy
+tf state init changes/v1-C1-domain-policy
+
+mkdir -p changes/v1-C2-policy-management
+tf state init changes/v1-C2-policy-management
 ```
 
+**命名规则**：
+- `v{N}`：创建时的 PRD 版本号（取自 orchestrator.yaml 的 `prd_version`），**创建后不变**（即使后续 PRD 升版，已创建的 change 目录名不改）
+- `C{n}`：plan.md 中的 C-ID 稳定编号（never renumbered）
+- `{kebab-name}`：plan.md 中 `### C{n}. [Name]` 的 kebab-case 形式
+- 续版需求（vN+1）新增的 change 使用新版本号前缀，与旧版本 change 天然区分
+
 > ⚠️ **路径约束**：change 脚手架目录固定为项目根 `changes/<change-name>/`。
 > 不要与 `specs/<cap>/`（change 内部行为规格目录）或 `architecture/`（change 内部架构设计目录）混淆。
 > 不要放入 `.team-flow/`（仅存产品级编排状态）。
@@ -88,7 +102,20 @@ plan_hash: sha256:<plan.md 内容摘要>    # 检测产品层改动后变更层
 
 ### 4. 写入 change_dag
 
-把每个 change 的 id / change_dir / state_file / depends_on / priority / parallel_group / status 写入 `.team-flow/requirements/<req-id>/orchestrator.yaml` 的 `change_dag`。详见 state-model.md「change_dag 结构」。
+把每个 change 的 id / change_dir / state_file / depends_on / priority / parallel_group / status / **prd_version**（v0.29.0 新增）写入 `.team-flow/requirements/<req-id>/orchestrator.yaml` 的 `change_dag`。详见 state-model.md「change_dag 结构」。
+
+**change_dag 条目格式（v0.29.0）**：
+```yaml
+change_dag:
+  - id: C1
+    change_dir: changes/v1-C1-domain-policy/
+    state_file: changes/v1-C1-domain-policy/.team-flow.yaml
+    depends_on: []
+    priority: 1
+    parallel_group: null
+    status: pending
+    prd_version: v1              # v0.29.0 新增：创建时的 PRD 版本号
+```
 
 ### 5. 分发
 
@@ -102,7 +129,7 @@ Change C1 已就绪，运行 /workflow-start 进入变更级流程。
 ## 完成条件
 
 - change-split-auditor 审计 verdict = PASS（必选门禁已通过，含 v0.9 D5 拆分维度合规）
-- 所有 change 目录已创建在项目根 `changes/` 下（非 `specs/` 或 `.team-flow/`），`.team-flow.yaml` 已初始化
+- 所有 change 目录已创建在项目根 `changes/` 下（非 `specs/` 或 `.team-flow/`），**命名符合 `v{N}-C{n}-{kebab-name}` 规范**（v0.29.0），`.team-flow.yaml` 已初始化
 - 每个 change 目录已落盘 `change-brief.md`（v0.9 交接物，含 scope/AC/技术方向/frontmatter）
-- `.team-flow/requirements/<req-id>/orchestrator.yaml` 的 `change_dag` 已填充
+- `.team-flow/requirements/<req-id>/orchestrator.yaml` 的 `change_dag` 已填充（含 `prd_version` 字段）
 - S4 状态 = completed，已告知用户执行顺序

package/skills/workflow-start/SKILL.md

@@ -55,8 +55,17 @@ Validate mode against artifact content. If hotfix/tweak criteria not met → upg
 ### Route to need-explorer
 Change is fuzzy, scope unclear, comparing options, no stable change name.
 
-### Route to architecture-design (v0.9 §26)
-Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before spec-writer. Dispatch `architecture-design` as sub-agent; after return, run reasonableness check and write yaml. Full protocol in `references/routing-rules.md`「Route to architecture-design」.
+### Route to architecture-design (v0.9 §26, v0.28.1 §36 审查增强, v0.29.0 §37 DP-A 确认门)
+Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before spec-writer.
+
+**Four-step protocol (MUST execute in order)**:
+
+1. **Dispatch**: `architecture-design` as sub-agent → returns `decision` + `reason` + `artifacts`
+2. **Auto-review** (decision=required 时触发): 校验产物文件存在且非空 → dispatch `architecture-reviewer` sub-agent → FAIL 则循环修正（≤3 轮 + 收敛检测，不收敛转人工）→ 报告落盘 `changes/<name>/architecture/auto-review.md`
+3. **Reasonableness check + state write**: PASS/PASS_WITH_WARNINGS → write `arch_design_decision` + `arch_review_*` to yaml; skipped + brief 含架构关键词 → BLOCK; required + artifacts 缺失 → BLOCK; required + auto-review FAIL → BLOCK
+4. **DP-A 用户确认门（v0.29.0 §37）**: 输出架构决策摘要 → AskUserQuestion 确认 → 需要调整时转交子代理修改（禁止主代理直接修改）→ 修改后重新 auto-review → 回到本步骤重新确认。含项目规范变更提示（advisory）。详见 `references/routing-rules.md`「Step 4: DP-A」
+
+Full protocol in `references/routing-rules.md`「Route to architecture-design」.
 
 ### Route to spec-writer
 Guard: `tf runtime guard check <dir> exploring specifying --json` → fail = BLOCK. **arch_design_decision must not be null** → fail = BLOCK (v0.9 §26). User knows what they want, artifacts missing/incomplete.
@@ -135,6 +144,9 @@ Use content inspection, not timestamps.
 - No auto-abandon without user confirmation
 - No merging delta specs from abandoned change
 - **No routing to spec-writer without architecture-design gate pass** (v0.9 §26): `arch_design_decision` must be `required` or `skipped` (not `null`). hotfix/tweak 不豁免
+- **No arch state write without auto-review PASS** (v0.28.1 §36): when `decision: required`, auto-review MUST complete with PASS or PASS_WITH_WARNINGS before writing `arch_design_decision` to yaml. FAIL → loop fix (≤3 rounds) or escalate to human
+- **No routing past DP-A without user confirmation** (v0.29.0 §37): architecture-design 三步协议完成后，必须经 DP-A 用户确认门（AskUserQuestion）才能路由到 spec-writer。用户选择"需要调整"时，修改必须通过子代理执行，修改后重新 auto-review + 重新 DP-A 确认
+- **Artifact Ownership — 主代理不得直接修改子代理产物** (v0.29.0 §37): 子代理是其产物的唯一负责人（architecture-design → `architecture/` 目录，spec-writer → `proposal.md`/`specs/`/`design.md`/`tasks.md`，contract-builder → `execution-contract.md`）。主代理（workflow-start）不得通过 Read + Edit/Write 直接修改子代理的产物文件。修改必须通过 `SendMessage` 恢复原子代理（优先）或启动新子代理执行。例外：仅当子代理无法启动且用户明确授权时，主代理可直接修改，但必须在修改后重新触发对应的 review 验证
 
 ## State Writes (v0.22.5 F06 修复)
 
@@ -154,19 +166,29 @@ workflow-start 负责写入以下字段到 `.team-flow.yaml`：
 - `dp_7_*`：其他决策点
 
 **架构设计门控字段**（v0.9 §26，v0.22.5 F02 修复）：
-- `arch_design_decision`：`required` | `skipped`（architecture-design 子代理返回，workflow-start 经 reasonableness check 后写入）
+- `arch_design_decision`：`required` | `skipped`（architecture-design 子代理返回，workflow-start 经 auto-review + reasonableness check 后写入）
 - `arch_design_reason`：判断理由
 - `arch_design_timestamp`：ISO 8601 时间戳（UTC）
 - `arch_design_artifacts`：产出路径列表（required 时必填，skipped 时为空）
 
-**职责边界**：architecture-design 负责判断+产出，workflow-start 负责 reasonableness check + 状态写入。详细写入命令见 `references/routing-rules.md`「Route to architecture-design」。
+**架构审查字段**（v0.28.1 §36，decision=required 时写入）：
+- `arch_review_verdict`：`PASS` | `PASS_WITH_WARNINGS`（auto-review 最终判定）
+- `arch_review_rounds`：审查轮次（1-3）
+- `arch_review_report`：`architecture/auto-review.md` 路径
+
+**DP-A 确认门字段**（v0.29.0 §37，DP-A 用户确认后写入）：
+- `dp_a_result`：`confirmed` | `adjustment_requested`（用户确认结果）
+- `dp_a_timestamp`：ISO 8601 时间戳（UTC）
+- `dp_a_adjustments`：用户调整意见摘要（adjustment_requested 时必填，confirmed 时为空）
+
+**职责边界**：architecture-design 负责判断+产出，architecture-reviewer 负责 6 维度审查，workflow-start 负责编排三步协议（dispatch → auto-review → reasonableness check）+ 状态写入。详细写入命令见 `references/routing-rules.md`「Route to architecture-design」。
 
 ## Output Standard
 
 Always state: (1) current detected state, (2) why (cite file/content/condition), (3) which skill should run next. If blocking, explain missing artifact/approval.
 
 Decision point references when routing:
-- architecture-design → DP-A（架构设计判断门，v0.9 §26）, contract-builder → DP-3, build-executor → DP-4, bug-investigator (escalation) → DP-5, release-archivist (verification failure) → DP-6, release-archivist → DP-7
+- architecture-design → DP-A（架构设计用户确认门，v0.9 §26 判断门 + v0.29.0 §37 用户确认门）, contract-builder → DP-3, build-executor → DP-4, bug-investigator (escalation) → DP-5, release-archivist (verification failure) → DP-6, release-archivist → DP-7
 
 ## Exception Handling
 

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

@@ -5,7 +5,7 @@
 ## Route to need-explorer
 Change is fuzzy, scope unclear, comparing options, no stable change name.
 
-## Route to architecture-design (v0.9 §26, v0.11 §34 审查增强)
+## Route to architecture-design (v0.9 §26, v0.11 §34 审查增强, v0.28.1 §36 主干补强, v0.29.0 §37 DP-A 确认门)
 
 Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before spec-writer.
 
@@ -68,10 +68,106 @@ tf state set <change-dir> arch_design_reason "<reason>"
 tf state set <change-dir> arch_design_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 # if required:
 tf state set <change-dir> arch_design_artifacts "architecture/architecture.md,architecture/database.md,architecture/api.md"
+# if required + auto-review completed (v0.28.1 §36):
+tf state set <change-dir> arch_review_verdict "<PASS|PASS_WITH_WARNINGS>"
+tf state set <change-dir> arch_review_rounds "<N>"
+tf state set <change-dir> arch_review_report "architecture/auto-review.md"
 ```
 
 **hotfix / tweak 不豁免**：同样过 architecture-design 子代理判断门（hotfix 可能正是架构缺陷导致）。
 
+### Step 4: DP-A 用户确认门 (v0.29.0 §37)
+
+> **设计动机**：v0.28.1 的三步协议是全自动闭环（dispatch → auto-review → state write → 路由下一步），缺少人工审批环节。用户在架构设计完成后无法确认或提出调整意见，被迫手动打断流程。DP-A 在 Step 3 之后、路由 spec-writer 之前插入结构化用户确认门。
+
+Step 3 reasonableness check + state write 完成后，**必须**执行 DP-A：
+
+**4a. 输出架构决策摘要**：
+
+```
+📐 架构设计完成 — 决策摘要
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+判定：{decision} ({reason})
+审查：{arch_review_verdict}（{arch_review_rounds} 轮）
+
+聚合定义：
+  {列出新增/修改的聚合及聚合根}
+
+限界上下文：
+  {列出 BC 边界变更}
+
+API 端点概览：
+  {端点总数} 个（Command: {n}, Query: {n}）
+  {列出关键端点}
+
+DB 变更概览：
+  {新增/修改的表数量}
+
+ADR 列表：
+  {列出关键架构决策记录}
+
+产物路径：
+  - changes/<name>/architecture/architecture.md
+  - changes/<name>/architecture/database.md
+  - changes/<name>/architecture/api.md
+  - changes/<name>/architecture/auto-review.md
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**4b. 项目规范变更提示（advisory，不阻断）**：
+
+在摘要末尾附加：
+```
+📋 项目规范变更检查（advisory）：
+  本次架构设计是否引入了新的项目级规范？
+  （如：新模块不使用 CQRS、Mapper 放 domain 等）
+  如是，请确认已更新 docs/architecture/ 相关文档
+  （ARCHITECTURE.md / baseline.md / CONCEPTS.md）。
+```
+
+**4c. AskUserQuestion 确认**：
+
+```
+AskUserQuestion:
+  question: "架构设计确认？"
+  options:
+    [A] "确认，进入 spec-writer"（推荐）
+    [B] "需要调整（列出调整点）"
+    [C] "需要查看详细产物（给出文件路径）"
+```
+
+**4d. 处理用户选择**：
+
+- **选择 A（确认）**：
+  ```bash
+  tf state set <change-dir> dp_a_result "confirmed"
+  tf state set <change-dir> dp_a_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+  tf state set <change-dir> dp_a_adjustments ""
+  ```
+  → 路由到 spec-writer
+
+- **选择 B（需要调整）**：
+  1. 记录用户调整意见
+  2. **通过子代理修改（禁止主代理直接 Edit 架构产物）**：
+     - 优先：`SendMessage(to: <原 architecture-design 子代理 ID>)` 发送修复指令，传入调整意见
+     - 子代理不可恢复时：启动新 architecture-design 子代理，传入：调整意见 + 原产物路径 + auto-review 报告
+  3. 子代理修改完成后，**重新触发 auto-review**（即使之前已 PASS）
+  4. auto-review PASS 后，更新 yaml 状态（arch_review_verdict / arch_review_rounds）
+  5. 回到 Step 4a 重新输出摘要 + 重新确认
+  ```bash
+  tf state set <change-dir> dp_a_result "adjustment_requested"
+  tf state set <change-dir> dp_a_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+  tf state set <change-dir> dp_a_adjustments "<调整意见摘要>"
+  ```
+
+- **选择 C（查看详细产物）**：
+  输出文件路径列表，等待用户阅读后重新 AskUserQuestion（回到 4c）
+
+**⛔ 反模式（禁止）**：
+- 主代理直接 Read + Edit `architecture/*.md` 文件（违反 Artifact Ownership 规则）
+- 跳过 DP-A 直接路由 spec-writer
+- 用户选择 B 后不重新 auto-review 就直接重新确认
+
 ## Route to spec-writer
 Guard: `tf runtime guard check <dir> exploring specifying --json` → fail = BLOCK.
 **arch_design_decision must not be null** → fail = BLOCK（architecture-design gate not passed，v0.9 §26）。