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

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

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

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

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

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

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

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

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

@@ -645,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:
@@ -671,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,
@@ -2469,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)

{workflow_loop-0.3.9 → workflow_loop-0.4.0}/src/workflow_loop/cli.py

@@ -1676,6 +1676,23 @@ def cmd_discuss(args) -> None:
         print("\n【当前主题验收进度】")
         for line in acceptance_records_mod.acceptance_progress(project_root, wf_state):
             print(f"- {line}")
+    if stage.name() == "spike":
+        # 验证技术不确定性 R32：返回重走决策树——三条路径的判断条件和建议动作，
+        # AI 不再靠翻源码或猜来选择跳过还是复用。
+        current_assets = [
+            asset
+            for asset in wf_state.spike_assets
+            if asset.workflow_id == wf_state.workflow_id
+        ]
+        print("\n【返回重走决策树】按当前事实选择路径，用户决定：")
+        print("  1. 设计变更引入了新技术不确定性 → 重新穿刺（正常执行穿刺项）")
+        print("  2. 没有引入，且本工作流从未登记穿刺资产 → workflow gate spike --skip")
+        if current_assets:
+            print(f"  3. 没有引入，但本工作流已登记 {len(current_assets)} 个穿刺资产 → "
+                  "workflow gate spike --reuse --reuse-rationale <每个被复用结论为何仍成立>")
+            print(f"     已登记资产：{'；'.join(asset.relative_path for asset in current_assets)}")
+        else:
+            print("  （本工作流没有已登记穿刺资产，--reuse 不适用）")
 
     # 写 journal：材料清单登记（记录本次清单的组成与内容指纹）
     journal_mod.append_entry(project_root, "材料清单登记", "workflow.py",
@@ -3902,13 +3919,18 @@ def cmd_gate(args) -> None:
         sys.exit(1)
 
     # 旧基线参数只为兼容历史调用；当前产品规则不再把它们作为门禁流程。
+    # 旧基线参数只为兼容历史调用；当前产品规则不再把它们作为门禁流程。
+    # getattr 容错：测试和历史调用方可能用 SimpleNamespace 模拟参数对象，
+    # 新参数（--reuse/--reuse-rationale）在其中不存在时按未使用处理。
+    _has_reuse = bool(getattr(args, "reuse", False))
+    _has_reuse_rationale = bool(getattr(args, "reuse_rationale", ""))
     if (
         args.rebaseline
         or args.prepare_code
         or args.accept_existing_code
         or args.accept_existing_test_code
     ) and (
-        args.skip or args.discuss_done or args.confirmed
+        args.skip or _has_reuse or args.discuss_done or args.confirmed
     ):
         print(
             "错误：--rebaseline、--prepare-code、--accept-existing-code 和 "
@@ -3916,12 +3938,129 @@ def cmd_gate(args) -> None:
         )
         sys.exit(1)
 
+    if args.skip and _has_reuse:
+        print("错误：--skip 和 --reuse 互斥；skip 表示本轮不做穿刺，reuse 表示复用既有穿刺结论")
+        sys.exit(1)
+
+    # ── 特殊：--reuse（仅 spike，验证技术不确定性 R30/R31）──
+    if _has_reuse:
+        if stage_name != "spike":
+            print(f"错误：--reuse 仅适用于 spike stage，不适用于 {stage_name}")
+            sys.exit(1)
+        current_assets = [
+            asset
+            for asset in wf_state.spike_assets
+            if asset.workflow_id == wf_state.workflow_id
+        ]
+        if not current_assets:
+            print(
+                "错误：本工作流没有已登记的穿刺资产，无内容可复用；"
+                "没有新技术不确定性时请用 --skip"
+            )
+            sys.exit(1)
+        rationale = (getattr(args, "reuse_rationale", "") or "").strip()
+        if len(rationale) < 12 or rationale in {"无", "暂无", "待定", "待补充"}:
+            print(
+                "错误：--reuse 必须用 --reuse-rationale 写明复用依据——"
+                "每个被复用穿刺项的结论为什么在当前设计变更后仍然成立"
+                "（不少于 12 个字符，不能写占位词）"
+            )
+            sys.exit(1)
+        _clear_pending_spike_assets(wf_state)
+        try:
+            cleanup_plan = plan_spike_tmp_cleanup(project_root, wf_state)
+            cleaned_paths = clean_spike_tmp(
+                project_root,
+                wf_state,
+                cleanup_plan=cleanup_plan,
+            )
+        except (OSError, ValueError) as exc:
+            _print_gate_failure(
+                stage_name="spike",
+                gate_name="复用前临时内容清理",
+                details=exc,
+                command="workflow gate spike --reuse --reuse-rationale <复用依据>",
+                side_effects="只删除当前工作流未登记的穿刺半成品，保留已登记资产和其它工作流目录",
+                success_condition="定向清理完成且没有触碰已登记或历史穿刺资产",
+            )
+            return
+        # 复用路径：跳过新穿刺但保留既有结论和资产的追踪表引用（R30/R31）。
+        wf_state.spike_reused = True
+        wf_state.spike_skipped = False
+        wf_state.meta["spike_reuse_rationales"] = [
+            {
+                "asset_count": len(current_assets),
+                "rationale": rationale,
+                "recorded_at": state_mod.now_iso(),
+            }
+        ]
+        # 退回重走路径：待复核文本在有资产引用时不动，无引用行回补为复用文本。
+        try:
+            traceability_mod.resolve_spike_recheck_for_skip(
+                project_root, wf_state.workflow_id
+            )
+        except ValueError:
+            pass
+        wf_state.stages[stage_name].gate.discussion_complete = True
+        wf_state.stages[stage_name].gate.code_validated = True
+        wf_state.stages[stage_name].gate.user_confirmed = True
+        wf_state.stages[stage_name].status = "done"
+        stage_names = list(wf_state.stages.keys())
+        current_idx = stage_names.index(stage_name)
+        if current_idx + 1 < len(stage_names):
+            next_stage = stage_names[current_idx + 1]
+            wf_state.current_stage = next_stage
+            wf_state.stages[next_stage].status = "in_progress"
+        state_mod.save_state(project_root, wf_state)
+        journal_mod.append_entry(
+            project_root,
+            "spike 复用",
+            "workflow.py",
+            workflow_id=wf_state.workflow_id,
+            reused_assets=[asset.relative_path for asset in current_assets],
+            rationale=rationale,
+            preserved_paths=cleanup_plan["preserved"],
+            cleaned_paths=cleaned_paths,
+        )
+        journal_mod.append_entry(project_root, "阶段推进", "workflow.py",
+                                from_=stage_name, to=wf_state.current_stage)
+        print(f"═══ {stage_name} 复用既有穿刺 ═══")
+        print(f"复用的穿刺资产: {[asset.relative_path for asset in current_assets]}")
+        print(f"复用依据: {rationale}")
+        _print_spike_cleanup_plan(cleanup_plan)
+        print(f"进入 {wf_state.current_stage}")
+        print_next_step(f"调 `workflow discuss` 加载 {wf_state.current_stage} stage 提示词")
+        return
+
     # ── 特殊：--skip（仅 spike）──
     if args.skip:
         # --skip 只适用于 spike stage
         if stage_name != "spike":
             print(f"错误：--skip 仅适用于 spike stage，不适用于 {stage_name}")
             sys.exit(1)
+        # 验证技术不确定性 R30：本工作流已有登记资产时先警告后果，让人在
+        # 犯错前看到选择；确认后才继续。
+        current_assets = [
+            asset
+            for asset in wf_state.spike_assets
+            if asset.workflow_id == wf_state.workflow_id
+        ]
+        if current_assets:
+            print("⚠️ 警告：本工作流已登记 "
+                  f"{len(current_assets)} 个穿刺资产：")
+            for asset in current_assets:
+                print(f"  - {asset.relative_path}")
+            print("执行 --skip 后，验收计划将无法引用这些资产（追踪表校验会拒绝"
+                  "本轮资产引用）；如需保留并复用它们，请改用：")
+            print("  workflow gate spike --reuse --reuse-rationale <每个被复用结论为何仍成立>")
+            print("确认要放弃引用继续 --skip 时，请再次执行本命令（用户已知情）。")
+            # R30：警告先于跳过动作出现——第一次执行只警告并退出；用户知情后
+            # 再次执行同一命令才真正跳过。
+            already_warned = wf_state.meta.get("spike_skip_warned_at")
+            if not already_warned:
+                wf_state.meta["spike_skip_warned_at"] = state_mod.now_iso()
+                state_mod.save_state(project_root, wf_state)
+                sys.exit(1)
         _clear_pending_spike_assets(wf_state)
         try:
             cleanup_plan = plan_spike_tmp_cleanup(project_root, wf_state)
@@ -3943,6 +4082,8 @@ def cmd_gate(args) -> None:
 
         # 清理成功后再标记 spike 跳过并推进，失败时始终停留在当前阶段。
         wf_state.spike_skipped = True
+        # 确认放弃后清除警告标记，避免污染后续轮次判断。
+        wf_state.meta.pop("spike_skip_warned_at", None)
         # 退回重走路径：回溯重置过的穿刺列停在待复核文本，本轮确认跳过后回补为跳过文本。
         # 首轮 spike 早于 acceptance_plan、追踪表还不存在时静默跳过回补。
         try:
@@ -5675,6 +5816,12 @@ def cmd_abort(args) -> None:
                     print(f"  - {item.get('path')}：{action}")
                 elif item.get("kind") == "project_fields":
                     print("  - .workflow_loop/project.json：恢复本轮受管项目字段")
+            no_copy_paths = abort_manifest.get("no_copy_paths")
+            if isinstance(no_copy_paths, list) and no_copy_paths:
+                # 整轮作废并恢复 R22：无副本的删除文件保持删除，不阻塞作废。
+                print("无副本的删除文件（实施前内容无法取得，作废时保持当前删除状态）：")
+                for entry in no_copy_paths:
+                    print(f"  - {entry}")
             print("清单外文件不会读取、恢复或删除。")
             if isinstance(abort_spike_plan, dict):
                 _print_spike_cleanup_plan(abort_spike_plan)
@@ -6324,7 +6471,13 @@ def main() -> None:
                              help="第三道门：记录用户看过当前结果并同意，随后进入下一环节")
     # --skip：跳过 stage（仅 spike）
     gate_parser.add_argument("--skip", action="store_true",
-                             help="跳过 stage（仅 spike）")
+                             help="跳过 stage（仅 spike；本工作流已登记穿刺资产时先警告后果）")
+    # --reuse：跳过新穿刺但复用本工作流已登记的穿刺结论和资产（仅 spike）
+    gate_parser.add_argument("--reuse", action="store_true",
+                             help="跳过新穿刺，保留并复用本工作流已登记的穿刺结论和资产（仅 spike）")
+    # --reuse-rationale：复用依据（--reuse 时必填，说明每个被复用结论为何仍成立）
+    gate_parser.add_argument("--reuse-rationale", default="",
+                             help="复用依据：--reuse 时必填，写清每个被复用穿刺项的结论为什么在当前设计下仍然成立")
     # --rebaseline：用户确认当前代码作为 impl 的新实施前基线
     gate_parser.add_argument("--rebaseline", action="store_true",
                              help="重设 impl 实施前代码基线（仅用户确认后使用）")

