a-share-analysis/docs/features/GOV-004-mandatory-gitea-push/implementation-plan.md

提交后强制推送 Gitea 实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将每次验证通过的本地提交和本次新增版本标签精确推送到项目专用 Gitea，并把推送成功设为任务完成条件。

Architecture: Git 仍使用当前项目 .git/config 中唯一的 origin，不增加脚本服务或全局配置。流程层通过现行治理文档、代理入口和 GOV-004 功能档案强制执行“验证—提交—推送—远程核对”，GOV-003 保持为历史决策，由 GOV-004 明确取代其推送规则。

Tech Stack: Git、Gitea、macOS Keychain、Markdown、GitNexus、Node.js 治理门禁。

Global Constraints

• 远程固定为 https://git.foximao.com/FoXiMao/a-share-analysis.git，作用域仅限当前项目。
• 不修改 Git 全局配置，不新增 GitHub 远程。
• 普通提交只推送当前分支；新标签只推送本次创建的标签。
• 推送失败时任务不得标记完成，且禁止任何形式的强推。
• 密码和令牌不得进入文件、远程 URL、命令参数或 Git 历史。
• 每次提交必须使用中文 Conventional Commit，并在提交后立即推送。

---

Task 1: 固化产品与工程规则

Files:

• Create: docs/features/GOV-004-mandatory-gitea-push/prd.md
• Create: docs/features/GOV-004-mandatory-gitea-push/requirements.md
• Create: docs/features/GOV-004-mandatory-gitea-push/test-plan.md
• Create: docs/features/GOV-004-mandatory-gitea-push/gitnexus/impact-plan.md
• Modify: docs/features/GOV-004-mandatory-gitea-push/implementation-plan.md

Interfaces:

• Consumes: 已确认的 design.md 和 GitNexus 开发前基线。

• Produces: 可由完成门禁和 Review 逐条验证的功能需求。

• Step 1: 编写 PRD 与工程需求

明确当前分支推送、新标签精确推送、失败阻断完成、禁止强推、凭据安全和现有历史标签同步六类验收项。

• Step 2: 编写测试及影响计划

列出治理测试、冲突文本扫描、远程 URL、远程分支 SHA、远程标签集合、全局配置边界和敏感信息扫描命令。

• Step 3: 核对规格覆盖

运行：

rg -n "当前分支|新标签|推送失败|禁止强推|Keychain|v0.0.0|v0.0.1|v0.0.2" docs/features/GOV-004-mandatory-gitea-push

预期：所有约束均能从设计、PRD、需求或测试计划定位。

Task 2: 更新现行治理入口

Files:

• Modify: AGENTS.md
• Modify: README.md
• Modify: docs/governance/development-workflow.md
• Modify: docs/governance/version-control-and-gitea.md
• Modify: docs/index.md
• Modify: CHANGELOG.md
• Modify: VERSION

Interfaces:

• Consumes: Task 1 的验收要求。

• Produces: 对所有后续代理和开发者生效的强制推送规范。

• Step 1: 更新代理入口和开发流程

删除“推送需逐次授权”的现行条款，加入提交后立即推送、标签精确推送、失败阻断完成和禁止强推。

• Step 2: 更新 Gitea 操作规范

记录 git push origin <当前分支>、git push origin <标签名>、远程 SHA 验证、错误留痕和安全重试规则。

• Step 3: 更新索引和版本记录

新增 GOV-004 文档入口，将版本提升到 0.0.3 并记录规则变化。

• Step 4: 验证不存在现行冲突

运行：

rg -n "不得主动.*推送|只有用户明确要求.*推送|本地提交和标签完成后仍不得自动推送" AGENTS.md README.md docs/governance

预期：无匹配。GOV-003 历史档案允许保留旧规则。

Task 3: 补齐验证、Review 与发布档案

Files:

• Create: docs/features/GOV-004-mandatory-gitea-push/manifest.yaml
• Create: docs/features/GOV-004-mandatory-gitea-push/gitnexus/after.md
• Create: docs/features/GOV-004-mandatory-gitea-push/gitnexus/detected-changes.md
• Create: docs/features/GOV-004-mandatory-gitea-push/gitnexus/comparison.md
• Create: docs/features/GOV-004-mandatory-gitea-push/qa/test-results.md
• Create: docs/features/GOV-004-mandatory-gitea-push/qa/visual-qa.md
• Create: docs/features/GOV-004-mandatory-gitea-push/review/code-review.md
• Create: docs/features/GOV-004-mandatory-gitea-push/review/standards-review.md
• Create: docs/features/GOV-004-mandatory-gitea-push/release-notes.md
• Create: docs/features/GOV-004-mandatory-gitea-push/rollback.md

Interfaces:

• Consumes: Task 2 的文档 diff 和远程同步结果。

• Produces: GOV-004 完成门禁所需的全部追溯文件。

• Step 1: 执行本地验证

运行：

npm run test:governance
git diff --check
npx gitnexus analyze
npx gitnexus detect-changes --repo a-share-analysis --scope all

预期：5 个治理测试通过、diff 无空白错误、GitNexus 状态最新且风险为低。

• Step 2: 扫描敏感信息和全局配置边界

对仓库文件与暂存 diff 扫描凭据 URL、密码和令牌赋值；确认全局 credential.helper 与 remote.pushDefault 未被本功能修改。

• Step 3: 编写双 Review 和完成档案

两份 Review 必须逐条对应 PRD，处理所有 Important 问题，并以固定行 最终结论：passed 结束。

• Step 4: 运行完成门禁

运行：

npm run governance:finish -- GOV-004 mandatory-gitea-push

预期：退出码为 0。

Task 4: 提交、推送并核对远程

Files:

• Modify: docs/features/GOV-004-mandatory-gitea-push/manifest.yaml
• Modify: docs/features/GOV-004-mandatory-gitea-push/qa/test-results.md
• Modify: docs/features/GOV-004-mandatory-gitea-push/release-notes.md

Interfaces:

• Consumes: 通过 Task 3 完成门禁的暂存区。

• Produces: 与本地 main 和版本标签一致的 Gitea 远程引用。

• Step 1: 创建中文实现提交并推送

git commit -m "docs(GOV-004): 强制提交后同步 Gitea"
git push origin main

预期：origin/main 指向新提交。

• Step 2: 同步既有标签

分别推送 v0.0.0、v0.0.1 和 v0.0.2，不使用 --tags。

• Step 3: 封存版本并推送

回填实现提交，创建中文封存提交并推送；创建带注释 v0.0.3 标签，再单独推送该标签。

• Step 4: 最终远程核对

比较 git rev-parse main 与 git ls-remote origin refs/heads/main；逐一比较四个本地标签与远程 peeled tag 提交，确认工作区干净、GitNexus 索引最新。