From 6ae08b89fbdd8caa766ea0d8078cb81981e8be89 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 16 Sep 2026 14:31:26 +0800 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E6=96=B0=E5=A2=9E=E3=80=8C?= =?UTF-8?q?=E7=89=88=E6=9C=AC=E6=8E=A7=E5=88=B6=E7=BA=A6=E5=AE=9A=E3=80=8D?= =?UTF-8?q?=E5=BC=BA=E5=88=B6=E8=8A=82=20+=20=E4=BF=AE=E6=AD=A3=20UI=20?= =?UTF-8?q?=E9=AA=8C=E6=94=B6=E5=8F=A3=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 背景：refs/heads 嵌套分支名被实时清理，导致 HEAD 悬空 提交 bc4531a 后，refs/heads/codex/ui-v11-fidelity 被某个常驻监听进程删除（连 codex/ 目录一起）， HEAD 悬空 → `git log` 报 does not have any commits yet，`git status` 把全仓库文件标成新增。 `git update-ref` 重建返回退出码 0，但 0.2 秒内文件又消失（假成功）。 定向实验（14:06~14:10）定位的真实规则，与最初判断完全不同： | ref 位置 | 结果 | |---------------------------------|--------------------------| | refs/heads/<单段名> | 存活（连续观测 30s 稳定）| | refs/heads/<任意>/<子名> | 0.2s 内删除（连父目录） | | refs/tags/<任意深度> | 存活 | | .git 下非 refs 的普通子目录 | 存活 | → 删除器只针对 refs/heads 的子目录，且是事件驱动（0.2s），不是定时轮询（schtasks 无匹配项）。 → 推论：标准 Git Flow 的 feature/ fix/ codex/ ui/ 前缀在本仓库全部不可用。 ## 更正一处此前的错误结论 refs/codex/turn-diffs/checkpoints/... 是 09-11 / 09-14 的存量 ref，不代表有活跃 Codex 进程； 且仓库 git config user.name 本来就是 Codex，故 reflog 中所有条目都署名 Codex （包括非 Codex 工具产生的提交）→ **reflog 署名不能用来判断是否存在并发进程**。 ## 仓库处置 - HEAD 由悬空的 refs/heads/codex/ui-v11-fidelity 改为有效的 refs/heads/main （symbolic-ref + reset -q，仅同步索引，未触碰任何工作区文件） - main 由 b8c33b9（09-11）快进至 bc4531a —— 纯快进：main 是 bc4531a 的严格祖先， `git rev-list --left-right --count main...bc4531a` = 0 58，无分叉、零冲突、零文件变化 - 保留顶层分支 feat-ui-v11 与 tag ui-v11-accepted-and-me-routes 作为冗余锚点 ## AGENTS.md 变更 - 新增「版本控制约定（本机环境强制，务必先读）」一节： 分支命名约束（禁用斜杠）、提交后自保清单（tag + bundle + 回读验证）、悬空 HEAD 的恢复方式 - 修正 UI 口径：首批范围（小程序 11 页 + 管理端框架/工作台）已于 2026-09-16 通过用户验收 （基本达标），关闭「视觉否决 / REOPENED」判定；管理端桌面端目视复验仍待用户执行 - 头部日期更新为 2026-09-16 ## STATUS.md - 分支引用由已不存在的 codex/ui-v11-fidelity 改为 main 验证：UI 契约门禁 13/13；工作区 vs bc4531a 差异 0 行 --- AGENTS.md | 46 ++++++++++++++++++++++++++++++++++++++++++++-- docs/STATUS.md | 2 +- 2 files changed, 45 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e1448f8..d950df7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # 善缘丹阳 V1.1 - AGENTS.md > 本文件为项目最高执行规则摘要，Codex 每次启动时必须首先阅读。 -> 版本：V1.1 | 最后更新：2026-09-13 | 基线：v1.0.0-RC.2 +> 版本：V1.1 | 最后更新：2026-09-16 | 基线：v1.0.0-RC.2 --- @@ -22,7 +22,7 @@ V1.1 是 V1.0 的增量升级。正确的 V1.0 核心按 KEEP 处理，不得因 业务 Phase 唯一执行计划：`docs/善缘丹阳 V1.1 客户需求基线增量开发与修复计划.md`。 -当前 UI 重设计唯一总计划：`docs/superpowers/plans/2026-09-13-reference-driven-dual-client-ui-redesign.md`。旧 Phase 07 视觉实现及其截图已被用户否决；Phase 08 暂停，必须先完成 UI 清理门禁，再按管理端框架/工作台和小程序 11 个核心页面的顺序重构。 +当前 UI 重设计唯一总计划：`docs/superpowers/plans/2026-09-13-reference-driven-dual-client-ui-redesign.md`。首批范围（小程序 11 个核心页面 + 管理端框架/工作台）已于 **2026-09-16 通过用户验收（结论：基本达标）**，此前"视觉否决 / REOPENED"的判定随之关闭，UI 契约门禁 13/13 全绿。管理端桌面端目视复验仍待用户执行。 --- @@ -154,6 +154,48 @@ Phase 完成后必须输出 Completion Report，不得自动进入下一阶段 --- +# 版本控制约定（本机环境强制，务必先读） + +## 分支命名：禁止使用带 `/` 的嵌套名 + +本机存在一个**常驻监听进程**，会**即时（< 0.2 秒）删除 `refs/heads/` 下的嵌套子目录**。 +2026-09-16 定向实验结果： + +| ref 位置 | 结果 | +|---|---| +| `refs/heads/<单段名>`（如 `feat-ui-v11`） | **存活**（连续观测 30s 稳定） | +| `refs/heads/<任意>/<子名>`（嵌套） | **0.2s 内被删除**（连父目录一起） | +| `refs/tags/<任意深度>` | **存活** | +| `.git/` 下非 refs 的普通子目录 | **存活** | + +**后果**：分支指针被删后 **HEAD 会悬空**（`ref: refs/heads/<被删分支>`）。此时 +任何 `git commit` 会生成**根提交**，切断全部历史；`git status` 还会把全仓库文件标成新增。 + +**因此标准 Git Flow 的 `feature/`、`fix/`、`codex/`、`ui/` 等前缀在本仓库一律不可用**， +必须使用**顶层单段名**（如 `feat-ui-v11`、`ui-acceptance`）。 + +## 提交后自保（本机环境必做） + +```bash +git tag # tag 不受清理影响，让提交变为可达，免被 gc 回收 +git bundle create .bundle # 参数必须是 ref 名；传裸 sha 会报 empty bundle +sleep 2 && ls .git/refs/heads/ && git log --oneline -1 # 回读验证，别信退出码 +``` + +- `git update-ref` **返回退出码 0 不代表持久化成功**，必须回读验证。 +- 判断是否有并发进程**不能看 reflog 署名**：本仓库 `git config user.name = Codex`， + 所有 reflog 条目都署名 Codex（含非 Codex 工具产生的提交）。 +- 若发现 HEAD 悬空（`git log` 报 `does not have any commits yet`），按以下方式恢复， + **不要触碰任何工作区文件**： + +```bash +git symbolic-ref HEAD refs/heads/<顶层单段分支> +git reset -q # 仅同步索引，不改工作区 +git status --short # 应干净 +``` + +--- + # 文档 - 主启动提示词: `docs/善缘丹阳 V1.1 Codex最终主启动提示词（整合版）.md` diff --git a/docs/STATUS.md b/docs/STATUS.md index 845c086..6a36ee2 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -4,7 +4,7 @@ > > 阶段 0（在途收口）、阶段 1（小程序 C 组 + discover 筛选重设计）、阶段 2（管理端 Vue 新框架适配）、阶段 3（CapabilityService 独立化）、阶段 4（双端总验收）全部完成。三端构建通过、**13/13 契约全绿**、核心 11 页面**全部 TS-only（11/11）**。后端全量回归已清偿（299 tests / 0 failures / 0 errors）。**UI 重设计首批 11 页已于 2026-09-16 通过用户验收（结论：基本达标）**；`/me/*` 前后端契约同轮收敛，17 个 404 调用已恢复。 -最后更新: 2026-09-16 — 分支 `codex/ui-v11-fidelity` +最后更新: 2026-09-16 — 分支 `main`（`bc4531a`；`feat-ui-v11` 保留为冗余锚点） ## 当前唯一有效状态