Add revisioned decisions and scoped consultation lifecycle

references/decision-sessions.md

@@ -0,0 +1,18 @@
+# 独立决策会话接入
+
+本流程由主控执行。仅对真实待决策事项建立卡片与宿主会话；隔离 API 测试不证明真实会话、模型往返或归档已通过。
+
+1. 在正式看板创建有依据的决策，关联唯一任务，写明简介、完整背景、全部选项和影响。保存创建回执。没有真实事项时不要为验收制造生产决策。
+2. 先为本决策规划本机私有有限配置路径。读取宿主项目/会话清单，确认没有既有绑定，再用宿主正式创建工具建立独立真实会话。使用 `assets/decision-consultation-prompt.txt` 生成角色说明，替换真实决策 ID 与计划配置路径；不指定未获人类选择的模型。配置尚未准备时，初始化只等待接入，不读取普通控制凭据或生成演示回复。保存宿主返回的真实 thread ID、执行主机和工作目录。
+3. 注册 `role=decision`、`wp=<decision_id>` 的看板 session；核对宿主真实会话身份后调用 `bind-session`。一个决策只绑定一个真实会话，不复用入口或执行会话。保存绑定回执；数据库中的占位 ID 不是宿主创建证据。
+4. 仅绑定后，使用普通控制连接调用该决策的 `consultation-credential`，把返回 token 直接写入本机私有文件，不打印、不传给聊天、不存源码。写一个私有配置，形如 `{"decision_id":"<真实ID>","control":{"url":"http://<已授权看板域名>:8796","token_file":"<本机私有token路径>"}}`。该配置只给对应咨询会话；普通控制连接和模型认证留在执行器，不分发给会话。签发响应未知时先核查既有私有回执和文件，不反复轮换已交付凭据。
+5. 本机桥接私有配置可启用 `decision_fleet: {"enabled":true,"runtime_root":"<私有目录>","max_active":3}`。fleet 从正式 bindings 接口读取已绑定会话，在其实际目录运行原有 worker/mirror。它不创建模型会话、不归档、不切模型，超过上限保留等待。每个会话有独立租期、幂等回执与未知结果保护；不能重复启动第二套执行器或抢 writer 锁。
+6. 验证决策详情内的一条真实咨询进入该 thread，并核对同一 thread 的真实回复回到本决策。再验证事实核实请求、主控保存答复及绑定会话收到答复；不把投递 ACK 当实际处理。咨询内容通过既有历史投影展示，内部工具和原始通知不混进聊天。
+7. 用户提交只进入待检查。主控读取提交时的不可变快照，核实适用范围与风险，再记录接受或重议、效果与执行规划；主控检查结论由唯一人类入口简短解释并链接卡片。权限相关动作另核实真实人类授权，不能仅靠网页来源、咨询建议或 accepted 状态执行。
+8. 完成后先保存检查结论、实际完成证据和交接。核对咨询输入没有 queued/claimed/uncertain，且私有 worker 不存在 inflight、pending_completion 或 needs_reconciliation。然后用宿主受支持归档工具归档真实 thread，成功后才保存 archive-receipt。仅写归档字段不是宿主归档；归档失败保留待归档，不抹去记录或删除会话。
+
+完成并归档后，卡片、版本、提交快照、检查结论和聊天只读保留。fleet 只停止自身桥接进程，不杀模型 writer；有未知执行状态时保留证据等待对账，不能盲重放。
+
+有限 API 凭据约束的是服务端接口，不是宿主操作系统沙箱。咨询会话的代码/系统边界同时依赖其角色约束及宿主权限；不要声称已提供未实际配置的硬隔离。
+
+决策通知外发前先调用 `/api/decision-notifications/submitting` 持久标记，再保存本机 submitting 状态并调用宿主队列。标记调用失败可幂等重试，但不发送模型输入；真实队列发送未知时先对账、不盲重发。服务端只取消未开始/未确认的过时通知，已开始或未知发送保留审计。

references/design-system.md

@@ -43,7 +43,7 @@
 
 需要用户决定的事项使用卡片展板，不做长日志列表。卡片只展示问题、影响、优先级及状态，点击打开详情抽屉。详情包括背景、问题、推荐与依据、方案说明和真实有依据的期限。可枚举方案使用可点击单选项，默认不选，推荐不视为批准。备注可补充；显式“提交选择”按钮与选择动作分开，失败保留草稿，同一草稿重试复用幂等键。
 
