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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workflow-loop
-Version: 0.3.7
+Version: 0.3.8
 Summary: 为 AI 驱动的软件开发提供有状态、可验证、可回退的工作流管理。
 Author: yuzyf
 License-Expression: MIT
@@ -95,29 +95,29 @@ flowchart TD
 - 安装时能够访问 GitHub 和 PyPI（Python 公共软件包仓库）。
 - 执行安装命令前，先进入要由 Workflow Loop 管理的项目根目录。
 
-## 安装 0.3.7
+## 安装 0.3.8
 
 安装器先进行只读检查并列出项目侧和电脑侧可能发生的全部持久修改。用户确认一次后，安装器才安装或复用全局 `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.8/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.8/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.8/install.ps1 | iex"
 ```
 
-安装命令固定读取 `v0.3.7` 正式发布中的脚本；不会跟随内容可能变化的 `latest`（最新版本）地址。
+安装命令固定读取 `v0.3.8` 正式发布中的脚本；不会跟随内容可能变化的 `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.8
 ```
 
 更新按需补齐电脑全局命令和当前项目，只直接覆盖项目根 `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.8` 替换成要发布的新版本号：
 
 ```bash
-uv run python scripts/release.py 0.3.7
+uv run python scripts/release.py 0.3.8
 ```
 
 运行这条命令本身就表示维护者接受当前仓库状态并承担跳过本地发布检查的风险。脚本不会再次确认，也不会在本地运行测试、构建或远程版本查询。它依次执行：

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

@@ -76,29 +76,29 @@ flowchart TD
 - 安装时能够访问 GitHub 和 PyPI（Python 公共软件包仓库）。
 - 执行安装命令前，先进入要由 Workflow Loop 管理的项目根目录。
 
-## 安装 0.3.7
+## 安装 0.3.8
 
 安装器先进行只读检查并列出项目侧和电脑侧可能发生的全部持久修改。用户确认一次后，安装器才安装或复用全局 `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.8/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.8/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.8/install.ps1 | iex"
 ```
 
-安装命令固定读取 `v0.3.7` 正式发布中的脚本；不会跟随内容可能变化的 `latest`（最新版本）地址。
+安装命令固定读取 `v0.3.8` 正式发布中的脚本；不会跟随内容可能变化的 `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.8
 ```
 
 更新按需补齐电脑全局命令和当前项目，只直接覆盖项目根 `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.8` 替换成要发布的新版本号：
 
 ```bash
-uv run python scripts/release.py 0.3.7
+uv run python scripts/release.py 0.3.8
 ```
 
 运行这条命令本身就表示维护者接受当前仓库状态并承担跳过本地发布检查的风险。脚本不会再次确认，也不会在本地运行测试、构建或远程版本查询。它依次执行：

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

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

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

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

{workflow_loop-0.3.7 → workflow_loop-0.3.8}/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.8}/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:
@@ -609,7 +636,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 +659,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)
 
@@ -1405,6 +1450,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 +1473,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 +1498,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("本阶段没有新增或修改缺陷记录文档")
 
