Songloft Dev Flow

用户交办任务后，连续完成调查、方案、实现、验证、自审和交付。阶段记录进度，不逐阶段审批。只有关键缺失信息影响正确性、需要用户决定产品行为或扩大范围时才询问；等待期间继续独立工作。用户指定的停点与已有授权优先。

入口与授权

• 先检查实际仓库的 git status --short，保留用户已有改动。读取本地 AGENTS.md、适用的 LESSONS.md 和任务对应文档；涉及宿主契约同时读父仓库规范。
• 父仓库流程见 docs/ai-development.md，子仓库使用本地 AI 流程文档。命令与平台闸门以各仓库规范为准。
• 授权范围内的调查、编辑、格式化、验证、自审和经验记录连续执行。提交、推送、正式发布、Issue 评论/关闭分别需要明确授权；已授权的动作不重复询问。
• 授权依据是当前会话中的用户指令；旧 handoff/progress 的授权描述仅是历史证据，不授权当前批次的提交或外部动作。
• 直接提交到 main，不引入功能分支或 PR。子仓库先提交，父仓库再更新指针；未提交的子模块修改报告为 dirty，不伪造新指针。
• 调查不调用批量更新、推送或发布脚本；复现使用临时数据库/配置。敏感日志、凭证和私人音频不进入证据或提交。

开发任务

1. 有 Issue URL 时读取正文、全部评论、标签、状态、关联修复与 CI；自由描述先用代码建立上下文。区分已证实根因、推断和待验证项。
2. 确定行为、影响仓库和验证场景；按报告人的平台、部署模式、版本和交互复现。检索同机制调用点和历史回归，不按标题归并根因。
3. 在范围内实现并同步文档/生成物。遵守各仓库格式化、数据库、API、平台约定；不在未验证的新能力上继续堆叠功能。
4. Bug 的新测试应在旧实现下因预期行为失败，修复后通过；必要时故意破坏关键条件，验证测试能否抓到。回退/破坏检查用隔离副本，不覆盖当前工作树。文案等低风险修改无需机械增加测试。
5. UI 在相关平台实际操作；截图证明渲染，HTTP、持久状态、设备进度或进程证据证明动作。分别记录编译、测试、浏览器和真机的覆盖边界。
6. 自审最终 diff、调用链、生命周期/并发、资源、兼容性和同类路径。能修的问题立即修复并重跑受影响检查。按需格式化，执行 git diff --check，检查改动文件编码。
7. 提供最终行为、验证记录、未跑项目、剩余问题和提交信息。必要检查通过才进入提交；缺失必要验证先说明阻塞，不把环境问题当通过。
8. 关联 Issue 的修复获授权推送后，主动准备并展示完整回复草稿、完整目标 owner/repo#编号 与待确认的评论动作，不等用户追问。草稿写明修复提交、实际验证、剩余问题和可用版本，随 CI/发布结果更新。未获评论授权则等待用户确认；已有适用授权直接回复，不重复询问。确认仅对应已展示的具体动作，提交/推送/发布授权不自动包含评论或关闭。发表前核对最新评论，发表后回读并交付链接。详见 关联 Issue 回复。

未解决 Issue 排查

• 请求排查未解决 Issue 时包含父仓库和所有子模块，递归发现并按 GitHub 仓库去重；不能只查当前目录，不能跳过已分配负责人或不同 owner 的子模块。
• 父仓库运行 node scripts/ai-review-context.mjs issues --output /tmp/songloft-issues-<唯一标识>.json；首次可用 inventory 检查范围。脚本完整分页、排除 PR，记录远端默认分支 SHA、本地 HEAD 和父仓库 gitlink。
• complete=false / 退出码 1 是覆盖不完整，仍读取已写出的报告。未初始化模块仍查 Issues，但嵌套清单未知；失败、非 GitHub 地址、Issues 功能关闭分别记录，不把失败视为零待办。
• 独立子仓库没有父仓库脚本时，读取父仓库的 .gitmodules 清单，用 GitHub 只读 API 达到同样范围，不悄悄退化为单仓库。
• 逐项读取正文、全部评论、关联提交、复发证据并核对远端最新代码；必要时读相关 closed Issues。收集不是排查结论，needs_triage 不等于未修复。
• 输出完整 owner/repo#编号、路径、未修复/部分修复/已修复但未关闭/等待信息/未验证、证据、下一步。子仓库修复、父指针同步、实际发布/设备安装分别判断。
• 排查默认产出报告；修复、评论、指派和关闭按用户明确授权执行。

验证记录与提交

每仓库记录基线 SHA、最终 SHA（未提交则基线 + 工作树标识）、时间、环境、命令、结果、预期行为和日志/截图位置。commits 模式包含 tracked diff、untracked 内容的 SHA-256，可标识本地验证对象；只读本地历史，不能证明已同步远端。

未执行的相关检查写 Not run 及原因；失败不能改写为未执行。不适用写依据。代码、依赖、生成物或子模块变化后重跑受影响检查，不能把旧验证绑定到后来变化的 HEAD。推送后追踪同一 SHA 的必要 CI，取消/跳过不算通过。正式发布按各仓库必要检查与构建结果验收。

提交使用 type(scope): 中文说明，不加 Co-Authored-By；跨仓库 Issue 用完整引用。只有完全修复才用 Fixes/Closes，部分工作用 Ref。只 stage 本次文件并核对 staged diff。缺少授权时在最终交付中集中请求下一步，不在实现中反复暂停。

经验复盘

完成有实际教训的任务后更新本仓库中英 LESSONS。用户要求时间窗口复盘时，在父仓库用 commits --since <ISO时间> --until <ISO时间> 收集各仓库历史，结合 Issue、CI、日志核对返工、错误改动和验证不足；按流程文档的提示执行。

每条有范围、规则、失败/修复证据、正确示例和 Seen N× 的独立事件日期。同一事故重复复盘不递增，三个不同日期的独立事件才提出规范升级。已有铁律继续生效，严重问题可立即形成约束；经验不扩大权限或推翻产品决定。

无证据不写结论、不虚构次数。公共契约放父仓库，业务/设备经验放子仓库；既有 pitfalls/progress/handoff 按职责维护，LESSONS 链接而不复制事故全文。升级后标记权威位置，按需补可执行闸门。