@guanlin4924/devflow-pi 0.1.96 → 0.1.97

package/plugins/devflow-quality/skills/workflow-generate-mainflow-cases/scripts/compile_dsl.py

@@ -51,6 +51,8 @@ from dsl_coverage import check as coverage_check  # noqa: E402
 from dsl_v1 import SCHEMA_VERSION, validate as validate_dsl  # noqa: E402
 from execution_surface import derive as derive_surface  # noqa: E402
 from tc_hash import tc_sha256  # noqa: E402
+from locator_map import LocatorMapError, expand_anchor_reference  # noqa: E402
+from locator_report import write_report  # noqa: E402
 
 
 FEATURE_RE = re.compile(r"^[^/\\\x00-\x1f\x7f]+$")
@@ -58,7 +60,7 @@ TC_ID_RE = re.compile(r"^TC-[0-9]{4,}$")
 GENERATABLE_SURFACES = frozenset({"ui", "api_flow"})
 
 UI_ACTIONS = frozenset({"goto", "click", "fill", "select", "check", "uncheck", "wait_for",
-                        "assert_visible", "assert_text", "assert_url", "screenshot"})
+                        "assert_visible", "assert_text", "assert_each_text", "assert_value", "assert_url", "screenshot"})
 TARGET_ACTIONS = UI_ACTIONS - {"goto", "assert_url", "screenshot"}
 HTTP_METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE")
 API_SHORTHAND = {method.lower(): method for method in HTTP_METHODS}
@@ -74,9 +76,13 @@ UI_KEYS = {
     "wait_for": {"locator", "exact", "state"},
     "assert_visible": {"locator", "exact"},
     "assert_text": {"locator", "exact", "expected", "match", "normalize_whitespace", "case_sensitive"},
+    "assert_each_text": {"locator", "exact", "expected", "match", "min_count", "normalize_whitespace", "case_sensitive"},
+    "assert_value": {"locator", "exact", "expected", "match", "normalize_whitespace", "case_sensitive"},
     "assert_url": {"expected", "match"},
     "screenshot": {"full_page"},
 }
+for _ui_action in UI_KEYS:
+    UI_KEYS[_ui_action] = UI_KEYS[_ui_action] | {"source_anchor"}
 API_KEYS = {"method", "url", "headers", "query", "json", "expect_status", "assertions", "extract", "retry", "idempotent"}
 CASE_KEYS = {"tc_id", "name", "description", "variables", "data", "steps", "source_evidence", "tags"}
 DATA_KEYS = {"namespace", "owner", "accounts", "repeatable", "setup", "cleanup"}
@@ -199,12 +205,73 @@ def _css_errors(css: str) -> list[str]:
     return errors
 
 
-def compile_target(raw: Any, exact: Any, label: str, warnings: list[str]) -> dict[str, Any]:
+def _validate_object_target(target: Any, label: str) -> dict[str, Any]:
+    """Validate new structured targets without duplicating Core semantics."""
+    if not isinstance(target, dict) or not target:
+        raise CompileError(f"{label}.locator target must be a non-empty object")
+    allowed = {"testid", "role", "name", "label", "placeholder", "text", "css", "exact",
+               "within", "table", "column", "table_kind", "row"}
+    unknown = set(target) - allowed
+    if unknown:
+        raise CompileError(f"{label}.locator has unsupported target keys {sorted(unknown)}")
+    forms = [key for key in ("testid", "role", "label", "placeholder", "text", "css", "table", "row") if key in target]
+    if "within" in target:
+        if len(forms) != 1:
+            raise CompileError(f"{label}.locator.within must wrap exactly one locator form")
+        _validate_object_target(target["within"], f"{label}.locator.within")
+    elif len(forms) != 1:
+        raise CompileError(f"{label}.locator must contain exactly one locator form")
+    if "role" in target and (not isinstance(target["role"], str) or not isinstance(target.get("name"), str)):
+        raise CompileError(f"{label}.locator role target requires role and name")
+    if "role" not in target and "name" in target:
+        raise CompileError(f"{label}.locator.name requires role")
+    if "exact" in target and not isinstance(target["exact"], bool):
+        raise CompileError(f"{label}.locator.exact must be a boolean")
+    if "table" in target:
+        table = target["table"]
+        if not isinstance(table, dict) or set(table) not in ({"near_heading"}, {"testid"}, {"only"}, {"ref"}):
+            raise CompileError(f"{label}.locator.table must use near_heading, testid, only, or ref")
+        if "column" not in target or not isinstance(target["column"], str) or not target["column"].strip():
+            raise CompileError(f"{label}.locator.table requires a non-empty column")
+        if target.get("table_kind", "html") not in {"html", "element-plus"}:
+            raise CompileError(f"{label}.locator.table_kind must be html or element-plus")
+    if "row" in target:
+        row = target["row"]
+        if not isinstance(row, dict) or set(row) not in ({"column", "equals"}, {"column", "contains"}):
+            raise CompileError(f"{label}.locator.row must be {{column, equals}} or {{column, contains}}")
+        match_key = "equals" if "equals" in row else "contains"
+        if not isinstance(row.get("column"), str) or not row["column"].strip() or not isinstance(row.get(match_key), str):
+            raise CompileError(f"{label}.locator.row column and match value must be strings")
+    return json.loads(json.dumps(target, ensure_ascii=False))
+
+
+def _compile_target(raw: Any, exact: Any, label: str, warnings: list[str], locator_dir: Path | None = None) -> tuple[dict[str, Any], str | None]:
     """'type:value' → one v1 target.  testid first; role/label/placeholder/text default to exact."""