{workflow_loop-0.3.9 → workflow_loop-0.4.0}/src/workflow_loop/project.py

@@ -34,6 +34,7 @@ MANAGED_PROJECT_FIELDS = (
     "test_entry",
     "test_parallelism",
     "artifact_file_keys",
+    "extra_code_suffixes",
 )
 
 
@@ -62,6 +63,10 @@ class ProjectState:
     # 显示名称到稳定中文文件标识的项目级映射，按 feature/topic/spike/bug 分组。
     # 显示名称仍写入正文；文件标识只进入文件名。跨轮次保存，不随新 Run 覆盖。
     artifact_file_keys: dict[str, dict[str, str]] = field(default_factory=dict)
+    # 项目级扩展代码后缀：项目主要产物不是常规代码格式（例如纯 HTML 站点）时，
+    # 维护者登记这些后缀，实际改动判定把它们当代码文件识别（实施并保护项目修改 R34）。
+    # 存[".html", ".htm"]这类小写后缀列表；空列表表示不扩展。
+    extra_code_suffixes: list[str] = field(default_factory=list)
 
 
 # 项目骨架检查结果：
@@ -124,6 +129,12 @@ def load_project(project_root: str) -> ProjectState | None:
         for category, mapping in raw_keys.items()
         if isinstance(mapping, dict)
     }