-提交后显示实际选择与结果，权限相关显示“待核实”，不显示“已授权”。采用#/decisions?decision=<id>打开具体卡片；沟通只做一句提醒并链接卡片，不复制全部方案。空状态不加入合成演示决策。既有tasks.decision文本保留只读兼容，不伪造选项。
+提交后显示实际选择快照及“待主控检查”，接受后显示“待落实”，完成与归档分别展示，不显示“已授权”。采用#/decisions?decision=<id>打开具体卡片；沟通只做一句提醒并链接卡片，不复制全部方案。空状态不加入合成演示决策。既有tasks.decision文本保留只读兼容，不伪造选项。
 
 任务卡的“目前进度”只展示current_progress，不能替换旧标签后仍显示eta_basis。进度实际变化后自动刷新，保留业务更新时间；活跃任务过期显示待更新需核查，完成剩余为0。新增改进单独登记，不沿用旧完成记录遮盖正在进行的工作。
 
@@ -74,3 +74,9 @@
 悬停节点高亮递归上游、下游及对应边，无关节点与边淡化但文字仍可读；mouseleave恢复。键盘focus提供等效交互，触屏通过选中节点提供同效高亮和明确的详情按钮；退出选择恢复。高亮不改变事实、筛选开关或自动切换全部。详情仍保留任务定位链接、目标、负责人、依赖、验收与集成状态。
 
 复用固定token和既有组件，以纯SVG与HTML实现，不引入新依赖。遍历使用visited与迭代队列/栈防循环和长链调用栈溢出。真实浏览器验收默认/全部、hover/focus/触屏、详情及窄屏；纯逻辑测试覆盖长链、多依赖、无依赖、筛选和汇合验收门禁。
+
+## 决策详情与独立咨询
+
+卡片展示关联任务标签、状态与summary简介。宽详情展示背景、完整候选方案、自由填写、主控检查结论及版本历史；有候选方案仍允许只填写意见，推荐不预选，显式提交。提交携当前revision，失败保留草稿和幂等键；版本冲突刷新并要求重新确认，不能偷偷提交到新版本。需要重新考虑时保留旧快照供对照。
+
+详情内独立咨询按decision_id隔离轮询、消息、草稿及client_key，发送显示pending并防重；未绑定显示待接通，不模拟回复。完成归档后只读历史。组件不修改普通沟通页，用户选择仍在卡片；事实核实回复、接受结论与实际授权分别呈现。键盘/窄屏可访问，不新增依赖。隔离验收覆盖切换决策不串消息、失败草稿、版本冲突、只填意见、历史及只读状态；真实会话未接通不显示已验证。

references/operations.md

@@ -81,7 +81,7 @@ source+event_id+status持久幂等，相同故障重复不打扰；恢复必须
 
 GET /api/state的decisions保存卡片与响应。POST /api/decisions登记固定id/title/question及impact/priority/details/recommendation/options/deadline/requires_authorization/task_id；同ID相同规范正文幂等，不同内容冲突。options是{id,label,description}数组，不指定真实thread或任意命令。
 
-POST /api/decisions/<id>/respond提交{option_id,comment,idempotency_key}。有选项须选择合法项，无选项至少写意见；第一次提交原子保存，同key同正文返回原响应，冲突重用或其他提交拒绝。普通状态为decided，权限相关为pending_verification；响应含authorization:false，不能作为提权批准。GET /api/decision-notifications提供最早100条待投递，POST /api/decision-notifications/ack以notification_id幂等确认。
+POST /api/decisions/<id>/respond提交{expected_revision,option_id|null,comment,idempotency_key}，允许选择合法方案或仅填写非空意见，至少一项。仅open/needs_reconsideration接受提交，保存内容及选项快照，状态统一pending_review；同key/body/revision幂等，不同返回409。旧decided/pending_verification且有response映射pending_review，不能伪造已接受。响应不授予运维权限。通知及ACK路径继续兼容，新增事件规则见下文。
 
 桥接私有配置decision_notifications:true启用notifier投递到notification_targets.control。保存回执与完整输入哈希，未知投递先对账，不盲重发；投递确认不代表方案执行。通知只携带问题、实际选项与意见，背景仍由总控通过API读取，避免塞满会话。沟通展示使用/api/conversation；后台继续用原始/api/messages做恢复与审计。
 
@@ -146,3 +146,25 @@ created_at由服务端在新建任务时记录，拒绝客户端输入及更新/
 本轮验收包括旧数据默认、创建和更新非法归属、被引用交付降级、报告字段保护；前端纯逻辑覆盖长链、多依赖、无依赖、筛选与汇合门禁。执行负责人以既有持久报告流程上报真实证据，收到落库回执后等待集成；集成负责人另做真实浏览器验证和发布，不能以执行完成代替正式验收。
 
 执行会话可按人类已授权的项目协作范围，使用宿主支持的定向消息就共享接口与交接点相互协调；无需每次抄送副主控。唯一事项负责人把关键决定、版本、影响与交接回执落库；范围或归属冲突才交直属副主控。普通进度只更新状态，不制造互相唤醒链。副主控的判断可由推理模型结合明确规则承担，具体模型、费用与执行权限分别核实；用户仅询问模型能力不构成切换型号或购买服务的授权。
