workflow-loop 0.3.7__tar.gz → 0.3.9__tar.gz

{workflow_loop-0.3.7/src/workflow_loop.egg-info → workflow_loop-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workflow-loop
-Version: 0.3.7
+Version: 0.3.9
 Summary: 为 AI 驱动的软件开发提供有状态、可验证、可回退的工作流管理。
 Author: yuzyf
 License-Expression: MIT
@@ -95,29 +95,29 @@ flowchart TD
 - 安装时能够访问 GitHub 和 PyPI（Python 公共软件包仓库）。
 - 执行安装命令前，先进入要由 Workflow Loop 管理的项目根目录。
 
-## 安装 0.3.7
+## 安装 0.3.9
 
 安装器先进行只读检查并列出项目侧和电脑侧可能发生的全部持久修改。用户确认一次后，安装器才安装或复用全局 `workflow` 命令，并把智能体契约、产物模板和工作规范写入当前项目；用户取消或安装失败时不会留下只完成一部分的安装。
 
 ### macOS
 
 ```bash
-curl -fsSL https://github.com/yuzyf/workflow_loop/releases/download/v0.3.7/install.sh | bash
+curl -fsSL https://github.com/yuzyf/workflow_loop/releases/download/v0.3.9/install.sh | bash
 ```
 
 ### Linux
 
 ```bash
-curl -fsSL https://github.com/yuzyf/workflow_loop/releases/download/v0.3.7/install.sh | bash
+curl -fsSL https://github.com/yuzyf/workflow_loop/releases/download/v0.3.9/install.sh | bash
 ```
 
 ### 原生 Windows
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/yuzyf/workflow_loop/releases/download/v0.3.7/install.ps1 | iex"
+powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/yuzyf/workflow_loop/releases/download/v0.3.9/install.ps1 | iex"
 ```
 
-安装命令固定读取 `v0.3.7` 正式发布中的脚本；不会跟随内容可能变化的 `latest`（最新版本）地址。
+安装命令固定读取 `v0.3.9` 正式发布中的脚本；不会跟随内容可能变化的 `latest`（最新版本）地址。
 
 ## 更新与卸载
 
@@ -125,7 +125,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/y
 
 ```bash
 workflow update
-workflow update --version 0.3.7
+workflow update --version 0.3.9
 ```
 
 更新按需补齐电脑全局命令和当前项目，只直接覆盖项目根 `AGENTS.md`、`.workflow_loop/Template_Repository/`、`.workflow_loop/Standardized_Repository/`，以及 `.workflow_loop/project.json` 中的安装版本字段。更新不创建备份，不回滚已经完成的步骤；当前轮次状态、历史、回退资料、业务代码和正式产物保持不变。失败后重新执行同一命令即可继续补齐。
@@ -229,10 +229,10 @@ uv run python -m build
 
 ## 发布正式版本
 
-项目维护者确认当前仓库内容可以直接发布后，在仓库根目录执行下面的命令，并把 `0.3.7` 替换成要发布的新版本号：
+项目维护者确认当前仓库内容可以直接发布后，在仓库根目录执行下面的命令，并把 `0.3.9` 替换成要发布的新版本号：
 
 ```bash
-uv run python scripts/release.py 0.3.7
+uv run python scripts/release.py 0.3.9
 ```
 
 运行这条命令本身就表示维护者接受当前仓库状态并承担跳过本地发布检查的风险。脚本不会再次确认，也不会在本地运行测试、构建或远程版本查询。它依次执行：

{workflow_loop-0.3.7 → workflow_loop-0.3.9}/README.md

@@ -76,29 +76,29 @@ flowchart TD
 - 安装时能够访问 GitHub 和 PyPI（Python 公共软件包仓库）。
 - 执行安装命令前，先进入要由 Workflow Loop 管理的项目根目录。
 
-## 安装 0.3.7
+## 安装 0.3.9
 
 安装器先进行只读检查并列出项目侧和电脑侧可能发生的全部持久修改。用户确认一次后，安装器才安装或复用全局 `workflow` 命令，并把智能体契约、产物模板和工作规范写入当前项目；用户取消或安装失败时不会留下只完成一部分的安装。
 
 ### macOS
 
 ```bash
-curl -fsSL https://github.com/yuzyf/workflow_loop/releases/download/v0.3.7/install.sh | bash
+curl -fsSL https://github.com/yuzyf/workflow_loop/releases/download/v0.3.9/install.sh | bash
 ```
 
 ### Linux
 
 ```bash
-curl -fsSL https://github.com/yuzyf/workflow_loop/releases/download/v0.3.7/install.sh | bash
+curl -fsSL https://github.com/yuzyf/workflow_loop/releases/download/v0.3.9/install.sh | bash
 ```
 
 ### 原生 Windows
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/yuzyf/workflow_loop/releases/download/v0.3.7/install.ps1 | iex"
+powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/yuzyf/workflow_loop/releases/download/v0.3.9/install.ps1 | iex"
 ```
 
-安装命令固定读取 `v0.3.7` 正式发布中的脚本；不会跟随内容可能变化的 `latest`（最新版本）地址。
+安装命令固定读取 `v0.3.9` 正式发布中的脚本；不会跟随内容可能变化的 `latest`（最新版本）地址。
 
 ## 更新与卸载
 
@@ -106,7 +106,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/y
 
 ```bash
 workflow update
-workflow update --version 0.3.7
+workflow update --version 0.3.9
 ```
 
 更新按需补齐电脑全局命令和当前项目，只直接覆盖项目根 `AGENTS.md`、`.workflow_loop/Template_Repository/`、`.workflow_loop/Standardized_Repository/`，以及 `.workflow_loop/project.json` 中的安装版本字段。更新不创建备份，不回滚已经完成的步骤；当前轮次状态、历史、回退资料、业务代码和正式产物保持不变。失败后重新执行同一命令即可继续补齐。
@@ -210,10 +210,10 @@ uv run python -m build
 
 ## 发布正式版本
 
-项目维护者确认当前仓库内容可以直接发布后，在仓库根目录执行下面的命令，并把 `0.3.7` 替换成要发布的新版本号：
+项目维护者确认当前仓库内容可以直接发布后，在仓库根目录执行下面的命令，并把 `0.3.9` 替换成要发布的新版本号：
 
 ```bash
-uv run python scripts/release.py 0.3.7
+uv run python scripts/release.py 0.3.9
 ```
 
 运行这条命令本身就表示维护者接受当前仓库状态并承担跳过本地发布检查的风险。脚本不会再次确认，也不会在本地运行测试、构建或远程版本查询。它依次执行：

{workflow_loop-0.3.7 → workflow_loop-0.3.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "workflow-loop"
-version = "0.3.7"
+version = "0.3.9"
 description = "为 AI 驱动的软件开发提供有状态、可验证、可回退的工作流管理。"
 readme = "README.md"
 requires-python = ">=3.11"

{workflow_loop-0.3.7 → workflow_loop-0.3.9}/src/workflow_loop/__init__.py

@@ -1,6 +1,6 @@
 # 包版本号，用于 pip/uv 安装时版本匹配
-__version__ = "0.3.7"
+__version__ = "0.3.9"
 # 产品身份标识：workflow --version 输出、安装脚本身份核对和安装事务校验共用同一组常量
-# 本次发布版本为 0.3.7；后续发布使用尚未被 PyPI 占用的新版本号
+# 本次发布版本为 0.3.9；后续发布使用尚未被 PyPI 占用的新版本号
 PRODUCT_NAME = "workflow-loop"
 PRODUCT_IDENTITY = f"{PRODUCT_NAME} {__version__}"

{workflow_loop-0.3.7 → workflow_loop-0.3.9}/src/workflow_loop/artifact_paths.py

@@ -82,15 +82,23 @@ def resolve_file_key(
     saved_keys: dict[str, str],
     all_used_keys: set[str],
     display_name: str,
+    keys_by_name_all: dict[str, str] | None = None,
 ) -> str:
     """在一个分类内解析显示名称的文件标识。
 
     saved_keys 是该分类已保存的 显示名称→文件标识 映射；all_used_keys 是全部
-    分类已占用的标识（大小写不敏感比较，避免只在大小写上不同的路径冲突）。
+    分类已占用的标识（大小写不敏感比较，避免只在大小写上不同的路径冲突）；
+    keys_by_name_all 是全部分类的 显示名称→文件标识 映射。
     已保存的名称直接返回旧标识；新名称生成标识，冲突时依次追加 `_2`、`_3`。
+
+    同一显示名称在不同分类表示同一件事（缺陷名与验收主题名相同是常态），
+    因此先在全部分类中按名称复用同一标识；否则第二个分类必然被迫追加 `_2`，
+    使生成路径与登记路径分叉。不同名称之间仍不允许共用标识。
     """
     if display_name in saved_keys:
         return saved_keys[display_name]
+    if keys_by_name_all is not None and display_name in keys_by_name_all:
+        return keys_by_name_all[display_name]
     base_key = make_file_key(display_name)
     used_lower = {key.lower() for key in all_used_keys}
     candidate = base_key
@@ -115,12 +123,13 @@ def register_file_keys(project, category: str, display_names: list[str]) -> dict
         for mapping in project.artifact_file_keys.values()
         for key in mapping.values()
     }
+    keys_by_name_all = _keys_by_name(project)
     reverse = {key: name for name, key in keys.items()}
     added: dict[str, str] = {}
     for display_name in display_names:
         if display_name in keys:
             continue
-        key = resolve_file_key(keys, all_used, display_name)
+        key = resolve_file_key(keys, all_used, display_name, keys_by_name_all)
         owner = reverse.get(key)
         if owner is not None and owner != display_name:
             raise ValueError(
@@ -129,10 +138,21 @@ def register_file_keys(project, category: str, display_names: list[str]) -> dict
         keys[display_name] = key
         reverse[key] = display_name
         all_used.add(key)
+        keys_by_name_all[display_name] = key
         added[display_name] = key
     return added
 
 
+def _keys_by_name(project) -> dict[str, str]:
+    """全部分类的 显示名称→文件标识 映射，供同名跨分类复用同一标识。"""
+    if project is None:
+        return {}
+    merged: dict[str, str] = {}
+    for mapping in project.artifact_file_keys.values():
+        merged.update(mapping)
+    return merged
+
+
 def lookup_file_key(project, category: str, display_name: str) -> str | None:
     """读取已保存的文件标识；没有登记时返回 None。"""
     if project is None:
@@ -152,7 +172,7 @@ def resolve_key_for(project, category: str, display_name: str) -> str:
         if project is not None
         else set()
     )
-    return resolve_file_key(saved, all_used, display_name)
+    return resolve_file_key(saved, all_used, display_name, _keys_by_name(project))
 
 
 # ─── 按文件标识生成动态正式产物路径 ───

{workflow_loop-0.3.7 → workflow_loop-0.3.9}/src/workflow_loop/artifact_validation.py

@@ -233,20 +233,47 @@ def _markdown_tables(content: str) -> list[tuple[list[str], list[list[str]]]]:
     return tables
 
 
-def _has_real_text(value: str | None, *, allow_none: bool = False) -> bool:
+# 模板占位写法：整行被尖括号包住，例如 `<用户在什么操作中看到了什么问题。>`。
+# 只按整行判定；正文里合法出现的半角小于号（路径占位写法、HTML 锚点、比较运算）
+# 不影响判定，否则含实质内容的长章节会被整段误判为未填写。
+_TEMPLATE_PLACEHOLDER_LINE_RE = re.compile(r"^<[^<>]*>$")
+
+
+def _placeholder_lines(value: str) -> list[str]:
+    """返回值中仍是模板占位写法的行；全部非空行都命中才算整体未填写。"""
+    stripped_lines = [
+        re.sub(r"^[-*]\s+", "", line).strip()
+        for line in value.splitlines()
+        if line.strip()
+    ]
+    if not stripped_lines:
+        return []
+    hits = [line for line in stripped_lines if _TEMPLATE_PLACEHOLDER_LINE_RE.match(line)]
+    return hits if len(hits) == len(stripped_lines) else []
+
+
+def _no_real_text_reason(value: str | None, *, allow_none: bool = False) -> str | None:
+    """值不算已填写时返回具体原因和命中内容；已填写时返回 None。"""
     if value is None:
-        return False
+        return "缺少这一节"
     normalized = value.strip()
     if not normalized:
-        return False
+        return "内容为空"
     if allow_none and normalized in {"无", "暂无"}:
-        return True
-    lowered = normalized.lower()
-    return not (
-        normalized in {"无", "暂无", "待补充", "未填写"}
-        or "<" in normalized
-        or "todo" in lowered
-    )
+        return None
+    if normalized in {"无", "暂无", "待补充", "未填写"}:
+        return f"整段只写了占位词 {normalized!r}"
+    if "todo" in normalized.lower():
+        return "内容里仍留着 TODO 标记"
+    hits = _placeholder_lines(normalized)
+    if hits:
+        sample = hits[0] if len(hits[0]) <= 40 else hits[0][:40] + "…"
+        return f"整段仍是模板占位写法，例如 {sample}"
+    return None
+
+
+def _has_real_text(value: str | None, *, allow_none: bool = False) -> bool:
+    return _no_real_text_reason(value, allow_none=allow_none) is None
 
 
 def _format_validation_failures(failures: list[str]) -> str:
@@ -587,6 +614,10 @@ def _required_final_machine_record_ids(wf_state) -> tuple[set[str] | None, str]:
             required.update(record.test_record_ids)
 
     regression = wf_state.regression_test
+    if regression.status == "skipped-by-no-change":
+        # R9/R9a：无代码改动跳过的轮次没有机器执行记录；设计同步照常，
+        # 结论按真实差异为无需修改，不要求不存在的 REG 编号。
+        return required, ""
     if regression.status != "passed" or not regression.record_id:
         return None, "最终全量回归没有当前有效的机器记录编号"
     required.add(regression.record_id)
@@ -609,7 +640,12 @@ def changed_stage_paths(
     stage_name: str,
     current_paths: list[str],
 ) -> tuple[bool, str, list[str]]:
-    """比较讨论完成时的基线，返回本阶段新增、修改或删除的文件。"""
+    """比较讨论完成时的基线，返回本阶段新增、修改或删除的文件。
+
+    启用工作记录表的轮次里正式文档是程序按表的确定性输出：表没有变化时文档必然
+    逐字节相同，"文档没变"不等于"本阶段没有产出"。这种情况下按表判断产出，并把
+    本阶段登记的产物路径交给下游检查，不要求 AI 制造无实质内容的修改。
+    """
     state = load_state(project_root)
     if state is None or stage_name not in state.stages:
         return (False, "找不到当前工作流阶段状态，无法判断文件是否属于本次工作", [])
@@ -627,6 +663,19 @@ def changed_stage_paths(
         if baseline_hashes.get(rel_path) != current_hashes.get(rel_path)
     ]
     if not changed:
+        from . import records as records_mod
+
+        if records_mod.stage_table_kinds(stage_name) and records_mod.workflow_uses_tables(
+            state, project_root
+        ):
+            # 变化清单如实为空：确实没有文件变化。调用方要判断“本阶段的产出是哪些”时
+            # 按内容识别，不能把未变化的文件当成本阶段改过——最终设计同步正是用这份
+            # 清单确认产品文档没有被改动。
+            return (
+                True,
+                "表模式：正式文档由程序按工作记录表生成，内容与上次相同时按表判断产出",
+                [],
+            )
         return (False, "相关文件与讨论完成时相同，不能证明本阶段已经生成或修改产物", [])
     return (True, f"本阶段发生变化的文件: {changed}", changed)
 
@@ -1218,6 +1267,8 @@ def validate_project_design_feature_consistency(project_root: str) -> tuple[bool
 def validate_final_code_design_document(
     project_root: str,
     workflow_id: str,
+    *,
+    candidate_content: str | None = None,
 ) -> tuple[bool, str]:
     """校验最终架构文档已经完成产品、功能、架构和真实代码映射。
 
@@ -1227,8 +1278,8 @@ def validate_final_code_design_document(
     relative_path = artifact_paths_mod.CODE_DESIGN_DOC
     full_path = os.path.join(project_root, relative_path)
     errors: list[str] = []
-    architecture_exists = os.path.isfile(full_path)
-    content = _read_text(project_root, relative_path) if architecture_exists else ""
+    architecture_exists = candidate_content is not None or os.path.isfile(full_path)
+    content = candidate_content if candidate_content is not None else (_read_text(project_root, relative_path) if architecture_exists else "")
     if not architecture_exists:
         errors.append(f"{relative_path} 不存在")
 
@@ -1393,7 +1444,9 @@ def validate_final_code_design_document(
                 extra_ids = sorted(actual_record_ids - required_record_ids)
                 errors.append(
                     f"{relative_path} 第 9 章“核对依据”字段必须精确列出当前机器记录编号；"
-                    f"缺少={missing_ids}，额外或拼接错误={extra_ids}"
+                    f"当前缺少={missing_ids}，不在当前有效集合中的编号={extra_ids}。"
+                    "测试或最终全量回归重跑会使旧编号失效；额外编号也可能是拼写或拼接错误，"
+                    "请从当前工作流状态重新取得有效编号集合，不要沿用历史编号"
                 )
 
     if errors:
@@ -1405,6 +1458,21 @@ def validate_final_code_design_document(
     )
 
 
+def _current_workflow_bug_documents(project_root: str, workflow_id: str) -> list[str]:
+    """按文件内的工作流编号找出本轮的缺陷记录，不依赖本阶段变化清单。"""
+    bug_dir = os.path.join(project_root, "bug")
+    if not os.path.isdir(bug_dir):
+        return []
+    found: list[str] = []
+    for filename in sorted(os.listdir(bug_dir)):
+        if not filename.endswith(".md") or filename in BUG_INDEX_FILENAMES:
+            continue
+        relative = f"bug/{filename}"
+        if _field(_read_text(project_root, relative), "工作流编号") == workflow_id:
+            found.append(relative)
+    return found
+
+
 def validate_reproduce_documents(
     project_root: str,
     changed_paths: list[str],
@@ -1413,8 +1481,8 @@ def validate_reproduce_documents(
     index_path = artifact_paths_mod.BUG_INDEX_DOC
     normalized_changed = [path.replace(os.sep, "/") for path in changed_paths]
     failures: list[str] = []
-    if index_path not in normalized_changed:
-        failures.append(f"{index_path} 没有在本阶段更新")
+    # 索引按内容判定：存在且链接本轮缺陷记录即可。索引由程序生成，内容已经正确时
+    # 本阶段不需要再改它，"这一轮没有改过"不是问题。
     index_exists = os.path.isfile(os.path.join(project_root, index_path))
     if not index_exists:
         failures.append(f"{index_path} 不存在")
@@ -1438,6 +1506,10 @@ def validate_reproduce_documents(
         for rel_path in changed_bug_candidates
         if os.path.isfile(os.path.join(project_root, rel_path))
     ]
+    if not changed_bug_docs:
+        # 表模式下缺陷记录由程序按表生成，重走本环节时内容可能与上次逐字节相同，
+        # 变化清单为空不等于本轮没有缺陷记录。按文件内的工作流编号识别本轮记录。
+        changed_bug_docs = _current_workflow_bug_documents(project_root, workflow_id)
     if not changed_bug_docs:
         failures.append("本阶段没有新增或修改缺陷记录文档")
 
@@ -1453,6 +1525,27 @@ def validate_reproduce_documents(
     ]
 
     topics: list[str] = []
+    from . import records as records_mod
+
+    workflow = load_state(project_root)
+    uses_tables = workflow is not None and records_mod.workflow_uses_tables(workflow, project_root)
+    fact_tables = {}
+    table_problems, tables = records_mod.bug_record_tables(
+        project_root, workflow_id, list(workflow.topics) if uses_tables else None,
+    )
+    failures.extend(detail for _, detail in table_problems)
+    for table_relative, table in tables:
+        fact_tables[table["验收主题"]] = table
+        failures.extend(
+            f"{table_relative}：{detail}" for _category, detail in
+            records_mod.validate_table("bug_record", table, project_root=project_root)
+        )
+    if uses_tables:
+        changed_bug_docs = list(dict.fromkeys(changed_bug_docs + _current_workflow_bug_documents(project_root, workflow_id)))
+        for table in fact_tables.values():
+            expected = f"bug/缺陷_{records_mod.bug_file_key(project_root, table['验收主题'])}.md"
+            if expected not in changed_bug_docs:
+                failures.append(f"主题「{table['验收主题']}」缺少本轮正式缺陷记录 {expected}")
     for rel_path in changed_bug_docs:
         filename = os.path.basename(rel_path)
         if not BUG_FILENAME_RE.match(filename):
@@ -1483,9 +1576,21 @@ def validate_reproduce_documents(
         else:
             topics.append(topic or "")
 
+        fact_table = fact_tables.get(topic)
+        if uses_tables and fact_table is None:
+            failures.append(f"{filename} 的主题「{topic}」缺少对应的缺陷记录工作记录表")
+        if fact_table is not None and fact_table.get("表版本") == "3":
+            for heading in required_sections:
+                if _section(content, heading) is None:
+                    failures.append(f"{filename} 缺少“{heading}”章节")
+            continue
+
         for heading in required_sections:
-            if not _has_real_text(_section(content, heading), allow_none=heading.startswith("7.")):
-                failures.append(f"{filename} 的“{heading}”缺少具体内容")
+            allow_none = heading.startswith("7.")
+            section_text = _section(content, heading)
+            reason = _no_real_text_reason(section_text, allow_none=allow_none)
+            if reason is not None:
+                failures.append(f"{filename} 的“{heading}”缺少具体内容：{reason}")
 
         condition_section = _section(content, "2. 真实复现条件") or ""
         if not _has_real_text(_field(condition_section, "运行环境")):
@@ -1874,24 +1979,17 @@ def validate_downstream_traceability(
 
 
 def _table_mode_qa(project_root: str, workflow_id: str, topics: list[str]) -> bool:
-    """全部主题都有已填测试工作记录表时，qa 的文档校验走表核对。"""
+    """本轮是否按测试工作记录表校验测试计划。
+
+    R11：只看开工时冻结在工作流状态里的表版本。表缺失、为空或解析失败时
+    仍留在表模式，由表校验报出具体问题，不退回按文档正文逐字检查的旧方式。
+    """
     from . import records as records_mod
 
-    if not topics:
+    state = load_state(project_root)
+    if state is None or state.workflow_id != workflow_id:
         return False
-    for topic in topics:
-        relative = records_mod.table_relative_path(
-            project_root, workflow_id, "test_plan", topic
-        )
-        if not records_mod.table_exists(project_root, relative):
-            return False
-        try:
-            table = records_mod.load_table(os.path.join(project_root, relative))
-        except records_mod.RecordsError:
-            return False
-        if not (table.get("测试项") or table.get("测试范围说明")):
-            return False
-    return True
+    return records_mod.workflow_uses_tables(state, project_root)
 
 
 def _validate_test_plan_from_tables(
@@ -1910,7 +2008,18 @@ def _validate_test_plan_from_tables(
         relative = records_mod.table_relative_path(
             project_root, workflow_id, "test_plan", topic
         )
-        table = records_mod.load_table(os.path.join(project_root, relative))
+        # 表模式下缺表、空表和解析失败都在这里报具体问题；不退回文档检查（R11）。
+        if not records_mod.table_exists(project_root, relative):
+            failures.append(
+                f"主题「{topic}」缺少测试计划工作记录表（{relative}）；"
+                "请执行 workflow scaffold 补齐后填写测试项，再重新门禁"
+            )
+            continue
+        try:
+            table = records_mod.load_table(os.path.join(project_root, relative))
+        except records_mod.RecordsError as exc:
+            failures.append(f"主题「{topic}」的测试计划工作记录表无法解析（{relative}）：{exc}")
+            continue
         rows = table.get("测试项", [])
         if not rows:
             # 纯人工主题：自动化验证由最终全量回归承担，验收条件在主题验收人工核对
@@ -2575,6 +2684,11 @@ def validate_final_regression_state(
         return (False, "找不到当前工作流状态，不能确认最终全量回归")
     result = state.regression_test
     failures: list[str] = []
+    if result.status == "skipped-by-no-change":
+        # R9：无代码改动跳过的轮次按判定依据核对，不要求不存在的执行事实
+        if not result.skip_reason or not result.skipped_at:
+            return (False, "最终全量回归标记为无代码改动跳过，但缺少跳过依据或判定时间")
+        return (True, f"最终全量回归按无代码改动跳过（依据已记录：{result.skipped_at}）")
     if result.status == "unavailable":
         failures.append("最终全量回归明确失败：当前平台没有可执行的项目全量测试入口")
     elif result.status != "passed":

{workflow_loop-0.3.7 → workflow_loop-0.3.9}/src/workflow_loop/bug_record.py

@@ -4,6 +4,10 @@ from __future__ import annotations
 
 import re
 from pathlib import Path
+from urllib.parse import unquote
+
+from markdown_it import MarkdownIt
+from markdown_it.common.utils import unescapeAll
 
 from . import artifact_paths as artifact_paths_mod
 from .state import load_state
@@ -77,28 +81,68 @@ def _replace_result_update(content: str, stage_label: str, workflow_id: str, bod
     return content[: section_match.start(1)] + section + content[section_match.end(1) :]
 
 
+def index_entry(content: str, filename: str) -> tuple[tuple[int, int], list[str]] | None:
+    """定位一个缺陷索引行，返回原文行范围和单元格；重复入口直接拒绝。"""
+    found = []
+    row_range = None
+    cells: list[str] = []
+    matches = False
+    for token in MarkdownIt("commonmark").enable("table").parse(content):
+        if token.type == "tr_open":
+            row_range, cells, matches = token.map, [], False
+        elif token.type == "inline" and row_range is not None:
+            if not cells:
+                matches = any(
+                    child.type == "link_open"
+                    and unquote(child.attrGet("href") or "") in {filename, f"./{filename}"}
+                    for child in token.children or []
+                )
+            cells.append(unescapeAll(token.content))
+        elif token.type == "tr_close":
+            if matches:
+                if len(cells) < 2:
+                    raise ValueError(f"缺陷索引中 {filename} 的条目缺少入口或状态列")
+                found.append((tuple(row_range), cells))
+            row_range = None
+    if len(found) > 1:
+        raise ValueError(f"缺陷索引中 {filename} 有重复入口，不能确定应更新哪一行")
+    return found[0] if found else None
+
+
+def replace_index_entry(content: str, entry: tuple[int, int], cells: list[str]) -> str:
+    lines = content.splitlines(keepends=True)
+    rendered = [cell.replace("\\", "\\\\").replace("|", "\\|").replace("\n", "<br>") for cell in cells]
+    lines[entry[0]:entry[1]] = ["| " + " | ".join(rendered) + " |\n"]
+    return "".join(lines)
+
+
+def index_width(content: str) -> int:
+    """旧索引可只有入口和状态两列；新增条目沿用其表格结构。"""
+    width = 0
+    for token in MarkdownIt("commonmark").enable("table").parse(content):
+        if token.type == "th_open":
+            width += 1
+        elif token.type == "thead_close":
+            if width not in {2, 4}:
+                raise ValueError("缺陷索引必须使用旧版两列或当前四列表格，不能覆盖未知表格结构")
+            return width
+    if content.strip():
+        raise ValueError("缺陷索引没有可解析的表格，保留原内容")
+    return 4
+
+
 def _update_index_status(project_root: str, filename: str, status: str) -> None:
     index_path = Path(project_root) / BUG_INDEX
     if not index_path.is_file():
         raise ValueError(f"{BUG_INDEX} 不存在，无法更新缺陷索引")
 
     content = index_path.read_text(encoding="utf-8")
-    lines = content.splitlines()
-    markers = {f"({filename})", f"(./{filename})"}
-    found = False
-    for index, line in enumerate(lines):
-        if not any(marker in line for marker in markers) or not line.strip().startswith("|"):
-            continue
-        cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
-        if len(cells) < 2:
-            continue
-        cells[-1] = status
-        lines[index] = "| " + " | ".join(cells) + " |"
-        found = True
-        break
-    if not found:
+    entry = index_entry(content, filename)
+    if entry is None:
         raise ValueError(f"{BUG_INDEX} 没有链接缺陷记录: {filename}")
-    index_path.write_text("\n".join(lines) + ("\n" if content.endswith("\n") else ""), encoding="utf-8")
+    row_range, cells = entry
+    cells[-1] = status
+    index_path.write_text(replace_index_entry(content, row_range, cells), encoding="utf-8")
 
 
 def update_status(
@@ -136,6 +180,69 @@ def update_status(
     return f"已更新缺陷状态“{status}”: {updated}"
 
 
+# 各阶段追加到第 8 节的结论块标题，按流程顺序排列。退回时清除目标环节之后的块。
+_RESULT_STAGE_LABELS = ("主题验收结果", "最终全量回归结果", "整体验收确认")
+# 退回目标 → 该目标之后失效的结论块起点下标
+_RETURN_TARGET_FIRST_INVALID = {
+    "spec": 0,
+    "reproduce": 0,
+    "spike": 0,
+    "acceptance_plan": 0,
+    "impl": 0,
+    "qa": 0,
+    "test_plan": 0,
+    "test_code": 0,
+    "test_execution": 0,
+    "topic_acceptance": 0,
+    "regression_test": 1,
+    "overall_acceptance": 2,
+}
+
+
+def reset_status_for_return(
+    project_root: str,
+    workflow_id: str,
+    topics: list[str],
+    target_stage: str,
+) -> str:
+    """退回时清除已经失效的阶段结论块，并把缺陷索引状态改回复现阶段状态。
+
+    这些结论块由程序追加，块内链接指向测试结果和验收结果文档。退回会删除那些
+    文档，块留在缺陷记录里就成了指向不存在文件的坏链接，同时也在冒充仍然有效的
+    结论。目标环节之前已经完成的阶段结论保留不动。
+    """
+    first_invalid = _RETURN_TARGET_FIRST_INVALID.get(target_stage)
+    if first_invalid is None:
+        return ""
+    invalid_labels = _RESULT_STAGE_LABELS[first_invalid:]
+    if not invalid_labels:
+        return ""
+    try:
+        records = _records_for_workflow(project_root, workflow_id, topics)
+    except ValueError:
+        # 本轮没有缺陷记录（非修缺陷轮次）时无需处理，不把它当成退回失败。
+        return ""
+    updated: list[str] = []
+    for path, _topic in records:
+        content = path.read_text(encoding="utf-8")
+        new_content = content
+        for label in invalid_labels:
+            new_content = re.sub(
+                rf"^###\s+{re.escape(label)}（工作流 {re.escape(workflow_id)}）\s*$\n"
+                r".*?(?=^###\s+|\Z)",
+                "",
+                new_content,
+                flags=re.MULTILINE | re.DOTALL,
+            )
+        if new_content != content:
+            path.write_text(new_content.rstrip() + "\n", encoding="utf-8")
+            _update_index_status(project_root, path.name, "根因已确认")
+            updated.append(path.name)
+    if not updated:
+        return ""
+    return f"已清除失效的缺陷结论块并把索引状态改回“根因已确认”: {updated}"
+
+
 def record_topic_acceptance_pass(project_root: str, workflow_id: str, topics: list[str]) -> str:
     return update_status(
         project_root,