specstamp 0.11.0__py3-none-any.whl

codex_sdlc/__init__.py

@@ -0,0 +1,5 @@
+"""SpecStamp 本机工具包。"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.11.0"

codex_sdlc/adapters/__init__.py

@@ -0,0 +1 @@
+"""适配层预留目录。"""

codex_sdlc/cli.py

@@ -0,0 +1,418 @@
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+from codex_sdlc.core.backup import create_backup, record_auto_backup_failure, require_matching_sdlc_identity
+from codex_sdlc.core.environment import version_text
+from codex_sdlc.core.errors import SdlcError
+from codex_sdlc.core.project import build_paths, resolve_project_root
+from codex_sdlc.core.state import derive_state, render_next_text
+from codex_sdlc.commands import (
+    accept_cmd,
+    add_cmd,
+    agent_sync_cmd,
+    backup_cmd,
+    capture_cmd,
+    change_cmd,
+    clean_cmd,
+    context_cmd,
+    draft_cmd,
+    design_cmd,
+    doctor_cmd,
+    docs_cmd,
+    export_cmd,
+    finish_cmd,
+    facts_cmd,
+    grill_cmd,
+    handoff_cmd,
+    hooks_cmd,
+    init_cmd,
+    lessons_cmd,
+    material_cmd,
+    next_cmd,
+    plan_cmd,
+    regression_cmd,
+    start_cmd,
+    status_cmd,
+    task_cmd,
+)
+
+
+def translate_argparse_error(message: str) -> str:
+    required_match = re.match(r"the following arguments are required: (.+)", message)
+    if required_match:
+        return f"缺少必填参数：{required_match.group(1)}"
+
+    invalid_choice_match = re.match(r"argument (.+): invalid choice: '(.+)' \((.+)\)", message)
+    if invalid_choice_match:
+        target, invalid_value, choices = invalid_choice_match.groups()
+        return f"{target} 的值 `{invalid_value}` 不支持，{choices.replace('choose from', '可选值：')}"
+
+    unrecognized_match = re.match(r"unrecognized arguments: (.+)", message)
+    if unrecognized_match:
+        return f"无法识别这些参数：{unrecognized_match.group(1)}"
+
+    expected_match = re.match(r"argument (.+): expected one argument", message)
+    if expected_match:
+        return f"{expected_match.group(1)} 后面还缺少参数值"
+
+    return message
+
+
+class ChineseArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        translated = translate_argparse_error(message)
+        raise SdlcError(f"{self.format_usage().strip()}\n参数错误：{translated}", exit_code=2)
+
+
+def render_uninitialized_next_recommendation() -> str:
+    return "\n".join(
+        [
+            "下一步推荐",
+            "- 主推荐：$sdlc-init",
+            "- 原因：当前目录还没有可用的 SDLC 状态，先初始化项目。",
+            "",
+            "备选指令",
+            "- $sdlc-doctor-install",
+            "- $sdlc-status",
+        ]
+    )
+
+
+def render_state_read_failed_recommendation(error_message: str) -> str:
+    return "\n".join(
+        [
+            "下一步推荐",
+            "- 主推荐：$sdlc-doctor-repair",
+            f"- 原因：当前状态读取失败：{error_message}",
+            "",
+            "备选指令",
+            "- $sdlc-doctor-deep",
+            "- $sdlc-status",
+        ]
+    )
+
+
+def render_cli_next_recommendation() -> str:
+    try:
+        root = resolve_project_root(Path.cwd(), allow_plain_directory=True)
+        paths = build_paths(root)
+        if not paths.events_file.exists():
+            return render_uninitialized_next_recommendation()
+        state = derive_state(paths)
+        return render_next_text(paths, state)
+    except SdlcError as exc:
+        return render_state_read_failed_recommendation(exc.message)
+
+
+def should_append_next_recommendation(args: argparse.Namespace, exit_code: int) -> bool:
+    if exit_code != 0:
+        return False
+    command = getattr(args, "command", None)
+    # 这些命令自己已经给出下一步，或可能处在恢复/体检场景；不要再按当前状态追加通用推荐。
+    skip_commands = {
+        "help",
+        "next",
+        "status",
+        "init",
+        "init-plain",
+        "init-basic",
+        "init-basic-plain",
+        "start",
+        "light-start",
+        "discuss",
+        "discuss-link",
+        "capture",
+        "capture-link",
+        "capture-requirement",
+        "capture-change",
+        "add",
+        "material",
+        "design",
+        "design-accept",
+        "draft",
+        "plan",
+        "plan-add-task",
+        "plan-amend-task",
+        "plan-reorder",
+        "plan-depends",
+        "plan-close",
+        "plan-priority",
+        "change",
+        "change-accept",
+        "change-capture",
+        "change-plan",
+        "task",
+        "task-done",
+        "task-restore",
+        "task-pause",
+        "fix",
+        "audit",
+        "accept",
+        "regression",
+        "backup",
+        "backup-list",
+        "backup-clean",
+        "restore",
+        "context",
+        "lessons",
+        "doctor",
+        "doctor-install",
+        "doctor-repair",
+        "doctor-deep",
+        "docs",
+        "finish",
+        "handoff",
+        "grill",
+        "agent-sync",
+        "hooks-upgrade",
+        "tasks",
+        "version",
+    }
+    return bool(command and command not in skip_commands)
+
+
+def print_next_recommendation_footer() -> None:
+    print()
+    print(render_cli_next_recommendation(), end="")
+
+
+AUTO_BACKUP_COMMANDS = {
+    "init",
+    "init-plain",
+    "init-basic",
+    "init-basic-plain",
+    "start",
+    "light-start",
+    "discuss",
+    "discuss-link",
+    "capture",
+    "capture-link",
+    "capture-requirement",
+    "capture-change",
+    "add",
+    "grill",
+    "material",
+    "design",
+    "design-accept",
+    "draft",
+    "tasks",
+    "plan",
+    "plan-add-task",
+    "plan-amend-task",
+    "plan-reorder",
+    "plan-depends",
+    "plan-close",
+    "plan-priority",
+    "change",
+    "change-accept",
+    "change-capture",
+    "change-plan",
+    "task",
+    "task-done",
+    "task-restore",
+    "task-pause",
+    "fix",
+    "audit",
+    "accept",
+    "regression",
+    "docs",
+    "finish",
+    "handoff",
+    "export",
+    "export-requirement",
+}
+
+PINNED_AUTO_BACKUP_COMMANDS = {
+    "design-accept",
+    "task-done",
+    "regression",
+    "docs",
+    "accept",
+    "finish",
+}
+
+# 大多数写命令成功后的快照已经能恢复上一步状态；只有修复类命令需要额外留下写入前状态。
+PRE_CHANGE_AUTO_BACKUP_COMMANDS = {"doctor-repair"}
+
+IDENTITY_CHECK_COMMANDS = {
+    *AUTO_BACKUP_COMMANDS,
+    "backup",
+    "next",
+    "status",
+    "doctor-repair",
+}
+
+
+def should_auto_backup(args: argparse.Namespace, *, phase: str) -> bool:
+    if os.environ.get("CODEX_SDLC_DISABLE_AUTO_BACKUP") == "1":
+        return False
+    if os.environ.get("PYTEST_CURRENT_TEST") and not os.environ.get("CODEX_SDLC_BACKUP_HOME"):
+        return False
+    command = getattr(args, "command", "")
+    if phase not in {"before", "after"}:
+        return False
+    is_repair_command = command == "doctor-repair" or (command == "doctor" and getattr(args, "repair", False))
+    if phase == "before":
+        return command in PRE_CHANGE_AUTO_BACKUP_COMMANDS or is_repair_command
+    if command == "lessons":
+        return getattr(args, "lesson_command", "") in {"add", "apply", "promote", "demote", "retire"}
+    if command in AUTO_BACKUP_COMMANDS:
+        return True
+    return is_repair_command
+
+
+def run_auto_backup(args: argparse.Namespace, *, phase: str) -> None:
+    if not should_auto_backup(args, phase=phase):
+        return
+    try:
+        root = resolve_project_root(Path.cwd(), allow_plain_directory=True)
+        paths = build_paths(root)
+        if not paths.events_file.exists():
+            return
+        command = getattr(args, "command", "command")
+        result = create_backup(
+            paths,
+            label=f"auto-{command}-{phase}",
+            pinned=command in PINNED_AUTO_BACKUP_COMMANDS and phase == "after",
+            automatic=True,
+            command=command,
+            phase=phase,
+        )
+        git_result = result.get("git", {})
+        if isinstance(git_result, dict) and git_result.get("status") == "failed":
+            record_auto_backup_failure(
+                command=command,
+                phase=phase,
+                message=str(git_result.get("message") or "Git 提交失败"),
+            )
+    except Exception as exc:
+        # 自动备份不能打断用户当前命令；手动备份失败才需要显式报错。
+        record_auto_backup_failure(command=getattr(args, "command", "command"), phase=phase, message=str(exc))
+        return
+
+
+def run_identity_guard(args: argparse.Namespace) -> None:
+    command = getattr(args, "command", "")
+    if command == "context":
+        if getattr(args, "context_command", "") != "save":
+            return
+        root = resolve_project_root(Path.cwd(), allow_plain_directory=True)
+        paths = build_paths(root)
+        require_matching_sdlc_identity(paths)
+        return
+    if command == "lessons":
+        if getattr(args, "lesson_command", "") not in {"add", "apply", "promote", "demote", "retire"}:
+            return
+        root = resolve_project_root(Path.cwd(), allow_plain_directory=True)
+        paths = build_paths(root)
+        require_matching_sdlc_identity(paths)
+        return
+    if command not in IDENTITY_CHECK_COMMANDS:
+        return
+    root = resolve_project_root(Path.cwd(), allow_plain_directory=True)
+    paths = build_paths(root)
+    require_matching_sdlc_identity(paths)
+
+
+def run_start_transaction_recovery() -> None:
+    """所有普通命令先收口建档事务，不能让身份检查或备份看到半成品。"""
+
+    from codex_sdlc.core.start_transaction import (
+        recover_incomplete_start_transactions,
+    )
+
+    root = resolve_project_root(Path.cwd(), allow_plain_directory=True)
+    paths = build_paths(root)
+    if not paths.sdlc_dir.is_dir():
+        return
+    recover_incomplete_start_transactions(paths)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = ChineseArgumentParser(
+        prog="specstamp",
+        description="SpecStamp 本机软件开发生命周期辅助工具",
+    )
+    parser.add_argument("--version", action="store_true", help="显示当前版本")
+    subparsers = parser.add_subparsers(dest="command", parser_class=ChineseArgumentParser)
+
+    help_parser = subparsers.add_parser("help", help="查看帮助")
+    help_parser.add_argument("topic", nargs="?", help="可选命令名")
+
+    version_parser = subparsers.add_parser("version", help="显示当前版本")
+    version_parser.set_defaults(func=lambda _args: print(version_text()) or 0)
+
+    init_cmd.register(subparsers)
+    agent_sync_cmd.register(subparsers)
+    hooks_cmd.register(subparsers)
+    clean_cmd.register(subparsers)
+    accept_cmd.register(subparsers)
+    backup_cmd.register(subparsers)
+    context_cmd.register(subparsers)
+    next_cmd.register(subparsers)
+    capture_cmd.register(subparsers)
+    add_cmd.register(subparsers)
+    grill_cmd.register(subparsers)
+    lessons_cmd.register(subparsers)
+    material_cmd.register(subparsers)
+    design_cmd.register(subparsers)
+    draft_cmd.register(subparsers)
+    facts_cmd.register(subparsers)
+    start_cmd.register(subparsers)
+    plan_cmd.register(subparsers)
+    regression_cmd.register(subparsers)
+    docs_cmd.register(subparsers)
+    task_cmd.register(subparsers)
+    change_cmd.register(subparsers)
+    finish_cmd.register(subparsers)
+    handoff_cmd.register(subparsers)
+    status_cmd.register(subparsers)
+    doctor_cmd.register(subparsers)
+    export_cmd.register(subparsers)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+
+        if args.version:
+            print(version_text())
+            return 0
+
+        if getattr(args, "command", None):
+            run_start_transaction_recovery()
+
+        if args.command == "help":
+            topic = getattr(args, "topic", None)
+            if not topic:
+                parser.print_help()
+                return 0
+            nested_args = parser.parse_args([topic, "--help"])
+            return 0 if nested_args else 0
+
+        if not getattr(args, "command", None):
+            parser.print_help()
+            return 0
+
+        run_identity_guard(args)
+        run_auto_backup(args, phase="before")
+        exit_code = int(args.func(args))
+        if exit_code == 0:
+            run_auto_backup(args, phase="after")
+        if should_append_next_recommendation(args, exit_code):
+            print_next_recommendation_footer()
+        return exit_code
+    except SdlcError as exc:
+        print(f"错误：{exc.message}", file=sys.stderr)
+        return exc.exit_code
+    except KeyboardInterrupt:
+        print("已取消。", file=sys.stderr)
+        return 130

codex_sdlc/commands/__init__.py

@@ -0,0 +1 @@
+"""命令入口模块。"""

codex_sdlc/commands/accept_cmd.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from codex_sdlc.core.errors import SdlcError
+from codex_sdlc.core.project import build_paths, project_lock, resolve_project_root
+from codex_sdlc.core.state import (
+    append_event,
+    collect_docs_actions,
+    derive_state,
+    latest_unresolved_manual_pending_event,
+    now_iso,
+    refresh_materialized_state,
+    resolve_requirement,
+)
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("accept", help="确认需求真正结束")
+    parser.add_argument("requirement_id", nargs="?", help="可选需求编号")
+    parser.set_defaults(func=run)
+
+
+def candidate_line(requirement: dict[str, object]) -> str:
+    return f"{requirement['requirement_id']}：{requirement['title']}"
+
+
+def recent_requirement(state: dict[str, object], candidates: list[dict[str, object]]) -> dict[str, object] | None:
+    candidate_map = {requirement["requirement_id"]: requirement for requirement in candidates}
+    for event in reversed(state["events"]):  # type: ignore[index]
+        requirement_id = event.get("requirement_id")
+        if requirement_id in candidate_map and event.get("source") in {"sdlc-task", "sdlc-plan", "sdlc-doctor"}:
+            return candidate_map[requirement_id]
+    return None
+
+
+def select_requirement_to_accept(state: dict[str, object], requirement_id: str | None) -> dict[str, object]:
+    if requirement_id:
+        return resolve_requirement(state, requirement_id)
+
+    done_candidates = [
+        requirement
+        for requirement in state["requirements"].values()  # type: ignore[index]
+        if requirement["status"] == "done"
+    ]
+    recent_done = recent_requirement(state, done_candidates)
+    if recent_done:
+        return recent_done
+    if len(done_candidates) == 1:
+        return done_candidates[0]
+    if len(done_candidates) > 1:
+        lines = ["多个需求都已完成，请指定要接受哪一个："]
+        lines.extend(f"- {candidate_line(requirement)}" for requirement in done_candidates)
+        raise SdlcError("\n".join(lines), exit_code=1)
+
+    active = list(state["active_requirements"])  # type: ignore[index]
+    if len(active) == 1:
+        return active[0]
+    if active:
+        lines = ["当前没有已完成需求，且有多个活跃需求，请指定需求编号："]
+        lines.extend(f"- {candidate_line(requirement)}" for requirement in active)
+        raise SdlcError("\n".join(lines), exit_code=1)
+    raise SdlcError("当前没有可接受的需求。", exit_code=1)
+
+
+def run(args: argparse.Namespace) -> int:
+    root = resolve_project_root(Path.cwd())
+    paths = build_paths(root)
+    if not paths.events_file.exists():
+        raise SdlcError("当前项目还没初始化，请先使用 `$sdlc-init`。")
+
+    with project_lock(paths):
+        state = derive_state(paths)
+        requirement = select_requirement_to_accept(state, args.requirement_id)
+        unfinished = [
+            task
+            for task in requirement["tasks"]  # type: ignore[index]
+            if task["status"] not in {"done", "closed"}
+        ]
+        if unfinished:
+            lines = [f"{requirement['requirement_id']} 还有未完成任务，不能接受需求："]
+            lines.extend(f"- {task['task_id']} [{task['status']}] {task['title']}" for task in unfinished)
+            raise SdlcError("\n".join(lines), exit_code=1)
+        pending_manual = latest_unresolved_manual_pending_event(state, requirement)
+        if pending_manual is not None:
+            payload = pending_manual.get("payload", {}) if isinstance(pending_manual.get("payload", {}), dict) else {}
+            manual_items = payload.get("manual_items", []) if isinstance(payload, dict) else []
+            lines = [f"{requirement['requirement_id']} 还有人工或模拟器验收项没确认，不能接受需求："]
+            for item in manual_items[:8]:
+                if not isinstance(item, dict):
+                    continue
+                case_ids = "、".join(str(case_id) for case_id in item.get("case_ids", []) if str(case_id).strip())
+                title = str(item.get("task_title", "")).strip()
+                task_id = str(item.get("task_id", "")).strip()
+                lines.append(f"- {task_id} {title}" + (f"；待确认测试：{case_ids}" if case_ids else ""))
+            lines.append(
+                "请先完成上面的人工/视觉验收，再写入验证记录，"
+                "例如 `$sdlc-task-done REQ-001 T-001 --verify \"人工验收通过：...\"`。"
+            )
+            raise SdlcError("\n".join(lines), exit_code=1)
+
+        append_event(
+            paths,
+            event_type="requirement_accepted",
+            source="sdlc-accept",
+            summary=f"接受需求 {requirement['requirement_id']}",
+            requirement_id=requirement["requirement_id"],
+            payload={"accepted_at": now_iso()},
+        )
+        refreshed_state = refresh_materialized_state(paths)
+        docs_actions = [
+            action
+            for action in collect_docs_actions(refreshed_state, paths.root)
+            if action["command"].startswith(f"$sdlc-docs {requirement['requirement_id']}")
+        ]
+        next_command = docs_actions[0]["command"] if docs_actions else "$sdlc-finish"
+
+    print(f"已接受需求：{requirement['requirement_id']}")
+    print("状态：accepted")
+    print(f"下一步建议：{next_command}")
+    return 0

codex_sdlc/commands/add_cmd.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from codex_sdlc.commands.plan_cmd import (
+    added_task_change_redirects,
+    append_extra_tasks,
+    build_initial_tasks,
+    ensure_mutable_task_plan_contract,
+    print_current_next_suggestion,
+    refresh_task_coverage_tests,
+    refresh_planning_state,
+    restore_existing_coverage_points,
+)
+from codex_sdlc.core.errors import SdlcError
+from codex_sdlc.core.project import build_paths, project_lock, resolve_project_root
+from codex_sdlc.core.state import (
+    append_event,
+    bind_tasks_to_current_contract,
+    derive_state,
+    resolve_requirement,
+)
+from codex_sdlc.core.task_quality import analyze_task_quality
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("add", help="按模型给出的显式类型追加内容")
+    parser.add_argument("requirement_id", help="需求编号")
+    parser.add_argument("description", help="要追加的内容")
+    parser.add_argument("--kind", choices=["bug", "task", "change"], required=True, help="模型已确认的内容类型")
+    parser.add_argument("--source-task", default="", help="bug 修复对应的原任务编号；--kind bug 时必填")
+    parser.add_argument("--coverage", action="append", default=[], help="任务显式覆盖的 FR 编号，可重复传入")
+    parser.add_argument("--acceptance", action="append", default=[], help="验收或回归要求，可重复传入")
+    parser.add_argument("--task", action="append", default=[], help="变更的结构化任务，可重复传入；格式为“标题||摘要||FR-001,FR-002”")
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    if not str(args.description).strip():
+        raise SdlcError("追加内容不能为空。", exit_code=1)
+
+    kind = str(args.kind)
+    if kind == "bug":
+        raise SdlcError(
+            "add 不再创建修复任务；当前任务反馈请使用 `$sdlc-task-restore`，历史已完成任务问题请使用 `$sdlc-fix`。",
+            exit_code=1,
+        )
+
+    if kind == "task":
+        return run_plain_task_autoflow(args)
+
+    raise SdlcError(
+        "add 不再登记自然语言变更；请先使用 `codex-sdlc change-create REQ-xxx --request-key <稳定请求键>` 创建结构化 CHG 工作区。",
+        exit_code=1,
+    )
+
+
+def append_plain_task(
+    paths,
+    state: dict[str, object],
+    requirement: dict[str, object],
+    description: str,
+    *,
+    allow_broad_scope_tasks: bool = False,
+    coverage_points: list[str] | None = None,
+) -> tuple[str, dict[str, object] | None, str | None, str]:
+    ensure_mutable_task_plan_contract(paths, requirement)
+    tasks = build_initial_tasks(requirement)
+    saved_coverage = {
+        str(task.get("task_id", "")): [str(item) for item in (task.get("coverage_points") or []) if str(item).strip()]
+        for task in tasks
+    }
+    tasks, created_tasks = append_extra_tasks(tasks, [description])
+    if created_tasks:
+        created_tasks[0]["coverage_points"] = list(dict.fromkeys(str(item).strip() for item in (coverage_points or []) if str(item).strip()))
+    bind_tasks_to_current_contract(requirement, tasks, force=True)
+    restore_existing_coverage_points(tasks, saved_coverage)
+    redirects = added_task_change_redirects(requirement, created_tasks, allow_broad_scope_tasks=allow_broad_scope_tasks)
+    if redirects:
+        raise SdlcError(
+            "--kind task 需要显式的任务覆盖关系：\n"
+            + "\n".join(f"- {task['title']}：{reason}" for task, reason in redirects)
+            + "\n请通过 --coverage 传入准确的 FR 编号，CLI 不会把它改猜为需求变更。",
+            exit_code=1,
+        )
+
+    refresh_task_coverage_tests(requirement, tasks)
+    quality_report = analyze_task_quality(tasks)
+    append_event(
+        paths,
+        event_type="plan_updated",
+        source="sdlc-add",
+        summary=f"追加普通任务 {created_tasks[0]['task_id']}",
+        requirement_id=requirement["requirement_id"],
+        task_id=created_tasks[0]["task_id"],
+        payload={
+            "tasks": tasks,
+            "priority": requirement.get("priority", "normal"),
+            "blocked_reason": "",
+            "resolved_change_ids": [],
+            "task_quality": quality_report,
+        },
+    )
+    refresh_planning_state(paths, str(requirement["requirement_id"]))
+    return "task", created_tasks[0], None, ""
+
+
+def run_plain_task_autoflow(args: argparse.Namespace) -> int:
+    root = resolve_project_root(Path.cwd())
+    paths = build_paths(root)
+    if not paths.events_file.exists():
+        raise SdlcError("当前项目还没初始化，请先使用 `$sdlc-init`。")
+
+    description = str(args.description).strip()
+    with project_lock(paths):
+        state = derive_state(paths)
+        requirement = resolve_requirement(state, args.requirement_id)
+        _result_kind, created_task, _change_id, _redirect_reason = append_plain_task(
+            paths,
+            state,
+            requirement,
+            description,
+            allow_broad_scope_tasks=False,
+            coverage_points=list(getattr(args, "coverage", []) or []),
+        )
+        refreshed_state = derive_state(paths)
+        refreshed_requirement = resolve_requirement(refreshed_state, args.requirement_id)
+        task_id = str(created_task["task_id"]) if created_task else ""
+
+    print("显式类型：已有需求下的普通任务")
+    print(f"已自动追加任务：{refreshed_requirement['requirement_id']} / {task_id}")
+    print("任务已经加入结构化任务计划，覆盖关系已同步。")
+    print_current_next_suggestion(paths)
+    return 0