work-ally 0.2.0-alpha.1

package/docs/completed/SPEC-engineering-sop-skillization.md

@@ -0,0 +1,190 @@
+# Engineering SOP Skillization
+
+更新时间：2026-03-21  
+状态：Implemented  
+Owner：Ally  
+相关文档：
+- `skills/issue-to-spec-triage/`
+- `skills/post-implementation-closure/`
+- `skills/feishu-production-debug/`
+- `skills/product-spec/`
+- `docs/developer-workflow.md`
+- `AGENTS.md`
+
+## 1. Summary
+
+这次已经把“工程 SOP Skill 化”的第一轮正式落地了。
+
+交付结果不是新的用户功能，而是给项目维护者补上 3 个内部工程 Skill，让一些高频、重复、容易靠聊天记录口耳相传的工程 workflow 变成明确、可复用、可按需触发的能力包：
+
+1. `issue-to-spec-triage`
+2. `post-implementation-closure`
+3. `feishu-production-debug`
+
+这轮落地同时也把一条边界写死了：
+
+> 基础纪律继续留在规则层；只有阶段性、按需触发、可复用的 workflow，才做成 Skill。
+
+## 2. 背景
+
+项目已经明确进入 `skill-first` 长期方向，但之前更偏“产品 capability 往哪里长”的判断，还缺一层“工程协作本身哪些东西值得 Skill 化”的收口。
+
+实际协作里反复出现的问题非常明确：
+
+- 需求、想法、问题进入项目时，经常需要先分诊，再决定要不要立 spec。
+- 一个实现做完后，经常需要把 `review -> 回归 -> 文档同步 -> 状态回写 -> commit readiness` 这整段闭环重新组织一遍。
+- 遇到真人 Feishu 链路异常时，容易先拍脑袋怀疑 bridge，而不是先按平台权限、事件投递、路由、回投的顺序排查。
+
+这些都不是 bridge core 的运行合同，但又明显不是一次性对话技巧，因此适合收成 Skill。
+
+## 3. 问题定义
+
+如果不把这类工程 SOP 收成稳定能力包，会持续出现这些问题：
+
+1. 基础纪律和阶段性 workflow 混在一起，规则层越来越重。
+2. 高频 SOP 只留在聊天记录里，每次低上下文场景都要重新讲。
+3. 本该始终生效的纪律可能被误塞进 Skill，导致触发不稳定。
+4. 没有明确 shortlist，后续容易无节制地长出低价值 Skill。
+
+## 4. 这次实际交付了什么
+
+### 4.1 新增 3 个工程 Skill
+
+#### A. `skills/issue-to-spec-triage/`
+
+用于在想法、抱怨、bug、需求和边界质疑进入项目时，先判断它到底是：
+
+- `small-bugfix`
+- `boundary-fix`
+- `spec-needed`
+- `hold`
+
+它解决的是“先分诊，再决定是否进入 spec 流”的问题。
+
+#### B. `skills/post-implementation-closure/`
+
+用于在实现基本完成后，推动工程闭环，而不是半成品汇报。
+
+它把这几件事收成一个固定 workflow：
+
+- self-review
+- 回归 / clean-env 验证
+- 文档漂移检查
+- dashboard / spec 状态回写
+- commit readiness 判断
+
+#### C. `skills/feishu-production-debug/`
+
+用于排查真实 Feishu 生产链路问题。
+
+它明确要求按顺序排查：
+
+- 先确认症状
+- 再看消息有没有进入 bridge
+- 再看平台权限和事件投递
+- 再看路由
+- 最后看回复回投
+
+### 4.2 每个 Skill 都采用 instruction-first 设计
+
+这轮没有为新 Skill 引入脚本执行层，也没有做额外 marketplace 或安装系统。
+
+当前统一采用：
+
+- `SKILL.md`
+- `references/`
+
+也就是说，先把工作流说明和参考材料收清楚，等后续真的出现高重复、强确定性的步骤，再决定是否需要 `scripts/`。
+
+### 4.3 项目规则已同步这条边界
+
+项目级规则已明确写出：
+
+- 基础纪律、长期产品边界、表达与协作铁律继续留在规则层
+- Skill 只承接阶段性、按需触发、可复用的 workflow
+
+## 5. 机制设计
+
+### 5.1 双层模型继续固定
+
+#### A. 规则层
+
+继续承接必须始终生效的内容，例如：
+
+- `faithful bridge / KISS`
+- `apply_patch` 编辑纪律
+- 文件规模约束
+- spec 纪律
+- 先闭环再汇报
+
+这些内容继续留在：
+
+- `AGENTS.md`
+- `SOUL.md`
+- `MISTAKES.md`
+- `MEMORY.md`
+
+#### B. Skill 层
+
+只承接：
+
+- 阶段性 workflow
+- 需要按任务相关性触发的 SOP
+- 可复用但不需要永远常驻的过程能力
+
+### 5.2 与现有 Skill 的关系
+
+- `product-spec` 仍负责写 spec / refine spec / review spec。
+- `issue-to-spec-triage` 负责更前一层：先决定要不要进入 spec 流。
+- `post-implementation-closure` 负责实现后闭环。
+- `feishu-production-debug` 负责真实 Feishu 产线链路排障。
+
+它们和已有 `archive-reader`、`memory-digest` 不重叠。
+
+## 6. 文档同步
+
+这次已同步更新：
+
+- `AGENTS.md`
+- `README.md`
+- `docs/developer-workflow.md`
+- `DASHBOARD.md`
+
+其中：
+
+- `README.md` 增加了工程维护 Skills 的入口说明
+- `docs/developer-workflow.md` 增加了推荐的工程 Skill 使用场景
+- `DASHBOARD.md` 把该专题从规划态收进已完成
+
+## 7. 验收标准
+
+### 7.1 能力包存在
+
+1. 仓库内已存在 3 个新的 Skill 目录。
+2. 每个 Skill 都有 `SKILL.md`。
+3. 每个 Skill 都有最小必要的 `references/`，而不是把细节全塞进 `SKILL.md`。
+
+### 7.2 边界清晰
+
+1. 规则层和 Skill 层的分工已写入项目规则。
+2. 新 Skill 没有篡改 bridge core 或用户主路径。
+3. 新 Skill 没有把“永远都要遵守”的纪律误搬进去。
+
+### 7.3 维护口径一致
+
+1. 工程维护入口文档已能看到这些 Skill。
+2. Dashboard 已把该专题记为完成，不再停留在规划态。
+3. assistant 长期记忆已同步这条稳定判断。
+
+## 8. 非目标与后续
+
+这次没有做的事情：
+
+1. 不做 Skill marketplace
+2. 不做第二套插件平台
+3. 不做脚本优先的复杂 Skill runtime
+4. 不把已有旧能力大规模外迁
+
+如果后续继续扩展，优先问题不是“还能做多少 Skill”，而是：
+
+> 这件事到底是不是阶段性 workflow，是否真的值得脱离规则层单独存在。

