宜博 / lemongraph

{
  "meta": {
    "project": "graphlemon",
    "version": "v1.7.0",
    "effective_date": "2026-07-30",
    "owner": "bboonnee",
    "changelog_v1.7.0": "新增 PH5 自举能力：deployment/deploy_health_signal 实体，bug_record.root_cause_category 新增 core_engine，c_deploy_supervisor_* 五个控制操作，c_org_loop_route 的 core_engine 路由分支，p_deploy_supervisor_blue_green 流程，REQ-15。Deploy Supervisor 与架构文档既有的 Supervisor（调度子 Agent）概念不同，见 docs/supervisor-auto-rollback-design.md 命名说明"
  },
  "model_contract": [
    {
      "entity": "project",
      "owner": "control-plane",
      "purpose": "目标项目=独立代码空间，架构文档第13节",
      "fields": [
        {"name": "project_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "name", "type": "string", "nullable": false, "constraints": []},
        {"name": "target_folder_path", "type": "string", "nullable": false, "constraints": ["unique"], "index": "unique"},
        {"name": "has_git_repo", "type": "boolean", "nullable": false, "constraints": []},
        {"name": "graphlemon_subdir_initialized", "type": "boolean", "nullable": false, "constraints": []},
        {"name": "status", "type": "varchar(20)", "nullable": false, "constraints": ["enum:active|archived"]},
        {"name": "created_at", "type": "timestamp", "nullable": false, "constraints": []}
      ]
    },
    {
      "entity": "org_graph_definition",
      "owner": "graph-engine",
      "purpose": "Org Graph 静态定义，人工维护",
      "fields": [
        {"name": "graph_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "version", "type": "string", "nullable": false, "constraints": ["git_ref"]},
        {"name": "nodes", "type": "json", "nullable": false, "constraints": []},
        {"name": "edges", "type": "json", "nullable": false, "constraints": []},
        {"name": "file_path", "type": "string", "nullable": false, "constraints": []},
        {"name": "status", "type": "varchar(20)", "nullable": false, "constraints": ["enum:draft|active|deprecated"]}
      ]
    },
    {
      "entity": "task",
      "owner": "graph-engine",
      "purpose": "任务队列条目，替代飞书 Base",
      "fields": [
        {"name": "task_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "project_id", "type": "string", "nullable": false, "constraints": ["fk:project.project_id", "idx"], "index": "idx"},
        {"name": "goal_text", "type": "text", "nullable": false, "constraints": []},
        {"name": "task_type", "type": "varchar(20)", "nullable": false, "constraints": ["enum:goal|bug_fix"]},
        {"name": "origin_ref", "type": "string", "nullable": true, "constraints": ["fk:bug_record.bug_id"]},
        {"name": "created_via", "type": "varchar(20)", "nullable": false, "constraints": ["enum:api|human_console"], "default": "api"},
        {"name": "status", "type": "varchar(30)", "nullable": false, "constraints": ["idx"], "index": "idx"},
        {"name": "route", "type": "varchar(20)", "nullable": true, "constraints": ["enum:fast_lane|full_replan"]},
        {"name": "loop_round", "type": "int", "nullable": false, "constraints": [">=0"], "default": 0},
        {"name": "blocked_reason", "type": "string", "nullable": true, "constraints": []},
        {"name": "assigned_org_node", "type": "varchar(20)", "nullable": false, "constraints": ["enum:planner|coder|validator", "idx"], "index": "idx"},
        {"name": "created_at", "type": "timestamp", "nullable": false, "constraints": []},
        {"name": "updated_at", "type": "timestamp", "nullable": false, "constraints": []}
      ]
    },
    {
      "entity": "work_graph_run",
      "owner": "graph-engine",
      "purpose": "Org Agent 针对 task 的一次 Work Graph 执行实例",
      "fields": [
        {"name": "run_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "task_id", "type": "string", "nullable": false, "constraints": ["fk:task.task_id"]},
        {"name": "org_node", "type": "varchar(20)", "nullable": false, "constraints": ["enum:planner|coder|validator"]},
        {"name": "graph_manifest", "type": "json", "nullable": false, "constraints": []},
        {"name": "orchestration_script_ref", "type": "string", "nullable": true, "constraints": []},
        {"name": "status", "type": "varchar(20)", "nullable": false, "constraints": ["enum:planning|running|merging|verifying|reflecting|blocked|done|failed"]},
        {"name": "started_at", "type": "timestamp", "nullable": true, "constraints": []},
        {"name": "completed_at", "type": "timestamp", "nullable": true, "constraints": []},
        {"name": "result_artifact_refs", "type": "json", "nullable": true, "constraints": []}
      ]
    },
    {
      "entity": "work_node_execution",
      "owner": "graph-engine",
      "purpose": "Work Graph 内每个节点的执行记录与契约校验",
      "fields": [
        {"name": "node_exec_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "run_id", "type": "string", "nullable": false, "constraints": ["fk:work_graph_run.run_id"]},
        {"name": "node_id", "type": "string", "nullable": false, "constraints": []},
        {"name": "subagent_type", "type": "string", "nullable": false, "constraints": []},
        {"name": "skill_ref", "type": "string", "nullable": false, "constraints": ["fk:skill.skill_id"]},
        {"name": "input_schema_ref", "type": "string", "nullable": false, "constraints": []},
        {"name": "output_schema_ref", "type": "string", "nullable": false, "constraints": []},
        {"name": "input_payload", "type": "json", "nullable": false, "constraints": []},
        {"name": "output_payload", "type": "json", "nullable": true, "constraints": []},
        {"name": "model_tier", "type": "varchar(20)", "nullable": false, "constraints": ["enum:cheap|standard|premium"], "default": "standard"},
        {"name": "status", "type": "varchar(20)", "nullable": false, "constraints": ["enum:pending|running|reflecting|retrying|waiting_for_quota|blocked|done|failed"]},
        {"name": "retry_count", "type": "int", "nullable": false, "constraints": [">=0"], "default": 0},
        {"name": "reflection_notes", "type": "json", "nullable": true, "constraints": []},
        {"name": "git_worktree_ref", "type": "string", "nullable": true, "constraints": []},
        {"name": "quota_wait_started_at", "type": "timestamp", "nullable": true, "constraints": []},
        {"name": "quota_limit_type", "type": "varchar(10)", "nullable": true, "constraints": ["enum:session|weekly|opus"]}
      ]
    },
    {
      "entity": "artifact",
      "owner": "graph-engine",
      "purpose": "BRD/PRD/SDD/Benchmark/BugRecord 等结构化产物，版本化不可变",
      "fields": [
        {"name": "artifact_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "artifact_type", "type": "varchar(20)", "nullable": false, "constraints": ["enum:brd|prd|sdd|benchmark|bug_record|code_diff|test_report"]},
        {"name": "task_id", "type": "string", "nullable": false, "constraints": ["fk:task.task_id"]},
        {"name": "produced_by_run_id", "type": "string", "nullable": false, "constraints": ["fk:work_graph_run.run_id"]},
        {"name": "file_path", "type": "string", "nullable": false, "constraints": []},
        {"name": "git_commit_sha", "type": "string", "nullable": false, "constraints": []},
        {"name": "depends_on_artifact_ids", "type": "json", "nullable": true, "constraints": []},
        {"name": "validation_status", "type": "varchar(20)", "nullable": false, "constraints": ["enum:pending|passed|failed"], "default": "pending"},
        {"name": "created_at", "type": "timestamp", "nullable": false, "constraints": []}
      ]
    },
    {
      "entity": "bug_record",
      "owner": "validator",
      "purpose": "结构化问题记录与根因归属，来源可为 Validator 自动生成或人工反馈",
      "fields": [
        {"name": "bug_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "task_id", "type": "string", "nullable": true, "constraints": ["fk:task.task_id"]},
        {"name": "source", "type": "varchar(20)", "nullable": false, "constraints": ["enum:validator|human"]},
        {"name": "reported_by", "type": "string", "nullable": true, "constraints": []},
        {"name": "description", "type": "text", "nullable": false, "constraints": []},
        {"name": "repro_steps", "type": "text", "nullable": true, "constraints": []},
        {"name": "root_cause_category", "type": "varchar(20)", "nullable": true, "constraints": ["enum:planning|coder|skill_defect|core_engine"]},
        {"name": "root_cause_detail", "type": "text", "nullable": true, "constraints": []},
        {"name": "related_artifact_ids", "type": "json", "nullable": true, "constraints": []},
        {"name": "suggested_route", "type": "varchar(20)", "nullable": true, "constraints": ["enum:fast_lane|full_replan"]},
        {"name": "skill_iteration_suggestion_id", "type": "string", "nullable": true, "constraints": ["fk:skill_iteration.iteration_id"]},
        {"name": "status", "type": "varchar(20)", "nullable": false, "constraints": ["enum:open|triaging|routed|resolved"]}
      ]
    },
    {
      "entity": "skill",
      "owner": "graph-engine",
      "purpose": "Skill 库条目，Git 版本化",
      "fields": [
        {"name": "skill_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "owner_org_node", "type": "varchar(20)", "nullable": false, "constraints": ["enum:planner|coder|validator"]},
        {"name": "file_path", "type": "string", "nullable": false, "constraints": []},
        {"name": "current_git_commit_sha", "type": "string", "nullable": false, "constraints": []},
        {"name": "source", "type": "varchar(20)", "nullable": false, "constraints": ["enum:migrated_from_hermes|new|auto_iterated"]},
        {"name": "migrated_from_profile", "type": "varchar(20)", "nullable": true, "constraints": ["enum:code|planning|qa"]},
        {"name": "status", "type": "varchar(20)", "nullable": false, "constraints": ["enum:active|archived"]}
      ]
    },
    {
      "entity": "skill_iteration",
      "owner": "graph-engine",
      "purpose": "Skill 自主迭代的变更记录，每条对应一次独立 Git 提交",
      "fields": [
        {"name": "iteration_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "skill_id", "type": "string", "nullable": false, "constraints": ["fk:skill.skill_id"]},
        {"name": "triggered_by_bug_id", "type": "string", "nullable": false, "constraints": ["fk:bug_record.bug_id"]},
        {"name": "before_git_commit_sha", "type": "string", "nullable": false, "constraints": []},
        {"name": "after_git_commit_sha", "type": "string", "nullable": false, "constraints": []},
        {"name": "change_summary", "type": "text", "nullable": false, "constraints": []},
        {"name": "applied_at", "type": "timestamp", "nullable": false, "constraints": []},
        {"name": "rollback_of_iteration_id", "type": "string", "nullable": true, "constraints": ["fk:skill_iteration.iteration_id"]}
      ]
    },
    {
      "entity": "agent_profile",
      "owner": "graph-engine",
      "purpose": "Org Agent 人设与运行契约文件元数据",
      "fields": [
        {"name": "org_node", "type": "varchar(20)", "nullable": false, "constraints": ["pk", "enum:planner|coder|validator"]},
        {"name": "soul_file_path", "type": "string", "nullable": false, "constraints": []},
        {"name": "agents_file_path", "type": "string", "nullable": true, "constraints": []},
        {"name": "migrated_from_profile", "type": "varchar(20)", "nullable": false, "constraints": ["enum:code|planning|qa"]},
        {"name": "current_git_commit_sha", "type": "string", "nullable": false, "constraints": []}
      ]
    },
    {
      "entity": "budget_guardrail_config",
      "owner": "graph-engine",
      "purpose": "预算/额度护栏配置，手工配置层",
      "fields": [
        {"name": "config_id", "type": "string", "nullable": false, "constraints": ["pk"], "default": "default"},
        {"name": "scope", "type": "varchar(20)", "nullable": false, "constraints": ["enum:global|per_task|per_day"]},
        {"name": "limit_type", "type": "varchar(20)", "nullable": false, "constraints": ["enum:token_count|call_count"]},
        {"name": "limit_value", "type": "int", "nullable": false, "constraints": [">0"]},
        {"name": "current_usage", "type": "int", "nullable": false, "constraints": [">=0"], "default": 0},
        {"name": "on_exceed_action", "type": "varchar(30)", "nullable": false, "constraints": [], "default": "pause_and_notify"},
        {"name": "updated_by", "type": "string", "nullable": false, "constraints": []},
        {"name": "updated_at", "type": "timestamp", "nullable": false, "constraints": []}
      ]
    },
    {
      "entity": "org_concurrency_config",
      "owner": "graph-engine",
      "purpose": "多 Goal 并发数配置，MVP 默认 1",
      "fields": [
        {"name": "config_id", "type": "string", "nullable": false, "constraints": ["pk"], "default": "default"},
        {"name": "max_concurrent_goals", "type": "int", "nullable": false, "constraints": ["range:1-50"], "default": 1},
        {"name": "updated_by", "type": "string", "nullable": false, "constraints": []},
        {"name": "updated_at", "type": "timestamp", "nullable": false, "constraints": []}
      ]
    },
    {
      "entity": "execution_event",
      "owner": "control-plane",
      "purpose": "实时看板的唯一数据源，append-only 事件流",
      "fields": [
        {"name": "event_id", "type": "string", "nullable": false, "constraints": ["pk", "sortable"]},
        {"name": "project_id", "type": "string", "nullable": false, "constraints": ["fk:project.project_id", "idx"], "index": "idx"},
        {"name": "task_id", "type": "string", "nullable": true, "constraints": ["fk:task.task_id", "idx"], "index": "idx"},
        {"name": "run_id", "type": "string", "nullable": true, "constraints": ["fk:work_graph_run.run_id"]},
        {"name": "node_exec_id", "type": "string", "nullable": true, "constraints": ["fk:work_node_execution.node_exec_id"]},
        {"name": "event_type", "type": "varchar(30)", "nullable": false, "constraints": ["enum:task_status_changed|node_status_changed|artifact_created|bug_recorded|loop_routed|budget_updated|skill_iterated|log_appended|quota_wait_started"]},
        {"name": "payload", "type": "json", "nullable": false, "constraints": []},
        {"name": "created_at", "type": "timestamp", "nullable": false, "constraints": ["idx"], "index": "idx"}
      ]
    },
    {
      "entity": "execution_log_file",
      "owner": "control-plane",
      "purpose": "Work Node 原始执行日志本地落盘记录，架构文档13.1决策4",
      "fields": [
        {"name": "log_file_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "node_exec_id", "type": "string", "nullable": false, "constraints": ["fk:work_node_execution.node_exec_id", "unique"], "index": "unique"},
        {"name": "project_id", "type": "string", "nullable": false, "constraints": ["fk:project.project_id", "idx"], "index": "idx"},
        {"name": "file_path", "type": "string", "nullable": false, "constraints": []},
        {"name": "format", "type": "varchar(20)", "nullable": false, "constraints": ["enum:jsonl|raw_text"]},
        {"name": "size_bytes", "type": "int", "nullable": false, "constraints": [">=0"], "default": 0},
        {"name": "status", "type": "varchar(20)", "nullable": false, "constraints": ["enum:active|closed|purged"]},
        {"name": "created_at", "type": "timestamp", "nullable": false, "constraints": []},
        {"name": "purged_at", "type": "timestamp", "nullable": true, "constraints": []}
      ]
    },
    {
      "entity": "log_retention_config",
      "owner": "control-plane",
      "purpose": "日志清理策略配置",
      "fields": [
        {"name": "config_id", "type": "string", "nullable": false, "constraints": ["pk"], "default": "default"},
        {"name": "retention_days", "type": "int", "nullable": false, "constraints": [">0"], "default": 14},
        {"name": "max_total_size_mb", "type": "int", "nullable": true, "constraints": [">0"]},
        {"name": "updated_by", "type": "string", "nullable": false, "constraints": []},
        {"name": "updated_at", "type": "timestamp", "nullable": false, "constraints": []}
      ]
    },
    {
      "entity": "deployment",
      "owner": "deploy-supervisor",
      "purpose": "PH5 新增（2026-07-30）：Deploy Supervisor 对 graphlemon 自身（self-target）执行一次蓝绿部署的记录，见 docs/supervisor-auto-rollback-design.md。不要与架构文档里的 Supervisor（调度子 Agent）概念混淆",
      "fields": [
        {"name": "deployment_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "git_commit_hash", "type": "string", "nullable": false, "constraints": []},
        {"name": "previous_commit_hash", "type": "string", "nullable": false, "constraints": []},
        {"name": "status", "type": "varchar(30)", "nullable": false, "constraints": ["enum:staged|candidate_starting|health_check_running|health_check_passed|health_check_failed|cutover_in_progress|live|monitoring|anomaly_detected|rollback_in_progress|rolled_back|rollback_failed|blocked_pending_human|monitoring_window_clean|finalized"]},
        {"name": "candidate_port", "type": "int", "nullable": true, "constraints": []},
        {"name": "candidate_db_path", "type": "string", "nullable": true, "constraints": []},
        {"name": "started_at", "type": "timestamp", "nullable": true, "constraints": []},
        {"name": "cutover_at", "type": "timestamp", "nullable": true, "constraints": []},
        {"name": "monitoring_closed_at", "type": "timestamp", "nullable": true, "constraints": []},
        {"name": "rollback_at", "type": "timestamp", "nullable": true, "constraints": []},
        {"name": "rollback_reason", "type": "string", "nullable": true, "constraints": []},
        {"name": "previous_instance_dir", "type": "string", "nullable": false, "constraints": []}
      ]
    },
    {
      "entity": "deploy_health_signal",
      "owner": "deploy-supervisor",
      "purpose": "PH5 新增（2026-07-30）：deployment 生命周期内每次健康检查/监控采样记录，全部确定性判断，不涉及 LLM",
      "fields": [
        {"name": "signal_id", "type": "string", "nullable": false, "constraints": ["pk"]},
        {"name": "deployment_id", "type": "string", "nullable": false, "constraints": ["fk:deployment.deployment_id"]},
        {"name": "sampled_at", "type": "timestamp", "nullable": false, "constraints": []},
        {"name": "signal_type", "type": "varchar(30)", "nullable": false, "constraints": ["enum:process_alive|http_health|canary_task|validator_approval_rate"]},
        {"name": "status", "type": "varchar(10)", "nullable": false, "constraints": ["enum:ok|degraded|fail"]},
        {"name": "detail", "type": "string", "nullable": true, "constraints": []}
      ]
    }
  ],
  "view_contract": [
    {
      "view_id": "v_project_setup",
      "route": "/setup",
      "fields": [
        {"name": "folder_path", "visible_when": "all", "validation": ["required"], "required": true},
        {"name": "project_name", "visible_when": "all", "validation": [], "required": false}
      ],
      "events": [
        {"event": "click_pick_folder", "target_controller_id": "c_pick_folder", "payload": {}},
        {"event": "submit_create", "target_controller_id": "c_project_create", "payload": {"target_folder_path": "string", "name": "string", "init_git_if_missing": "boolean"}}
      ]
    },
    {
      "view_id": "v_dashboard",
      "route": "/",
      "fields": [],
      "events": [
        {"event": "click_propose_goal", "target_controller_id": "c_task_create", "payload": {}},
        {"event": "click_report_bug", "target_controller_id": "c_bug_report_create", "payload": {}},
        {"event": "click_task_card", "target_controller_id": "c_task_get", "payload": {"task_id": "string"}}
      ]
    },
    {
      "view_id": "v_goal_composer",
      "route": "/goals/new",
      "fields": [
        {"name": "goal_text", "visible_when": "all", "validation": ["required", "maxLen:4000"], "required": true}
      ],
      "events": [
        {"event": "submit_create", "target_controller_id": "c_task_create", "payload": {"goal_text": "string", "created_via": "human_console"}}
      ]
    },
    {
      "view_id": "v_bug_feedback",
      "route": "/bugs/new",
      "fields": [
        {"name": "description", "visible_when": "all", "validation": ["required"], "required": true},
        {"name": "repro_steps", "visible_when": "all", "validation": [], "required": false},
        {"name": "related_task_id", "visible_when": "all", "validation": [], "required": false}
      ],
      "events": [
        {"event": "submit_create", "target_controller_id": "c_bug_report_create", "payload": {"description": "string", "repro_steps": "string", "related_task_id": "string"}}
      ]
    },
    {
      "view_id": "v_artifact_browser",
      "route": "/artifacts",
      "fields": [
        {"name": "artifact_type_filter", "visible_when": "all", "validation": [], "required": false},
        {"name": "task_id_filter", "visible_when": "all", "validation": [], "required": false}
      ],
      "events": [
        {"event": "click_row", "target_controller_id": "c_artifact_get", "payload": {"artifact_id": "string"}}
      ]
    },
    {
      "view_id": "v_skill_library",
      "route": "/skills",
      "fields": [],
      "events": [
        {"event": "click_skill", "target_controller_id": "c_skill_diff", "payload": {"skill_id": "string"}}
      ]
    },
    {
      "view_id": "v_task_board",
      "route": "/tasks",
      "fields": [
        {"name": "keyword", "visible_when": "all", "validation": ["maxLen:128"], "required": false},
        {"name": "status_filter", "visible_when": "all", "validation": [], "required": false},
        {"name": "org_node_filter", "visible_when": "all", "validation": [], "required": false}
      ],
      "events": [
        {"event": "click_row", "target_controller_id": "c_task_get", "payload": {"task_id": "string"}},
        {"event": "click_search", "target_controller_id": "c_task_list", "payload": {"filters": ["keyword", "status_filter", "org_node_filter"]}}
      ]
    },
    {
      "view_id": "v_task_detail",
      "route": "/tasks/:task_id",
      "fields": [
        {"name": "task_id", "visible_when": "all", "validation": ["required"], "required": true}
      ],
      "events": [
        {"event": "click_artifact_link", "target_controller_id": "c_artifact_get", "payload": {"artifact_id": "string"}},
        {"event": "click_view_raw_log", "target_controller_id": "c_execution_log_get", "payload": {"node_exec_id": "string"}},
        {"event": "click_retry", "target_controller_id": "c_org_loop_route", "payload": {"task_id": "string", "action": "manual_resume"}}
      ]
    },
    {
      "view_id": "v_log_viewer",
      "route": "embedded",
      "fields": [
        {"name": "node_exec_id", "visible_when": "all", "validation": ["required"], "required": true}
      ],
      "events": [
        {"event": "toggle_auto_scroll", "target_controller_id": "none", "payload": {}},
        {"event": "click_download", "target_controller_id": "c_execution_log_get", "payload": {"node_exec_id": "string", "download": true}}
      ]
    },
    {
      "view_id": "v_log_retention_settings",
      "route": "/settings/log-retention",
      "fields": [
        {"name": "retention_days", "visible_when": "all", "validation": [">0"], "required": true},
        {"name": "max_total_size_mb", "visible_when": "all", "validation": [">0"], "required": false}
      ],
      "events": [
        {"event": "submit_save", "target_controller_id": "c_log_retention_config_update", "payload": {"retention_days": "int", "max_total_size_mb": "int"}}
      ]
    },
    {
      "view_id": "v_concurrency_settings",
      "route": "/settings/concurrency",
      "fields": [
        {"name": "max_concurrent_goals", "visible_when": "all", "validation": ["range:1-50"], "required": true}
      ],
      "events": [
        {"event": "submit_save", "target_controller_id": "c_concurrency_config_update", "payload": {"max_concurrent_goals": "int"}}
      ]
    },
    {
      "view_id": "v_budget_settings",
      "route": "/settings/budget",
      "fields": [
        {"name": "scope", "visible_when": "all", "validation": ["required"], "required": true},
        {"name": "limit_type", "visible_when": "all", "validation": ["required"], "required": true},
        {"name": "limit_value", "visible_when": "all", "validation": [">0"], "required": true}
      ],
      "events": [
        {"event": "submit_save", "target_controller_id": "c_budget_config_update", "payload": {"scope": "string", "limit_type": "string", "limit_value": "int"}}
      ]
    },
    {
      "view_id": "v_skill_audit_log",
      "route": "/skills/:skill_id/audit",
      "fields": [
        {"name": "skill_id", "visible_when": "all", "validation": ["required"], "required": true}
      ],
      "events": [
        {"event": "click_diff", "target_controller_id": "c_skill_diff", "payload": {"before": "string", "after": "string"}},
        {"event": "click_rollback", "target_controller_id": "c_skill_rollback", "payload": {"iteration_id": "string"}}
      ]
    },
    {
      "view_id": "v_graph_visualizer",
      "route": "embedded",
      "fields": [
        {"name": "run_id", "visible_when": "task_has_active_run", "validation": [], "required": false}
      ],
      "events": [
        {"event": "hover_node", "target_controller_id": "c_work_node_get", "payload": {"node_exec_id": "string"}}
      ]
    },
    {
      "view_id": "v_deployment_status",
      "route": "embedded",
      "fields": [
        {"name": "deployment_id", "visible_when": "self_target_deployment_active", "validation": [], "required": false}
      ],
      "events": [
        {"event": "click_deployment_card", "target_controller_id": "c_deploy_supervisor_monitor", "payload": {"deployment_id": "string"}}
      ]
    }
  ],
  "controller_contract": [
    {
      "operation_id": "c_pick_folder",
      "method": "POST",
      "path": "/api/system/pick-folder",
      "auth": "system_internal",
      "input": {},
      "output": {"selected_path": "string|null"},
      "idempotent": false,
      "errors": [
        {"code": "DIALOG_UNAVAILABLE", "retryable": false, "description": "后端所在环境不支持原生文件夹对话框，前端应回退到手动路径输入"}
      ]
    },
    {
      "operation_id": "c_project_create",
      "method": "POST",
      "path": "/api/projects",
      "auth": "system_internal",
      "input": {"target_folder_path": "string(required)", "name": "string(optional)", "init_git_if_missing": "boolean(required)"},
      "output": {"project_id": "string", "has_git_repo": "boolean", "graphlemon_subdir_initialized": "boolean"},
      "idempotent": true,
      "errors": [
        {"code": "PATH_NOT_FOUND", "retryable": false, "description": "文件夹不存在"},
        {"code": "PATH_NOT_WRITABLE", "retryable": false, "description": "无写权限"},
        {"code": "GIT_INIT_DECLINED", "retryable": false, "description": "非 Git 仓库且用户未确认初始化"}
      ]
    },
    {
      "operation_id": "c_project_get",
      "method": "GET",
      "path": "/api/projects/:project_id",
      "auth": "system_internal",
      "input": {"path": {"project_id": "string(required)"}},
      "output": {"project": "object"},
      "idempotent": true,
      "errors": [
        {"code": "NOT_FOUND", "retryable": false, "description": "project_id 不存在"}
      ]
    },
    {
      "operation_id": "c_project_list",
      "method": "GET",
      "path": "/api/projects",
      "auth": "system_internal",
      "input": {},
      "output": {"items": "array"},
      "idempotent": true,
      "errors": []
    },
    {
      "operation_id": "c_task_create",
      "method": "POST",
      "path": "/api/tasks",
      "auth": "system_internal",
      "input": {"project_id": "string(required)", "goal_text": "string(required)", "task_type": "enum(goal)", "created_via": "enum(api|human_console)"},
      "output": {"task_id": "string", "status": "queued"},
      "idempotent": false,
      "errors": [
        {"code": "INVALID_PARAM", "retryable": false, "description": "goal_text 为空或 project_id 不存在"}
      ]
    },
    {
      "operation_id": "c_bug_report_create",
      "method": "POST",
      "path": "/api/bug-reports",
      "auth": "system_internal",
      "input": {"description": "string(required)", "repro_steps": "string(optional)", "related_task_id": "string(optional)"},
      "output": {"bug_id": "string", "status": "open"},
      "idempotent": false,
      "errors": [
        {"code": "INVALID_PARAM", "retryable": false, "description": "description 为空"}
      ]
    },
    {
      "operation_id": "c_ws_subscribe",
      "method": "GET",
      "path": "/api/ws/projects/:project_id",
      "auth": "system_internal",
      "input": {"query": {"project_id": "string(required)", "task_id": "string(optional)"}},
      "output": {"stream": "execution_event[]"},
      "idempotent": false,
      "errors": [
        {"code": "PROJECT_NOT_FOUND", "retryable": false, "description": "订阅的 project_id 不存在，拒绝建立连接"}
      ]
    },
    {
      "operation_id": "c_task_list",
      "method": "GET",
      "path": "/api/tasks",
      "auth": "system_internal",
      "input": {"query": {"status": "string(optional)", "org_node": "string(optional)", "keyword": "string(optional)"}},
      "output": {"items": "array", "total": "int"},
      "idempotent": true,
      "errors": []
    },
    {
      "operation_id": "c_task_get",
      "method": "GET",
      "path": "/api/tasks/:task_id",
      "auth": "system_internal",
      "input": {"path": {"task_id": "string(required)"}},
      "output": {"task": "object", "artifacts": "array", "bug_records": "array"},
      "idempotent": true,
      "errors": [
        {"code": "NOT_FOUND", "retryable": false, "description": "task_id 不存在"}
      ]
    },
    {
      "operation_id": "c_org_node_trigger",
      "method": "POST",
      "path": "/api/org-nodes/:org_node/trigger",
      "auth": "system_internal",
      "input": {"task_id": "string(required)"},
      "output": {"run_id": "string", "status": "string"},
      "idempotent": false,
      "errors": [
        {"code": "TASK_NOT_READY", "retryable": true, "description": "上游依赖 Artifact 未就绪"},
        {"code": "CONCURRENCY_LIMIT_REACHED", "retryable": true, "description": "超过 max_concurrent_goals"},
        {"code": "USAGE_LIMIT_REACHED", "retryable": true, "description": "Claude Code plan 额度耗尽（session/weekly/opus），走退避轮询等待重试，非立即重试，见 p_usage_limit_wait"}
      ]
    },
    {
      "operation_id": "c_work_graph_plan",
      "method": "POST",
      "path": "/api/work-graph/plan",
      "auth": "system_internal",
      "input": {"task_id": "string(required)", "org_node": "string(required)"},
      "output": {"run_id": "string", "graph_manifest": "object"},
      "idempotent": false,
      "errors": [
        {"code": "PLANNING_FAILED", "retryable": true, "description": "Work Graph 规划失败"}
      ]
    },
    {
      "operation_id": "c_work_graph_execute",
      "method": "POST",
      "path": "/api/work-graph/:run_id/execute",
      "auth": "system_internal",
      "input": {"run_id": "string(required)"},
      "output": {"status": "string", "result_artifact_refs": "array"},
      "idempotent": false,
      "errors": [
        {"code": "NODE_CONTRACT_VIOLATION", "retryable": true, "description": "节点输出未通过 schema 校验"},
        {"code": "BUDGET_EXCEEDED", "retryable": false, "description": "预算护栏拦截"},
        {"code": "CLASSIFIER_BLOCKED", "retryable": false, "description": "auto mode 分类器连续拦截 3 次或累计 20 次，-p 非交互模式下无人可确认，进程直接中止"}
      ]
    },
    {
      "operation_id": "c_work_node_run",
      "method": "POST",
      "path": "internal://work-node/run",
      "auth": "system_internal",
      "input": {"node_exec_id": "string(required)", "input_payload": "object", "input_schema_ref": "string"},
      "output": {"output_payload": "object"},
      "idempotent": false,
      "errors": [
        {"code": "SCHEMA_VALIDATION_FAILED", "retryable": true, "description": "输出未通过 output_schema_ref 校验"},
        {"code": "USAGE_LIMIT_REACHED", "retryable": true, "description": "Claude Code plan 额度耗尽，退避轮询等待重试，见 p_usage_limit_wait"}
      ]
    },
    {
      "operation_id": "c_execution_log_get",
      "method": "GET",
      "path": "/api/work-nodes/:node_exec_id/log",
      "auth": "system_internal",
      "input": {"path": {"node_exec_id": "string(required)"}, "query": {"offset": "int(optional)", "limit": "int(optional)", "download": "boolean(optional)"}},
      "output": {"content": "string", "format": "string", "total_size_bytes": "int", "status": "string"},
      "idempotent": true,
      "errors": [
        {"code": "LOG_NOT_FOUND", "retryable": false, "description": "node_exec_id 不存在对应日志记录"},
        {"code": "LOG_PURGED", "retryable": false, "description": "日志已被定时清理任务删除"}
      ]
    },
    {
      "operation_id": "c_ws_log_tail",
      "method": "GET",
      "path": "/api/ws/work-nodes/:node_exec_id/log",
      "auth": "system_internal",
      "input": {"path": {"node_exec_id": "string(required)"}},
      "output": {"stream": "log_chunk[]"},
      "idempotent": false,
      "errors": [
        {"code": "NODE_EXEC_NOT_FOUND", "retryable": false, "description": "node_exec_id 不存在"}
      ]
    },
    {
      "operation_id": "c_log_retention_config_update",
      "method": "PUT",
      "path": "/api/settings/log-retention",
      "auth": "system_internal",
      "input": {"retention_days": "int(required, >0)", "max_total_size_mb": "int(optional)"},
      "output": {"config": "object"},
      "idempotent": true,
      "errors": [
        {"code": "INVALID_PARAM", "retryable": false, "description": "retention_days<=0"}
      ]
    },
    {
      "operation_id": "c_artifact_write",
      "method": "POST",
      "path": "/api/artifacts",
      "auth": "system_internal",
      "input": {"artifact_type": "string(required)", "task_id": "string(required)", "produced_by_run_id": "string(required)", "file_path": "string(required)", "content": "string(required)", "depends_on_artifact_ids": "array(optional)"},
      "output": {"artifact_id": "string", "git_commit_sha": "string"},
      "idempotent": false,
      "errors": [
        {"code": "GIT_COMMIT_FAILED", "retryable": true, "description": "Git 提交失败"}
      ]
    },
    {
      "operation_id": "c_artifact_get",
      "method": "GET",
      "path": "/api/artifacts/:artifact_id",
      "auth": "system_internal",
      "input": {"path": {"artifact_id": "string(required)"}},
      "output": {"artifact": "object"},
      "idempotent": true,
      "errors": [
        {"code": "NOT_FOUND", "retryable": false, "description": "artifact_id 不存在"}
      ]
    },
    {
      "operation_id": "c_skill_update",
      "method": "POST",
      "path": "/api/skills/:skill_id/update",
      "auth": "system_internal",
      "input": {"skill_id": "string(required)", "triggered_by_bug_id": "string(required)", "new_content": "string(required)", "change_summary": "string(required)"},
      "output": {"iteration_id": "string", "after_git_commit_sha": "string"},
      "idempotent": false,
      "errors": [
        {"code": "MISSING_TRIGGER_REF", "retryable": false, "description": "triggered_by_bug_id 缺失，不允许无来源变更"}
      ]
    },
    {
      "operation_id": "c_skill_rollback",
      "method": "POST",
      "path": "/api/skills/:skill_id/rollback",
      "auth": "system_internal",
      "input": {"iteration_id": "string(required)"},
      "output": {"new_iteration_id": "string"},
      "idempotent": false,
      "errors": [
        {"code": "ITERATION_NOT_FOUND", "retryable": false, "description": "iteration_id 不存在"}
      ]
    },
    {
      "operation_id": "c_skill_diff",
      "method": "GET",
      "path": "/api/skills/diff",
      "auth": "system_internal",
      "input": {"query": {"before": "string(required)", "after": "string(required)"}},
      "output": {"diff_text": "string"},
      "idempotent": true,
      "errors": []
    },
    {
      "operation_id": "c_bug_record_create",
      "method": "POST",
      "path": "/api/bug-records",
      "auth": "system_internal",
      "input": {"task_id": "string(required)", "description": "string(required)", "repro_steps": "string(required)", "root_cause_category": "enum(required)", "root_cause_detail": "string(required)", "related_artifact_ids": "array(required)", "suggested_route": "enum(required)"},
      "output": {"bug_id": "string"},
      "idempotent": false,
      "errors": [
        {"code": "INVALID_ROOT_CAUSE_CATEGORY", "retryable": false, "description": "未落在 planning|coder|skill_defect|core_engine 四类之一（core_engine 为 2026-07-30 新增，见 01-M bug_record 实体）"}
      ]
    },
    {
      "operation_id": "c_org_loop_route",
      "method": "POST",
      "path": "/api/tasks/:task_id/route",
      "auth": "system_internal",
      "input": {"task_id": "string(required)", "decided_route": "enum(fast_lane|full_replan|manual_resume)"},
      "output": {"task_id": "string", "new_status": "string", "new_assigned_org_node": "string"},
      "idempotent": false,
      "errors": [
        {"code": "LOOP_LIMIT_REACHED", "retryable": false, "description": "loop_round 已达上限，仅接受 manual_resume"}
      ]
    },
    {
      "operation_id": "c_work_node_get",
      "method": "GET",
      "path": "/api/work-nodes/:node_exec_id",
      "auth": "system_internal",
      "input": {"path": {"node_exec_id": "string(required)"}},
      "output": {"node": "object"},
      "idempotent": true,
      "errors": [
        {"code": "NOT_FOUND", "retryable": false, "description": "node_exec_id 不存在"}
      ]
    },
    {
      "operation_id": "c_budget_check",
      "method": "POST",
      "path": "internal://budget/check",
      "auth": "system_internal",
      "input": {"scope": "string(required)", "estimated_usage": "int(required)"},
      "output": {"allowed": "boolean", "remaining_quota": "int"},
      "idempotent": true,
      "errors": [
        {"code": "BUDGET_EXCEEDED", "retryable": false, "description": "超出配置额度"}
      ]
    },
    {
      "operation_id": "c_concurrency_config_update",
      "method": "PUT",
      "path": "/api/settings/concurrency",
      "auth": "system_internal",
      "input": {"max_concurrent_goals": "int(required, range:1-50)"},
      "output": {"config": "object"},
      "idempotent": true,
      "errors": [
        {"code": "INVALID_PARAM", "retryable": false, "description": "数值超出范围"}
      ]
    },
    {
      "operation_id": "c_budget_config_update",
      "method": "PUT",
      "path": "/api/settings/budget",
      "auth": "system_internal",
      "input": {"scope": "string(required)", "limit_type": "string(required)", "limit_value": "int(required, >0)"},
      "output": {"config": "object"},
      "idempotent": true,
      "errors": [
        {"code": "INVALID_PARAM", "retryable": false, "description": "数值超出范围"}
      ]
    },
    {
      "operation_id": "c_deploy_supervisor_stage",
      "method": "POST",
      "path": "internal://deploy-supervisor/stage",
      "auth": "system_internal",
      "input": {"git_commit_hash": "string(required)"},
      "output": {"deployment_id": "string", "status": "staged"},
      "idempotent": false,
      "errors": [
        {"code": "CHECKOUT_FAILED", "retryable": false, "description": "全新目录 checkout 失败（如磁盘空间不足），转 blocked_pending_human"}
      ]
    },
    {
      "operation_id": "c_deploy_supervisor_health_check",
      "method": "POST",
      "path": "internal://deploy-supervisor/health-check",
      "auth": "system_internal",
      "input": {"deployment_id": "string(required)"},
      "output": {"status": "string", "signals": "deploy_health_signal[]"},
      "idempotent": true,
      "errors": [
        {"code": "HEALTH_CHECK_TIMEOUT", "retryable": false, "description": "process_alive/http_health/canary_task 任一超时，直接判定该项 fail，进入回滚路径 A，不重试"}
      ]
    },
    {
      "operation_id": "c_deploy_supervisor_cutover",
      "method": "POST",
      "path": "internal://deploy-supervisor/cutover",
      "auth": "system_internal",
      "input": {"deployment_id": "string(required)"},
      "output": {"status": "live", "cutover_at": "timestamp"},
      "idempotent": false,
      "errors": [
        {"code": "CUTOVER_FAILED", "retryable": false, "description": "候选进程未能正确绑定生产端口/生产库，转 blocked_pending_human"}
      ]
    },
    {
      "operation_id": "c_deploy_supervisor_monitor",
      "method": "POST",
      "path": "internal://deploy-supervisor/monitor",
      "auth": "system_internal",
      "input": {"deployment_id": "string(required)"},
      "output": {"status": "string", "latest_signal": "object"},
      "idempotent": true,
      "errors": []
    },
    {
      "operation_id": "c_deploy_supervisor_rollback",
      "method": "POST",
      "path": "internal://deploy-supervisor/rollback",
      "auth": "system_internal",
      "input": {"deployment_id": "string(required)", "rollback_reason": "string(required)"},
      "output": {"status": "string"},
      "idempotent": false,
      "errors": [
        {"code": "ROLLBACK_FAILED", "retryable": false, "description": "previous_instance_dir 也无法启动，或 git revert 冲突，转 blocked_pending_human，blocked_reason=rollback_failed；这是唯一保留的人工介入点，触发条件严格限定为自动恢复机制本身失效，不是代码判断谁对谁错"}
      ]
    }
  ],
  "process_contract": [
    {
      "flow_id": "p_org_task_lifecycle",
      "start_state": "queued",
      "end_state": "done",
      "transitions": [
        {"from": "queued", "to": "planning_brd_prd_sdd", "trigger": "c_org_node_trigger(planner)", "action": "c_work_graph_plan+c_work_graph_execute", "guard": "concurrency_ok", "error_state": "blocked_pending_human", "retry_max": 0},
        {"from": "planning_brd_prd_sdd", "to": "coding", "trigger": "planner_work_graph_done", "action": "c_org_node_trigger(coder)", "guard": "artifacts_validated", "error_state": "planning_failed", "retry_max": 2},
        {"from": "planning_failed", "to": "planning_brd_prd_sdd", "trigger": "retry", "action": "replan", "guard": "retry_count<2", "error_state": "blocked_pending_human"},
        {"from": "coding", "to": "validating", "trigger": "coder_work_graph_done", "action": "c_org_node_trigger(validator)", "guard": "self_test_passed", "error_state": "coding_failed", "retry_max": 2},
        {"from": "coding_failed", "to": "coding", "trigger": "retry", "action": "recode", "guard": "retry_count<2", "error_state": "blocked_pending_human"},
        {"from": "validating", "to": "done", "trigger": "validator_pass", "action": "close_task", "error_state": ""},
        {"from": "validating", "to": "routed_fast_lane", "trigger": "validator_fail", "action": "c_bug_record_create+c_org_loop_route(fast_lane)", "guard": "loop_round<3", "error_state": "blocked_pending_human"},
        {"from": "validating", "to": "routed_full_replan", "trigger": "validator_fail", "action": "c_bug_record_create+c_org_loop_route(full_replan)", "guard": "loop_round<3", "error_state": "blocked_pending_human"},
        {"from": "routed_fast_lane", "to": "coding", "trigger": "route_applied", "action": "loop_round+=1", "error_state": ""},
        {"from": "routed_full_replan", "to": "planning_brd_prd_sdd", "trigger": "route_applied", "action": "loop_round+=1", "error_state": ""},
        {"from": "blocked_pending_human", "to": "resumed_prior_state", "trigger": "c_org_loop_route(manual_resume)", "action": "manual_resume", "error_state": ""}
      ]
    },
    {
      "flow_id": "p_work_graph_execution",
      "start_state": "planning",
      "end_state": "done",
      "transitions": [
        {"from": "planning", "to": "running", "trigger": "plan_ready", "action": "c_work_graph_execute", "guard": "manifest_passes_antipattern_gate", "error_state": "failed"},
        {"from": "running", "to": "merging", "trigger": "fanout_nodes_settled", "action": "fanin_edge", "error_state": "failed"},
        {"from": "merging", "to": "verifying", "trigger": "fanin_done", "action": "node_verification", "error_state": "failed"},
        {"from": "verifying", "to": "done", "trigger": "verify_passed", "action": "c_artifact_write", "error_state": ""},
        {"from": "verifying", "to": "reflecting", "trigger": "verify_failed", "action": "record_gap", "guard": "retry_count<node_level_max", "error_state": "failed"},
        {"from": "reflecting", "to": "running", "trigger": "reflection_retry", "action": "rerun_min_subgraph", "error_state": ""},
        {"from": "running", "to": "blocked", "trigger": "all_parallel_branches_failed", "action": "bubble_up", "error_state": ""}
      ]
    },
    {
      "flow_id": "p_validator_root_cause_trace",
      "start_state": "test_failed_or_human_reported",
      "end_state": "bug_recorded",
      "transitions": [
        {"from": "human_reported", "to": "tracing_lineage", "trigger": "c_bug_report_create", "action": "validator_claims_open_bug_record", "error_state": "tracing_failed", "retry_max": 1},
        {"from": "test_failed", "to": "tracing_lineage", "trigger": "test_or_benchmark_failed", "action": "read_lineage", "error_state": "tracing_failed", "retry_max": 1},
        {"from": "tracing_lineage", "to": "judging_root_cause", "trigger": "lineage_ready", "action": "multi_perspective_verify", "guard": "2_of_3_perspectives_agree", "error_state": "inconclusive_escalate"},
        {"from": "judging_root_cause", "to": "bug_recorded", "trigger": "root_cause_decided", "action": "c_bug_record_create", "guard": "root_cause_detail_present", "error_state": ""},
        {"from": "judging_root_cause", "to": "inconclusive_escalate", "trigger": "perspectives_disagree", "action": "mark_blocked_pending_human", "error_state": ""},
        {"from": "bug_recorded", "to": "skill_iteration_triggered", "trigger": "root_cause_category==skill_defect", "action": "c_skill_update", "guard": "triggered_by_bug_id_present", "error_state": "skill_update_failed", "retry_max": 1}
      ]
    },
    {
      "flow_id": "p_budget_guardrail",
      "start_state": "monitoring",
      "end_state": "paused",
      "transitions": [
        {"from": "monitoring", "to": "monitoring", "trigger": "c_budget_check_before_node_run", "action": "accumulate_usage", "guard": "current_usage<limit_value", "error_state": ""},
        {"from": "monitoring", "to": "paused", "trigger": "budget_check_denied", "action": "mark_blocked_pending_human", "error_state": ""},
        {"from": "paused", "to": "monitoring", "trigger": "manual_resume_or_limit_raised", "action": "resume_scheduling", "error_state": ""}
      ]
    },
    {
      "flow_id": "p_usage_limit_wait",
      "start_state": "running",
      "end_state": "done",
      "transitions": [
        {"from": "running", "to": "waiting_for_quota", "trigger": "USAGE_LIMIT_REACHED", "action": "record_quota_wait_started_at_and_type", "guard": "", "error_state": ""},
        {"from": "waiting_for_quota", "to": "waiting_for_quota", "trigger": "backoff_interval_elapsed", "action": "retry_original_call_as_probe", "guard": "elapsed<timeout_threshold", "error_state": ""},
        {"from": "waiting_for_quota", "to": "running", "trigger": "probe_succeeded", "action": "resume_normal_execution", "guard": "", "error_state": ""},
        {"from": "waiting_for_quota", "to": "blocked_pending_human", "trigger": "timeout_threshold_exceeded", "action": "mark_blocked_pending_human", "guard": "", "error_state": "usage_limit_wait_timeout"}
      ]
    },
    {
      "flow_id": "p_log_retention_cleanup",
      "start_state": "idle",
      "end_state": "idle",
      "transitions": [
        {"from": "idle", "to": "scanning", "trigger": "scheduled_daily", "action": "scan_closed_log_files", "error_state": "scan_failed", "retry_max": 1},
        {"from": "scanning", "to": "purging", "trigger": "scan_complete", "action": "filter_by_retention_and_size_policy", "error_state": ""},
        {"from": "purging", "to": "idle", "trigger": "delete_success", "action": "mark_purged", "error_state": "purge_partial_failed"},
        {"from": "purge_partial_failed", "to": "idle", "trigger": "partial_failure_recorded", "action": "keep_closed_for_next_cycle", "error_state": ""}
      ]
    },
    {
      "flow_id": "p_deploy_supervisor_blue_green",
      "start_state": "staged",
      "end_state": "finalized",
      "transitions": [
        {"from": "staged", "to": "candidate_starting", "trigger": "c_deploy_supervisor_stage_done", "action": "checkout_new_dir_and_start_candidate", "error_state": "blocked_pending_human", "retry_max": 0},
        {"from": "candidate_starting", "to": "health_check_running", "trigger": "candidate_process_started", "action": "c_deploy_supervisor_health_check", "error_state": "", "retry_max": 0},
        {"from": "health_check_running", "to": "health_check_failed", "trigger": "any_signal_fail_or_timeout", "action": "rollback_path_a", "error_state": "", "retry_max": 0},
        {"from": "health_check_running", "to": "health_check_passed", "trigger": "all_signals_ok", "action": "proceed_to_cutover", "error_state": "", "retry_max": 0},
        {"from": "health_check_passed", "to": "cutover_in_progress", "trigger": "c_deploy_supervisor_cutover", "action": "stop_live_accept_no_new_triggers", "error_state": "blocked_pending_human", "retry_max": 0},
        {"from": "cutover_in_progress", "to": "live", "trigger": "candidate_bound_to_prod_port_and_db", "action": "mark_cutover_at", "error_state": "", "retry_max": 0},
        {"from": "live", "to": "monitoring", "trigger": "cutover_done", "action": "c_deploy_supervisor_monitor_start", "error_state": "", "retry_max": 0},
        {"from": "monitoring", "to": "anomaly_detected", "trigger": "signal_deviation_exceeds_threshold", "action": "record_rollback_reason_snapshot", "error_state": "", "retry_max": 0},
        {"from": "monitoring", "to": "monitoring_window_clean", "trigger": "monitoring_window_elapsed_without_anomaly", "action": "", "error_state": "", "retry_max": 0},
        {"from": "monitoring_window_clean", "to": "finalized", "trigger": "", "action": "allow_previous_instance_dir_cleanup", "error_state": "", "retry_max": 0},
        {"from": "anomaly_detected", "to": "rollback_in_progress", "trigger": "c_deploy_supervisor_rollback", "action": "rollback_path_b", "error_state": "", "retry_max": 0},
        {"from": "rollback_in_progress", "to": "rolled_back", "trigger": "previous_instance_dir_restarted_and_healthy", "action": "bind_live_port_and_prod_db_git_revert_bug_record", "error_state": "", "retry_max": 0},
        {"from": "rollback_in_progress", "to": "rollback_failed", "trigger": "previous_instance_also_unhealthy_or_git_revert_conflict", "action": "", "error_state": "blocked_pending_human", "retry_max": 0},
        {"from": "health_check_failed", "to": "rolled_back", "trigger": "rollback_path_a_complete", "action": "terminate_candidate_delete_db_copy_git_revert_bug_record", "error_state": "", "retry_max": 0}
      ]
    }
  ],
  "acceptance_matrix": [
    {
      "requirement_id": "REQ-01",
      "coverage": {"model": ["org_graph_definition", "task"], "view": ["v_task_board"], "controller": ["c_task_create", "c_org_node_trigger"], "process": ["p_org_task_lifecycle"]},
      "acceptance_cases": [
        {"type": "happy", "description": "创建贪吃蛇任务并依次触发三个 org_node", "expected": "task.status 按状态机正确流转"},
        {"type": "boundary", "description": "并发数=1 时创建第二个任务", "expected": "第二个任务落 queued 不被立即调度"},
        {"type": "failure", "description": "goal_text 为空", "expected": "返回 INVALID_PARAM"}
      ]
    },
    {
      "requirement_id": "REQ-02",
      "coverage": {"model": ["artifact", "work_graph_run"], "view": ["v_task_detail"], "controller": ["c_work_graph_plan", "c_work_graph_execute", "c_artifact_write"], "process": ["p_work_graph_execution"]},
      "acceptance_cases": [
        {"type": "happy", "description": "Planner 产出 BRD/PRD/SDD/Benchmark 四类 artifact 且血缘完整", "expected": "四条记录存在且 depends_on_artifact_ids 链完整"},
        {"type": "boundary", "description": "PRD 出现矛盾场景假设", "expected": "verifying 态拦截，转 reflecting"},
        {"type": "failure", "description": "SDD 引用不存在的 PRD 版本", "expected": "c_artifact_write 拒绝写入"}
      ]
    },
    {
      "requirement_id": "REQ-03",
      "coverage": {"model": ["work_node_execution"], "view": [], "controller": ["c_work_node_run"], "process": ["p_work_graph_execution"]},
      "acceptance_cases": [
        {"type": "happy", "description": "Coder 完成编码并通过 unit+integration test", "expected": "code_diff 与 test_report 产出且测试全部通过"},
        {"type": "boundary", "description": "两模块并行编码使用独立 git worktree", "expected": "合并后代码无冲突"},
        {"type": "failure", "description": "单测失败达重试上限", "expected": "work_node_execution.status=blocked"}
      ]
    },
    {
      "requirement_id": "REQ-04",
      "coverage": {"model": ["bug_record"], "view": [], "controller": ["c_bug_record_create"], "process": ["p_validator_root_cause_trace"]},
      "acceptance_cases": [
        {"type": "happy", "description": "植入 coder 类型 bug", "expected": "root_cause_category=coder 且 detail 引用具体位置"},
        {"type": "boundary", "description": "植入 planning 类型 bug", "expected": "root_cause_category=planning"},
        {"type": "failure", "description": "三视角判断不一致", "expected": "落在 inconclusive_escalate"}
      ]
    },
    {
      "requirement_id": "REQ-05",
      "coverage": {"model": ["task"], "view": ["v_task_detail"], "controller": ["c_org_loop_route"], "process": ["p_org_task_lifecycle"]},
      "acceptance_cases": [
        {"type": "happy", "description": "fast_lane 路由修复后重新验证通过", "expected": "task.status=done，loop_round=1"},
        {"type": "boundary", "description": "full_replan 路由", "expected": "回到 Planner 而非 Coder"},
        {"type": "failure", "description": "连续 3 轮未收敛", "expected": "转 blocked_pending_human，调度器继续跑其他任务"}
      ]
    },
    {
      "requirement_id": "REQ-06",
      "coverage": {"model": ["work_graph_run", "work_node_execution"], "view": [], "controller": [], "process": ["p_work_graph_execution"]},
      "acceptance_cases": [
        {"type": "happy", "description": "running 中人为中断进程后重启", "expected": "从持久化状态恢复，不重跑已完成节点"},
        {"type": "boundary", "description": "中断发生在 retrying 中途", "expected": "恢复到重试逻辑而非跳过"},
        {"type": "failure", "description": "持久化数据损坏", "expected": "明确报错并转 blocked_pending_human"}
      ]
    },
    {
      "requirement_id": "REQ-07",
      "coverage": {"model": [], "view": [], "controller": ["c_work_graph_execute"], "process": []},
      "acceptance_cases": [
        {"type": "happy", "description": "Claude Code ACP 后端跑通 REQ-01~06", "expected": "全部通过"},
        {"type": "boundary", "description": "claude -p 调用不加 --bare（A-1 spike 结论）", "expected": "冷启动开销在可接受范围内"},
        {"type": "failure", "description": "auto mode 分类器连续拦截 3 次或累计 20 次", "expected": "返回 CLASSIFIER_BLOCKED，task 转 blocked_pending_human，blocked_reason=classifier_blocked"}
      ]
    },
    {
      "requirement_id": "REQ-08",
      "coverage": {"model": ["skill", "skill_iteration"], "view": ["v_skill_audit_log"], "controller": ["c_skill_update", "c_skill_rollback"], "process": ["p_validator_root_cause_trace"]},
      "acceptance_cases": [
        {"type": "happy", "description": "skill_defect 类 bug 触发 skill 自主迭代", "expected": "生成独立 git commit，审计日志可查"},
        {"type": "boundary", "description": "triggered_by_bug_id 缺失", "expected": "c_skill_update 拒绝"},
        {"type": "failure", "description": "回滚到不存在的 iteration_id", "expected": "返回 ITERATION_NOT_FOUND"}
      ]
    },
    {
      "requirement_id": "REQ-09",
      "coverage": {"model": ["task"], "view": ["v_task_detail"], "controller": ["c_org_loop_route"], "process": ["p_org_task_lifecycle"]},
      "acceptance_cases": [
        {"type": "happy", "description": "人工 manual_resume 恢复任务", "expected": "恢复到触发前状态继续执行"},
        {"type": "boundary", "description": "一个任务 blocked 时其余 queued 任务", "expected": "调度器不被阻塞任务卡住"},
        {"type": "failure", "description": "对已 done 任务调用 manual_resume", "expected": "返回明确错误"}
      ]
    },
    {
      "requirement_id": "REQ-10",
      "coverage": {"model": ["budget_guardrail_config"], "view": ["v_budget_settings"], "controller": ["c_budget_check", "c_budget_config_update"], "process": ["p_budget_guardrail"]},
      "acceptance_cases": [
        {"type": "happy", "description": "超出配置额度", "expected": "任务自动转 blocked_pending_human，blocked_reason=budget_exceeded"},
        {"type": "boundary", "description": "调高额度后", "expected": "paused 态任务恢复调度"},
        {"type": "failure", "description": "平台层额度耗尽（非业务配置触发）", "expected": "blocked_reason=platform_quota_exhausted，UI 区分展示"}
      ]
    },
    {
      "requirement_id": "REQ-11",
      "coverage": {"model": ["project", "bug_record"], "view": ["v_project_setup", "v_goal_composer", "v_bug_feedback"], "controller": ["c_project_create", "c_task_create", "c_bug_report_create"], "process": ["p_validator_root_cause_trace"]},
      "acceptance_cases": [
        {"type": "happy", "description": "选择已有 Git 仓库文件夹创建项目并提出目标", "expected": ".graphlemon/ 子目录创建成功，task 成功进入 Org Graph"},
        {"type": "boundary", "description": "选择非 Git 仓库文件夹", "expected": "用户确认后 git init，不确认则中止且无任何写入"},
        {"type": "failure", "description": "重复创建同一 target_folder_path 的项目 / 提交空 description 的 bug 反馈", "expected": "前者幂等返回已有项目，后者被拦截"}
      ]
    },
    {
      "requirement_id": "REQ-12",
      "coverage": {"model": ["execution_event"], "view": ["v_dashboard", "v_graph_visualizer", "v_task_detail"], "controller": ["c_ws_subscribe"], "process": []},
      "acceptance_cases": [
        {"type": "happy", "description": "节点状态变化后图可视化实时着色更新", "expected": "≤2秒内更新，无需手动刷新"},
        {"type": "boundary", "description": "WebSocket 断线重连", "expected": "展示重连提示，重连后拉取当前快照兜底"},
        {"type": "failure", "description": "订阅不存在的 project_id", "expected": "连接被拒绝，返回 PROJECT_NOT_FOUND"}
      ]
    },
    {
      "requirement_id": "REQ-13",
      "coverage": {"model": ["execution_log_file", "log_retention_config"], "view": ["v_log_viewer", "v_log_retention_settings"], "controller": ["c_execution_log_get", "c_ws_log_tail", "c_log_retention_config_update"], "process": ["p_log_retention_cleanup"]},
      "acceptance_cases": [
        {"type": "happy", "description": "运行中节点实时滚动日志，结束后切换静态查看", "expected": "日志内容与实际执行过程一致，无缺失"},
        {"type": "boundary", "description": "retention_days=1 时清理超过1天的closed日志", "expected": "状态转purged，物理文件删除，UI展示已清理提示"},
        {"type": "failure", "description": "订阅不存在的 node_exec_id 日志流 / 清理时文件删除失败", "expected": "前者返回 NODE_EXEC_NOT_FOUND，后者仅记录失败不影响其余清理项"}
      ]
    },
    {
      "requirement_id": "REQ-14",
      "coverage": {"model": ["work_node_execution"], "view": ["v_dashboard", "v_graph_visualizer"], "controller": ["c_work_node_run", "c_org_node_trigger"], "process": ["p_usage_limit_wait"]},
      "acceptance_cases": [
        {"type": "happy", "description": "claude -p 返回 session limit 错误", "expected": "work_node_execution.status 转 waiting_for_quota，退避轮询后探测成功恢复正常执行，全程不产生 blocked_pending_human"},
        {"type": "boundary", "description": "quota_limit_type=opus", "expected": "不走退避轮询，直接降级到非 Opus 模型重试"},
        {"type": "failure", "description": "等待超过超时阈值（session 8小时/weekly 9天）仍未恢复", "expected": "转 blocked_pending_human，blocked_reason=usage_limit_wait_timeout"}
      ]
    },
    {
      "requirement_id": "REQ-15",
      "coverage": {"model": ["deployment", "deploy_health_signal", "bug_record"], "view": ["v_deployment_status"], "controller": ["c_deploy_supervisor_stage", "c_deploy_supervisor_health_check", "c_deploy_supervisor_cutover", "c_deploy_supervisor_monitor", "c_deploy_supervisor_rollback", "c_org_loop_route"], "process": ["p_deploy_supervisor_blue_green"]},
      "acceptance_cases": [
        {"type": "happy", "description": "graphlemon 自身真实植入 bug 修复后，root_cause_category=core_engine 触发蓝绿部署，健康检查全过，监控窗口无异常", "expected": "staged 到 finalized 全流程走完，全程无需人工评审代码内容"},
        {"type": "boundary", "description": "候选实例 canary_task 健康检查失败", "expected": "立即判定 health_check_failed，不重试，走回滚路径 A，Live 全程未受影响"},
        {"type": "boundary", "description": "cutover 完成后 validator_approval_rate 偏离历史基线阈值", "expected": "判定 anomaly_detected，走回滚路径 B，previous_instance_dir 重新成为 Live，生产库数据未丢失"},
        {"type": "failure", "description": "回滚路径 B 中 previous_instance_dir 也无法启动", "expected": "转 blocked_pending_human，blocked_reason=rollback_failed，且控制台展示的原因需清楚区分自动恢复机制失效与代码内容问题"}
      ]
    }
  ],
  "non_goals": [
    "不做飞书 Base 历史数据自动迁移",
    "不做多租户/多团队权限体系",
    "不考虑 Hermes CLI 执行后端（决策，2026-07-29：MVP 阶段只用 Claude Code ACP 一种后端）",
    "不做 Skill 自主迭代的人工审批 UI（立即生效，仅需 Git 可追溯）",
    "不做完整多项目管理 UI（项目列表/切换），数据模型预留 project 但 MVP 只支持单个 active 项目",
    "不做日志清理周期的用户可配置（仅保留天数/总量上限可配，清理任务本身触发频率由平台固定，不开放给用户调整）"
  ],
  "assumptions": [
    {"id": "A-1", "statement": "Claude Code 的 agent()/parallel()/pipeline() 原语可通过 claude -p 非交互式调用并返回结构化可解析结果", "owner": "bboonnee", "verification_plan": "spike 实测（spikes/a1-dynamic-workflows/），真实账号运行验证", "status": "confirmed", "verified_at": "2026-07-29", "verification_note": "claude -p ... < /dev/null 无交互提示、40s 完成、structured_output 精确匹配预期（sum=29）、permission_denials 为空；限制：不能加 --bare（会跳过登录态发现），须用完整冷启动调用，见 03-C 3.5 节实现契约"},
    {"id": "A-2", "statement": "本地 Hermes profile 的 SOUL.md/AGENTS.md 可原样迁移到目标项目 .claude/agents/*.md 不需大改", "owner": "bboonnee", "verification_plan": "实际迁移一次并跑通 MVP 场景验证", "status": "pending"},
    {"id": "A-3", "statement": "Hermes CLI 后端 MVP 阶段以单点执行 Org Agent 方式接入即可满足验收", "owner": "bboonnee", "verification_plan": "不适用", "status": "not_applicable", "resolution_note": "决策，2026-07-29：MVP 阶段不考虑 Hermes CLI 执行后端，只用 Claude Code ACP，见架构文档 7.2 节"},
    {"id": "A-4", "statement": "控制台为本地 Web 应用，文件夹选择由本地后端代拉系统原生对话框（c_pick_folder）实现", "owner": "bboonnee", "verification_plan": "已确认为产品决策（架构文档13.1决策5），转为实施约束，需在实施时按 macOS/Windows/Linux 分别验证 c_pick_folder 的原生对话框调用方式", "status": "confirmed"}
  ],
  "risks": [
    {"id": "R-1", "description": "A-1 假设不成立，Claude Code 动态工作流无法编程式调用", "impact": "high", "mitigation": "回退到架构文档 10.1 节方案 B（完全自研 Work Graph 执行层），需重新评估工作量和排期", "status": "resolved", "resolution_note": "A-1 已于 2026-07-29 spike 实测确认成立，方案 A 按 03-C 3.5 节实现契约推进；方案 B 作为长期备选保留，未触发"},
    {"id": "R-2", "description": "双后端能力不对等导致后续开发中被误判为对等而产生缺陷", "impact": "medium", "mitigation": "架构文档 7.2 节 2026-07-29 决策：MVP 阶段不考虑 Hermes CLI 后端，只用 Claude Code ACP 一种后端，风险不再适用", "status": "not_applicable"},
    {"id": "R-3", "description": "Skill 自主迭代立即生效可能引入回归缺陷", "impact": "medium", "mitigation": "强制 Git 提交 + c_skill_rollback 一键回滚能力兜底", "status": "mitigated"},
    {"id": "R-4", "description": "WebSocket 长连接在弱网/断线场景下的一致性问题（推送丢失）", "impact": "medium", "mitigation": "MVP 用重连后拉取快照兜底，不做完整消息重放缓冲，见 03-C 3.14 节", "status": "mitigated"},
    {"id": "R-5", "description": "原始日志本地落盘在高频/长时间运行下可能造成磁盘占用持续增长", "impact": "medium", "mitigation": "log_retention_config 提供按天数和总大小双重上限的定时清理（p_log_retention_cleanup），MVP 默认 14 天", "status": "mitigated"},
    {"id": "R-6", "description": "auto mode 分类器误拦截合法操作，导致任务频繁转 blocked_pending_human，影响无人值守吞吐", "impact": "medium", "mitigation": "MVP 阶段接受较高误拦截率，靠人工在 v_task_detail 复核放行；03-C 3.5/04-P 已定义 CLASSIFIER_BLOCKED 到 blocked_pending_human 的路由；后续可评估是否引入 auto mode 的受信任基础设施配置（05 节 5.3.1 待办项）降低误拦截率", "status": "accepted"},
    {"id": "R-7", "description": "Claude Code plan 额度等待重试的超时阈值（session 8小时/weekly 9天）是基于当前官方文档窗口周期（5小时滚动/7天）估算的硬编码值，若额度窗口周期变化会导致阈值不再合理（过早误报或过晚才升级人工）", "impact": "low", "mitigation": "05 节 5.4.2 已注明需要跟踪官方文档变化同步调整；MVP 阶段接受这个假设固定的风险", "status": "accepted"},
    {"id": "R-8", "description": "PH5 Deploy Supervisor 的 MVP 固定参数（05 节 §5.9：健康检查超时、监控窗口时长、validator_approval_rate 偏离阈值等）是工程经验草案，没有类似 R-7 额度窗口那样的外部权威依据，实现前无法验证是否合理", "impact": "medium", "mitigation": "05 节 §5.9 已标注为需要在真实跑通几轮自我修改后实测校准，不建议实现时直接当成不可变常量写入测试断言；PH5 U-042 端到端验收本身就是校准这些参数的第一个真实数据点", "status": "accepted"},
    {"id": "R-9", "description": "PH5 Deploy Supervisor 的实现代码（c_deploy_supervisor_* 五个控制操作、p_deploy_supervisor_blue_green 状态机本体）尚未编写，仅 supervisor/isolation/ 四个隔离/manifest/apply 模块（从 graphloop 复制改造）已落地且经过一次手工冒烟测试，未有正式 unittest 覆盖", "impact": "medium", "mitigation": "development-plan.md PH5-S2 的 U-036 明确把补齐单元测试列为独立 Unit；PH5 依赖 PH4 全部收口才启动，不影响 PH0-PH4 主线进度", "status": "accepted"}
  ]
}