+    raw_suffixes = data.get("extra_code_suffixes", [])
+    extra_code_suffixes = [
+        suffix.strip().lower()
+        for suffix in raw_suffixes
+        if isinstance(suffix, str) and suffix.strip()
+    ]
     return ProjectState(
         installer_version=data.get("installer_version", ""),
         installed_at=data.get("installed_at", ""),
@@ -132,6 +143,7 @@ def load_project(project_root: str) -> ProjectState | None:
         test_entry=data.get("test_entry", DEFAULT_TEST_ENTRY),
         test_parallelism=max(1, int(data.get("test_parallelism", DEFAULT_TEST_PARALLELISM))),
         artifact_file_keys=artifact_file_keys,
+        extra_code_suffixes=extra_code_suffixes,
     )
 
 
@@ -179,9 +191,17 @@ def save_project(project_root: str, project: ProjectState) -> None:
 def _validate_managed_fields(fields: dict) -> None:
     if not isinstance(fields, dict):
         raise ValueError("项目受管字段快照必须是 JSON 对象")
-    missing = [name for name in MANAGED_PROJECT_FIELDS if name not in fields]
+    # extra_code_suffixes 是后加字段：旧轮次的作废清单快照没有它，恢复旧快照
+    # 时按空列表处理，不因缺新字段拒绝历史恢复。
+    legacy_tolerated = {"extra_code_suffixes"}
+    missing = [
+        name
+        for name in MANAGED_PROJECT_FIELDS
+        if name not in fields and name not in legacy_tolerated
+    ]
     if missing:
         raise ValueError(f"项目受管字段快照缺少字段: {missing}")