package/docs/completed/SPEC-faithful-bridge-core-thinning-v2.md

@@ -0,0 +1,376 @@
+# SPEC: 忠实中间层核心瘦身重构（低上下文版）
+
+更新时间：2026-03-20  
+状态：Completed  
+Owner：work-ally product / engineering  
+相关文档：
+- `README.md`
+- `AGENTS.md`
+- `docs/planning/SPEC-minimal-bridge-semantics-and-user-visible-surface.md`
+- `docs/planning/SPEC-bridge-app-server-protocol-alignment.md`
+
+## 0. 当前进度
+
+- Slice 1 已落地：普通自然语言主路径不再读取 `work-session ownership / attached session`。
+- Slice 2 / 3 已完成第一轮减法：`SessionMeta`、`TurnLedgerRecord` 与 `/status` surface 已移除一批不再服务 bridge core 的厚状态字段，例如 `lastTurnStatus`、`pendingUserInputPrompt`、`pendingUserInputQuestionIds`、`runtimeStatus`、`resultPersistedAt`。
+- Slice 4 已完成：旧厚状态与普通聊天主路径无关的判断已退出主链路，相关文档与测试已同步收口。
+- 当前验证已完成：`npm run test:bridge` 全绿（206/206）。
+
+## 1. Summary
+
+这次重构只做一件事：
+
+> 把 `work-ally` 的 bridge core 收回到“忠实桥接 Feishu <-> Codex App Server + 最小必要补偿”，删掉不该长期留在核心路径里的厚语义和外围依赖。
+
+这不是一次“继续拆文件”的整理，而是一次明确的减法重构。
+
+本次必须做到三件事：
+
+1. 普通聊天主路径不再依赖 `work-session / handoff / archive / supervisor` 才能成立。
+2. `turn / session / recovery` 只保留最小必要状态，不再维护一套本地任务脑。
+3. 每一刀都独立自测、回归、提交；用小步重构保稳定，不用长期保留旧路径来求稳。
+
+## 2. 背景
+
+当前 bridge 已经过一轮模块拆分，但核心问题还在：
+
+1. 文件拆开了，产品边界没有真正收回来。
+2. 普通聊天主路径旁边仍挂着一圈外围语义。
+3. `SessionStore`、`recovery`、`human-gate` 仍然偏厚。
+4. 某些文件已经明显过大，维护成本继续上升。
+
+代码现状已经说明：
+
+- `receiver.ts` 仍直接连着 `receiver-work-session.ts`、`receiver-recovery.ts`、`receiver-human-gate.ts`。
+- `server-runtime-app.ts` 仍把 bridge core、scheduler、archive、receiver、session store 黏在一起。
+- `session-store-turn-ledger.ts` 不只是记录 active turn，而是在承担一套更厚的 turn lifecycle。
+
+所以这次不是继续讲“以后要变薄”，而是直接规定：
+
+- 什么保留
+- 什么收薄
+- 什么退出主路径
+- 什么确认无用后删除
+
+## 3. 问题定义
+
+### 3.1 普通聊天主路径还不够“忠实桥接”
+
+当前普通消息路径仍容易被外围能力影响：
+
+- `work-session / handoff`
+- `archive / conversation view`
+- supervisor / hosting 语义
+
+这不符合产品边界。普通聊天应当只取决于：
+
+- Feishu 入站消息
+- 当前 conversation 对应的 thread
+- runtime 当前 turn 状态
+- 最小必要的人机 gate
+- 最终结果投递
+
+### 3.2 bridge 自己仍然维护了偏厚的本地语义
+
+当前 bridge 不只是在做桥接，还在维护额外语义：
+
+- 厚的 turn ledger
+- 厚的 recovery 分支
+- 厚的 waiting / gate 语义
+
+这会让中间层慢慢长成第二套任务系统。
+
+### 3.3 代码体量和模块边界仍然不健康
+
+这次重构也要顺手落实工程纪律：
+
+- 触碰到的超大文件应主动拆分。
+- 300 行左右就要反思是否继续拆。
+- 1700~2000 行级别文件不可接受。
+
+重点不是为了“漂亮”，而是为了让后续继续做减法时不被文件规模拖死。
+
+## 4. 目标
+
+本次重构的完成标准只有 5 条：
+
+1. bridge core 重新只围绕“协议转接 + 最小补偿”成立。
+2. 普通聊天主路径不再依赖外围层语义成立。
+3. turn / recovery / gate 状态明显减少。
+4. 新代码不再围绕旧厚状态继续长分支。
+5. 相关文档、测试、代码结构对齐同一套边界。
+
+## 5. 非目标
+
+这次明确不做：
+
+1. 不新造第二套任务状态系统。
+2. 不为了瘦身牺牲消息稳定性。
+3. 不顺手做新的运维平台、面板或调度器。
+4. 不保留“也许以后有用”的废路径。
+5. 不把所有外围能力一次性连根拔掉；本次只要求它们退出普通聊天主路径。
+
+## 6. 这次重构后的 bridge core 定义
+
+本次之后，bridge core 的产品定义固定为：
+
+> 接收 Feishu 消息，路由到对应 Codex thread / turn，把 Codex 的真实进度、审批请求、user input 请求与最终结果稳定送回 Feishu，并只承担最小必要补偿。
+
+bridge core 允许保留的最小补偿只有：
+
+1. inbound 去重
+2. active turn 最小跟踪
+3. visible approval / user-input gate
+4. final-state authoritative confirmation
+5. final reply delivery ledger
+6. bounded redelivery
+
+除此之外，不再往 bridge core 里继续长：
+
+1. 本地任务生命周期世界
+2. 丰富 recovery 状态树
+3. 多表面 ownership 语义
+4. archive 反向主导主路径判断
+
+## 7. 模块边界结论
+
+### 7.1 必须保留在 core 的模块
+
+这些是 bridge core 的一部分，保留：
+
+- `bridge/src/channels/feishu/*`
+- `bridge/src/runtime-client*`
+- `bridge/src/router.ts`
+- `bridge/src/runtime-user-input.ts`
+- `bridge/src/channel-delivery.ts`
+- `bridge/src/receiver-thread-start.ts`
+- `bridge/src/receiver-turn-steer.ts`
+- `bridge/src/receiver-turn-result.ts`
+- `bridge/src/receiver-delivery.ts`
+- `bridge/src/session-store-inbound-acceptance.ts`
+- `bridge/src/session-store-delivery.ts`
+
+### 7.2 必须收薄但仍留在 core 的模块
+
+这些能力仍需要，但语义必须变薄：
+
+- `bridge/src/session-store-turn-ledger.ts`
+- `bridge/src/session-store-human-gate.ts`
+- `bridge/src/receiver-recovery.ts`
+- `bridge/src/receiver-human-gate.ts`
+- `bridge/src/receiver-turn-coordination.ts`
+- `bridge/src/receiver-runtime-state.ts`
+
+要求：
+
+- 只保留 core 真正需要的状态
+- 不再继续长新的厚状态分支
+- 触碰时顺手拆掉过大的文件段落
+
+### 7.3 必须退出普通聊天主路径的外围模块
+
+这些能力可以继续存在，但不得再参与普通聊天默认路径：
+
+- `bridge/src/handoff-service.ts`
+- `bridge/src/work-session-store.ts`
+- `bridge/src/receiver-work-session.ts`
+- `bridge/src/receiver-control-work-session.ts`
+- `bridge/src/archive-store.ts`
+- `bridge/src/conversation-view-store.ts`
+- `bridge/src/scheduler.ts`
+- `bridge/src/server-routine-*`
+- `internal/modules/runtime/supervisor.sh`
+- `internal/modules/runtime/assistant-autosave.sh`
+
+规则：
+
+- 显式控制命令可继续进入这些模块。
+- 普通自然语言消息默认不经过这些判断。
+- 确认无调用、无产品价值后，直接删除，不保留“温和退出”状态。
+
+## 8. 机制设计
+
+### 8.1 普通消息主路径
+
+普通 Feishu 消息进入 bridge 后，只允许经过下面 5 个判断：
+
+1. 标准化 inbound，并完成去重。
+2. 基于 `conversationKey` 找到绑定的 `threadId`。
+3. 若当前存在 active turn，则走 `turn/steer`；否则按需 `thread/start` + `turn/start`。
+4. 若 runtime 发来 approval / user-input 请求，则只记录“当前可见 gate”。
+5. 当 runtime 或 authoritative pull 确认 final result 后，完成投递与必要补发。
+
+普通主路径禁止再读取：
+
+- work-session ownership
+- archive 事实
+- routine / scheduler 状态
+- supervisor 运行态
+
+### 8.2 human gate 语义
+
+human gate 只表达一件事：
+
+> 当前 conversation 上，是否存在一个已经对用户可见、且仍等待人类回复的 approval / user-input 请求。
+
+不再承担：
+
+- 更丰富的 waiting 分类
+- recovery 中间状态
+- 与 work-session 绑定的复杂协作语义
+
+### 8.3 recovery 语义
+
+recovery 只保留两类补偿：
+
+1. final-state reconcile
+2. final reply redelivery
+
+不再继续维护：
+
+- `pending_recovery`
+- `recovery_required`
+- `superseded`
+- 其他为了描述本地 turn 生命周期而存在的状态分支
+
+### 8.4 turn ledger 语义
+
+turn ledger 只保留：
+
+- 当前 active turn
+- final result 投递所需最小记录
+- 必要的 suppression / delivery 防重信息
+
+不再继续承担：
+
+- 丰富 execution lifecycle
+- 额外 waiting / interrupted / resumed 世界
+- 与外围产品层耦合的状态表达
+
+## 9. 实施切片
+
+这次必须按切片推进。每一刀都要做到：改完、自测、review、回归、提交，再进下一刀。
+
+### Slice 1：切断外围层对普通聊天主路径的影响
+
+目标：先让普通聊天独立成立。
+
+本刀要改：
+
+- `receiver.ts`
+- `receiver-work-session.ts`
+- `handoff-service.ts`
+- `server-runtime-app.ts`
+- 与 archive / supervisor 相关的主路径调用点
+
+完成标准：
+
+1. 普通自然语言消息不再依赖 work-session / handoff / archive / supervisor 判断。
+2. 显式控制命令仍可走对应控制路径。
+3. 普通聊天回归通过。
+
+### Slice 2：收薄 human gate 与 recovery
+
+目标：删掉不必要的 waiting / recovery 语义。
+
+本刀要改：
+
+- `receiver-human-gate.ts`
+- `session-store-human-gate.ts`
+- `receiver-recovery.ts`
+
+完成标准：
+
+1. gate 只保留 approval / user-input 的当前可见阻塞。
+2. recovery 只剩 final-state reconcile + redelivery。
+3. 旧厚 recovery 状态不再被新主路径读取。
+
+### Slice 3：收薄 turn ledger 与 session store
+
+目标：把 turn state 收回最小集合。
+
+本刀要改：
+
+- `session-store-turn-ledger.ts`
+- `session-store.ts`
+- `receiver-turn-coordination.ts`
+- `receiver-runtime-state.ts`
+
+完成标准：
+
+1. active turn / final delivery 之外的厚状态明显减少。
+2. 新主路径不再依赖旧 lifecycle 状态名。
+3. 触碰到的过大文件同步拆分。
+
+### Slice 4：删除确认无用的旧路径，并收口文档与测试
+
+目标：不要留下“已经不用，但还躺着”的债。
+
+本刀要改：
+
+- 删除已确认无入口、无回归价值的旧分支 / 旧状态 / 旧调用
+- 更新 `README.md`、`AGENTS.md`、相关 planning / completed 文档
+- 补齐或更新对应测试
+
+完成标准：
+
+1. 旧厚路径没有继续被保留成“备用分支”。
+2. 文档与代码口径一致。
+3. 测试门禁覆盖新的主路径边界。
+
+## 10. 测试与回归要求
+
+每个 slice 至少覆盖：
+
+1. 普通消息进入正确 thread
+2. active turn follow-up 正确走 `turn/steer`
+3. approval / user-input 请求可见且可回复
+4. final result 能稳定回 Feishu
+5. delivery unavailable 后能补发
+6. foreground bridge 不依赖 supervisor 也能跑通主链路
+
+如果某个 slice 触碰到相关模块，还必须补：
+
+- 对应 unit / integration 测试
+- 必要的 shell 回归
+- 被改文件的结构 review，避免继续养大文件
+
+## 11. DoD
+
+整个专题完成时，必须同时满足：
+
+1. 普通聊天主路径只剩“桥接 + 最小补偿”。
+2. work-session / archive / supervisor 不再参与普通聊天默认路径。
+3. recovery / gate / turn ledger 的状态数量明显下降。
+4. 已确认无价值的旧路径已删除，不留长期兼容壳。
+5. 触碰到的超大文件已按需拆分。
+6. README / AGENTS / 相关 spec 已同步当前边界。
+7. 核心回归通过，没有出现消息丢失、审批失效、结果不回来的回归。
+
+## 12. 风险与护栏
+
+### 12.1 风险
+
+1. 删厚状态时，可能误伤异常补偿路径。
+2. 切外围依赖时，可能误伤显式控制命令。
+3. 重构如果步子过大，问题会很难定位。
+
+### 12.2 护栏
+
+1. 先切主路径依赖，再删旧结构。
+2. 每一刀都必须是可独立验证、可独立提交的完整切片。
+3. 不用“长期双轨”来求稳；只允许短暂过渡，下一刀就收掉。
+4. 任何时候只要发现普通聊天稳定性下降，立即以稳定性优先。
+
+## 13. 最终结论
+
+这份 spec 落地时，bridge core 要回到一句话：
+
+> 它只是一个忠实、稳定、克制的中间层，不再试图变成第二套任务系统。
+
+这次重构真正要做的，不是“继续整理”，而是四个动作：
+
+1. 保留核心
+2. 收薄核心
+3. 退出外围
+4. 删除废路径