开发流程

英文版本 为准，本文供参考；AGENTS.md 规定仓库规则。

1. 确认范围及审查选择

每个新功能或独立变更编写需求之前，询问需求、计划、执行、验收四轮审查要做哪些，并在变更文章中记录一次。用户已明确本任务选择时无需重复询问；不设默认值，豁免仅适用于本任务。可先进行只读调研。需求或决策不清楚时询问，并暂停依赖该决定的工作。

本地 main 的仅文档首次提交是一次性例外；用户随后选定 Fieldnotes 并授权本地集成至 main，仍遵守提交前确认。后续改动仍使用同级 worktree 和 PR。未授权推送或部署。

2. 创建同级 worktree

首次提交存在后，每项变更（包括文档）都从最新 main 在独立同级 worktree 开始。在主 main/ 目录先确认分支为 main、工作区干净：

git status --short --branch

已配置 origin 时，更新基线，不创建本地合并提交：

git fetch origin
git merge --ff-only origin/main

无远程时使用本地 main。替换示例名，选择合适的分支前缀（feat/、fix/、docs/ 或 ci/）：

git worktree add -b feat/new-feature-name ../new-feature-name main
cd ../new-feature-name

全部变更在新目录完成，不占用已有非空路径、不强制重置分支。主 main/ worktree 用于集成与检查，未来可通过 PR 合并收到应用代码。

3. 按选定关卡开发

省略审查仍保留阶段顺序；省略关卡记为用户豁免，不能记为通过。仅选最终审查时，对完成的文档及交付物做一次独立综合审查。审查通过不授权提交或未要求的工作。

每个选中的审查者都须检查正确性，并从第一性原理质疑复杂度：每部分服务什么需求、是否有足够简单的方案、能否复用、维护成本是否值得。同时检查测试价值、日志/文档价值和隐私。除非用户改变关卡，阻断问题须解决，并由独立审查者在本轮内核实受影响修复。

依赖变更遵循版本规则 ：从官方来源核实最新稳定版，固定精确版本，在日志记录版本/日期/来源。添加包时使用 pnpm 的 --save-exact ，提交生成的锁文件，CI 运行 pnpm install --frozen-lockfile 。同时固定运行时、构建/部署工具及 Git/CI 引用。检查兼容性和相关构建/测试；无法使用最新稳定版时，选择旧版之前询问用户。

4. 每项变更保留一份可读记录

采用 logs/changes/<stable-id>/index.md 与 index.zh.md，英文为主、简体中文参考。同一 PR 合并前的迭代沿用该记录，后续 PR 新建关联记录。有真实 PR 后补充信息，不虚构 PR、测试结果或批准。

概要：问题、状态、审查选择、真实 PR 存在后关联
需求：范围及验收标准
计划与决策：选定方案、重要备选、检查
执行：交付改动及实质发现
验收：关键命令、预期/实际结果、限制；本地手册已交付
  迁移：基线、重要影响及长期升级/回滚操作，或无需迁移及理由

选中的阶段审查紧邻相应阶段，最终综合审查放在验收部分。记录审查者、日期、结论、范围、实质发现及处理；有 Git 版本时引用被审查版本。尚无提交的基线须明确当前文档版本和范围。被审查内容改变后，在已选审查内核实，不沿用过时结论；追加后续章节不使未变的前文审查失效。

保留有效需求、工程决策理由、重要被拒备选及有用验证。省略对话回顾、道歉、Agent 误解/纠正、文书性审查反复及重复进度；影响交付结果的缺陷或限制不能隐去。写简洁决策依据，不写原始内部推理或会话记录。

可复用指南放 docs/，通过链接引用；仅在理解或验证结果确有需要时添加 evidence/ 附件。常规工作不要求阶段分文件、manifest、快照归档或全仓库摘要框架。文章形式借鉴 Silo 设计记录 ，本仓库保留每个变更/PR 的独立标识。独立 OINK 网站实现后展示这些记录。

所有仓库文件引用（含证据）必须使用相对路径，外部公开来源可用 HTTPS。发布前检查正文、截图和附件中的个人隐私、本地绝对路径、凭据、私有服务地址和原始会话。最小化/脱敏证据并标明脱敏副本，不在公开仓库归档敏感原文。

5. 验证、预览，再提交

每次变更必须在 .local/acceptance/<change-id>.md 提供仅中文的本地验收手册，包括文档变更及已豁免审查的任务。该忽略目录位于 docs/ 和 Hugo mount 之外，不提交/force-add，不在公开 Markdown 链接它。交付前：

1. 标明上一基线及本次交付；本次有序操作写入本地手册，通用设置复用长期开发指南 ，不复制到多份公开文档。
2. 写清前提、环境/依赖/配置变化、适用的启动/停止命令、手动检查和自动命令及预期结果。仅文档变更使用相应文档检查，并说明运行时步骤不适用的原因。
3. 评估依赖/配置/内容/数据/路由/部署迁移，提供有序操作、必要备份、迁移后检查、回滚/恢复及不可逆限制；没有迁移也写“无需迁移”及原因。依赖用户决策的工作先解决决策。
4. 记录实际结果与待检查项；公开双语日志只保留简明证据、关键命令及重要迁移决策，未来维护者必需的升级/回滚操作保留在日志或长期指南中。公开证据不应依赖被忽略文件才能理解。
5. 最终交接附本地中文手册链接。文件不随 Git 同步、不显示在 OINK；删除 worktree 前完成验收或另行保存。选中的验收审查核查可复现性、迁移完整性及本地/公开边界。

按变更执行相称检查，应用变更须有有效测试；区分实际结果与计划检查。仅文档变更可检查链接、语言、空白和隐私，不运行应用测试。

提交使用英文 Conventional Commits，可选 scope，标题用祈使句；多项实质改动须有 bullet-point 正文：

docs(workflow): define contribution rules

- Require sibling worktrees for new changes
- Define task-specific reviews and commit checkpoints

只暂存预期路径，检查 git diff --cached --check、git diff --cached --stat、git diff --cached --name-only 及完整 git diff --cached。每次提交前展示准确暂存文件清单和完整信息，等待用户确认；内容或信息改变后重新预览并确认。

6. 创建 PR 与发布

已有远程且获准发布时，推送功能分支并向 main 创建 PR，在日志关联真实 PR。禁止直推 main，合并前必需检查须通过。当前 GitHub Free 私有仓库由维护者遵守只经 PR 修改的要求，并手动确认最新 checks 结果；该套餐不会强制执行规则集。以后选择支持的套餐时可启用远程强制执行。仅有 workflow 文件无法实施分支保护。

合并后，计划中的 CI/CD 将已检查的 main 版本发布到个人站和独立 OINK 站。工程基础已包含 CI/CD 源码配置；远程规则、凭据、域名和生产启用仍属另行授权工作，按部署指南开展。