diff --git a/docs/features/GOV-004-mandatory-gitea-push/design.md b/docs/features/GOV-004-mandatory-gitea-push/design.md new file mode 100644 index 0000000..e098141 --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/design.md @@ -0,0 +1,78 @@ +# 提交后强制推送 Gitea 设计规格 + +- 功能编号:GOV-004 +- 规格版本:0.1 +- 状态:approved_for_review +- 日期:2026-08-12 + +## 背景与目标 + +本地提交如果没有同步到远程,无法实现跨设备备份、Gitea 审阅和可靠的版本追溯。本功能把推送从“需要逐次授权的可选动作”改成项目开发流程的固定完成条件。 + +目标是:每次本地提交在验证通过后立即同步当前分支;创建版本标签后同步该标签;任何推送失败都会阻止任务被报告为完成。 + +## 方案比较 + +### 方案 A:按变化精确推送(采用) + +- 普通提交执行 `git push origin <当前分支>`。 +- 创建新标签后执行 `git push origin <标签名>`。 +- 优点:只同步本次明确产生的引用,行为可预测,不会意外发布其他本地标签。 +- 代价:分支和标签需要分别执行推送。 + +### 方案 B:每次提交推送分支及全部标签 + +- 执行 `git push origin <当前分支> --tags`。 +- 优点:命令较少。 +- 缺点:可能把尚未准备发布的历史或实验标签一并推送,不采用。 + +### 方案 C:仅发布时批量推送 + +- 多个本地提交积累到版本发布时再统一同步。 +- 优点:减少远程交互次数。 +- 缺点:提交期间缺少远程备份,也不符合“提交后需要推送”的要求,不采用。 + +## 强制流程 + +1. 完成测试、构建、Review、GitNexus 变更检测和敏感信息检查。 +2. 创建符合中文 Conventional Commit 的本地提交。 +3. 获取当前分支名,执行 `git push origin <当前分支>`。 +4. 如果本次创建了标签,再执行 `git push origin <标签名>`。 +5. 使用 `git status -sb` 或远程引用检查,确认本地分支与远程分支一致。 +6. 把提交 SHA、推送目标、推送结果和标签结果写入功能档案。 +7. 只有分支及本次新建标签全部推送成功后,任务才可以标记完成。 + +## 失败处理 + +- 认证、网络、分支保护或服务器错误发生时,保留本地提交和标签,不删除、不改写历史。 +- 将任务状态标为“推送失败/未完成”,记录失败命令、时间和不包含凭据的错误摘要。 +- 修复原因后重复同一个精确推送命令;禁止使用 `--force`、`--force-with-lease` 或绕过保护规则。 +- 远程出现未知提交导致非快进失败时,先获取并检查差异,不自动 rebase、merge 或覆盖远程。 +- 密码和令牌继续由 macOS Keychain 管理,禁止写入文档、脚本、远程 URL、命令参数和 Git 历史。 + +## 配置与作用域 + +- 唯一允许的推送远程是当前项目 `.git/config` 中的 `origin`。 +- 推送前必须验证 `origin` 仍为 `https://git.foximao.com/FoXiMao/a-share-analysis.git`。 +- 禁止修改 Git 全局配置,禁止影响其他项目,禁止新增 GitHub 远程。 +- 本规则适用于业务代码、治理文档、规格、Review 修正和版本封存等所有提交。 + +## 文档变更范围 + +- `AGENTS.md`:把提交后推送改为代理强制要求。 +- `docs/governance/development-workflow.md`:把推送加入开发后流程和完成定义。 +- `docs/governance/version-control-and-gitea.md`:记录标准命令、失败处理和验证方法。 +- `README.md`:简述项目提交会同步到 Gitea。 +- `docs/features/GOV-004-mandatory-gitea-push/`:保存 PRD、需求、实施计划、测试、Review、GitNexus 前后对比、发布和回退证据。 + +GOV-003 是当时“只接入、不推送”的历史决策记录,保持原文不变;GOV-004 作为后续决策明确取代其推送授权规则,保证历史可追溯。 + +## 验收标准 + +- 所有现行入口规范不再包含“默认不推送”或“逐次取得用户授权”的冲突要求。 +- 规范明确普通提交推当前分支、新标签单独推送、失败不算完成、禁止强推。 +- `main` 的本地历史同步到 `origin/main`。 +- 已有版本标签 `v0.0.0`、`v0.0.1`、`v0.0.2` 同步到远程。 +- GOV-004 的提交和后续封存标签也按相同规则同步。 +- 全局 Git 配置保持不变,敏感信息扫描无发现。 +- 治理测试、完成门禁和 GitNexus 前后检测通过。 diff --git a/docs/features/GOV-004-mandatory-gitea-push/gitnexus/before.md b/docs/features/GOV-004-mandatory-gitea-push/gitnexus/before.md new file mode 100644 index 0000000..27e71eb --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/gitnexus/before.md @@ -0,0 +1,26 @@ +# GitNexus 开发前基线 + +- 功能编号:GOV-004 +- 记录时间:2026年8月12日 GMT+8 18:35:43 +- 分支:main +- 基线提交:4b390d998909 + +## 工作区 + +```text +(干净) +``` + +## GitNexus 状态 + +```text +Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis +Indexed: 8/12/2026, 6:34:06 PM +Indexed commit: 4b390d9 +Current commit: 4b390d9 +Status: ✅ up-to-date +``` + +## 后续人工分析 + +在修改代码前,将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。