+    if isinstance(raw, dict):
+        if exact is not None:
+            raise CompileError(f"{label}.exact must be inside a structured locator object")
+        target = _validate_object_target(raw, label)
+        if "table" in target:
+            warnings.append(f"{label} uses table+column locator; verify the table adapter and column uniqueness")
+        elif "row" in target:
+            warnings.append(f"{label} uses a data-dependent row locator")
+        elif "within" in target:
+            warnings.append(f"{label} uses a within-scoped locator")
+        return target, None
     if not isinstance(raw, str) or ":" not in raw:
         raise CompileError(f"{label}.locator must be 'testid:<id>' | 'role:<role>:<name>' | 'label:<text>' | "
                            "'placeholder:<text>' | 'text:<text>' | 'css:<selector>'")
     kind, _, value = raw.strip().partition(":")
+    if kind.strip().lower() == "anchor":
+        if locator_dir is None:
+            raise CompileError(f"{label}.locator anchor requires the test-locators directory")
+        try:
+            target, source_anchor = expand_anchor_reference(raw, locator_dir)
+        except LocatorMapError as error:
+            raise CompileError(f"{label}.locator: {error}") from error
+        if exact is not None:
+            raise CompileError(f"{label}.exact cannot override an anchor target")
+        return _compile_target(target, None, label, warnings, locator_dir)[0], source_anchor
     kind = kind.strip().lower()
     if kind in REJECTED_LOCATOR_TYPES:
         raise CompileError(f"{label}.locator: {REJECTED_LOCATOR_TYPES[kind]}")
@@ -217,7 +284,7 @@ def compile_target(raw: Any, exact: Any, label: str, warnings: list[str]) -> dic
             raise CompileError(f"{label}.exact does not apply to testid locators")
         if not value.strip():
             raise CompileError(f"{label}.locator has an empty value")
-        return {"testid": value.strip()}
+        return {"testid": value.strip()}, None
     if kind == "css":
         if exact is not None:
             raise CompileError(f"{label}.exact does not apply to css locators")
@@ -225,7 +292,7 @@ def compile_target(raw: Any, exact: Any, label: str, warnings: list[str]) -> dic
         if errors:
             raise CompileError(f"{label}: " + "; ".join(errors))
         warnings.append(f"{label} uses a css locator; prefer a data-testid and cite the selector source in source-map.md")
-        return {"css": value.strip()}
+        return {"css": value.strip()}, None
     if kind == "role":
         role, _, name = value.partition(":")
         if not re.fullmatch(r"[a-z]+", role.strip()) or not name.strip():
@@ -242,7 +309,12 @@ def compile_target(raw: Any, exact: Any, label: str, warnings: list[str]) -> dic
         warnings.append(f"{label} locates '{text}' by {kind}; this text usually repeats per row/dialog and fails strict mode — use a data-testid")
     else:
         warnings.append(f"{label} uses {kind} instead of a data-testid")
-    return target
+    return target, None
+
+
+def compile_target(raw: Any, exact: Any, label: str, warnings: list[str], locator_dir: Path | None = None) -> dict[str, Any]:
+    """Backward-compatible public target compiler; anchor provenance is step-level."""
+    return _compile_target(raw, exact, label, warnings, locator_dir)[0]
 
 
 # ---------------------------------------------------------------------------