+
+## 决策生命周期接口契约
+
+状态为open/pending_review/accepted/completed/needs_reconsideration。对象增加summary、task_id、revision正整数、session_id/session_thread_id可空、archive_status（none/pending/archived）、review/completion可空、supersedes_id及related_decision_ids。GET /api/decisions/<id>读取当前对象，GET /history返回{history:[版本、提交、检查、完成、绑定、归档事件]}，所有版本与提交快照保留。创建支持简介、关联任务及替代来源并持久生成session_required；仅创建真实需求。
+
+PATCH当前对象携expected_revision、reason及允许内容字段，乐观锁成功增版本，禁止覆盖response/submissions/review/binding。影响已提交问题或方案的实质改动保留旧选择并转needs_reconsideration，必须重新确认新版本。POST /review携expected_revision/idempotency_key/outcome（accept或reconsider）/reason/impact/execution_plan，可附authorization_evidence；仅检查当前revision真实pending_review提交，转accepted或needs_reconsideration。授权证据只是记录，须主控核对真实人类消息，不能自动执行。
+
+POST /complete携expected_revision/idempotency_key/conclusion/handoff/evidence可选列表，仅有review的accepted/needs_reconsideration可完成并置archive_status=pending。POST /archive-receipt携thread_id/idempotency_key/receipt，仅completed且review/completion/handoff齐备；先由根调用宿主真实归档，再登记回执。
+
+POST /bind-session携expected_revision/idempotency_key/session_id/thread_id，仅普通控制凭据。会话须已注册role=decision、wp=decision.id，真实thread UUID不复用其他决策、主会话或执行者；仅首次或严格重复绑定，禁止静默换绑。真实存在另由宿主工具验证。GET /consultation返回{messages:[既有conversation projection]}，POST携text/client_key仅发送绑定session，不接受替代sid；完成归档后只读。GET /api/decision-bridge-bindings仅控制凭据，返回bindings内decision_id/session_id/thread_id/worktree/status/archive_status；fleet只接已有真实thread，不创建模型会话。
+
+POST /consultation-credential由普通凭据签发专用token，数据库只存hash；该token仅允许本决策GET当前/history/consultation、PATCH内容和POST /facts，其余403，completed后禁写仍可读历史。不得向咨询agent分发普通panel token。POST /facts携idempotency_key/question/context可选，持久去重核实请求；POST /facts/<request_id>/answer由普通凭据提交idempotency_key/answer/evidence可选，写历史并通知绑定咨询thread，回复不是用户批准。
+
+通知保留原GET /api/decision-notifications及ACK；工作流事件用独立持久表避免旧decision_id唯一约束。返回notification_id/target（control、human、decision）/通知创建时不可变decision与event快照（含kind、revision及相关字段），event_key幂等。GET不得重写为最新对象，避免破坏持久输入哈希；已提交/未知发送标记和历史保留。只有fact_answered可target=decision，绑定thread由真实session_thread_id确定。session_required、submitted、fact_requested、archive_required送control；reviewed送human仅简述影响与计划；fact_answered送decision，由notifier按已核实绑定定位。绑定后未发session_required、已答facts、已归档请求不再出队；已实际入宿主队列的旧输入按版本核对，不伪称撤回。普通决策事件不能一律路由control覆盖上述目标。
+
+已有唯一人类入口时，所有主控、副主控、执行者的问题/选择/授权/关键结论定向交入口，不能直接使用用户提问工具绕过；入口理解后直接交主控，不经下层事件队列。独立咨询只限该决策内嵌页面，不成为一般项目沟通入口。真实会话创建、绑定核实和归档由根按既定授权执行。
+
+验收覆盖两种检查分支、版本并发、不可改提交快照、选项变化重确认、关联新决策、有限凭据与任务/会话隔离、归档前置及幂等；真实咨询绑定与往返单独验收。暂无真实事项时仅做隔离测试，保留未验证限制，不造生产事项。
+
+完成与归档前须检查绑定咨询session消息：有queued/claimed/uncertain未完成输入时返回409，保持可交流；completed立即拒绝新咨询POST，历史GET保留。fleet仅在archive_status=archived且本机worker无inflight/pending_completion/needs_reconciliation时停止自有子进程，不终止模型writer。已入队旧通知接收者fresh GET核对revision，过期静默停止，不能由快照直接执行。有限CLI及fleet负责已有绑定的桥接，不自行创建或归档宿主会话。
+
+真实决策独立会话的创建、绑定后签发有限凭据、桥接、事实核实和完成归档步骤见 [独立决策会话接入](decision-sessions.md)。notifier调用决策通知submitting接口后才向宿主队列外发，保留不可变快照与未知结果保护；不能仅清应用队列冒充取消宿主输入。