+    fields = {**{name: [] for name in legacy_tolerated if name not in fields}, **fields}
     if not isinstance(fields["project_design_initialized"], bool):
         raise ValueError("project_design_initialized（项目设计已初始化）必须是布尔值")
     if (
@@ -203,6 +223,14 @@ def _validate_managed_fields(fields: dict) -> None:
     for category, mapping in mappings.items():
         if not isinstance(category, str) or not isinstance(mapping, dict):
             raise ValueError("正式文件标识映射的分类和值必须是对象")
+    if (
+        not isinstance(fields["extra_code_suffixes"], list)
+        or not all(
+            isinstance(item, str) and item.startswith(".") and item.strip(".")
+            for item in fields["extra_code_suffixes"]
+        )
+    ):
+        raise ValueError("extra_code_suffixes（项目扩展代码后缀）必须是以点开头的字符串数组")
         if not all(
             isinstance(display_name, str) and isinstance(file_key, str)
             for display_name, file_key in mapping.items()
@@ -221,6 +249,7 @@ def snapshot_managed_fields(project_root: str) -> dict:
         "test_entry": copy.deepcopy(project.test_entry),
         "test_parallelism": project.test_parallelism,
         "artifact_file_keys": copy.deepcopy(project.artifact_file_keys),
+        "extra_code_suffixes": list(project.extra_code_suffixes),
     }
     _validate_managed_fields(fields)
     return fields
@@ -241,7 +270,7 @@ def restore_managed_fields(project_root: str, fields: dict) -> None:
         raise ValueError(f"{PROJECT_FILE} 必须是 JSON 对象")
 
     for name in MANAGED_PROJECT_FIELDS:
-        data[name] = copy.deepcopy(fields[name])
+        data[name] = copy.deepcopy(fields.get(name, [] if name == "extra_code_suffixes" else None))
     _atomic_write_json(path, data)
     if snapshot_managed_fields(project_root) != fields:
         raise ValueError("项目受管字段写回后复核不一致")