@@ -360,7 +432,7 @@ def compile_api_step(step: dict[str, Any], method: str | None, default_id: str,
     return compiled
 
 
-def compile_step(step: Any, default_id: str, label: str, warnings: list[str], api_only: bool = False) -> dict[str, Any]:
+def compile_step(step: Any, default_id: str, label: str, warnings: list[str], api_only: bool = False, locator_dir: Path | None = None) -> dict[str, Any]:
     if not isinstance(step, dict):
         raise CompileError(f"{label} must be an object")
     _check_forbidden(step, label)
@@ -384,16 +456,20 @@ def compile_step(step: Any, default_id: str, label: str, warnings: list[str], ap
     if lowered in TARGET_ACTIONS:
         if "locator" not in step:
             raise CompileError(f"{label}.locator is required for {lowered}")
-        compiled["target"] = compile_target(step["locator"], step.get("exact"), label, warnings)
+        compiled["target"], source_anchor = _compile_target(step["locator"], step.get("exact"), label, warnings, locator_dir)
+        if source_anchor:
+            compiled["source_anchor"] = source_anchor
     if lowered == "goto":
         compiled["url"] = step.get("url")
     elif lowered in {"fill", "select"}:
         compiled["value"] = step.get("value")
     elif lowered == "wait_for":
         compiled["state"] = step.get("state", "visible")
-    elif lowered == "assert_text":
+    elif lowered in {"assert_text", "assert_each_text", "assert_value"}:
         compiled["match"] = step.get("match", "exact")
         compiled["expected"] = step.get("expected")
+        if lowered == "assert_each_text" and "min_count" in step:
+            compiled["min_count"] = step["min_count"]
         for key in ("normalize_whitespace", "case_sensitive"):
             if key in step:
                 compiled[key] = step[key]
@@ -428,7 +504,7 @@ def compile_variables(raw: Any, label: str) -> dict[str, Any]:
     return compiled
 
 
-def compile_case(desc: Any, index: int, eligible: dict[str, dict[str, Any]], rejected: dict[str, str]) -> tuple[str, dict[str, Any], list[str]]:
+def compile_case(desc: Any, index: int, eligible: dict[str, dict[str, Any]], rejected: dict[str, str], locator_dir: Path | None = None) -> tuple[str, dict[str, Any], list[str]]:
     label = f"cases[{index}]"
     if not isinstance(desc, dict):
         raise CompileError(f"{label} must be an object")
@@ -457,12 +533,12 @@ def compile_case(desc: Any, index: int, eligible: dict[str, dict[str, Any]], rej
         steps = data_raw.get(phase, [])
         if not isinstance(steps, list):
             raise CompileError(f"{label}.data.{phase} must be an array")
-        data[phase] = [compile_step(step, f"{phase}-{i:02d}", f"{label}.data.{phase}[{i - 1}]", warnings, api_only=True)
+        data[phase] = [compile_step(step, f"{phase}-{i:02d}", f"{label}.data.{phase}[{i - 1}]", warnings, api_only=True, locator_dir=locator_dir)
                        for i, step in enumerate(steps, start=1)]
     raw_steps = desc.get("steps")
     if not isinstance(raw_steps, list) or not raw_steps:
         raise CompileError(f"{label}.steps must be a non-empty array")
-    steps = [compile_step(step, f"s{i:02d}", f"{label}.steps[{i - 1}]", warnings) for i, step in enumerate(raw_steps, start=1)]
+    steps = [compile_step(step, f"s{i:02d}", f"{label}.steps[{i - 1}]", warnings, locator_dir=locator_dir) for i, step in enumerate(raw_steps, start=1)]
     source = eligible[tc_id]
     name = desc.get("name")
     dsl = {
@@ -482,7 +558,7 @@ def compile_case(desc: Any, index: int, eligible: dict[str, dict[str, Any]], rej
     return tc_id, dsl, [f"{label}: {warning}" for warning in warnings]
 
 
-def compile_all(payload: Any, suite: dict[str, Any]) -> tuple[dict[str, dict[str, Any]], list[str], list[str]]:
+def compile_all(payload: Any, suite: dict[str, Any], locator_dir: Path | None = None) -> tuple[dict[str, dict[str, Any]], list[str], list[str]]:
     """Return ({tc_id: dsl}, warnings, errors).  Errors are collected per case."""
     cases = payload.get("cases") if isinstance(payload, dict) else payload
     if not isinstance(cases, list):
@@ -493,7 +569,7 @@ def compile_all(payload: Any, suite: dict[str, Any]) -> tuple[dict[str, dict[str
     errors: list[str] = []
     for index, desc in enumerate(cases):
         try:
-            tc_id, dsl, case_warnings = compile_case(desc, index, eligible, rejected)
+            tc_id, dsl, case_warnings = compile_case(desc, index, eligible, rejected, locator_dir=locator_dir)
         except CompileError as error:
             errors.append(str(error))
             continue
@@ -540,7 +616,8 @@ def main() -> int:
             payload = json.loads(Path(args.input).read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError) as error:
             raise CompileError(f"cannot read case descriptions: {error}") from error
-        compiled, warnings, errors = compile_all(payload, suite)
+        locator_dir = root / ".devflow/planning/test-locators"
+        compiled, warnings, errors = compile_all(payload, suite, locator_dir=locator_dir)
     except CompileError as error:
         print(f"COMPILE ERROR: {error}", file=sys.stderr)
         return 1
@@ -561,8 +638,14 @@ def main() -> int:
             write_atomic(path, content)
         files.append({"tc_id": tc_id, "path": path.relative_to(root).as_posix() if path.is_relative_to(root) else str(path),
                       "changed": not unchanged})
+    report_path = root / ".devflow/planning/features" / feature / "locator-stability.md"
+    try:
+        write_report(report_path, compiled.values(), feature)
+    except (OSError, ValueError) as error:
+        print(f"COMPILE ERROR: cannot write locator stability report: {error}", file=sys.stderr)
+        return 1
     print(json.dumps({"status": "compiled", "feature": feature, "case_count": len(files), "files": files,
-                      "warnings": len(warnings)}, ensure_ascii=False, indent=2))
+                      "warnings": len(warnings), "locator_report": str(report_path.relative_to(root))}, ensure_ascii=False, indent=2))
     return 0
 
 

package/plugins/devflow-quality/skills/workflow-generate-mainflow-cases/scripts/locator_report.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Render the internal locator stability report for generated DSL."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterable
+
+
+def _strategy(target: dict[str, Any]) -> tuple[str, str, str]:
+    if "within" in target:
+        return "within", "中", "区域限定目标；区域与内层目标都必须唯一匹配。"
+    if "table" in target:
+        return "table_column", "中", f"按表格选择器和表头‘{target.get('column', '')}’解析，运行时计算列位置。"
+    if "row" in target:
+        return "row", "高", "依赖测试数据；行值变化或重复会导致失败。"
+    for key, risk, reason in (
+        ("testid", "低", "使用稳定的 data-testid。"),
+        ("role", "中", "依赖可访问角色和名称。"),
+        ("label", "中", "依赖表单 label 文本。"),
+        ("placeholder", "中", "依赖 placeholder 文本。"),
+        ("text", "高", "可见文本可能重复或随文案变化。"),
+        ("css", "高", "CSS 选择器容易受结构或构建变化影响。"),
+    ):
+        if key in target:
+            return key, risk, reason
+    return "unknown", "高", "无法识别的定位形式。"
+
+
+def _steps(dsl: dict[str, Any]) -> Iterable[tuple[str, dict[str, Any]]]:
+    for phase, values in (("setup", dsl.get("data", {}).get("setup", [])), ("main", dsl.get("steps", [])),
+                          ("cleanup", dsl.get("data", {}).get("cleanup", []))):
+        for step in values if isinstance(values, list) else []:
+            if isinstance(step, dict) and step.get("driver") == "ui" and "target" in step:
+                yield phase, step
+
+
+def report_entries(dsl: dict[str, Any]) -> list[dict[str, str]]:
+    entries: list[dict[str, str]] = []
+    for phase, step in _steps(dsl):
+        strategy, risk, reason = _strategy(step["target"])
+        entry = {"step": str(step.get("id", "")), "phase": phase, "strategy": strategy,
+                 "risk": risk, "reason": reason}
+        if step.get("source_anchor"):
+            entry["source_anchor"] = str(step["source_anchor"])
+        entries.append(entry)
+    return entries
+
+
+def render_report(dsls: Iterable[dict[str, Any]], feature: str | None = None) -> str:
+    cases = list(dsls)
+    title = f"# 定位稳定性报告{f'：{feature}' if feature else ''}\n\n"
+    lines = [title, "本报告由编译后的 DSL 自动生成，仅用于内部留档；运行时只执行展开后的 DSL。", ""]
+    for dsl in sorted(cases, key=lambda item: str(item.get("tc_id", ""))):
+        lines.extend([f"## {dsl.get('tc_id', 'unknown')}：{dsl.get('name', '')}", "", "| 步骤 | 阶段 | 定位方式 | 风险 | 原因 | 来源锚点 |", "|---|---|---|---|---|---|"])
+        entries = report_entries(dsl)
+        if not entries:
+            lines.append("| — | — | — | — | UI 步骤无定位目标 | — |")
+        else:
+            for item in entries:
+                row = dict(item)
+                row["source_anchor"] = "`" + item["source_anchor"] + "`" if item.get("source_anchor") else "—"
+                lines.append("| {step} | {phase} | {strategy} | {risk} | {reason} | {source_anchor} |".format(**row))
+        lines.extend(["", "可选前端改进：优先补充已有业务语义的 `data-testid`；本报告不要求修改被测前端。", ""])
+    return "\n".join(lines)
+
+
+def write_report(path: Path, dsls: Iterable[dict[str, Any]], feature: str | None = None) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_report(dsls, feature), encoding="utf-8")
+
+
+__all__ = ["render_report", "report_entries", "write_report"]

package/plugins/devflow-quality/skills/workflow-regression-test-design/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: workflow-regression-test-design
+description: "Use from an idle project to derive a user-confirmed, frozen regression acceptance suite for an existing feature without requiring a requirement baseline."
+---
+
+# 存量功能回归验收测试设计
+
+本步骤为已经上线或已有实现的功能建立可复现的回归验收套件。它不补造需求，也不把当前实现自动宣布为正确；它把代码、代码索引、外部契约和用户确认的现有行为整理为候选 `TC-*`，然后交给 Core 在 CP-3 冻结。
+
+## 执行合同
+
+图谱写入受 ExecutionContract v2 约束，active contract 的 step 必须是 `regression-test-design`。开始时先调用 `devflow_contract(action="status")`；没有 active contract 时调用 `devflow_contract(action="activate", feature="<feature>", step="regression-test-design")`。不得用普通对话、Skill 自己写 `tests.json` 或逐条确认替代 Core 的冻结操作。
+
+## 输入顺序与范围
+
+需要补充当前页面行为时，可在已批准的测试环境中调用 `devflow_explore`（start/observe/act/assert/draft）。探索只用于发现和录制草稿，不是验收证据；密码、密钥和凭据值不得写入描述、日志或草稿。草稿必须由后续 `workflow-generate-mainflow-cases` 编译、校验并经用户批准后才能执行。
+
+1. 读取 `devflow_requirement_graph(action="inspect")` 和 `.devflow/planning/code-index/`，确认当前功能、代码索引 revision、入口、接口、数据流和调用关系。
+2. 阅读实际前端与后端源码、路由/控制器、服务、权限规则、数据访问和已有测试；代码只能用于发现真实功能点与可执行入口，不能把实现细节直接当作预期。
+3. 阅读 `.devflow/planning/test-environments/*.json` 中的环境声明；需要登录或测试 token 时，只记录 `secret_env` 的变量名和所需前置，不读取或输出值。
+4. 阅读项目已有文档、接口定义和公开约定，区分可引用的 `contract` 与仅能说明当前行为的 `characterization`。
+
+如果代码索引缺失、源码与索引明显不一致、或无法写出外部可观察的判定标准，先记录阻塞，不用猜测补全。
+
+## 生成流程
+
+先列出功能点和证据来源，再为每个功能点提出候选 TC。优先顺序是 `invariant`、`contract`，其次是 `characterization`；只有明确的需求/验收文档才使用 `requirement`。每条回归 TC 必须显式填写 `oracle_source`。非 `requirement` 必须填写 `oracle_evidence`，包括文件:行、接口定义、不变量说明，或带环境和时间的观察记录。
+
+候选结构至少包含：
+
+```json
+{
+  "acceptance_refs": [],
+  "requirement_refs": [],
+  "test_type": "page|api|permission|boundary|resilience|migration|performance|analytics|freshness|reconciliation",
+  "execution_surface": "http|ui|api_flow|project_test",
+  "target": "外部可观察功能点",
+  "preconditions": ["身份、环境和数据前置"],
+  "steps": ["原子化操作"],
+  "oracle": "不依赖易变业务数据值的可观察结果",
+  "oracle_source": "invariant",
+  "oracle_evidence": "不变量说明及其来源",
+  "automation_mode": "automated|manual|blocked",
+  "evidence_strategy": "replay|causal|observation"
+}
+```
+
+- `requirement` 必须有非空 `requirement_refs` 与 `acceptance_refs`，并通过已有 `verified_by`/确认校验；`contract`、`invariant`、`characterization` 在回归工作流中可以两者均为空，因为存量功能可能没有 REQ/AC 图谱节点，但仍必须有 `oracle_evidence`。如果实际存在 REQ/AC 引用，则必须按普通边和确认规则校验。
+- 禁止把依赖环境数据的值写死为预期，例如“公海 = 394”。优先断言结构、关系、权限边界、稳定状态和每行一致性；`characterization` 只证明行为未变化，不证明行为正确。
+- `execution_surface` 必须显式填写，且遵守已有 DSL/adapter 兼容矩阵。具体 selector、endpoint、测试数据和命令属于后续绑定，不得改变 TC 意图。
+- `automated` 的 `ui`/`api_flow` 用例必须能由 `workflow-generate-mainflow-cases` 生成确定性 DSL；没有稳定 locator、无法隔离数据或需要纯视觉判断时标为 `manual` 或 `blocked`。
+- 回归用例需要绑定定位时，优先复用已有 `data-testid`，其次在 `.devflow/planning/test-locators/<page-key>.json` 建立可审计锚点；用例描述使用 `anchor:<page-key>/<anchor-name>`，不要把映射文件交给 Runtime。
+- `observation` 只能配合 `automation_mode: blocked`，并填写 `observation_plan`；不能把人工看过当作通过证据。
+- 需要当前行为观察时，可以在已批准测试环境中执行只读观察。记录环境、时间、身份类别、操作摘要、观察到的结构/关系和复现条件，不记录凭据、响应中的秘密或脱敏前的个人数据。
+
+## 用户检查点与冻结
+
+写入 `.devflow/planning/features/{feature}/回归验收测试设计.md`，包含功能点清单、每条 TC 的来源和证据、执行面、自动化可行性、环境前置、风险与未决问题；同时维护 `tests.meta.json` 作为该候选套件的元数据视图。检查点前必须有这两个回归设计产出，Core 才能生成并冻结 `tests.json`。回归没有实现任务，因此不生成 `test-bindings.json`；后续 DSL 和验收步骤的绑定/结果文件不属于本步骤输出。
+
+在 CP-3 展示所有候选，明确提示：`characterization` 只保证行为不变；`contract`/`invariant`/`characterization` 的证据是否足够；哪些用例会因无环境或无稳定执行面而 blocked。只有用户确认后，Core 才能一次性冻结完整套件。冻结失败时严格拒绝，修正候选后重新走检查点。
+
+冻结后移交 `workflow-generate-mainflow-cases` 的 `regression-dsl` 步骤。该步骤只绑定已冻结意图；它不能新增、删减或改写 oracle、步骤或 `oracle_source`。
+
+## 输出与禁止事项
+
+- 输出：回归设计文档及其 meta 视图；结构化 `TC-*` 只由 Core 图谱冻结产生。
+- 不读取或使用 agent 交付自述、`SUMMARY.md` 或 git diff 来决定测试范围。
+- 不写入 `acceptance-results.json`，不生成人工通过结果，不确认执行计划或环境批准。
+- 不向模型上下文、文档或日志输出测试凭据值。

package/plugins/devflow-quality/skills/workflow-release-closeout/SKILL.md

@@ -31,7 +31,7 @@ description: "在冻结需求验收测试全部通过后，执行 Devflow 自有
 
 ## 收口动作
 
-1. 调用 `devflow_run_acceptance_tests(action="validate_results", feature=...)`，让 Core 重新校验 `acceptance-results.json`（suite pins、`execution_surface` 兼容、当前仍有效的 `execution_plan`/`environment_profile`/`human_result`/`mode_override` 批准、运行目录与工件哈希）；运行后 DSL 或 profile 被修改、批准被替换，都会使已记录结果失效，需要回到 `run-acceptance-tests` 重跑；不通过则停止收口。通过后读取该文件（读取即可，不得写入），计算通过/失败/阻塞数量，并展示 `legacy_unclassified`、有效降级记录和逐 TC `dsl_approval`。任何 `dsl_approval: none` 必须对应 blocked；若其被标为 passed、结果未全 passed 或存在未批准降级，立即拒绝收口。人工 TC 的 passed 只来自已确认的 `human_result` approval，`human-acceptance-results.json` 草稿不算证据。失败分析和证据读取只依据 `result.json` 与 `acceptance-results.json`；Agent 不得读取 trace、截图、网络工件或 `runtime.log`，这些由用户本地查看（hook 会拒绝 Agent 读取）。
+1. 调用 `devflow_run_acceptance_tests(action="validate_results", feature=...)`，让 Core 重新校验 `acceptance-results.json`（suite pins、`execution_surface` 兼容、当前仍有效的 `execution_plan`/`environment_profile`/`human_result`/`mode_override` 批准、运行目录与工件哈希）；运行后 DSL 或 profile 被修改、批准被替换，都会使已记录结果失效，需要回到 `run-acceptance-tests` 重跑；不通过则停止收口。通过后读取该文件（读取即可，不得写入），计算通过/失败/阻塞数量，展示逐 TC 的 `oracle_source`、按来源计数、`legacy_unclassified`、有效降级记录和逐 TC `dsl_approval`。`characterization` 用例只证明行为未变化，不证明正确性。任何 `dsl_approval: none` 必须对应 blocked；若其被标为 passed、结果未全 passed 或存在未批准降级，立即拒绝收口。人工 TC 的 passed 只来自已确认的 `human_result` approval，`human-acceptance-results.json` 草稿不算证据。失败分析和证据读取只依据 `result.json` 与 `acceptance-results.json`；Agent 不得读取 trace、截图、网络工件或 `runtime.log`，这些由用户本地查看（hook 会拒绝 Agent 读取）。
 2. 更新 `.devflow/planning/navigation/INDEX.md`，记录本次 code-index revision 和验收结果 fingerprint。
 3. 在 `.devflow/planning/milestones/` 写入本版本的 ROADMAP、需求覆盖、测试结果、变更清单和已接受风险摘要。
 4. 更新 `.devflow/planning/PROJECT.md` 的当前版本与下一步目标。

package/plugins/devflow-quality/skills/workflow-run-acceptance-tests/SKILL.md

@@ -28,7 +28,7 @@ description: "Execute the frozen TC acceptance suite after code review. Use the
 ## 过程
 
 1. 用 `devflow_acceptance_tests(feature)` 检查测试集已由 CP-3 冻结。若有 stale 或候选 TC，停止并回到需求/测试设计。
-2. 读取冻结 TC 与其 oracle、前置数据、身份、自动化模式和 `execution_surface`。
+2. 读取冻结 TC 与其 oracle、`oracle_source`/`oracle_evidence`、前置数据、身份、自动化模式和 `execution_surface`。结果与交接报告必须逐 TC 展示 `oracle_source`，并按来源汇总；`characterization` 用例只证明行为未变化。
    对 `api_refs`、`workload_refs` 和 `risk_refs` 指向的专项用例，保留其契约、性能/迁移或韧性义务；没有适配器或环境时必须写为 blocked，不能用普通主流程替代。
 3. 读取代码审查报告、代码索引和实际源码，仅为每个 TC 绑定运行适配器；不得改变 TC 的断言、范围或预期。对每个自动化 `ui|api_flow` TC，若 `generated-cases/{feature}/TC-xxxx.json` 不存在或已过期（TC 重冻结、代码变更），先调用 `workflow-generate-mainflow-cases`；它无法生成的正向 UI/API TC（无稳定 locator、无法准备或隔离数据、纯视觉判断）按下一步降级，异常/边界/权限/性能专项 TC 也不由它生成。
 4. 写入 `.devflow/planning/features/{feature}/acceptance-test-bindings.json`：

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.96";
+export const PRODUCT_VERSION = "0.1.97";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";
 

package/src/startup-briefing.ts

@@ -0,0 +1,109 @@
+export type StartupIssue = { code?: unknown; detail?: unknown; path?: unknown };
+
+type StartupFacts = {
+  feature?: unknown;
+  phase?: unknown;
+  step?: { id?: unknown; label?: unknown; skill?: unknown; description?: unknown };
+  progress?: { index?: unknown; total?: unknown };
+  inputs?: Array<{ path?: unknown; required?: unknown; exists?: unknown }>;
+  outputs?: unknown[];
+  allowed_paths?: unknown[];
+  contract_id?: unknown;
+};
+
+type StartupHandoff = {
+  previous_step?: { id?: unknown; label?: unknown; outputs?: Array<{ path?: unknown }> };
+  carry?: { user_notes?: unknown[]; agent_report?: unknown };
+};
+
+type StartupMeta = { revision?: unknown; handoffProvided?: boolean };
+
+const issueDescriptions: Record<string, (issue: StartupIssue) => string> = {
+  PREVIOUS_OUTPUT_CHANGED: issue => `上一步的产物 ${String(issue.path ?? "未知路径")} 在交接后被修改过`,
+  PREVIOUS_OUTPUT_MISSING: issue => `上一步的产物 ${String(issue.path ?? "未知路径")} 不存在`,
+  HANDOFF_UNAVAILABLE: issue => `无法读取或校验交接单${issue.path ? ` ${String(issue.path)}` : ""}`,
+  STEP_UNAVAILABLE: () => "当前步骤不在工作流中",
+  MISSING_INPUT_FACT: issue => `本步需要的输入 ${String(issue.path ?? "未知路径")} 不存在`,
+  STALE_EXECUTION_CONTRACT: () => "执行合同已过期，请重新激活",
+  STALE_WORKFLOW_SNAPSHOT: () => "工作流快照已变化，执行合同不再有效",
+  STALE_STATE_SNAPSHOT: () => "STATE 快照已变化，执行合同不再有效",
+  UNREACHABLE_OBLIGATION: issue => `执行合同不允许产出 ${String(issue.path ?? "该必需产物")}`,
+  CONTRACT_TARGET_MISMATCH: () => "执行合同与当前 Feature 或步骤不匹配",
+  STARTUP_PREFLIGHT_INPUT_UNAVAILABLE: issue => `开工预检输入不可用${issue.detail ? `：${String(issue.detail)}` : ""}`,
+};
+
+export function describeStartupIssue(issue: StartupIssue): string {
+  const code = typeof issue.code === "string" && issue.code ? issue.code : "UNKNOWN_ISSUE";
+  return issueDescriptions[code]?.(issue) ?? `${code}：${String(issue.detail ?? "无详细信息")}`;
+}
+
+function strings(values: unknown[] | undefined): string[] {
+  return Array.isArray(values) ? values.filter((value): value is string => typeof value === "string" && value.length > 0) : [];
+}
+
+function truncate(value: string, limit: number): string {
+  if (value.length <= limit) return value;
+  return limit <= 1 ? "…".slice(0, limit) : `${value.slice(0, limit - 1)}…`;
+}
+
+export function renderStartupBriefing(facts: StartupFacts, handoff: StartupHandoff = {}, meta: StartupMeta = {}): string {
+  const render = (report: string, notes: string[]): string => {
+    const sections: string[] = [];
+    const step = facts.step;
+    const progress = facts.progress;
+    if (facts.feature && step?.id && step.label && progress?.index !== undefined && progress.total !== undefined) {
+      sections.push(`【需求】${String(facts.feature)} · 第 ${String(progress.index)} / ${String(progress.total)} 步：${String(step.label)}（${String(step.id)}）`);
+    }
+    if (step?.description) sections.push(`【本步目标】${String(step.description)}`);
+
+    const previous = handoff.previous_step;
+    const previousOutputs = previous?.outputs?.flatMap(item => typeof item?.path === "string" ? [item.path] : []) ?? [];
+    const handoffLines: string[] = [];
+    if (previous?.label) {
+      handoffLines.push(`- 上一步「${String(previous.label)}」已完成，产物：${previousOutputs.join("、") || "无已记录产物"}`);
+    }
+    if (notes.length > 0) {
+      handoffLines.push("- 用户在上一步审查期间的意见：", ...notes.map(note => `- ${note}`));
+    }
+    if (report) handoffLines.push(`- 上一步 AI 报告摘要：${report}`);
+    if (handoffLines.length > 0) sections.push(["【上一棒交接】", ...handoffLines].join("\n"));
+
+    const work: string[] = [];
+    if (step?.skill) work.push(`- 使用技能：skill://${String(step.skill)}`);
+    const inputText = facts.inputs?.flatMap(input => {
+      if (typeof input?.path !== "string") return [];
+      if (input.required === true && input.exists === true) return [`${input.path} ✓`];
+      if (input.required === false && input.exists !== true) return [`${input.path}（可选，缺失）`];
+      return [input.path];
+    }) ?? [];
+    if (inputText.length > 0) work.push(`- 已核对的输入：${inputText.join("／")}`);
+    const outputs = strings(facts.outputs);
+    if (outputs.length > 0) work.push(`- 必须产出：${outputs.join("、")}`);
+    const allowedPaths = strings(facts.allowed_paths);
+    if (allowedPaths.length > 0) work.push(`- 只允许写入：${allowedPaths.join("、")}`);
+    if (facts.contract_id) work.push(`- 执行合同已由 Runtime 激活：${String(facts.contract_id)}（不要再次 inspect 或 activate）`);
+    if (work.length > 0) sections.push(["【这一步你要做】", ...work].join("\n"));
+
+    sections.push("【完成标准】产出完成后，报告证据、未决项和验证结果并停止，等待用户回复\"批准执行\"。");
+    if (meta.revision !== undefined || facts.contract_id) {
+      sections.push(`【预检记录】STATE revision ${String(meta.revision ?? "未知")} · 环境体检通过 · 交接单校验${meta.handoffProvided ? "通过" : "不适用"} · 合同 ${String(facts.contract_id ?? "无")}`);
+    }
+    return sections.join("\n");
+  };
+
+  let report = typeof handoff.carry?.agent_report === "string" ? handoff.carry.agent_report : "";
+  let notes = handoff.carry?.user_notes?.flatMap(note => typeof note === "string" ? [note] : []) ?? [];
+  let result = render(report, notes);
+  if (result.length > 6000 && report) {
+    report = truncate(report, Math.max(0, report.length - (result.length - 6000)));
+    result = render(report, notes);
+  }
+  while (result.length > 6000 && notes.length > 0) {
+    const last = notes.at(-1)!;
+    const excess = result.length - 6000;
+    if (last.length > excess + 1) notes = [...notes.slice(0, -1), truncate(last, last.length - excess)];
+    else notes = notes.slice(0, -1);
+    result = render(report, notes);
+  }
+  return result.length <= 6000 ? result : truncate(result, 6000);
+}