workflow-loop 0.1.0__py3-none-any.whl

workflow_loop/project.py

@@ -0,0 +1,397 @@
+import copy
+import json
+import os
+import tempfile
+from dataclasses import dataclass, asdict, field
+from datetime import datetime, timezone
+
+# 统一产品身份：版本常量只在包 __init__ 定义一份，安装、CLI 和项目检查共用
+from . import __version__ as PRODUCT_VERSION
+
+# project.json 的相对路径（相对于项目根）
+# 放在 .workflow_loop/ 下，和 state.json、journal.jsonl 同级
+# 但 project.json 是项目级持久字段，跨 Run 不被新 Run 覆盖
+PROJECT_FILE = os.path.join(".workflow_loop", "project.json")
+
+# 安装器版本号，用于重复安装保护判断
+# 严格等于产品版本 0.1.0，不存在兼容版本范围
+INSTALLER_VERSION = PRODUCT_VERSION
+# 项目全量测试入口是"操作系统 → 命令参数数组"的映射；新安装项目默认为空。
+# 旧开发状态可能仍是字符串脚本路径；读取时原样保留，由受控迁移转换。
+DEFAULT_TEST_ENTRY: dict = {}
+DEFAULT_TEST_PARALLELISM = 2
+
+# 完整项目骨架的组成部分：安装时一次写入，日常检查必须全部存在
+WORKFLOW_LOOP_DIRNAME = ".workflow_loop"
+TEMPLATE_DIRNAME = "Template_Repository"
+STANDARDIZED_DIRNAME = "Standardized_Repository"
+AGENTS_MD_FILENAME = "AGENTS.md"
+MANAGED_PROJECT_FIELDS = (
+    "project_design_initialized",
+    "topic_history",
+    "test_entry",
+    "test_parallelism",
+    "artifact_file_keys",
+)
+
+
+# 项目级持久状态（跨 Run 不被覆盖）
+# 和 WorkflowState（单次 Run 快照，新 Run 整份覆盖）分离
+# project_design_initialized 不放 state.json，因为它跨 Run 持久
+@dataclass
+class ProjectState:
+    # 安装器版本号，安装时写入
+    # is_installed() 检查这个字段判断项目是否已安装
+    installer_version: str = INSTALLER_VERSION
+    # 安装时间 ISO 8601 UTC，用于追溯项目何时接入 workflow_loop
+    installed_at: str = ""
+    # 项目设计架构初始化标记
+    # 安装时 false；project_design_init stage --confirmed 后置 true
+    # from_scratch 在 spec + code_design 都 --confirmed 后置 true
+    # PathComposer 用这个字段决定 product_change/bugfix 是否前置 project_design_init
+    project_design_initialized: bool = False
+    # 已经确认过的验收主题名称。修 bug 在 reproduce 确认，其他意图在 acceptance_plan 确认。
+    topic_history: list[str] = field(default_factory=list)
+    # 项目统一全量测试入口：操作系统（windows/linux/darwin/default）到参数数组的映射。
+    # 不再把当前仓库脚本当成所有项目默认；旧字符串配置读取时原样保留，等待受控迁移。
+    test_entry: dict | str = field(default_factory=dict)
+    # 主题测试执行阶段最多同时运行多少个独立主题；同一主题内仍按测试项依赖顺序执行。
+    test_parallelism: int = DEFAULT_TEST_PARALLELISM
+    # 显示名称到稳定中文文件标识的项目级映射，按 feature/topic/spike/bug 分组。
+    # 显示名称仍写入正文；文件标识只进入文件名。跨轮次保存，不随新 Run 覆盖。
+    artifact_file_keys: dict[str, dict[str, str]] = field(default_factory=dict)
+
+
+# 项目骨架检查结果：
+# state 取值 "installed"（完整安装 0.1.0）/ "uninstalled"（干净未安装）/ "broken"（残缺或版本异常）
+# problems 保存 broken 时的具体缺项，供安装脚本和日常命令直接打印
+@dataclass
+class SkeletonStatus:
+    state: str
+    problems: list[str] = field(default_factory=list)
+
+
+# 生成 ISO 8601 UTC 时间戳（内部用，不对外暴露）
+# 和 state.py 的 now_iso() 逻辑一致，但独立定义避免循环导入
+def _now_iso() -> str:
+    # datetime.now(timezone.utc) 拿到 UTC 时间
+    # .replace(microsecond=0) 去掉微秒
+    # .isoformat() 转 ISO 8601 字符串
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+# 从被管理项目的 .workflow_loop/project.json 读取项目级状态
+# 如果文件不存在（还没安装），返回 None
+def load_project(project_root: str) -> ProjectState | None:
+    # 拼出 project.json 的完整路径
+    path = os.path.join(project_root, PROJECT_FILE)
+    # 文件不存在说明项目还没安装
+    if not os.path.exists(path):
+        return None
+    # 读文件、解析 JSON
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    # 重建 ProjectState dataclass
+    raw_keys = data.get("artifact_file_keys", {})
+    artifact_file_keys = {
+        category: dict(mapping)
+        for category, mapping in raw_keys.items()
+        if isinstance(mapping, dict)
+    }
+    return ProjectState(
+        installer_version=data.get("installer_version", ""),
+        installed_at=data.get("installed_at", ""),
+        project_design_initialized=data.get("project_design_initialized", False),
+        topic_history=data.get("topic_history", []),
+        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,
+    )
+
+
+def _atomic_write_json(path: str, data: dict) -> None:
+    """在目标文件同目录写完整临时文件，再原子替换目标。"""
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    handle = tempfile.NamedTemporaryFile(
+        mode="w",
+        encoding="utf-8",
+        prefix=".project-",
+        suffix=".tmp",
+        dir=os.path.dirname(path),
+        delete=False,
+    )
+    temp_path = handle.name
+    try:
+        with handle:
+            json.dump(data, handle, ensure_ascii=False, indent=2)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_path, path)
+    finally:
+        if os.path.exists(temp_path):
+            os.remove(temp_path)
+
+
+# 把 ProjectState 写到被管理项目的 .workflow_loop/project.json
+# ensure_ascii=False 让中文不被转义；indent=2 让文件可读
+def save_project(project_root: str, project: ProjectState) -> None:
+    path = os.path.join(project_root, PROJECT_FILE)
+    # 保留未来版本或项目扩展写入的未知字段；当前版本只更新自己拥有的键。
+    data = {}
+    if os.path.isfile(path):
+        try:
+            with open(path, "r", encoding="utf-8") as stream:
+                existing = json.load(stream)
+            if isinstance(existing, dict):
+                data.update(existing)
+        except (OSError, json.JSONDecodeError):
+            data = {}
+    data.update(asdict(project))
+    _atomic_write_json(path, data)
+
+
+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]
+    if missing:
+        raise ValueError(f"项目受管字段快照缺少字段: {missing}")
+    if not isinstance(fields["project_design_initialized"], bool):
+        raise ValueError("project_design_initialized（项目设计已初始化）必须是布尔值")
+    if (
+        not isinstance(fields["topic_history"], list)
+        or not all(isinstance(item, str) for item in fields["topic_history"])
+    ):
+        raise ValueError("topic_history（历史主题）必须是字符串数组")
+    if not isinstance(fields["test_entry"], (dict, str)):
+        raise ValueError("test_entry（项目全量测试入口）必须是平台映射或旧字符串")
+    if (
+        not isinstance(fields["test_parallelism"], int)
+        or isinstance(fields["test_parallelism"], bool)
+        or fields["test_parallelism"] < 1
+    ):
+        raise ValueError("test_parallelism（主题测试最大并行数）必须是正整数")
+    mappings = fields["artifact_file_keys"]
+    if not isinstance(mappings, dict):
+        raise ValueError("artifact_file_keys（正式文件标识映射）必须是对象")
+    for category, mapping in mappings.items():
+        if not isinstance(category, str) or not isinstance(mapping, dict):
+            raise ValueError("正式文件标识映射的分类和值必须是对象")
+        if not all(
+            isinstance(display_name, str) and isinstance(file_key, str)
+            for display_name, file_key in mapping.items()
+        ):
+            raise ValueError("正式文件标识映射的显示名称和文件标识必须是字符串")
+
+
+def snapshot_managed_fields(project_root: str) -> dict:
+    """保存本轮可能修改的项目级字段，不包含安装身份等无关字段。"""
+    project = load_project(project_root)
+    if project is None:
+        raise ValueError(f"缺少 {PROJECT_FILE}，不能保存项目受管字段")
+    fields = {
+        "project_design_initialized": project.project_design_initialized,
+        "topic_history": list(project.topic_history),
+        "test_entry": copy.deepcopy(project.test_entry),
+        "test_parallelism": project.test_parallelism,
+        "artifact_file_keys": copy.deepcopy(project.artifact_file_keys),
+    }
+    _validate_managed_fields(fields)
+    return fields
+
+
+def restore_managed_fields(project_root: str, fields: dict) -> None:
+    """只恢复本轮受管字段，保留安装身份和未知扩展字段。"""
+    _validate_managed_fields(fields)
+    path = os.path.join(project_root, PROJECT_FILE)
+    if not os.path.isfile(path):
+        raise ValueError(f"缺少 {PROJECT_FILE}，不能恢复项目受管字段")
+    try:
+        with open(path, "r", encoding="utf-8") as stream:
+            data = json.load(stream)
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError(f"{PROJECT_FILE} 无法读取，不能恢复项目受管字段: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValueError(f"{PROJECT_FILE} 必须是 JSON 对象")
+
+    for name in MANAGED_PROJECT_FIELDS:
+        data[name] = copy.deepcopy(fields[name])
+    _atomic_write_json(path, data)
+    if snapshot_managed_fields(project_root) != fields:
+        raise ValueError("项目受管字段写回后复核不一致")
+
+
+def register_artifact_names(
+    project_root: str,
+    category: str,
+    display_names: list[str],
+) -> dict[str, str]:
+    """登记正式产物的显示名称到稳定文件标识，并在有新增时落盘。"""
+    from . import artifact_paths as artifact_paths_mod
+
+    project = load_project(project_root)
+    if project is None:
+        raise ValueError("项目尚未安装，不能登记正式文件标识")
+    added = artifact_paths_mod.register_file_keys(project, category, display_names)
+    if added:
+        save_project(project_root, project)
+    return added
+
+
+def _required_repository_files(dirname: str) -> list[str]:
+    """返回当前产品发布要求目标项目具备的仓库文件。"""
+    source_root = os.path.join(os.path.dirname(__file__), "data", dirname)
+    required: list[str] = []
+    if not os.path.isdir(source_root):
+        return required
+    for root, _dirs, files in os.walk(source_root):
+        for filename in files:
+            relative = os.path.relpath(os.path.join(root, filename), source_root)
+            required.append(relative.replace(os.sep, "/"))
+    return sorted(required)
+
+
+# 检查项目骨架完整性，区分三种状态：
+# - installed：项目标记、模板仓库、规范仓库和 AGENTS.md 共同构成完整骨架，且版本严格等于 0.1.0
+# - uninstalled：.workflow_loop/ 完全不存在（干净目录，可以首次安装）
+# - broken：骨架部分存在、版本不符或 project.json 无法读取；任何写入前必须停止
+def check_skeleton(project_root: str) -> SkeletonStatus:
+    wf_dir = os.path.join(project_root, WORKFLOW_LOOP_DIRNAME)
+    project_json = os.path.join(project_root, PROJECT_FILE)
+
+    # .workflow_loop/ 完全不存在 → 干净未安装
+    if not os.path.exists(wf_dir):
+        return SkeletonStatus(state="uninstalled")
+
+    problems: list[str] = []
+
+    # project.json：必须存在、可解析、版本严格等于 0.1.0
+    if not os.path.isfile(project_json):
+        problems.append(f"缺少安装版本标记 {PROJECT_FILE}")
+    else:
+        try:
+            with open(project_json, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except (OSError, json.JSONDecodeError) as exc:
+            problems.append(f"{PROJECT_FILE} 无法读取: {exc}")
+        else:
+            if not isinstance(data, dict):
+                problems.append(f"{PROJECT_FILE} 顶层必须是 JSON 对象")
+            else:
+                version = data.get("installer_version")
+                if version != INSTALLER_VERSION:
+                    problems.append(
+                        f"安装版本标记是 {version!r}，当前产品只接受 {INSTALLER_VERSION!r}"
+                    )
+                if not isinstance(data.get("project_design_initialized", False), bool):
+                    problems.append("project_design_initialized（项目设计已初始化）字段无效")
+                if not isinstance(data.get("topic_history", []), list):
+                    problems.append("topic_history（历史主题）字段无效")
+                if not isinstance(data.get("test_entry", {}), (dict, str)):
+                    problems.append("test_entry（项目全量测试入口）字段无效")
+                if not isinstance(data.get("artifact_file_keys", {}), dict):
+                    problems.append("artifact_file_keys（正式文件标识映射）字段无效")
+
+    # 模板仓库和规范仓库：当前产品发布中的每一份必需材料都必须存在。
+    # 允许项目增加其它文件，也允许在工作流内按规则修改正文，但不能缺文件。
+    for dirname in (TEMPLATE_DIRNAME, STANDARDIZED_DIRNAME):
+        dir_path = os.path.join(wf_dir, dirname)
+        if not os.path.isdir(dir_path):
+            problems.append(f"缺少 .workflow_loop/{dirname}/")
+            continue
+        required_files = _required_repository_files(dirname)
+        if not required_files:
+            problems.append(f"当前安装包没有携带 {dirname} 文件清单")
+            continue
+        for relative_path in required_files:
+            full_path = os.path.join(dir_path, *relative_path.split("/"))
+            if not os.path.isfile(full_path):
+                problems.append(f"缺少 .workflow_loop/{dirname}/{relative_path}")
+
+    # 最小代理契约：必须存在于项目根
+    if not os.path.isfile(os.path.join(project_root, AGENTS_MD_FILENAME)):
+        problems.append(f"缺少项目根 {AGENTS_MD_FILENAME}")
+
+    if problems:
+        return SkeletonStatus(state="broken", problems=problems)
+    return SkeletonStatus(state="installed")
+
+
+# 判断项目设计架构是否已初始化（PathComposer 用）
+# true → product_change/bugfix 跳过 project_design_init stage
+# false → 必须执行 project_design_init
+# 不用架构文档是否存在决定跳过（CONTEXT.md "Project Design Init Skip"）
+def is_project_design_initialized(project_root: str) -> bool:
+    # 读 project.json
+    project = load_project(project_root)
+    # project 存在且 project_design_initialized 为 true 才返回 True
+    return project is not None and project.project_design_initialized
+
+
+# 设置项目设计架构初始化标记
+# 在 project_design_init stage --confirmed 后置 true
+# 在 from_scratch 的 spec + code_design 都 --confirmed 后置 true
+# 在 from_scratch start 时重置为 false（清场后重新做）
+def set_project_design_initialized(project_root: str, value: bool) -> None:
+    # 读当前 project 状态
+    project = load_project(project_root)
+    # project 不存在（异常情况）→ 新建一个，带当前时间戳
+    if project is None:
+        project = ProjectState(installed_at=_now_iso())
+    # 更新标记
+    project.project_design_initialized = value
+    # 写回 project.json
+    save_project(project_root, project)
+
+
+def register_topics(project_root: str, topics: list[str]) -> None:
+    """原子登记本次主题历史及对应的稳定正式文件标识。"""
+    from . import artifact_paths as artifact_paths_mod
+
+    project = load_project(project_root)
+    if project is None:
+        project = ProjectState(installed_at=_now_iso())
+
+    duplicates = sorted(set(topics) & set(project.topic_history))
+    if duplicates:
+        raise ValueError(f"主题名称已经使用过: {duplicates}")
+
+    artifact_paths_mod.register_file_keys(project, "topic", topics)
+    project.topic_history.extend(topic for topic in topics if topic not in project.topic_history)
+    save_project(project_root, project)
+
+
+def register_test_entry(project_root: str, entry_config: dict) -> None:
+    """更新项目全量测试入口配置；只应由入口登记命令在测试计划阶段调用。"""
+    from . import test_entry as test_entry_mod
+
+    normalized = test_entry_mod.normalized_entry_config(entry_config)
+    project = load_project(project_root)
+    if project is None:
+        raise ValueError("项目尚未安装，不能登记测试入口")
+    project.test_entry = normalized
+    save_project(project_root, project)
+
+
+# 判断项目是否已安装（安装事务和 start 命令用）
+# 完整骨架 + 版本严格等于 0.1.0 才算已安装；残缺骨架不算
+# 未安装时 start 命令报错，提示用户先跑官方安装脚本
+def is_installed(project_root: str) -> bool:
+    return check_skeleton(project_root).state == "installed"
+
+
+# 创建项目级状态（installer.py 在安装事务中调用）
+# 只写精简项目级字段；不创建正式产物目录，也不下发全量测试脚本
+# 初始 project_design_initialized=false，后续由 project_design_init stage 更新
+def create_project(project_root: str) -> ProjectState:
+    # 新建 ProjectState，带当前版本号和时间戳
+    project = ProjectState(
+        installer_version=INSTALLER_VERSION,
+        installed_at=_now_iso(),
+        # 初始为 false，需要走 project_design_init stage 才置 true
+        project_design_initialized=False,
+    )
+    # 写到 project.json
+    save_project(project_root, project)
+    # 返回新建的 project，供调用方使用
+    return project

workflow_loop/role_doc.py

@@ -0,0 +1,133 @@
+# 文档概览文本（start 命令和 status 命令可能打印）
+# 给 AI 和用户介绍项目文档结构：spec/bug/qa/acceptance/impl 各是什么、命名规则
+# AI 读完理解项目文档全貌，后面每个 stage 基于这个理解工作
+DOC_OVERVIEW = """═══ 文档概览 ═══
+
+本项目使用 workflow_loop 工作流管理。正式产物使用中文文件名；
+spec、acceptance、qa、impl、bug 等程序固定目录名保持英文。文档结构：
+
+【spec/】产品与设计
+  - 产品总说明.md：产品设计说明书 + 功能清单
+  - 功能_<功能文件标识>.md：按功能拆分的功能设计文档；标题保留完整显示名称
+  - 代码架构设计.md：代码架构设计文档
+  - 穿刺清单.md / 穿刺_<穿刺项文件标识>.md：穿刺清单与结论
+  - 项目设计初始化证据.md：存量项目初始化的调查证据
+
+【bug/】缺陷记录
+  - 缺陷_<缺陷文件标识>.md：单个缺陷记录
+  - 索引.md：缺陷索引表
+
+【qa/】测试
+  - 索引.md：测试索引表
+  - <主题文件标识>_测试计划.md：主题测试计划
+  - <主题文件标识>_测试结果.md：主题测试结果
+  - state.json / journal.jsonl：记录最终全量回归的命令、退出码、状态和输出摘要
+
+【acceptance/】验收
+  - 索引.md：验收主题关系和验收文档索引
+  - <主题文件标识>_验收计划.md：主题验收计划
+  - <主题文件标识>_验收结果.md：主题验收结果
+
+【需求交付追踪表.md】需求交付追踪表
+  - 按工作流编号记录需求、验收主题、验收条件和后续阶段的对应位置
+
+【impl/】实施记录
+  - 索引.md：继承验收主题关系的实施索引
+  - <主题文件标识>_实施记录.md：每个验收主题一份实施计划和实施记录
+
+验收计划、测试计划、实施记录和主题测试/验收结果使用同一个主题显示名称和文件标识。
+从零开发和修改产品在 acceptance_plan（验收计划）环节确定主题；修 bug 在 reproduce（缺陷复现）环节确定主题。"""
+
+# stage 名 → 角色定义的映射表
+# discuss 命令用 get_role_doc(stage_name) 拿角色定义，打印给 AI 看
+# 角色定义告诉 AI："这个 stage 你是什么角色、要产出什么文件、文件放哪"
+# 加新 stage 时在这里加一行映射即可
+ROLE_DOC_MAP = {
+    # 产品设计阶段：从零建立或改产品重新设计
+    "spec": {
+        "role": "产品设计师",
+        "description": "和用户讨论产品要做什么、功能清单、功能拆分。产出 spec/产品总说明.md 和每个功能的 spec/功能_<功能文件标识>.md；文档标题写完整功能名称，文件名使用稳定中文文件标识。",
+    },
+    # 从零做的初步代码架构阶段：从已确认产品设计推导代码设计
+    "code_design": {
+        "role": "代码架构设计师（初步）",
+        "description": "从已确认的产品设计推导代码分层、架构关键节点和各功能的完整代码过程，产出 spec/代码架构设计.md。",
+    },
+    # 穿刺阶段：验证真实场景中的技术不确定性
+    "spike": {
+        "role": "技术不确定性验证工程师",
+        "description": "先查看产品设计、代码设计、相关代码和运行事实，找出必须用真实场景确认的技术不确定性。用户决定执行哪些穿刺项；验证完成后在 spec/穿刺清单.md 和 spec/穿刺_<穿刺项文件标识>.md 记录真实证据，并把结论同步到受影响的设计文档。",
+    },
+    # 存量项目首次初始化：一次建立产品+功能+架构三类产物
+    "project_design_init": {
+        "role": "存量产品与架构分析师",
+        "description": "首次处理已有代码项目时，必须查看代码和测试，具备安全条件时实际运行，一次建立相互一致的 spec/产品总说明.md、spec/功能_*.md、spec/代码架构设计.md 和 spec/项目设计初始化证据.md。",
+    },
+    # 改产品设计期架构修订：按新设计改架构图
+    "revise_code_design": {
+        "role": "架构文档修订者",
+        "description": "改产品路径上，按变更后的产品设计修改 spec/代码架构设计.md。",
+    },
+    # 末段最终设计同步：核对产品、功能、架构和真实代码映射
+    "update_code_design": {
+        "role": "最终设计同步者",
+        "description": "最终全量回归和整体验收通过后，核对产品总说明、功能文档、代码架构设计和真实代码；架构有变化时更新架构与功能到代码的映射，发现功能变化返回 spec（产品设计），发现代码未实现返回 impl（代码实施）。",
+    },
+    # 验收计划制定阶段
+    "acceptance_plan": {
+        "role": "验收计划制定者",
+        "description": "根据已确认需求确定或复用全部验收主题，确认主题前置关系，并为每个主题制定什么算完成。产出 需求交付追踪表.md、acceptance/索引.md 和 acceptance/<主题文件标识>_验收计划.md。",
+    },
+    # 测试计划制定阶段
+    "test_plan": {
+        "role": "测试计划制定者",
+        "description": "对已确认验收条件做测试覆盖审查，登记项目全量测试入口。产出 qa/<主题文件标识>_测试计划.md 和 qa/索引.md；本阶段不执行测试。",
+    },
+    # 实施执行阶段：改真实代码
+    "impl": {
+        "role": "实施执行者",
+        "description": "先根据验收计划和测试计划为全部主题确认实施前计划，再修改真实代码，并在 impl/<主题文件标识>_实施记录.md 中记录实际实施结果。",
+    },
+    # 测试代码阶段：调查真实代码并写测试代码
+    "test_code": {
+        "role": "测试代码编写者",
+        "description": "先读取验收计划、测试计划、实施记录和真实代码，确认每个测试项的代码落点，再编写带 Workflow-Test 标识的测试代码。可以运行与当前修改直接相关的局部测试作为开发反馈，但不产出正式测试结果。",
+    },
+    # 测试执行阶段：运行测试代码并记录结果
+    "test_execution": {
+        "role": "测试执行者",
+        "description": "逐项登记并运行 test_code 阶段写好的测试，按照 qa/<主题文件标识>_测试计划.md 记录真实机器执行结果，产出 qa/<主题文件标识>_测试结果.md。",
+    },
+    # 主题验收阶段：测试通过后核对用户结果
+    "topic_acceptance": {
+        "role": "主题验收执行者",
+        "description": "确认对应主题的测试结果通过后，按照 acceptance/<主题文件标识>_验收计划.md 逐条核对用户结果，产出 acceptance/<主题文件标识>_验收结果.md。",
+    },
+    "regression_test": {
+        "role": "最终回归测试执行者",
+        "description": "全部主题完成后，执行项目配置的统一测试入口。退出码为 0 才算回归通过；状态写入 state.json、journal 和 需求交付追踪表.md。",
+    },
+    "overall_acceptance": {
+        "role": "整体验收执行者",
+        "description": "代码先复核全部主题验收和最终全量回归已经通过，再由用户确认整个需求是否完成。本阶段不生成新的结果文档。",
+    },
+    # bug 复现阶段：复现+根因分析
+    "reproduce": {
+        "role": "bug 复现者",
+        "description": "使用真实场景复现缺陷并确认根因，根据修复后用户应该恢复得到的结果确定一个验收主题，产出 bug/缺陷_<缺陷文件标识>.md 并更新 bug/索引.md。",
+    },
+}
+
+
+# 根据 stage 名拿角色定义
+# discuss 命令调用：拿到 {role, description} dict，打印给 AI 看
+# 返回 None 表示该 stage 没有角色定义（discuss 会打印"无角色定义"）
+def get_role_doc(stage_name: str) -> dict | None:
+    # 从映射表查找，找不到返回 None
+    return ROLE_DOC_MAP.get(stage_name)
+
+
+# 返回文档概览文本
+# start 命令和其它命令可能调用，打印给 AI 和用户看
+def get_overview() -> str:
+    return DOC_OVERVIEW