@@ -1484,8 +1548,11 @@ def validate_reproduce_documents(
             topics.append(topic or "")
 
         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 +1941,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 +1970,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:
             # 纯人工主题：自动化验证由最终全量回归承担，验收条件在主题验收人工核对

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

@@ -136,6 +136,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,

{workflow_loop-0.3.7 → workflow_loop-0.3.8}/src/workflow_loop/cli.py

@@ -2129,6 +2129,28 @@ def _stage_failure_diagnostics(
     return legacy_diagnostics + list(structured_report.diagnostics)
 
 
+def _sync_stage_tables_before_checks(
+    project_root: str,
+    wf_state: state_mod.WorkflowState,
+    stage_name: str,
+) -> None:
+    """在本阶段全部固定检查之前，按当前工作记录表重新生成正式文档。
+
+    只负责生成；表本身的问题由阶段校验统一报告，这里不产出诊断，也不因表有问题
+    而中断——那样会掩盖同一次输出中其它可独立确认的问题。
+    """
+    if stage_name != wf_state.current_stage:
+        return
+    if not records_mod.stage_table_kinds(stage_name):
+        return
+    if not records_mod.workflow_uses_tables(wf_state, project_root):
+        return
+    try:
+        records_mod.sync_stage_tables(project_root, wf_state)
+    except (records_mod.RecordsError, OSError, ValueError):
+        return
+
+
 def validate_stage_output(
     project_root: str,
     wf_state: state_mod.WorkflowState,
@@ -2138,6 +2160,11 @@ def validate_stage_output(
     execute_regression: bool = True,
 ) -> tuple[bool, str]:
     """汇总安全只读检查；有前置错误时不执行最终回归。"""
+    # 产品规则要求第二道门先按当前工作记录表重新生成正式文档，再执行包括链接在内的
+    # 固定检查。先查链接会读到尚未重新生成的旧文档，于是第一次报坏链接、这一次顺带
+    # 把文档生成好，第二次原样重跑就通过。阶段校验内部仍会再同步一次，内容相同时
+    # 不写盘，因此这里提前同步不改变结果，只保证检查看到的是当前表对应的文档。
+    _sync_stage_tables_before_checks(project_root, wf_state, stage_name)
     responsibility_paths = verification_mod.stage_responsibility_paths(
         project_root,
         wf_state,
@@ -3704,6 +3731,21 @@ def cmd_return(args) -> None:
         wf_state.regression_test = state_mod.RegressionTestState()
     # 返回整体验收或最终设计同步：不删除已经通过的回归记录
 
+    # 删除下游结果文件后立即回补引用：指向已删文件的链接是程序自己写进上游文档和
+    # 索引的，不在同一次动作里改回“（待生成）”，退回后第一次门禁就会把它们报成坏链接。
+    reference_detail = ""
+    refreshed = records_mod.refresh_references_after_removal(
+        project_root, wf_state, affected_topics
+    )
+    if refreshed:
+        reference_detail = f"已按当前文件存在情况回补 {len(refreshed)} 份文档的下游引用"
+    bug_detail = bug_record_mod.reset_status_for_return(
+        project_root,
+        wf_state.workflow_id,
+        affected_topics,
+        args.to,
+    )
+
     journal_mod.append_entry(
         project_root,
         "流程退回",
@@ -3711,6 +3753,8 @@ def cmd_return(args) -> None:
         workflow_id=wf_state.workflow_id,
         from_stage=previous_stage,
         to_stage=args.to,
+        references_refreshed=refreshed,
+        bug_status_reset=bug_detail,
         topics=affected_topics,
         reason=args.reason.strip(),
         traceability=trace_detail,
@@ -3725,6 +3769,10 @@ def cmd_return(args) -> None:
     print(f"原因: {args.reason.strip()}")
     if trace_detail:
         print(trace_detail)
+    if reference_detail:
+        print(reference_detail)
+    if bug_detail:
+        print(bug_detail)
     print("未列出的独立主题保留当前测试和验收记录。")
     print_recovery_details(wf_state)
     print_next_step(current_stage_next_instruction(wf_state))
@@ -4242,6 +4290,7 @@ def cmd_gate(args) -> None:
                 stage_state.internal_step = "test_code"
             # 写 journal：门禁讨论完毕
             journal_mod.append_entry(project_root, "门禁讨论完毕", "user",
+                                    workflow_id=wf_state.workflow_id,
                                     stage=stage_name, passed=True,
                                     plan_confirmed_hash=stage_state.plan_confirmed_hash
                                     if stage_name == "impl" else None,
@@ -4450,6 +4499,7 @@ def cmd_gate(args) -> None:
                 project_root,
                 "门禁代码校验",
                 "workflow.py",
+                workflow_id=wf_state.workflow_id,
                 stage=stage_name,
                 passed=False,
                 details=details,
@@ -4529,6 +4579,7 @@ def cmd_gate(args) -> None:
             project_root,
             "门禁代码校验",
             "workflow.py",
+            workflow_id=wf_state.workflow_id,
             stage=stage_name,
             passed=True,
             details=details,
@@ -4996,6 +5047,7 @@ def cmd_gate(args) -> None:
 
     # 写 journal：门禁用户确认
     journal_mod.append_entry(project_root, "门禁用户确认", "user",
+                            workflow_id=wf_state.workflow_id,
                             stage=stage_name, passed=True)
 
     # 找下一个 stage
@@ -6260,7 +6312,20 @@ def main() -> None:
     except SystemExit:
         raise
     except Exception as exc:  # noqa: BLE001
-        print(f"错误：命令执行失败（{type(exc).__name__}: {exc}）")
+        # 异常自带结构化诊断时按统一格式逐项展示，不把已经取得的位置、预期、
+        # 实际、证据、影响和改法压成一行文字（R22）。
+        carried = getattr(exc, "diagnostics", None)
+        if carried:
+            print(f"错误：命令执行失败（{type(exc).__name__}）")
+            print(
+                diagnostics_mod.ValidationReport(
+                    stage=getattr(args, "stage", "") or args.command,
+                    gate="命令执行中断",
+                    diagnostics=list(carried),
+                ).render()
+            )
+        else:
+            print(f"错误：命令执行失败（{type(exc).__name__}: {exc}）")
         print("工作流状态没有被本次失败修改；先处理上面指出的原因。")
         print_next_step("由 AI 执行 `workflow status` 查看当前状态；问题无法自行恢复时如实报告用户")
 

{workflow_loop-0.3.7 → workflow_loop-0.3.8}/src/workflow_loop/data/Standardized_Repository/global/workflow_lifecycle.md

@@ -110,6 +110,7 @@ AI 每次执行命令前，先用直白中文说明四件事：
 
 某项检查依赖已经失败或缺失的前置事实时，不猜结论，明确写“未检查”，并说明依赖哪个前置问题。全部问题之后只给一条当前可执行的下一命令，同时写清执行者、会修改的状态或文件、成功条件，以及成功后进入的阶段。AI 必须原样单独执行这条命令，不加 `head`、`tail`、管道、分号或 `echo`，避免掩盖真实退出码和完整错误。
 
+<a id="文档链接要求"></a>
 ### 文档链接要求
 
 只有目标文件已经存在时才写 Markdown 链接。后续阶段尚未生成的文档只写反引号包裹的普通项目相对路径和“（待生成）”；不得创建指向不存在文件的链接。文件生成后，再把对应普通路径改成可导航链接。

{workflow_loop-0.3.7 → workflow_loop-0.3.8}/src/workflow_loop/installer.py

@@ -55,6 +55,11 @@ AGENTS_MD_CONTENT = """# Agent 契约
 - 失败或作废时保留已经发生的本地和外部状态，不自动回滚，并写清已完成、未执行和失败内容。
 - 执行中发现需要开发时，结束当前简单轮次，说明原因并推荐完整路线；用户确认后再开始新轮次。
 
+## 工作记录表
+
+- 环节材料列出工作记录表时，AI 在表中填写固定事实（数据按栏目填，叙述一段一条），
+  不手写正式文档的固定标题和表格；正式文档由程序按表生成，改内容只改表。
+
 ## 表达要求
 
 AI 回复用户和编写正式文档时：