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

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

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

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

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

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

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

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

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

{workflow_loop-0.3.8 → workflow_loop-0.4.0}/src/workflow_loop/artifact_validation.py

@@ -614,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)
@@ -641,6 +645,11 @@ def changed_stage_paths(
     启用工作记录表的轮次里正式文档是程序按表的确定性输出：表没有变化时文档必然
     逐字节相同，"文档没变"不等于"本阶段没有产出"。这种情况下按表判断产出，并把
     本阶段登记的产物路径交给下游检查，不要求 AI 制造无实质内容的修改。
+
+    退回核对场景（推进 R47）：变化清单为空、且当前环节任一主题表填有有效的
+    "核对结论：无需修改"声明（核对对象和核对依据都有实质内容）时，返回通过并
+    标注声明放行——产物确实不用改也是合法完成状态。产物有实际变化时声明不参与
+    判定，按普通流程走。
     """
     state = load_state(project_root)
     if state is None or stage_name not in state.stages:
@@ -667,15 +676,90 @@ def changed_stage_paths(
             # 变化清单如实为空：确实没有文件变化。调用方要判断“本阶段的产出是哪些”时
             # 按内容识别，不能把未变化的文件当成本阶段改过——最终设计同步正是用这份
             # 清单确认产品文档没有被改动。
+            declaration = _valid_no_change_declaration(project_root, state, stage_name)
+            if declaration is not None:
+                return (
+                    True,
+                    "核对结论：无需修改——产物相对基线无变化，声明的核对依据有效"
+                    f"（核对对象：{declaration['核对对象']}）",
+                    [],
+                )
             return (
                 True,
                 "表模式：正式文档由程序按工作记录表生成，内容与上次相同时按表判断产出",
                 [],
             )
+        # 文档模式退回核对：声明同样适用（R47 不限于表模式）。
+        declaration = _valid_no_change_declaration(project_root, state, stage_name)
+        if declaration is not None:
+            return (
+                True,
+                "核对结论：无需修改——产物相对基线无变化，声明的核对依据有效"
+                f"（核对对象：{declaration['核对对象']}）",
+                [],
+            )
         return (False, "相关文件与讨论完成时相同，不能证明本阶段已经生成或修改产物", [])
     return (True, f"本阶段发生变化的文件: {changed}", changed)
 
 
+def _valid_no_change_declaration(
+    project_root: str,
+    state,
+    stage_name: str,
+) -> dict | None:
+    """读当前环节工作记录表的“核对结论：无需修改”声明；有效时返回声明行。
+
+    有效 = 声明行存在、核对对象非空、核对依据有实质内容（非占位词且达到
+    最小长度）。表不存在或声明无效时返回 None，调用方维持原有判定。
+
+    查找范围：主题级表（impl_record、acceptance_plan、test_plan 等）按主题
+    逐个查；只有轮次级表的环节（如 spec 的 product_features）查轮次级表——
+    退回核对发生在哪个环节，声明就填在那个环节的表里。
+    """
+    from . import records as records_mod
+
+    if state is None:
+        return None
+    kinds = records_mod.stage_table_kinds(stage_name)
+    topic_level = [kind for kind in kinds if kind not in records_mod.WORKFLOW_LEVEL_KINDS]
+    workflow_level = [kind for kind in kinds if kind in records_mod.WORKFLOW_LEVEL_KINDS]
+
+    for kind in topic_level:
+        for topic in list(state.topics or []):
+            declaration = records_mod.no_change_declaration(
+                project_root,
+                state.workflow_id,
+                kind,
+                topic,
+            )
+            if declaration is None:
+                continue
+            if not records_mod.declaration_rationale_has_substance(
+                declaration.get("核对依据", "")
+            ):
+                continue
+            return declaration
+
+    # 轮次级表：表定位时 topic 用空串（records 的轮次级表约定）
+    for kind in workflow_level:
+        if kind == "topic_relations":
+            continue
+        declaration = records_mod.no_change_declaration(
+            project_root,
+            state.workflow_id,
+            kind,
+            "",
+        )
+        if declaration is None:
+            continue
+        if not records_mod.declaration_rationale_has_substance(
+            declaration.get("核对依据", "")
+        ):
+            continue
+        return declaration
+    return None
+
+
 def validate_project_design_init_evidence(
     project_root: str,
     workflow_id: str,
@@ -1263,6 +1347,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]:
     """校验最终架构文档已经完成产品、功能、架构和真实代码映射。
 
@@ -1272,8 +1358,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} 不存在")
 
@@ -1438,7 +1524,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:
@@ -1517,6 +1605,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):
@@ -1547,6 +1656,15 @@ 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:
             allow_none = heading.startswith("7.")
             section_text = _section(content, heading)
@@ -2431,9 +2549,33 @@ def _validate_topic_test_execution_result(
         failures.append(f"{rel_path} 有人工验收内容，但缺少具体人工验收交接")
 
     sections = _test_result_sections(content)
-    expected_ids = {item.test_id for item in items}
-    if set(sections) != expected_ids:
+    # 单一数据源：自动化项编号集合与生成器同源（R12/R14），不再各写各的筛选
+    from . import test_mapping as test_mapping_mod
+
+    try:
+        all_plan_items = parse_test_plan_items(project_root, topic)
+    except ValueError:
+        all_plan_items = list(items)
+    automated_ids = test_mapping_mod.automated_test_ids_in_plan(all_plan_items)
+    if not automated_ids:
+        automated_ids = {item.test_id for item in items}
+    expected_ids = automated_ids if automated_ids else {item.test_id for item in items}
+    # 第 3 节的自动化项小节必须正好覆盖自动化项；人工项小节是合法呈现，
+    # 不计入"正好覆盖"集合（生成器对人工项渲染"测试方式：人工验收"小节）。
+    automated_sections = {tid for tid in sections if tid in expected_ids}
+    manual_sections = set(sections) - automated_sections
+    if automated_sections != expected_ids:
         failures.append(f"{rel_path} 的测试项结果必须正好覆盖 {sorted(expected_ids)}")
+    for tid in sorted(manual_sections):
+        section = sections[tid]
+        if "测试方式：人工验收" not in section:
+            failures.append(
+                f"{rel_path} 的 {tid} 是人工验收项小节，必须标注“测试方式：人工验收”"
+            )
+        if "自动化测试结果：未执行" in section:
+            failures.append(
+                f"{rel_path} 的 {tid} 人工验收项不能写“自动化测试结果：未执行”（人工项转人工验收交接）"
+            )
 
     for item in items:
         task = tasks.get(item.test_id)
@@ -2646,6 +2788,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.8 → workflow_loop-0.4.0}/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(