UI/ITERATION.md

无人值守自我迭代协议（ITERATION.md）

本协议由自动化 Agent 执行，也可供人工参考。任何迭代必须遵守 CODING.md、AGENTS.md、ARCHITECTURE.md 三份规范，门禁 npm run check 不通过的一切产出作废。

分支流水线

qa/probe ──门禁通过──▶ qa/stable ──人工审阅──▶ main（受保护，禁直接推送）

分支	用途	谁能写
main	稳定发布线，受 Gitea 分支保护	仅人工审阅后合并
qa/stable	集成测试线，所有通过门禁的迭代落在这里	自动化（仅 fast-forward 合并）
qa/probe	试验分支，每轮迭代的工作现场，可被强制重置	自动化

每轮迭代流程（自动化 Agent 执行）

所有远程推送一律使用认证包装脚本：node scripts/gitea.mjs push <remote> <分支>（令牌读自本地 .gitea-token，不入库；凭据管理器不可用）。

1. 同步：git fetch --all --prune，切到 qa/stable 并 git pull；从其最新提交强制重建 qa/probe 并切换过去。
2. 选题：读 .ua/backlog.json，取第一条 status === "open" 的条目；若全部关闭，按《选题规则》自行补充一条新点子后继续。
3. 实现：按 CODING.md 编码规范实现，保持低侵入，单文件 < 200 行，涉及组件需同步 manifest/docs/llms-full.txt。
4. 门禁：跑 npm run check（build → style → typecheck → smoke → index）。
   • 通过：提交到 qa/probe（commit message 以 iter: 开头，注明 backlog 条目 id），推送 qa/probe，fast-forward 合并到 qa/stable 并推送；将 backlog 条目 status 置为 done 并随迭代提交。
   • 失败：尝试修复一次；仍失败则放弃本轮——qa/probe 直接重置回 qa/stable，backlog 条目在 notes 里追加失败原因、status 保持 open，提交并推送该元数据变更（仅改 .ua/backlog.json，不碰代码）。
5. 留痕：在 .ua/iterations.log 追加一行 JSON：{时间, 条目id, 结果, 摘要}，随本轮提交。
6. 边界：不改 main 分支保护、不删分支、不动 .workbuddy/、不重写历史、不 force push 到 qa/stable 与 main。

选题规则（自主补点子时）

• 只从以下方向选：组件补充（皮肤包缺的常规组件）、既有组件的可用性细节、文档站与 Agent 文档完善、构建/门禁工具链改进、演示页完善。
• 单轮改动范围可控：新增文件 + 少量既有文件修改，避免跨包大规模重构。
• 每条点子必须写清 title / motivation / acceptance（验收标准，可被 npm run check 与人工检查验证）。

人工介入点

• 审阅 qa/stable 的提交，确认质量后合入 main（PR 或本地 merge 后推送）。
• 发现自动化产出质量下滑时：暂停自动化、在 backlog 中把质量要求写进条目、恢复运行。