@guanlin4924/devflow-pi 0.1.94 → 0.1.95

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/tc_hash.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""RFC 8785 JSON Canonicalization Scheme (JCS) and the single tc_sha256 implementation.
+
+tc_sha256 = lowercase hex SHA-256 of JCS(node.data).  Generators, validators and
+approval pins must call this module; the Runtime only echoes the value back.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import sys
+from typing import Any
+
+
+_ESCAPES = {'"': '\\"', "\\": "\\\\", "\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+
+
+def _string(value: str) -> str:
+    out = ['"']
+    for char in value:
+        if char in _ESCAPES:
+            out.append(_ESCAPES[char])
+        elif ord(char) < 0x20:
+            out.append(f"\\u{ord(char):04x}")
+        elif 0xD800 <= ord(char) <= 0xDFFF:
+            raise ValueError("lone surrogate cannot be canonicalized")
+        else:
+            out.append(char)
+    out.append('"')
+    return "".join(out)
+
+
+def _number(value: int | float) -> str:
+    """ECMAScript Number.prototype.toString for an IEEE-754 double (RFC 8785 §3.2.2.3)."""
+    if isinstance(value, int):
+        converted = float(value)
+        if int(converted) != value:
+            raise ValueError(f"integer {value} is not exactly representable as an IEEE-754 double")
+        value = converted
+    if math.isnan(value) or math.isinf(value):
+        raise ValueError("NaN and Infinity are not valid JSON numbers")
+    if value == 0:
+        return "0"
+    sign = "-" if value < 0 else ""
+    text = repr(abs(value))  # shortest round-trip digits
+    mantissa, _, exponent = text.partition("e")
+    integer, _, fraction = mantissa.partition(".")
+    raw = integer + fraction
+    leading = len(raw) - len(raw.lstrip("0"))
+    digits = raw.lstrip("0").rstrip("0")
+    point = len(integer) + int(exponent or 0) - leading  # value = 0.digits * 10**point
+    count = len(digits)
+    if count <= point <= 21:
+        body = digits + "0" * (point - count)
+    elif 0 < point <= 21:
+        body = digits[:point] + "." + digits[point:]
+    elif -6 < point <= 0:
+        body = "0." + "0" * (-point) + digits
+    else:
+        power = point - 1
+        suffix = f"e{'+' if power >= 0 else '-'}{abs(power)}"
+        body = (digits if count == 1 else digits[0] + "." + digits[1:]) + suffix
+    return sign + body
+
+
+def _utf16_key(key: str) -> list[int]:
+    encoded = key.encode("utf-16-be")
+    return [int.from_bytes(encoded[index:index + 2], "big") for index in range(0, len(encoded), 2)]
+
+
+def _serialize(value: Any, out: list[str]) -> None:
+    if value is None:
+        out.append("null")
+    elif value is True:
+        out.append("true")
+    elif value is False:
+        out.append("false")
+    elif isinstance(value, (int, float)):
+        out.append(_number(value))
+    elif isinstance(value, str):
+        out.append(_string(value))
+    elif isinstance(value, (list, tuple)):
+        out.append("[")
+        for index, item in enumerate(value):
+            if index:
+                out.append(",")
+            _serialize(item, out)
+        out.append("]")
+    elif isinstance(value, dict):
+        if not all(isinstance(key, str) for key in value):
+            raise ValueError("object keys must be strings")
+        out.append("{")
+        for index, key in enumerate(sorted(value, key=_utf16_key)):
+            if index:
+                out.append(",")
+            out.append(_string(key))
+            out.append(":")
+            _serialize(value[key], out)
+        out.append("}")
+    else:
+        raise ValueError(f"unsupported JSON value type: {type(value).__name__}")
+
+
+def canonicalize(value: Any) -> bytes:
+    out: list[str] = []
+    _serialize(value, out)
+    return "".join(out).encode("utf-8")
+
+
+def jcs_sha256(value: Any) -> str:
+    return hashlib.sha256(canonicalize(value)).hexdigest()
+
+
+def tc_sha256(data: Any) -> str:
+    if not isinstance(data, dict):
+        raise ValueError("TC data must be an object")
+    return jcs_sha256(data)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Print tc_sha256 (JCS SHA-256) of a JSON document read from a file or stdin.")
+    parser.add_argument("path", nargs="?")
+    args = parser.parse_args()
+    text = open(args.path, encoding="utf-8").read() if args.path else sys.stdin.read()
+    print(jcs_sha256(json.loads(text)))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/test_command_policy.py

@@ -6,18 +6,25 @@ from pathlib import Path
 from typing import Any
 import json
 import os
+import re
 import sqlite3
 
+from approval_store import devflow_home
 
-def database_toolchain(root: Path) -> list[str] | None:
+
+PACKAGE_RUNNERS = {"npm", "pnpm", "yarn"}
+RUNTIME_MARKERS = ("devflow-quality/runtime/playwright", "runtime-manifest.json", "runner.spec.mjs", "devflow-test-dsl-v1.schema.json")
+MARKDOWN_ROW_RE = re.compile(r"^\|(.+)\|\s*$")
+
+
+def database_toolchain_facts(root: Path) -> list[dict[str, Any]] | None:
     manifest_path = root / ".devflow" / "project.json"
     if not manifest_path.is_file():
         return None
     try:
         project_id = json.loads(manifest_path.read_text(encoding="utf-8"))["projectId"]
-        data_home = Path(os.environ.get("DEVFLOW_HOME", Path.home() / ".devflow-pi"))
-        database = data_home / "projects" / project_id / "control.db"
-        connection = sqlite3.connect(f"file:{database}?mode=ro", uri=True)
+        database = devflow_home() / "projects" / project_id / "control.db"
+        connection = sqlite3.connect(f"{database.as_uri()}?mode=ro", uri=True)
         connection.row_factory = sqlite3.Row
         try:
             authority = connection.execute("SELECT authority FROM authority_state WHERE project_id=?", (project_id,)).fetchone()
@@ -32,13 +39,87 @@ def database_toolchain(root: Path) -> list[str] | None:
                    ORDER BY c.revision DESC""",
                 (project_id, str(root.resolve())),
             ).fetchall()
-            return [str(json.loads(row["value_json"]).get("command", "")) for row in rows]
+            facts = [json.loads(row["value_json"]) for row in rows]
+            return [fact for fact in facts if isinstance(fact, dict)]
         finally:
             connection.close()
     except (OSError, KeyError, ValueError, json.JSONDecodeError, sqlite3.Error):
         return None
 
 
+def database_toolchain(root: Path) -> list[str] | None:
+    facts = database_toolchain_facts(root)
+    return None if facts is None else [str(fact.get("command", "")) for fact in facts]
+
+
+def _root_directory(value: Any) -> bool:
+    return value in (None, "", ".", "./")
+
+
+def registered_scripts(root: Path, facts: list[dict[str, Any]] | None) -> tuple[set[str], str]:
+    """Package script names Core may run from the project root, and their source.
+
+    Toolchain facts (package-json@1) carry {name, command, workingDirectory};
+    the compatibility toolchain.md projects them as a 名称/工作目录 table.  A
+    legacy free-form toolchain.md has no script names, so only then fall back
+    to the root package.json scripts.
+    """
+    if facts is not None:
+        return {str(fact["name"]) for fact in facts if isinstance(fact.get("name"), str) and "command" in fact and _root_directory(fact.get("workingDirectory"))}, "toolchain facts"
+    names: set[str] = set()
+    toolchain = root / ".devflow/planning" / "toolchain.md"
+    header: list[str] | None = None
+    if toolchain.is_file():
+        for line in toolchain.read_text(encoding="utf-8").splitlines():
+            match = MARKDOWN_ROW_RE.match(line.strip())
+            if not match:
+                header = None
+                continue
+            cells = [cell.strip() for cell in match.group(1).split("|")]
+            if header is None:
+                header = cells
+            elif "名称" in header and "命令" in header and not set("".join(cells)) <= set("-: "):
+                row = dict(zip(header, cells))
+                if row.get("名称") not in (None, "", "undefined") and row.get("命令") not in (None, "", "undefined") and _root_directory(row.get("工作目录")):
+                    names.add(row["名称"])
+        if names:
+            return names, "toolchain.md"
+    try:
+        scripts = json.loads((root / "package.json").read_text(encoding="utf-8")).get("scripts", {})
+        return ({name for name in scripts if isinstance(name, str)} if isinstance(scripts, dict) else set()), "package.json"
+    except (OSError, ValueError, AttributeError):
+        return set(), "package.json"
+
+
+def package_script(argv: list[str]) -> tuple[str | None, str | None]:
+    """Return (script name, error) for npm/pnpm/yarn test|run argv."""
+    if argv[1] == "test":
+        rest, name = argv[2:], "test"
+    else:
+        if len(argv) < 3 or argv[2].startswith("-"):
+            return None, f"{Path(argv[0]).name} run must name a script immediately after 'run' (options before the script name are rejected)"
+        rest, name = argv[3:], argv[2]
+    if rest and rest[0] != "--":
+        return None, f"{Path(argv[0]).name} {argv[1]} extra arguments must follow '--'"
+    return name, None
+
+
+def reserved_reference(root: Path, argv: list[str]) -> str | None:
+    runtime_dirs: list[str] = []
+    try:
+        from dsl_v1 import runtime_dir_candidates
+        runtime_dirs = [str(path) for path in runtime_dir_candidates()]
+    except ImportError:
+        pass
+    for token in argv:
+        if "DEVFLOW_" in token:
+            return "test command must not reference DEVFLOW_ reserved variables"
+        normalized = token.replace("\\", "/")
+        if any(marker in normalized for marker in RUNTIME_MARKERS) or any(directory and directory in token for directory in runtime_dirs):
+            return "test command must not reference the Devflow Playwright Runtime; use the devflow_playwright adapter"
+    return None
+
+
 def runner_marker(argv: list[str]) -> str | None:
     if not argv:
         return None
@@ -73,18 +154,31 @@ def runner_marker(argv: list[str]) -> str | None:
 def validate_test_command(root: Path, argv: Any) -> str | None:
     if not isinstance(argv, list) or not argv or not all(isinstance(token, str) and token and "\x00" not in token for token in argv):
         return "test command must be a non-empty argv array"
+    reserved = reserved_reference(root, argv)
+    if reserved:
+        return reserved
     marker = runner_marker(argv)
     if marker is None:
+        if Path(argv[0]).name in PACKAGE_RUNNERS and len(argv) >= 2 and argv[1].startswith("-"):
+            return f"{Path(argv[0]).name} global options before the command are rejected (they can switch to another package)"
         return "test command runner is not in the Core allowlist"
-    commands = database_toolchain(root)
-    if commands is None:
+    facts = database_toolchain_facts(root)
+    if facts is None:
         toolchain = root / ".devflow/planning" / "toolchain.md"
         if not toolchain.is_file():
             return "initialized toolchain context (database or .devflow/planning/toolchain.md compatibility projection) is required before Core can execute a test command"
         content = toolchain.read_text(encoding="utf-8").lower()
     else:
-        content = "\n".join(commands).lower()
+        content = "\n".join(str(fact.get("command", "")) for fact in facts).lower()
     aliases = {"pytest": ("pytest",), "unittest": ("unittest",), "bun test": ("bun test",), "npm": ("npm",), "pnpm": ("pnpm",), "yarn": ("yarn",), "go test": ("go test",), "newman": ("newman",), "playwright": ("playwright",), "vitest": ("vitest",)}
+    if marker in PACKAGE_RUNNERS:
+        script, error = package_script(argv)
+        if error:
+            return error
+        names, source = registered_scripts(root, facts)
+        if script not in names:
+            return f"package script '{script}' is not registered in the initialization toolchain ({source})"
+        return None
     if not any(alias in content for alias in aliases[marker]):
         return f"test runner '{marker}' was not discovered in the initialization toolchain snapshot"
     return None

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/validate_state.rb

@@ -44,10 +44,23 @@ module WorkflowStateValidator
     workflow_step_unknown
     phase_ownership_conflict
   ].freeze
+  # Acceptance-execution trust failures are never downgraded by soft gates.
+  ACCEPTANCE_HARD_VALIDATION_CODES = %w[
+    acceptance_results_not_passed
+    execution_surface_mismatch
+    approval_invalid
+    human_result_unapproved
+    dsl_not_approved
+    environment_profile_not_approved
+    runtime_integrity_error
+    acceptance_tests_not_passed
+    acceptance_tests_empty
+  ].freeze
 
   def self.hard_validation_code?(code)
     value = code.to_s
     return true if HARD_VALIDATION_CODES.include?(value)
+    return true if ACCEPTANCE_HARD_VALIDATION_CODES.include?(value)
     return true if value.start_with?("artifact_registry_", "parallel_", "PARALLEL_")
     return true if value.start_with?("duplicate_", "unknown_", "missing_tracked_step")
     return true if value.start_with?("step_in_", "completed_", "terminal_", "non_completed_")

package/plugins/devflow-core/skills/workflow-orchestrator/templates/feature-development.yaml

@@ -1019,46 +1019,23 @@ steps:
         type: code-review-report
         required: true
 
-  - id: generate-mainflow-cases
+  - id: human-acceptance
     order: 86
-    label: Generate mainflow cases
-    skill: workflow-generate-mainflow-cases
+    label: Human acceptance and developer handoff
+    skill: workflow-human-acceptance
     engine_evidence_gate: enforced
     depends_on:
-      - execute
+      - code-review
     inputs:
-      - ".devflow/planning/STATE.md"
-      - ".devflow/planning/navigation/INDEX.md"
-      - ".devflow/context/spec/index.md"
-      - ".devflow/planning/requirements/baseline.md"
-      - ".devflow/planning/features/{feature}/功能点梳理.md"
-      - ".devflow/planning/features/{feature}/UI-SPEC.md"
-      - ".devflow/planning/features/{feature}/前端技术方案.md"
-      - ".devflow/planning/features/{feature}/后端技术方案.md"
-      - ".devflow/planning/features/{feature}/变更清单.md"
-      - ".devflow/planning/features/{feature}/PROGRESS.md"
       - ".devflow/planning/requirements/{feature}/tests.json"
+      - ".devflow/planning/phases/{phase}/REVIEW.md"
+      - ".devflow/planning/features/{feature}/验收测试设计.md"
     outputs:
-      - path: ".devflow/planning/generated-cases/{feature}/codebase-discovery.json"
-        type: mainflow-codebase-discovery
-        required: true
-      - path: ".devflow/planning/generated-cases/{feature}/source-map.md"
-        type: mainflow-source-map
-        required: true
-      - path: ".devflow/planning/generated-cases/{feature}/mainflow-analysis.md"
-        type: mainflow-analysis
+      - path: ".devflow/planning/test-runs/{feature}/human-acceptance-results.json"
+        type: human-acceptance-results
         required: true
-      - path: ".devflow/planning/generated-cases/{feature}/case-descriptions.json"
-        type: mainflow-case-descriptions
-        required: true
-      - path: ".devflow/planning/generated-cases/{feature}/case-import-payloads.json"
-        type: mainflow-case-import-payloads
-        required: true
-      - path: ".devflow/planning/generated-cases/{feature}/validation-report.md"
-        type: mainflow-case-validation
-        required: true
-      - path: ".devflow/planning/phases/{phase}/MAINFLOW-CASES.md"
-        type: mainflow-cases-summary
+      - path: ".devflow/planning/test-runs/{feature}/developer-handoff.md"
+        type: developer-acceptance-handoff
         required: true
 
   - id: run-acceptance-tests
@@ -1067,12 +1044,14 @@ steps:
     skill: workflow-run-acceptance-tests
     engine_evidence_gate: enforced
     depends_on:
-      - code-review
+      - human-acceptance
     inputs:
       - ".devflow/planning/requirements/{feature}/tests.json"
       - ".devflow/planning/code-index/index.sqlite"
       - ".devflow/planning/code-index/relations.jsonl"
       - ".devflow/planning/phases/{phase}/REVIEW.md"
+      - ".devflow/planning/test-runs/{feature}/human-acceptance-results.json"
+      - ".devflow/planning/test-runs/{feature}/developer-handoff.md"
     outputs:
       - path: ".devflow/planning/features/{feature}/acceptance-test-bindings.json"
         type: acceptance-test-bindings

package/plugins/devflow-core/skills/workflow-pipeline/SKILL.md

@@ -49,7 +49,7 @@ pipeline 本身不包含执行规则——所有门禁、CP 协议、失败分
 | 80 | execute | 代码执行 |
 | 84 | code-index-refresh | 刷新机器代码索引并审查 |
 | 85 | code-review | 代码审查（完成标准验证） |
-| 86 | generate-mainflow-cases | 主流程自动化用例生成 |
+| 86 | human-acceptance | 人工验收与开发者同步 |
 | 88 | run-acceptance-tests | 冻结 TC 验收执行 |
 | 100 | release-closeout | 验收通过后的版本收口与里程碑归档 |
 
@@ -60,6 +60,8 @@ pipeline 本身不包含执行规则——所有门禁、CP 协议、失败分
 
 双轨制原则：API 契约是分叉前的共同事实，`integration-verify` 是合并前的强门禁。单轨只产出局部轨道文档，不代表完整交付。
 
+`workflow-generate-mainflow-cases` 不是独立 workflow step，而是 `run-acceptance-tests` 绑定阶段的组成部分：对执行面为 `ui` / `api_flow` 且绑定为 `automated` 的 TC，必须先生成 v1 DSL 并经 `devflow_approval` 批准执行计划，否则该 TC 保持 blocked。人工 TC 结果同样只经 `human_result` 批准计入聚合门禁。
+
 如果提供了需求文档但未指定功能名，从文档标题自动提取功能名。
 
 ## 1. 需求入口前置路由

package/plugins/devflow-core/skills/workflow-pipeline/references/pipeline-flow.md

@@ -1,154 +1,82 @@
 # 研发交付全链路流程
 
+`feature-development.yaml` 是步骤拓扑、checkpoint 和失败分支的规范来源。本文档只做人类可读投影；两者不一致时，以 workflow YAML 及 `.devflow/planning/STATE.md` 为准。
+
+## 规范链路
+
+```text
+workflow-pipeline
+  → devflow_state(action="inspect")
+  → 缺少项目上下文时执行 workflow-project-context
+  → requirement-triage
+  → requirement-wayfinder
+  → domain-modeling
+  → requirement-feasibility-review
+  → requirement-baseline
+  → CP-1：需求基线确认
+  → wireframe-proposal
+  → wireframe-validate
+  → wireframe-render
+  → wireframe-review
+  → CP-WIREFRAME：线框确认
+  → api-contract
+  → CP-API：API 契约确认
+  → architecture-feasibility
+  → 双轨设计
+      ├─ Track A: backend-tech-spec → api-call-guide
+      └─ Track B: ui-spec → feature-breakdown → frontend-tech-spec → api-supplement
+  → integration-verify
+  → CP-2：双轨合并方案确认
+  → acceptance-test-design（编码前产生候选 TC-*）
+  → change-plan（任务绑定候选 TC-*）
+  → CP-3：确认变更计划并冻结验收套件
+  → phase-structure
+  → execute（代码与 TDD 证据）
+  → code-index-refresh
+  → code-review
+  → human-acceptance（人工 TC、问题反馈和开发者同步）
+  → run-acceptance-tests（执行冻结 TC-*）
+  → CP-4：验收结果确认
+  → release-closeout
+  → 完成
 ```
-workflow-pipeline 启动
-         │
-         ▼
-┌─────────────────────────────────────┐
-│ Step 0: 断点检测                     │
-│ 读取 STATE.md + inspector 恢复进度   │
-└─────────────────────────────────────┘
-         │
-         ▼
-┌─────────────────────────────────────┐
-│ Step 1: 项目初始化                   │
-│ workflow-project-context                     │
-│ 输出: .devflow/planning/PROJECT.md          │
-└─────────────────────────────────────┘
-         │
-         ▼
-┌─────────────────────────────────────┐
-│ Step 2: 需求完善                     │
-│ workflow-requirement-baseline                 │
-│ 输出: .devflow/planning/requirements/baseline.md │
-│ 门禁: 冲突/复用/过度工程/替代方案已拍板 │
-└──────────────┬──────────────────────┘
-         │             ↑
-         ▼             │ 用户拒绝
-┌─────────────────────────────────────┐
-│ 🔴 CP-1: 需求基线人工确认             │
-│ ask 强制暂停              │
-│ 确认: FP/BR/BC 准确完整              │
-└──────────────┬──────────────────────┘
-         │ 用户确认
-         ▼
-┌─────────────────────────────────────┐
-│ Step 3: 三文档并行生成                │
-│                                    │
-│  ┌──────────┐ ┌──────────┐ ┌──────┐ │
-│  │ feature- │ │frontend- │ │back- │ │
-│  │breakdown │ │tech-spec │ │end-  │ │
-│  │          │ │          │ │tech- │ │
-│  │ 功能点   │ │ 前端方案 │ │spec  │ │
-│  │ 梳理.md  │ │ .md      │ │后端  │ │
-│  └──────────┘ └──────────┘ └──────┘ │
-└─────────────────────────────────────┘
-         │             ↑
-         ▼             │ 用户拒绝
-┌─────────────────────────────────────┐
-│ 🟡 CP-2: 技术方案人工确认             │
-│ ask 强制暂停              │
-│ --no-review 可跳过                    │
-│ 确认: DB/API/架构决策合理可行         │
-└──────────────┬──────────────────────┘
-         │ 用户确认
-         ▼
-┌─────────────────────────────────────┐
-│ Step 4: 变更清单                     │
-│ workflow-change-plan                         │
-│ 输入: 前端+后端技术方案               │
-│ 输出: .devflow/planning/features/{功能名}/变更清单.md │
-└──────────────┬──────────────────────┘
-         │             ↑
-         ▼             │ 用户拒绝
-┌─────────────────────────────────────┐
-│ 🔴 CP-3: 变更清单人工确认             │
-│ ask 强制暂停              │
-│ 不可跳过                              │
-│ 确认: DDL/代码/上线步骤可执行         │
-└──────────────┬──────────────────────┘
-         │ 用户确认
-         ▼
-┌─────────────────────────────────────┐
-│ Step 4.5: Phase 结构初始化           │
-│ phase-init                           │
-│ 创建 ROADMAP.md + .devflow/planning/phases/  │
-│ 桥接 workflow 产物到 phase 结构      │
-└─────────────────────────────────────┘
-         │
-         ▼
-┌─────────────────────────────────────┐
-│ Step 5: 代码执行                     │
-│ workflow-execute-phase                   │
-│ Wave1: DDL → Wave2: Domain/Service  │
-│ Wave3: API → Wave4: 前端 → Wave5: 联调│
-│ 输出: SUMMARY.md 写入 phases/ 目录   │
-└──────────────┬──────────────────────┘
-	         │             ↑
-	         ▼             │ 修复后重试
-┌─────────────────────────────────────┐
-│ Step 5.5: 代码索引刷新               │
-│ workflow-code-index                  │
-│ 刷新 Symbol/Relation/Call Graph      │
-│ 输出 .devflow/planning/code-index/ + AUDIT   │
-└──────────────┬──────────────────────┘
-	         │             ↑
-	         ▼             │ 索引审查失败
-┌─────────────────────────────────────┐
-│ Step 5.6: 代码审查 + 主流程用例      │
-│ code-review + generate-mainflow-cases│
-│ 基于 code-index + 源码 evidence       │
-└──────────────┬──────────────────────┘
-	         │             ↑
-	         ▼             │ 审查失败/用例生成失败
-┌─────────────────────────────────────┐
-│ Step 6: 需求验收测试执行              │
-│ workflow-run-acceptance-tests         │
-│ 执行冻结的 TC-*                       │
-│ 失败/阻塞 → 修复 → 重跑                │
-└──────────────┬──────────────────────┘
-	         │             ↑
-	         ▼             │ 用户拒绝
-┌─────────────────────────────────────┐
-│ 🔴 CP-4: 验收结果确认                 │
-│ ask 强制暂停              │
-│ 不可跳过                              │
-│ 确认: TC-* 全部通过,允许版本收口       │
-└──────────────┬──────────────────────┘
-         │ 用户确认
-         ▼
-┌─────────────────────────────────────┐
-│ Step 7: 版本收口与里程碑归档          │
-│ workflow-release-closeout             │
-│ 校验 TC/code-index → 归档 → 更新状态   │
-└─────────────────────────────────────┘
-         │
-         ▼
-           完成 ✓
+
+`workflow-generate-mainflow-cases` 不参与独立排序，而是 `run-acceptance-tests` 绑定阶段的组成部分：automated 的 ui / api_flow TC 需要先生成 v1 DSL 并批准执行计划。人工验收结果（经 `human_result` 批准）会与自动执行结果聚合，验收失败是硬门禁。
+
+## 双轨与 Checkpoint 规则
+
+- 双轨设计支持时最多并行两个步骤；不支持时按 workflow 声明顺序串行降级。
+- `CP-1`、`CP-WIREFRAME`、`CP-API`、`CP-2`、`CP-3` 和 `CP-4` 都会暂停链路，等待用户审查当前产物。
+- `--no-review` 仅保留参数位，不会跳过 `CP-2`；`integration-verify` Merge Gate 不可跳过。
+- 用户拒绝或提出修改意见时，流程保持在当前步骤，不会自动推进。
+- 单轨 `--track A` / `--track B` 只产出对应轨道文档，不会越过 `integration-verify` 进入完整实施。
+
+## 失败分支
+
+`run-acceptance-tests` 失败、阻塞或验收结果被拒绝时，进入 `acceptance-failed-remediation`：
+
+```text
+验收失败 → 诊断/修复 → 刷新代码索引 → 重跑原冻结 TC-* → CP-4
 ```
 
 ## 断点续接
 
-每次启动时，workflow-pipeline 通过 `devflow_state(action="inspect")` 读取规范状态文件 `.devflow/planning/STATE.md`，由 inspector 返回当前动作和下一节点：
+Pipeline 通过 `devflow_state(action="inspect")` 读取 `.devflow/planning/STATE.md`，并根据 inspector 返回的 `action` 路由到下一步、当前步骤、checkpoint、失败分支或并行窗口。
 
-```
-1. 校验 `.devflow/planning/STATE.md` 的 YAML front matter、workflow 配置和 artifact registry
-2. 根据 inspector 返回的 `action` 路由到下一步、当前步骤、确认、失败分支或并行窗口
-3. 如果控制面缺失或校验失败，报告阻塞并提示运行 `init_workflow.rb --write`、`init_state.rb --write` 修复
-4. `.devflow/planning/pipeline-state.md` 已废弃，不作为恢复状态来源
-```
+1. 校验 `STATE.md` 的 YAML front matter、workflow 配置和 artifact registry。
+2. 如果控制面缺失或校验失败，报告阻塞并通过专用 Core 恢复链路处理。
+3. `.devflow/planning/pipeline-state.md` 已废弃，不作为恢复状态来源。
 
-## 简化流程门禁
+## 需求基线门禁
 
-只有单文件/单方法/单文档、无跨层影响、无未拍板需求决策时，才允许向用户提议简化流程。用户未明确同意时，继续完整 pipeline。
+`requirement-baseline` 完成后必须检查：
 
-## 需求拍板门禁
+- `.devflow/planning/requirements/baseline.md` 中的待确认事项、反向审视与下游输入契约。
+- `.devflow/planning/requirements/baseline.meta.json` 的 `review_status` 必须为 `passed`。
+- `blocking_pending_count`、`critical_image_missing_count`、`challenge_pending_count` 和 `code_reality_missing_count` 必须全为 `0`。
 
-Step 2 之后必须检查 `.devflow/planning/requirements/baseline.md`：
+影响 scope、语义、归属、兼容性或实现成本的未确认项是阻塞项，不得将其当作已确认范围传入技术方案或变更清单。
 
-- `待确认事项`
-- `反向审视与用户拍板`
-- `下游输入契约`
-- `.devflow/planning/requirements/baseline.meta.json` 中 `review_status` 必须为 `passed`，且 `blocking_pending_count`、`critical_image_missing_count`、`challenge_pending_count`、`code_reality_missing_count` 必须全为 0
+## 简化流程
 
-影响 scope、语义、归属、兼容性或实现成本的未确认项是阻塞项。不能把它们传入技术方案或变更清单当成已确认范围。
+只有单文件、单方法或单文档变更，且无跨层影响、无未拍板需求决策时，才能向用户提议简化流程。用户未明确同意时，继续完整 Pipeline。

package/plugins/devflow-core/skills/workflow-project-context/scripts/validate_initialization_database.py

@@ -32,7 +32,7 @@ def validate(database: Path, project_id: str, workspace_id: str | None = None, r
     connection.row_factory = sqlite3.Row
     try:
         version = connection.execute("SELECT version FROM schema_meta LIMIT 1").fetchone()
-        if not version or version["version"] != 2:
+        if not version or version["version"] != 3:
             errors.append(f"unsupported initialization schema: {version['version'] if version else 'missing'}")
         if not connection.execute("SELECT 1 FROM projects WHERE id=?", (project_id,)).fetchone():
             errors.append("project identity is not registered in the database")

package/plugins/devflow-implementation/skills/workflow-execute-phase/references/execute-phase.md

@@ -63,12 +63,14 @@
 ```text
 execute-phase
   → code-review
-  → workflow-generate-mainflow-cases（如适用）
+  → workflow-human-acceptance
   → workflow-run-acceptance-tests
   → CP-4 验收结果确认
   → workflow-release-closeout
 ```
 
+`workflow-generate-mainflow-cases` 不是独立主链步骤，而是 `workflow-run-acceptance-tests` 绑定阶段的组成部分：automated 的 ui / api_flow TC 需要先生成 v1 DSL 并批准执行计划才能执行。
+
 `workflow-run-acceptance-tests` 只消费冻结的 `TC-*`。每个已确认验收条件都必须覆盖；异常、边界、权限、兼容和架构风险用例不能被主流程用例替代。验收结果保存在 `.devflow/planning/test-runs/{feature}/acceptance-results.json`。
 
 只有当所有冻结 `TC-*` 已执行且通过、无 `failed`/`blocked`，且代码索引审计通过时，才允许进入 `workflow-release-closeout`。版本收口负责生成项目自己的里程碑收口记录并更新项目状态；它不生成旧式人工验收或独立验证报告。