plan-20260923.md

# 首次使用路径策略与 ImportRepo 生命周期修复计划（2026-09-23）

**模板版本：** v2.1；依据 [`plan-template.md`](plan-template.md)。源码核对日期 2026-09-23；tip `137065f`（`Merge pull request #24 from gitmono-dev/feat/mst2-blob-lookup`），crate `0.38.21`，已与 `origin/main` 同步（`libra fetch origin` → `Already up to date`）。

> **文档落点说明（2026-09-24）：** 按用户要求移除 `docs/monorepo.md` 与 `docs/sync/`。本计划中待执行的用户文档交付改由 `docs/user-guide(.zh).md`、`docs/manual/monorepo-init(.zh).md`、`docs/refactoring/trunk-push.md` 和对应专题文档承接；本计划其余已完成卡片记录保留为历史。

**计划状态（2026-09-26）：** **已完成**。计划评审经 22 轮 Codex 复审于 R22 取得 `VERDICT: PASS`（Phase 0 退出）；FU-01..FU-23 与 FU-04A 全部 `done` / `complete`（v0.38.22..v0.40.12，其中 v0.40.10 属 `plan-20260913`；FU-11、FU-22 为无独立发布的文档卡），收口发布 v0.40.12 / `4bf6cc2`。「计划完成门」在 v0.40.13（`5e1cbd0`，git-lfs 钉住版本上调与本机调试文档，D 组 run `36226158231` 绿）的最终树上补跑通过：全量 `cargo test --all --no-fail-fast` 18 个 target 0 失败，fmt / clippy / `cargo build` 0 警告，`cargo build --tests` 只有 macOS `ld` 的 `__eh_frame` 链接提示——按用户决定（2026-09-26）视为平台噪音。

**来源：** GitHub issues [#25](https://github.com/gitmono-dev/mega2/issues/25)、[#26](https://github.com/gitmono-dev/mega2/issues/26)、[#27](https://github.com/gitmono-dev/mega2/issues/27)、[#28](https://github.com/gitmono-dev/mega2/issues/28)、[#29](https://github.com/gitmono-dev/mega2/issues/29)（2026-09-23 用 `gh issue view` 读取；五个 issue 均为 `OPEN`，来自 2026-09-23 用户试用报告 P0-2 / P1-1 / P1-2 / P1-3 / P2）。

## 文档职责

本文解决五个首次使用问题：新子路径无法用普通 Git/Libra 流程开通，且错误文案不可操作（#25 / #29）；ImportRepo 第二次推送被拒，与文档矛盾（#26）；失败或废弃的 ImportRepo 叶子无法清理（#27）；签名 commit 推到子路径后 Mega2 合成的祖先层 commit 主题变成 `gpgsig -----BEGIN PGP SIGNATURE-----`（#28）。目标是：稳定、可操作的路径策略错误码；幂等的路径开通操作（HTTP + CLI）；可增量更新、按 Git 语义做 ref CAS 的 ImportRepo；有鉴权、可审计、可续做的 ImportRepo 清理；不泄漏签名头、帧格式正确的服务端合成 commit。

本文只规划任务，不宣称实现完成。落地时每个任务都必须先刷新源码锚点，再按任务卡验收。

### 适用范围

- 服务端合成 commit：`src/common/utils.rs`（消息分解与成帧 helper）、`src/ceres/pack/trunk_provenance.rs`、`src/ceres/pack/materialize.rs`、`src/jupiter/service/push_queue_service.rs`（attach 根消息）、`src/ceres/api_service/mono_api_service.rs` 与 `src/jupiter/storage/mono_storage.rs` 的 `Commit::from_tree_id` 生产调用点。
- 配置：`src/config/validate.rs` 对 `monorepo.root_dirs` / `monorepo.import_dir` 的形状校验。
- 路径策略：`PathPolicyError` 错误域与唯一的创建路径分类函数；`MonoApiService::resolve_trunk_land_path` 全新栈回落；`POST /api/v1/path/provision`；`mega2 path provision` CLI；`src/ceres/pack/push_chain.rs` 孤儿拒绝黏性；`src/ceres/pack/monorepo.rs` trunk 首推分类。
- ImportRepo：B3 attach 挂载幂等、分支与 tag ref CAS、`ImportRepoError` 错误域；B3 detach（同 `attach` kind，payload `op` 枚举）、事务内审计、锁外分批清扫与续做；对**全部** ImportRepo ref 写路径（B3 attach、tag 直写、仅删除分支）的行锁存活栅栏；`POST /api/v1/import-repo/remove`。
- 测试：`tests/integration_git_cli.rs`、`tests/integration_api_write_trunk.rs`、各模块 `#[cfg(test)]`。
- 文档：`README.md` / `README.zh.md`、`docs/quick-start(.zh).md`、`docs/user-guide(.zh).md`、`docs/configuration(.zh).md`、`docs/manual/monorepo-init(.zh).md`、`docs/errors.md`、`docs/deploy-trunk.md`、`docs/refactoring/trunk-push.md`、`docs/refactoring/directory-entry-api.md`、`docs/plan/README.md`、`docs/plan/plan-long.md`。

### 非目标

- 接受任意无父历史落为任意 Monorepo 子树；首次推送自动创建拼错的路径（#25 / #29 明确排除）。
- 用 Git push 创建新的顶层根目录；运行时增删根目录（`root_dirs` 变更仍需重启）。
- 改变单 trunk / 客户端 tag 策略；在普通 Monorepo 路径开放多分支或客户端 tag。
- ImportRepo 目录内的文件级删移（`delete-entry` / `move-entry` 对 ImportRepo 内部路径的拒绝保持不变）；未鉴权的破坏性端点。
- Git 命名空间对象存储 GC（`DEFER-FU-01`）；`atomic` 推送能力（`DEFER-FU-05`）。
- 改动 `../libra` 仓（`DEP-FU-03`）；review 形态的新增表面（`DEFER-FU-02`）。
- 重写历史 commit（`DEFER-FU-07` 永久非目标）。
- 关闭或评论 GitHub issue（维护者动作）。

### 成功定义

- 无父首推到根外路径返回 `MONO_PATH_NOT_ALLOWED`（列出允许的根），到合法根下未开通路径返回 `MONO_PATH_UNINITIALIZED`（点名开通动作）；重试同一 commit 得到同一码；真实 non-fast-forward 保持原文与对齐提示。
- `mega2 path provision --server <url> <path>` 或 `POST /api/v1/path/provision` 在全新栈上一次开通、重试报告已存在；之后 Git clone → commit → 两次增量 push 全部成功，无需手写 HTTP。
- ImportRepo 第二次 fast-forward push、后续新分支与 tag 推送成功；陈旧 ref 更新被拒；失败文案为稳定码。
- 有鉴权的 `POST /api/v1/import-repo/remove` 删除一个完整 ImportRepo 叶子：之后 404，重试稳定返回 `absent`，留下事务内审计行；不能删除 import 根、不能越出命名空间、不能经前缀匹配误删兄弟仓库。
- 签名 commit 推到任意子路径后，Mega2 合成的祖先/后代/物化 commit 主题等于原 commit 主题；合成 commit 通过 `git fsck --strict`；`git -c transfer.fsckObjects=true clone` 成功。
- 非延后卡 `Lifecycle=done` 且 `Acceptance=complete`；每张卡 Codex 评审最终 `VERDICT: PASS`；三门、`cargo build`、`cargo build --tests` 全绿。

## 事实基线

> 行号以 2026-09-23 工作树 tip `137065f`、版本 `0.38.21` 为准；开工当天按 ER-02 重刷。历史计划不是实现证据。

| 类别 | 当前事实 | 证据 |
|---|---|---|
| VCS / tip | **Libra**（`.libra`，无 `.git`）；`## main...origin/main` 干净；tip `137065f` | 2026-09-23 `libra status`、`libra log --oneline -5` |
| 工作区前置 | `.env.test` 存在；测试栈 `docker compose -f docker/docker-compose.test.yml up -d --wait postgres redis` 已起（15432 / 16379） | 2026-09-23 本地执行 |
| 版本 / 发布 | `Cargo.toml:3` `version = "0.38.21"`；最新 tag / GitHub Release 为 `v0.38.18`（0.38.19..21 未打 tag） | `libra tag -l`；`gh release list -R gitmono-dev/mega2` |
| CI / D 组 | 唯一 workflow `.github/workflows/docker.yml`，job `docker`，触发 `push: tags: ["v*.*.*","v*"]`，无 `paths:` 过滤 | `docker.yml:3-12` |
| 首推孤儿拒绝 | `PushChain::resolve`：tip 为新、第一父链走到根 → `walk_stop=None` → `old_id=ZERO` 时 `Can not init directory under monorepo directory!` | `src/ceres/pack/push_chain.rs:171-176,272-275,295-303` |
| 重试措辞漂移 | 被拒首推的对象已入库；重试时 `tip_is_new=false` → `fork = path.last()`（根 commit 自身）→ `base=根` → `validate` 报 `push chain is broken: base R is not on the first-parent chain of tip R` | `push_chain.rs:276-289,476-481`；对象先入库 `src/ceres/pack/monorepo.rs:208-246` |
| trunk 对齐提示 | `trunk_align_finalize_err` 对含 `non-fast-forward` / `push chain is broken` 的文案追加 ``align with `git fetch && git reset --hard origin/main` `` | `monorepo.rs:91-99`；`src/ceres/pack/api_tip_lander.rs:25-34` |
| `root_dirs` 运行时 | 只在 `init_trees` 作为根树项名逐字使用；运行时**无**消费者、无根外路径拒绝；校验只要求非空（含 `/`、重复、`..` 的条目今日会生成非法根树） | `src/jupiter/utils/converter.rs:420-445`；`src/config/validate.rs:450-458`；`src/config/model.rs:418-458` |
| 默认配置 | `root_dirs` 默认含 `third-party`，同时 `import_dir = "/third-party"` | `config/config.toml:64-71`；`src/config/model.rs:442-458` |
| B3 创建语义 | `creating = path_row.is_none()`：树项插入原语可补齐任意缺失组件（含新顶层）；今日只有「fork 为已知 commit」的链可到达 | `src/jupiter/service/push_queue_service.rs:1776-1821,1910-1928`；`src/ceres/api_service/tree_ops.rs:368-440`；设计意图 `docs/refactoring/trunk-push.md:149,155-159,1392` |
| advertise | 缺失路径 → `PathAbsent` → 空 refs → `capabilities^{}`（客户端送 `old_id=ZERO`） | `src/ceres/pack/materialize.rs:107,175-221`；`src/ceres/protocol/smart.rs:99-103` |
| 协议错误出口 | finalize 失败把所有 ok 分支命令标 `ng <ref> <msg>`（HTTP 200 report-status）；消息为 `MegaError::Other` 的 `Other error: {0}`；receive-pack 能力不含 `atomic` | `smart.rs:605-617,632-634`；`src/common/errors/mod.rs:64`；E1 抓包 `report-status delete-refs no-thin side-band-64k ofs-delta` |
| create-entry | trunk 经 `resolve_trunk_land_path` 要求**非根**祖先已有 `main` ref，否则 `[code:400] no non-root path tip …`；重名 `Duplicate name` 无 `[code:]` → 500 | `src/ceres/api_service/mono_api_service.rs:2127-2387,2219,2360,2412-2427` |
| 写鉴权 | `authorize_trunk_api_write`：`push_auth=none` → `anonymous`；`token` 取自配置 `git.push_tokens`，Basic 或 Bearer；缺失/无效 401，路径不覆盖 403 | `src/api/api_write_auth.rs:1-60`；`src/api/router/preview_router.rs:475-485` |
| 签名头在 message 内 | git-internal `Commit::from_bytes` 把 committer 行之后全部（额外头块、头/体空行、正文）放进 `message`；`to_data` 直接拼接 `message`，不补空行 | `~/.cargo/registry/.../git-internal-0.10.2/src/internal/object/commit.rs:233-330` |
| N=1 层消息 | `n1_message = tip.message.clone()`；`layer_message` 在 N≤1 时原样返回；祖先层经 `synthesize` + `sign_commit_preserving_identities` 嵌入服务端 `gpgsig` 后，客户端 `gpgsig` 块落入正文 | `src/ceres/pack/trunk_provenance.rs:38-90`；`mono_api_service.rs:3721-3736`；`src/contract/vault/server_signing.rs:145-160,208-245` |
| squash 主题 | `commit_subject` 取 `message` 首个非空行 → 签名 commit 得 `gpgsig -----BEGIN …` | `trunk_provenance.rs:131-174,216-223` |
| 物化消息 | `persist_walked_refs` 用根 commit 原始 `message`（含服务端 `gpgsig` 头）经 `Commit::new` 合成未签名路径 commit → 带不可验证的签名头 | `materialize.rs:249-277` |
| 现存帧工具 | `format_commit_msg` / `parse_commit_msg` 存在、生产代码零调用；`parse_commit_msg` 不识别 `gpgsig-sha256` 且 `trim_start` 改变字节；测试模块名为 `common::utils::test` | `src/common/utils.rs:60-90,195` |
| API 合成帧 | `Commit::from_tree_id(tree, parents, "create new directory …")` 不带头/体空行 → `git fsck --strict`：`unterminatedHeader` | `mono_api_service.rs:885,1121,2045`；`src/jupiter/storage/mono_storage.rs:700`；`import_api_service.rs:475`（`mono_api_service.rs:964` 构造后立即签名，由 `embed_gpgsig` 成帧，不属此缺陷） |
| ImportRepo 分派与查找 | 路径 `starts_with(import_dir)`（组件级）→ `ImportRepo`；ReceivePack 无行时先插 `git_repo`；`find_git_repo_exact_match` 为绑定参数的等值查询；`find_git_repo_like_path` 为字符串拼接 `'<input>' LIKE repo_path || '%'`（无组件边界、无参数绑定，`DEFER-LB-09`） | `src/ceres/protocol/mod.rs:236-290`；`src/jupiter/storage/git_db_storage.rs:385-416` |
| ImportRepo attach | 每个含非零 new_id 的 ok 分支命令的 push 都入队 attach；`search_and_create_tree` 全部组件已存在时报 `… (cannot attach leaf)`；叶子只是 `.gitkeep` 占位；分支 ref：`Update` 不校验 old_id、`Create` 不校验不存在、`Delete` 已 CAS | `src/ceres/pack/import_repo.rs:503-660`；`push_queue_service.rs:1295-1664,1481-1555`；`tree_ops.rs:159-171` |
| ImportRepo tag | tag 命令在 unpack 后立即直写（不经队列）：`Create` 不校验存在、`Update` 不校验 old_id、`Delete` 已 CAS | `import_repo.rs:356-394`；`smart.rs:562-571` |
| attach 队列身份 | `attach_operation_id = sha256(repo_id \0 normalized_commands)`；入队去重键 `(kind, path, operation_id)`，`Queued/Running/Done` 同键即重放；终态重试复制前驱 payload | `push_queue_service.rs:47-53`；`src/jupiter/storage/push_queue_storage.rs:150-213` |
| ImportRepo 客户端文案 | `attach B3 did not complete successfully: {other:?}`（Debug 格式） | `import_repo.rs:652-654` |
| ImportRepo 删移 | `delete-entry` / `move-entry` 对 ImportRepo 内部返回 `[code:409] import dir does not support …`；叶子本身走 Monorepo 分支，trunk 下先报 `no non-root path tip` | `src/ceres/api_service/import_api_service.rs:69-89`；`src/api/mod.rs:139-167` |
| 删除工具 / 审计 | 无删除 `git_repo` 的 API/CLI/storage 函数；`audit_logs`（`actor_id i64`、`actor_type` 必填 `human|bot`、`action`、`target_type`、`target_id`、`metadata jsonb`）+ `AuditStorage::log_audit`（自有连接，非事务）无调用者 | `src/jupiter/storage/audit_storage.rs:33-55`；`src/callisto/audit_logs.rs`；`src/callisto/sea_orm_active_enums.rs:8-30,286-299` |
| 对象存储 | Git 与 Monorepo blob 共用 `ObjectNamespace::Git` 内容寻址命名空间；Git 命名空间无 GC | `src/jupiter/service/git_service.rs:59-66`；`mono_service.rs:249` |
| `repo_id` 索引 | `git_commit` / `git_tree` / `git_blob` 有以 `repo_id` 前导的唯一索引；`git_tag` 为 `(repo_id, tag_id)` | `src/jupiter/migration/m20250314_025943_init.rs:384,435,486`；`m20260921_000100_fix_git_tag_unique.rs` |
| LIKE 转义 | `escape_like`（`%`、`_`、`\`）已存在 | `src/common/utils.rs:146-159` |
| 错误扩展规则 | 新领域错误进 `src/common/errors/mod.rs` 并经 `MegaError` 包装；HTTP 状态只在 `ApiError` 映射；5xx 只回 `Internal server error` | `docs/errors.md:68-77,110-115`；`src/common/errors/api.rs:9-38,150-190` |
| CLI 注册 | `builtin()` / `builtin_exec()` / `load_mode()` 三处；`LoadMode::None` 存在；`reqwest` 已是依赖 | `src/commands/mod.rs:22-30,92-124`；`Cargo.toml:72` |
| 迁移 | 最近迁移 `m20260921_000100_fix_git_tag_unique`（`src/jupiter/migration/mod.rs:138,262`）；本计划新增两个有序迁移：`m20260923_000100_import_repo_cleanups`（FU-14，清理台账表）与 `m20260923_000200_canonicalize_import_repo_paths`（FU-15，存量别名路径改写，forward-only）；`audit_logs` 有 `idx_audit_logs_target`，无按 JSON 字段的索引 | `src/jupiter/migration/mod.rs:155-262`；`m20260306_121829_create_bots_related_table.rs:350-370` |
| 测试 target | `tests/` 下 15 个 target（14 个 `integration_*` + `orbit_backend_integration`）；相关：`integration_git_cli`、`integration_api_write_trunk` | `ls tests/` |
| 基线全量测试 | tip `137065f`、规范栈 `docker compose -p mega2-it -f docker/docker-compose.test.yml --profile git up -d --wait`（`MEGA2_IT_GIT_WORKDIR` 指向会话临时目录、`MEGA2_IT_GIT_UID/GID=$(id -u/-g)`）上 `source .env.test && cargo test --all --no-fail-fast`：lib 1656 通过、`integration_git_cli` 24/24 通过；**6 个本机环境失败**（与本计划改动面无关）：`integration_git_lfs` 的 `storage_events_basic_upload`、`storage_events_presigned_gap`、`trunk_push_auth_none_round_trip`、`trunk_push_auth_token_round_trip`（宿主 `git-lfs/3.8.0` ≠ 钉住的 `3.7.1`）；`integration_oci_docker_gated`（`docker push failed: unauthorized`）；`integration_object_storage_s3_compatible_smoke`（RustFS PUT 经 macOS 系统代理返回 `502 Bad Gateway`；直连 RustFS 正常）。另：macOS `ld` 在链接 lib 测试二进制时输出 `warning: linker stderr: ld: __eh_frame section too large (max 16MB)`（`linker_messages`，基线同样存在，非本计划代码引入） | 2026-09-23 本地运行（1114 s）；`scutil --proxy` |
| 外部参照 | Libra `0.23.46`（与报告一致）；git `2.54.0`；git-internal `0.10.2` | `libra --version`；`git --version`；`Cargo.toml:45` |

### 复现证据（2026-09-23，本地 storage-only 栈，`push_auth=none`，tip `137065f` 的 debug 构建）

服务以隔离的 `MEGA_BASE_DIR` / `MEGA_CACHE_DIR` 与独立库 `mega2_repro` 运行（不触碰开发者 vault）。证据已脱敏：签名 armor 截断，不含凭据。

| # | 操作 | 观测（原文摘录） | 结论 |
|---|---|---|---|
| E1 | git 无父 commit 推 `/nosuchroot/demo` | `! [remote rejected] main -> main (Other error: Can not init directory under monorepo directory!)` | #29：根外路径无路径策略分类 |
| E2 | git / Libra 无父 commit 推 `/project/workbuddy/demo`（未开通） | 同 E1 文案（Libra：`LBR-NET-002 … Can not init directory …`） | #29：与 E1 不可区分 |
| E3 | **同一 commit 重试**推 `/project/retrydemo` | `push chain is broken: base 6844bbb… is not on the first-parent chain of tip 6844bbb…; rebase onto the current base and re-push; align with \`git fetch && git reset --hard origin/main\`` | #25 报告文案的真实来源：重试时 base==tip，且误导对齐 |
| E4 | 同一 commit 再推根外 `/nosuch2/x` | 同 E3 文案 | 路径策略分类随对象已知性漂移 |
| E5 | 全新栈 `create-entry {path:"/project",name:"workbuddy"}` | `"err_message":"no non-root path tip under /project for trunk API write"`；`git clone /project` 之后同请求成功 | #25：变通方案在全新栈上也失败 |
| E6 | 重复 `create-entry` 同名目录 | `"err_message":"Internal server error"`；服务日志 `Application error: Duplicate name`（500） | #25 AC1：不幂等 |
| E7 | ImportRepo `/third-party/workbuddy/demo` 首推 → 第二次 ff 推 | 首推 `* [new branch]`；二推 `attach B3 did not complete successfully: Failed { id: 4, failure: "AttachFailure", message: "Other error: path '/third-party/workbuddy/demo' already exists in monorepo tree (cannot attach leaf)" }`；`ls-remote` 仍为 v1；新分支推送同样被拒；tag 推送成功 | #26 复现 |
| E8 | `delete-entry {path:"/third-party/workbuddy",name:"demo"}` | `no non-root path tip under /third-party/workbuddy for trunk API write` | #27：无清理路径 |
| E9 | Libra（`vault.signing=true`）签名 commit 推已开通子路径 `/project/workbuddy/demo`，再 `git clone` P 与祖先 | P：`ebc1d0b [feat: signed subject line]`，原始对象含客户端 `gpgsig`（逐字落地）；`/project/workbuddy`、`/project`、`/`：`git log --oneline` = `… gpgsig -----BEGIN PGP SIGNATURE-----`；原始字节：`committer …` / `gpgsig <服务端 armor>` / 空行 / `gpgsig -----BEGIN PGP SIGNATURE-----`（客户端 armor 作为正文） | #28：Mega2 合成的祖先层是源头，非 Libra 渲染问题 |
| E10 | 对照：同样签名 commit 推一级根 `/project` | P=`/project`：`09897c0 [feat: root control subject]`（Git 与 `libra log --oneline` 一致）；祖先 `/`：`c2adc80 [gpgsig -----BEGIN PGP SIGNATURE-----]` | 报告「根路径正常」= 被推路径逐字落地；症状只在 Mega2 合成层（trunk 拒绝 `path=/` 推送） |
| E11 | 签名 commit 落地后首次 clone 未物化的 `/doc` | 物化 commit 带从根 commit 复制来的服务端 `gpgsig` 头（对本 commit 不可验证），主题为 `gpgsig -----BEGIN …` | #28：物化路径同源缺陷 |
| E12 | `git fsck --strict`；`git -c transfer.fsckObjects=true clone /project` | `unterminatedHeader: unterminated header`（create-entry commit `35c2803`、`b37f6f5`）；严格 clone `fatal: fsck error in packed object` | API 合成 commit 帧错误，阻断严格客户端 |

### 当前缺口

| ID | 缺口 | 影响 | 证据 | 计划动作 |
|---|---|---|---|---|
| GAP-FU-01 | 首推根外路径与合法根下未开通路径同一文案，无码、无下一步；产品写对根外路径只报拓扑错误 | 用户靠试错；Git 与 API 口径不一 | E1/E2/E5 | FU-05、FU-06、FU-10 |
| GAP-FU-02 | 重试时孤儿拒绝漂移为 base==tip 的 `push chain is broken` 并附误导对齐提示 | 与真实 NFF 不可区分 | E3/E4 | FU-09 |
| GAP-FU-03 | 无受支持、可发现、幂等的开通操作；create-entry 全新栈失败、重复 500 | 首个仓库需手写 HTTP 且依赖先 clone 祖先 | E5/E6 | FU-06、FU-07、FU-08、FU-11 |
| GAP-FU-04 | `root_dirs` 无形状校验、运行时不约束创建；fork 型创建推送可造新顶层 | 无稳定策略面 | `converter.rs:420-445`；`validate.rs:450-458` | FU-04、FU-05、FU-10 |
| GAP-FU-05 | ImportRepo 已挂载叶子的后续分支推送被 attach 拒绝；文案暴露 Debug | 文档承诺的跟随上游不可用 | E7 | FU-12 |
| GAP-FU-06 | ImportRepo 分支 `Create/Update` 与 tag `Create/Update` 无 CAS | 并发覆盖、非普通 Git 语义 | `push_queue_service.rs:1481-1555`；`import_repo.rs:356-394` | FU-13 |
| GAP-FU-07 | ImportRepo 叶子无授权清理路径；无事务内审计原语；LIKE 查找可越界 | 试错残留永久驻留 | E8；`git_db_storage.rs` 的 `find_git_repo_exact_match` / `find_git_repo_like_path`（FU-20 核对：前缀解析越界为祖先 / 别名，非 LIKE） | FU-16、FU-17、FU-20、FU-22 |
| GAP-FU-11 | ImportRepo 元数据写路径（`save_entry` 对象行、B3 attach、tag 直写、仅删除分支、`ImportApiService` 的 edit/save 与 tag 创建/删除）不校验仓库存活；`import_refs` 无指向 `git_repo` 的外键 | 清理进行中的陈旧推送或 API 请求可在清理后写回 ref、tag 或对象行 | `import_repo.rs:356-394,511-538`；`push_queue_service.rs:1295-1664`；`import_api_service.rs` 的 `save_file_edit` / `create_tag` / `delete_tag` | FU-18、FU-19 |
| GAP-FU-08 | N=1 层消息、squash 主题携带源签名头 | 祖先历史主题错乱 | E9/E10 | FU-01 |
| GAP-FU-09 | 物化与 attach 根消息复制源签名头/只认 PGP | 物化 commit 带不可验证签名头 | E11 | FU-02 |
| GAP-FU-10 | API 合成 commit 缺头/体空行 | `fsck --strict` 与严格 clone 失败 | E12 | FU-03 |

## 与其它计划的关系

| 计划/文档 | 关系 | 本计划处理 |
|---|---|---|
| `plan-long.md` | 无对应 PT（mega2 原生可用性修复） | FU-23 在日期计划索引加一行，PT 列 `N/A` |
| [`plan-20260905.md`](plan-20260905.md) / `docs/refactoring/trunk-push.md` | trunk 写模型事实源；创建语义写「`old_id=ZERO` 向未物化路径的首推按创建语义落地」 | FU-10 登记订正：无父链首推仍拒绝（`MONO_PATH_UNINITIALIZED`），创建语义仅对 fork 型链成立且受 `root_dirs` 白名单约束；不改 B3 创建分支 |
| [`plan-20260827.md`](plan-20260827.md) | PushChain「拒绝黏性」原则（Codex R2 P1-1）；MC-09 服务端签名 | FU-09 把孤儿拒绝纳入黏性；不改签名算法 |
| [`plan-20260917.md`](plan-20260917.md) / [`plan-20260918.md`](plan-20260918.md) / `docs/refactoring/directory-entry-api.md` | 产品写契约与 Libra pin；ImportRepo 删移非目标；`DEFER-LB-09`（LIKE 无组件边界） | 不改 create/delete/move-entry 字段与语义；FU-07、FU-20 在契约页新增独立小节；FU-20 不使用 LIKE 查找，`DEFER-LB-09` 其余读面不承接 |
| [`plan-20260904.md`](plan-20260904.md) | `land_api_tip_push` / `push_auth` 写鉴权 | 只消费；FU-06 只改落点解析 |
| `AGENTS.md` / `.cursor/rules/task-card-release.mdc` | Libra 工作流、三门、每卡 bump+commit+push | 遵守；模板 C 组的 tag + 手写 Release 同样执行 |

## 评审结论与修订记录

计划成稿前自审；Codex 计划评审结论写入 Review log，不预填 PASS。

| 维度 | 结论 | 修订动作 |
|---|---|---|
| 合理性 | 五个 issue 全部本地复现（E1–E12）；#28 所有者经原始字节确认为 Mega2 | 另登记分析中发现的 GAP-FU-10（直接阻断 #25 开通旅程） |
| 可行性 | 所需原语均已存在：`materialize_path_refs`、create-entry 树构建、B3 attach 队列、`audit_logs`、`format_commit_msg`、`escape_like`、`find_git_repo_exact_match` | 复用；新增两个有序迁移（FU-14 清理台账表、FU-15 存量别名路径规范化） |
| 任务卡粒度 | 19 卡，每卡单一行为轴；每条 AC 为一个具名用例或一个单谓词；后端原语、栅栏与机器接口按「表面轴」拆；跨多卡的用户旅程文档单列 `docs` 卡 | 见粒度审计表与计数口径 |
| 依赖与顺序 | 单链 FU-01→…→FU-23，无环；写集相交处全部有顺序边 | 见实施顺序 |
| 完整性 | 每张实现卡含测试与本轴契约文档；用户旅程文档由 FU-11 / FU-22 收口；FU-23 在最终树跑计划完成门 | 兼容与文档收口清单 |
| 安全性 | 新写端点复用 `authorize_trunk_api_write`；开通按「最高新建组件」授权；清理用绑定参数等值查找、转义 LIKE 子仓检查；全部 ImportRepo ref 写有行锁存活栅栏；审计不含凭据 | ADR-FU-05/09/10 |
| 功能正确性 | 分类只作用于「`old_id=ZERO` 且路径在根树不可解析」；存在路径与真实 NFF 零变化；ImportRepo ref 按标准 receive-pack 语义 CAS；tag 逐 ref 独立、同一 push 的分支批量原子（未广告 `atomic`） | ADR-FU-04/07/08 |
| 接口兼容 | 新增 API/CLI；推送拒绝文案变化；关闭 fork 型创建新顶层 → FU-10 `minor`；非法 `root_dirs` 配置改为启动前校验失败（今日已生成非法根树） | ADR-FU-04 |
| 数据流与控制流 | 所有 ref/树写仍经 MonoWriteQueue；detach 单事务原子（含审计）；行锁存活栅栏阻止陈旧 attach / tag / 删除写回；清扫锁外、按关联 id 续做 | ADR-FU-09 |
| 性能与容量 | 锁内只做 O(1) 行删除 + O(depth) 树重写；元数据按 ≤1000 行分批清扫 | 性能与容量摘要 |
| 可靠性与容错 | 清扫崩溃由同路径请求续做；ref CAS 失败有终态；开通竞态回落 `created:false` | 故障恢复矩阵 |
| 可维护性 | 消息分解/成帧单一 helper；路径分类单一函数；审计事务原语单一入口 | GC-FU-01/02 |

### 修订历史

| 日期 | 触发 | 变更内容 | 原卡 → 新卡 | 受影响的引用 |
|---|---|---|---|---|
| 2026-09-23 | 成稿 | 初版：issue #25–#29 分析、本地复现 E1–E12、ADR-FU-01..10、FU-01..FU-10 | N/A → FU-01..FU-10 | 全文 |
| 2026-09-23 | 计划 R1 Codex FAIL（3×P0、8×P1、1×P2） | P0：清理改为绑定参数等值查找 + 转义 LIKE 子仓检查（ADR-FU-10）；B3 attach 增存活栅栏并在拒绝后清扫陈旧行（ADR-FU-09 第 5 条）；detach 用 `op` 枚举与域分离 `detach_operation_id`（ADR-FU-09 第 1 条）。P1：事务内审计原语、保留 actor 语义与关联 id `cleanup_id`（第 3、6 条）；tag CAS 与逐 ref 语义（ADR-FU-08）；`root_dirs`/`import_dir` 形状校验、import 优先、开通按最高新建组件授权（ADR-FU-04/05）；消息字节级文法（ADR-FU-01）；按独立谓词重计 AC 并拆卡；Verification 改用真实模块名 `common::utils::test`、统一 `source .env.test &&`、零命中守卫全文展开；FU-18 作为最终树收口门，D 组精确绑定 tag 的 run 与 `docker` job；CLI 卡改 M。P2：测试 target 计数改为 15 | FU-01 → FU-01、FU-02；FU-02 → FU-03；（新）FU-04；FU-04 → FU-05、FU-07；FU-03 → FU-06；FU-05 → FU-08、FU-11；FU-06 → FU-09、FU-10；FU-07 → FU-12、FU-13；FU-08 → FU-14、FU-15；FU-09 → FU-16、FU-17；FU-10 → FU-18 | 全部 ADR、实施顺序、依赖登记表、发布顺序、粒度审计表、全部任务卡、测试矩阵、追溯表、里程碑、故障恢复、风险、性能、DEFER |
| 2026-09-23 | 计划 R2 Codex FAIL（2×P0、4×P1 含 1 条未关闭、2×P2） | P0：B3 真创建分支锁内再分类 + 非零 `old_id` 原始推送测试（ADR-FU-04 第 5 条，FU-10）；存活栅栏扩展到 tag 直写与仅删除分支写并改为行锁互斥（ADR-FU-09 第 5 条，新卡 FU-16）。P1：每条 AC 改为单一具名用例或单谓词并重计；所有 Verification 写出完整命令（去掉「同上」）；#28 AC1 由 FU-01 两个对照集成用例承接；#29 产品写口径由 FU-06 分类承接（ADR-FU-04 第 4 条、ADR-FU-06）；文档卡 scope 改 M。P2：Review 表 ADR 引用订正；`root_dirs` 拒绝反斜杠 | FU-14 栅栏部分 → FU-16（新）；FU-16 → FU-17；FU-17 → FU-18；FU-18 → FU-19 | ADR-FU-04/06/09、GAP 表、实施顺序、发布顺序、粒度审计表、FU-01/04/06/10/14..19 卡、测试矩阵、追溯表、里程碑、故障恢复、风险 |
| 2026-09-23 | 计划 R3 Codex FAIL（1×P0、2×P1） | P0：FU-16 栅栏扩展到 `ImportApiService` 的 edit/save、tag 创建/删除直写（单事务取锁）并删除 `DEFER-FU-08`（ADR-FU-09 第 5 条）。P1：ADR-FU-08 第 4 条改为「分支批量原子、tag 逐 ref 独立」，FU-13 用例改为两分支 + tag 混合推送，`DEFER-FU-05` 承接逐分支独立；FU-01 根对照 Verification 写出完整契约 | 卡号不变 | ADR-FU-08/09、GC-FU-03、GAP-FU-11、FU-01/13/16 卡、粒度审计表、追溯表、故障恢复、风险、DEFER |
| 2026-09-23 | 计划 R4 Codex FAIL（1×P0、5×P1） | P0：detach 事务内再检查子仓并定义「检查后注册的子仓为独立导入」（ADR-FU-09 第 2 条，FU-14 `fu14_detach_child_orderings`）。P1：审查表成败粒度措辞与 ADR-FU-08 对齐；清理端点改为语法校验后、任何查询前鉴权，新增无泄漏用例（ADR-FU-10 第 4 条，FU-18）；ADR-FU-02 与 FU-03 纳入 `ImportApiService::save_file_edit`；ADR-FU-09 第 5 条澄清单事务范围（对象行不入事务，由清扫回收）并把栅栏拆为 receive-pack（FU-16）与 `ImportApiService`（新 FU-17）；docs 卡守卫改为「只暂存 Deliverables + 暂存集子集校验」 | FU-16 → FU-16、FU-17（新）；FU-17 → FU-18；FU-18 → FU-19；FU-19 → FU-20 | ADR-FU-02/08/09/10、FU-03/14/16/17/18 卡与 docs 卡、实施顺序、发布顺序、粒度审计表、测试矩阵、追溯表、里程碑、风险、GC-FU-08 |
| 2026-09-23 | 计划 R5 Codex FAIL（1×P0、4×P1） | P0：祖先生命周期栅栏——detach 先 `FOR UPDATE` 锁自身行再查子仓（FU-14），子仓 `git_repo` 注册对祖先行取 `FOR SHARE`（FU-16，触及 `protocol/mod.rs`，加协议 smoke 门）。P1：清理端点鉴权失败固定响应体（`ApiError::status()`，FU-18 写集加 `src/common/errors/api.rs`）；C 组与 docs 卡暂存前快照、非空即停并交接；FU-06 加 `api_write_custom_root_dirs`，API 面 NFF 不适用登记 `DEFER-FU-08`；`import_dir` 拒 NUL 与 `\` | 卡号不变 | ADR-FU-04/09/10、ER 本地化、FU-04/06/14/16/18 与 docs 卡、粒度审计表、追溯表、风险、DEFER |
| 2026-09-23 | 计划 R6 Codex FAIL（1×P0、1×P1） | P0：HTTP 清理改用 `authorize_import_repo_removal`（只接受覆盖路径的 token，`push_auth=none` 一律 403，FU-18 写集加 `api_write_auth.rs`），新增 ADR-FU-11 与运维 CLI 卡 FU-19 覆盖无鉴权部署。P1：FU-16 协议 smoke 改为 fail-closed 完整脚本（隔离库/目录、后台启动、就绪轮询、日志、`trap` 清理、summary 断言） | 新增 FU-19；FU-19 → FU-20；FU-20 → FU-21 | ADR-FU-10/11、FU-16/18/20 卡、实施顺序、发布顺序、粒度审计表、测试矩阵、追溯表、里程碑、风险 |
| 2026-09-23 | 计划 R7 Codex FAIL（2×P1） | ADR-FU-09 第 5 条：栅栏前移到 `ImportService::save_entry` 的每批对象行插入（FU-16 写集加 `import_service.rs`），detach 之后无任何元数据行可写入，`swept` 为终态；移除「被拒后清扫」依赖；FU-16/17 用例改为 `fu16_object_writes_fenced_after_detach` / `fu17_edit_save_after_detach_writes_no_rows`。FU-16 协议 smoke：内含 `cargo build`、经 compose 解析 Postgres 容器、逐个选择 `HTTP clone` 与 `HTTP trunk push (none)`、在整份日志中断言 summary | 卡号不变 | ADR-FU-09、GC-FU-08、GAP-FU-11、FU-16/17 卡、粒度审计表、追溯表、故障恢复、风险 |
| 2026-09-23 | 计划 R8 Codex FAIL（2×P1） | FU-16 smoke 在起服务前对隔离库执行 `service init --yes`；ADR-FU-04/06 与 FU-06 增加无条件 import 命名空间守卫（`MonoApiService` 写路径位于 `import_dir` 下一律 `MONO_PATH_NOT_ALLOWED`，与是否已物化、是否刚清理无关），用例改为 `api_write_import_namespace_guard` | 卡号不变 | ADR-FU-04/06、FU-06/16 卡、风险 |
| 2026-09-23 | 计划 R9 Codex FAIL（3×P0、2×P1） | P0：ADR-FU-06 守卫覆盖 move 源与目的，FU-06 用例 (c)；ADR-FU-08 第 1 条改为持久挂载来源记录（`audit_logs` + 存量 `.gitkeep`-only 回填），ADR-FU-09 清理只移除有来源记录的叶子；FU-12/FU-13 互换——CAS（FU-12）先于更新开放（FU-13）发布，`log_audit_in_txn` 前移到 FU-13。P1：FU-04 改 `minor`，后续版本整体重算；D 组改为按 tag 与提交 SHA 有界轮询 | FU-12 ↔ FU-13 内容互换 | ADR-FU-06/08/09、ER 本地化 D 组、FU-04/06/12/13/14/20 卡、默认覆盖、粒度审计表、发布顺序、里程碑、追溯表、风险 |
| 2026-09-23 | 计划 R10 Codex FAIL（3×P1） | 新增迁移卡 FU-14（`import_repo_cleanups` 台账 + `(path, state)` 索引），ADR-FU-09 第 6 条续做改为按台账有界查询、审计仅作证据；ADR-FU-08 第 7 条与 ADR-FU-10 第 1 条引入唯一严格叶子校验 `strict_import_repo_leaf_input`，协议分派拒绝 `import_dir` 本身（FU-17 `import_root_push_rejected`，`DEFER-FU-09` 登记存量根行）；FU-04 同步三份样例配置注释并以具名用例 `shipped_configs_pass_monorepo_shape` 合并样例校验 | 新增 FU-14；FU-14..FU-21 → FU-15..FU-22（测试名前缀同步） | ADR-FU-04/08/09/10、事实基线迁移行、FU-04/14..17 卡、实施顺序、发布顺序、粒度审计表、测试矩阵、追溯表、里程碑、默认覆盖、DEFER |
| 2026-09-23 | 基线全量测试 | 登记规范测试栈（`-p mega2-it --profile git`）与 6 个本机环境失败用例；ER 本地化新增「本机基线环境失败」口径；新增 `DEP-FU-05` | 卡号不变 | 事实基线、ER 本地化、依赖登记表 |
| 2026-09-23 | 计划 R11 Codex FAIL（2×P1） | C 组 ③ 改为 `cargo test --all --no-fail-fast` 且要求全部 target 已运行后再比对；FU-04 三份样例注释合并为具名用例 `monorepo_shipped_config_comments`，Verification 拆为独立行，重计 AC 7/8、VER 6/8 | 卡号不变 | ER 本地化 C 组、FU-04 卡、粒度审计表 |
| 2026-09-23 | 计划 R12 Codex FAIL（5×P1） | 重计 FU-05/07/11/18/19/21/22 的 VER；ADR-FU-04 第 2 条与 ADR-FU-10 第 1 条要求显式拒绝 NUL/`\` 与原始输入不变量 `input == canonicalize_mono_ref_path(input)`，FU-05/10/17/19 用例补别名与 NUL；FU-17 smoke 的 compose 查找加 `-p mega2-it`；C 组覆盖 `migration` 卡（FU-14） | 卡号不变 | ADR-FU-04/10、ER 本地化 C 组、FU-05/07/10/11/17/18/19/21/22 卡、粒度审计表 |
| 2026-09-23 | 计划 R13/R14 Codex FAIL（R13 3×P1 + R14 新增 2×P1） | FU-07 VER 7/8、FU-10 VER 6/8；FU-04 storage-only 样例改为替换 secret 占位符后的临时副本校验，`shipped_configs_pass_monorepo_shape` 只校验 `[monorepo]` 段；ER 本地化写明 A/B → locally-accepted → 评审 PASS → C → D；ADR-FU-09 第 5 条与 FU-17 纳入 `traverses_tree_and_update_filepath`（先存活检查、去 `unwrap()`）；ADR-FU-09 第 4/6 条、ADR-FU-10 第 5 条、ADR-FU-11 引入每请求固定预算（16 条台账行、100 批）与 `pending` 结局，FU-16/19/20 用例相应调整 | 卡号不变 | ADR-FU-09/10/11、ER 本地化、FU-04/07/10/16/17/19/20 卡、粒度审计表、性能摘要、测试矩阵 |
| 2026-09-23 | 计划 R15 Codex FAIL（4×P1） | 台账索引改 `(path, state, id)` 且续做查询固定为 `ORDER BY id ASC LIMIT 16`，FU-14 `EXPLAIN` 断言无 Sort；FU-17 写集补 `path_policy.rs`；FU-15 依赖统一为 FU-14；FU-22 改为 `release` 卡执行完整 C/D（`0.40.10`），FU-21 继承其覆盖 | FU-22 `docs` → `release` | ADR-FU-09、ER 本地化、FU-14/15/17/21/22 卡、默认覆盖、粒度审计表、发布顺序、里程碑、完成判据 |
| 2026-09-23 | 计划 R16 Codex FAIL（2×P1） | ADR-FU-03 第 2 条改为「每个码在首次对用户暴露它的卡中登记 `docs/errors.md`」：FU-12 `STALE_REF`、FU-13 `PATH_OCCUPIED`、FU-17 `REMOVED`/`PATH_INVALID`、FU-19 `HAS_CHILDREN`；相应合并用例保持 AC ≤ 8，FU-21 去掉 errors.md 项（AC 11/20）；FU-22 VER 10/12 | 卡号不变 | ADR-FU-03、默认覆盖、FU-13/17/19/21/22 卡、粒度审计表、追溯表、兼容收口 |
| 2026-09-23 | 计划 R17 Codex FAIL（2×P1） | FU-13 VER 6/8；FU-19 复核为 7/8（三条测试命令 + 零命中守卫 + 文档行三门）；全部卡 VER 经脚本按计数口径复算一致 | 卡号不变 | FU-13 卡、粒度审计表、Review log |
| 2026-09-23 | 计划 R18 Codex FAIL（1×P0、1×P1） | P0：ADR-FU-10 第 5 条续做显式化——请求带 `cleanup_id` 才是续做且永不 detach 存活仓库，新增 `IMPORT_REPO_CLEANUP_NOT_FOUND`（404，FU-12 错误域、FU-20 登记），FU-17/20/21 用例相应调整。P1：新增迁移卡 FU-15 一次性规范化存量别名行（冲突保留并告警，`DEFER-FU-10`）；ADR-FU-04 第 2 条与 ADR-FU-08 第 7 条、ADR-FU-10 第 1 条区分「JSON 严格入口」与「协议 URL 经 TP-08 规范化」（Libra 尾斜杠远端不被拒绝），叶子校验拆为核心 `check_import_repo_leaf` 与严格入口 | 新增 FU-15；FU-15..FU-22 → FU-16..FU-23（测试名前缀同步） | ADR-FU-03/04/08/10、FU-05/10/12/15..FU-21 卡、实施顺序、发布顺序、粒度审计表、追溯表、里程碑、默认覆盖、DEFER |
| 2026-09-23 | 计划 R19 Codex FAIL（1×P1） | FU-15 迁移改为与配置无关：按行判定 `repo_path != canonicalize_mono_ref_path(repo_path)` 覆盖全部 `git_repo` 行（该表只由 ImportRepo 协议分派写入），新增具名用例 `import_repo_alias_non_default_import_dir`（AC 7/8） | 卡号不变 | FU-15 卡、粒度审计表 |
| 2026-09-23 | 计划 R20 Codex FAIL（1×P1） | 事实基线迁移行、自审可行性、Rollback / Migration 默认、兼容收口与 FU-23 release note AC 统一声明两个有序迁移（FU-14、FU-15）及 FU-15 的不可逆改写、冲突保留与告警 | 卡号不变 | 事实基线、评审结论表、字段默认、兼容收口、FU-23 |
| 2026-09-23 | 计划 R21 Codex FAIL（1×P1） | ADR-FU-04 第 1 条与 FU-04 要求 `import_dir` 首组件属于 `root_dirs`（`monorepo_import_dir_shape` 断言 `root_dirs=["project"]`+`import_dir="/vendor"` 被拒）；FU-18 `import_root_push_rejected` 追加「首推不改变根树顶层名集合」断言；风险表同步 | 卡号不变 | ADR-FU-04、FU-04/18 卡、风险 |
| 2026-09-23 | 计划 R22 Codex PASS | 计划评审闭环，Phase 0 退出；进入 FU-01 | 卡号不变 | 状态横幅、Review log |
| 2026-09-23 | FU-01 评审 P2 | ADR-FU-01 第 1 条的返回类型文字与实现对齐（`headers: Vec<(&str, String)>`，键借用） | 卡号不变 | ADR-FU-01 |
| 2026-09-23 | FU-01 C 组执行 | C 组 ① 版本面 parity 预检命令改为排除 `target/` 与 `.libra/` 的 `find`（原 `rg -l --glob` 扫描巨大的 `target/` 超时） | 卡号不变 | 执行检查必备需求 C 组 |
| 2026-09-24 | FU-02 R1 Codex FAIL（3×P1） | ADR-FU-01 第 5 条澄清：物化取完整正文，attach 根 commit 保持既有只取主题行语义（与 FU-02 AC/Verification 一致）；FU-02 新增真实 attach 路径用例 `fu02_attach_root_commit_uses_signed_tip_subject`（写集加 `import_repo.rs` 测试模块，AC 6/8、VER 5/8）；FU-01 收尾（D 组绿灯、勾选）拆为独立提交 `b76d04d` | 卡号不变 | ADR-FU-01、FU-02、粒度审计表 |
| 2026-09-24 | FU-03 执行（ER-10 本卡轴内） | Current evidence 订正：`mono_api_service.rs:964`（`process_ref_updates_cl_only`）为签名路径，移出成帧范围并登记于 Out of scope；登记 `tp16_review_merge_keeps_from_tree_id_shape` 断言随成帧更新；`deploy-trunk.md` 规避改为 `fetch.fsck.skipList`（`unterminatedHeader` 为 Git 不可降级的致命类检查，实测） | 卡号不变 | FU-03 |
| 2026-09-24 | FU-04 执行（ER-10 本卡轴内） | Verification 首条命令补 `shipped_configs_pass_monorepo_shape` 过滤（原 `monorepo_` 子串匹配不到该具名用例）；写集补 `src/config/reload.rs`、`tests/integration_vault.rs` 两处测试数据（其候选配置的 `import_dir` 首组件不在 `root_dirs`，新校验下会被拒） | 卡号不变 | FU-04 |
| 2026-09-24 | FU-04 R1 Codex FAIL（1×P1）+ Claude FAIL（2×P1） | ADR-FU-04 第 1 条补：`root_dirs` 拒绝 `init_trees` 自带根条目名（`INIT_ROOT_RESERVED_NAMES`）、`.git`（不区分大小写）与首尾空白；storage-only 样例 `import_dir` 注释补 NUL / `\` 并纳入注释断言；`docs/manual/monorepo-init.md`、`docs/monorepo.md` 的「只校验非空 / 引擎不强制 / 已知缺口」描述随行为更新并纳入写集；兼容说明补 `import_dir` | 卡号不变 | ADR-FU-04、FU-04 |
| 2026-09-24 | FU-04 R2 Codex PASS + Claude PASS（4×P2） | 措辞「首次 `service init`」改为「首次初始化（`service init` 或空库首次启动）」；保留名常量改为与 `init_trees` 双向断言；粒度 `prod-files=2`、审计表 `1/2`、追溯表补 `converter.rs` 与文档；新增 `DEFER-FU-11`（其余 Git 特殊名） | 卡号不变 | FU-04、粒度审计表、追溯表、DEFER |
| 2026-09-24 | FU-05 R1 Codex FAIL（1×P1）+ Claude PASS（10×P2） | `PathPolicyError` 文本恒单行（根名 / 原因 / 开通命令路径转义控制字符）；`MegaError::PathPolicy → GitError` 带 `[code:400/409]` 标记；`ApiError` 对裸 / 包装的 `PathPolicyError` 按类型映射且原样输出（`[code:…]` 字样不截断）；分类拒绝 NUL；导出 `in_import_namespace` / `is_import_dir_ancestor` / `not_allowed`；ADR-FU-06 与 GC-FU-04 补「不物化嵌套 `import_dir` 的严格祖先」；`docs/errors.md` 类型表与措辞 | 卡号不变 | ADR-FU-06、GC-FU-04、FU-05 |
| 2026-09-24 | FU-06 执行（ER-10 本卡轴内） | `api_write_custom_root_dirs` 改用 `root_dirs=["apps","third-party"]`（FU-04 形状约束）；`fresh_stack_concurrent_writes` 改为两个不同一级根并发（同路径并发受既有 ADR-TP-10 约束，新增 `DEFER-FU-12`）；写集补 `docs/refactoring/directory-entry-api.md`；兼容说明补 `/` 落地写的文本变化与存活 ImportRepo 目的地保留 409 | 卡号不变 | FU-06、DEFER |
| 2026-09-24 | FU-06 R1 Codex FAIL（1×P1）+ Claude FAIL（1×P1 + 7×P2） | 守卫下沉为 `path_policy::check_write_operands`（组件判定，不再因 `\` 误拒，`..` 给出准确原因）并单测平铺 / 嵌套 / 祖先删除；回落以用户写的路径分类并点名；`api_write_import_namespace_guard` 改用真实内容（导入后删 `git_repo` 行 + 手工 `main@/third-party`）；嵌套 `import_dir` 栈覆盖 409 `MONO_PATH_UNINITIALIZED` 与目的地守卫；文档区分存活 ImportRepo（行为不变）与无存活仓库的命名空间（400）、ADR-TP-10 按同一落点 tip 描述、开通命令待 FU-07/08；新增 `DEFER-FU-13` | 卡号不变 | FU-06、DEFER |
| 2026-09-24 | FU-06 R2 Codex PASS（1×P2）+ Claude PASS（4×P2） | `MONO_PATH_UNINITIALIZED` 点名写入所在目录（文件写 / 删除 / move 为父目录，新建目录为其本身）；非法顶层名一律 `NotAllowed` 点名用户路径；文档区分「从父目录删除 / 移动挂载叶子（不论存活）→ 400」与「存活仓库内部 → 行为不变」、点名 `/` 仅限跨顶层 move 与删除顶层目录；用例补存活叶子父级 delete / 改名与文件创建提示；粒度 `prod-files=2`、审计表 `1/2`、追溯表、Verification (b)(c) 描述 | 卡号不变 | FU-06、粒度审计表、追溯表 |
| 2026-09-24 | FU-07 执行（ER-10 本卡轴内） | 写集补 `src/api/api_router.rs`（开通路由只合并进 storage-only 表面）；实现形态：`PathProvisioner` trait（`MonoApiService` 实现 plan / apply）+ 可单测的 `run_path_provision` 重试循环（先以目标路径鉴权预检，再每轮按最高新建组件鉴权；4xx 不重试，至多 10 轮）；同路径并发经 ADR-TP-10 冲突后重规划返回 `created:false` | 卡号不变 | FU-07 |
| 2026-09-24 | FU-07 R1 Codex FAIL（1×P0）+ Claude FAIL（2×P1） | apply 改为自有建树：同一快照遍历、推导最高新建组件并与已鉴权计划比对（不同 → 不写、`ApplyOutcome::Retry` 重规划重鉴权），新建层级处任何同名条目 → `MONO_PATH_CONFLICT`，`TreeCommitInput.expected_bases` 让 `commit_tree_update` 在落点 tip 的 tree 与快照不一致时返回可重试的过期标记（关闭丢失更新窗口）；重试只针对类型化 Retry（过期快照 / ADR-TP-10 / non-fast-forward），末轮不等待；不再复用 `prepare_create_entry_update`（其子串推导使 `/project/pro/x` 等失败）；新增 `fu07_apply_bound_to_plan` 与重名多级回归；契约页补状态表 / 鉴权 / 形态 / JSON 解析失败的纯文本 4xx / 两项已知限制；新增 `DEFER-FU-14`，ADR-FU-04 运维新增根流程改为 `git push` | 卡号不变 | ADR-FU-04、FU-07、DEFER |
| 2026-09-24 | FU-07 R2 Codex FAIL（2×P1 + 1×P2）+ Claude PASS（5×P2） | 重试判定类型化：`[code:…]` 错误恒不重试，过期快照按常量相等，队列拒绝按固定服务端文本（去掉固定前缀后前缀匹配，含墓碑 / 缺失路径）；每次尝试的 `.gitkeep` 内容唯一（UUID），并发尝试不再构造相同 commit 而被队列重放；`highest_new=None` 的计划在 apply 早返回；严格入口拒绝控制字符；新增 `fu07_retry_reasons_are_typed`、`fu07_concurrent_apply_one_lands`（真实 trunk 存储并发 apply 恰一个落地）、嵌套 `import_dir` 下路径拼出重试文本仍返回 409 的 HTTP 回归、Barrier 同步的并发开通；ADR-FU-05 第 1 条与契约页改述建树方式；`DEFER-FU-14` 补 FU-10 互指说明 | 卡号不变 | ADR-FU-05、FU-07、DEFER |
| 2026-09-24 | FU-08 执行（ER-10 本卡轴内） | CLI 对回环地址（127.0.0.0/8、::1、localhost）的 `--server` 直连、不经代理（实测：子进程清空环境后 reqwest 回落到 macOS 系统代理，回环请求得 502；代理不可能到达调用方自身的回环）；远程地址仍按环境 / 系统代理；同源重定向才跟随（至多 5 次），跨源返回错误不跟随 | 卡号不变 | FU-08 |
| 2026-09-24 | FU-08 R1 Codex FAIL（3×P1 + 1×P2）+ Claude PASS（11×P2） | 错误文本不回显 secret：拒绝带凭据 / query / fragment 的 `--server`、错误只显示 origin、服务端回显的 token 以 `***` 脱敏、非 JSON 响应体不回显；响应体读取上限 64 KiB（含 chunked）；成功响应按 `CommonResult<PathProvisionResult>` 契约校验（`req_result`、路径一致、`created` 与 `commit_id` 一致）；强制代理下回环直连的真实回归（对照组经代理）；`MEGA2_TOKEN` 用 `var_os` 读取、拒绝非 UTF-8 与控制字符、`bearer_auth`（敏感头）；传输错误带原因（超时单列）；重定向错误给出状态与目标 origin；补同源重定向与上限、超时耗时、token 读取、不读配置反证（缺失 `MEGA_CONFIG` + 空 base 目录不产生文件）；新增 `DEFER-FU-15`（Ctrl-C 退出码） | 卡号不变 | FU-08、DEFER |
| 2026-09-24 | 用户决定：blame 修复独立成卡 | 新增 FU-04A（blame `commit_message` / `commit_summary` 取源正文；来源 FU-03 R1 Claude P2；实现由独立会话完成，本会话按 ER-12 评审与发布）；卡片置于 FU-04 之后，发布链插入 FU-08 与 FU-09 之间：FU-04A `0.39.5`、FU-09 `0.39.6`，FU-10 起版本不变 | 新增 FU-04A；其余卡号不变 | 实施顺序（`FU-08 -> FU-04A -> FU-09`）、发布顺序、Phase 2 退出条件、粒度审计表、FU-09 依赖（改为 FU-04A）、测试矩阵、追溯表、里程碑 M2、FU-03 状态与 Review log 互指 |
| 2026-09-24 | FU-04A R1 Codex FAIL（4×P1）+ Claude FAIL（1×P1 + 5×P2） | 新增真实 blame 路径回归 `import_repo_blame_summary_framed`（写集加 `tests/integration_api_write_trunk.rs`）与 `blame_commit_text_unframed_multiline_legacy`；AC 拆为单一谓词（8/8）、VER 5/8；Lifecycle / Acceptance 改为 `in-progress` / `locally-accepted`；Phase 2 退出条件含 FU-04A；依赖边与卡字段对齐（FU-04A deps=FU-08，FU-09 deps=FU-04A，去掉冗余边 `FU-08 -> FU-09`）；手工证据改为 ImportRepo 未签名推送（trunk blame 归因到 PGP 签名层 commit，无法区分新旧）；Out of scope 理由订正并新增 `DEFER-FU-16`；兼容说明补多行历史消息与 `mergetag` / `encoding` | 卡号不变 | FU-04A、FU-09、实施顺序、Phase 2、粒度审计表、测试矩阵、追溯表、DEFER |
| 2026-09-24 | FU-04A R2 Codex PASS + Claude PASS（2×P2） | `format_message()` 外露面的措辞订正为「SSH 签名、`encoding` 头以及与 `gpgsig` 同时出现的 `mergetag`」（`gpgsig-sha256` 配 PGP 装甲与单独的 `mergetag` 已被正确剥离）；`blame_commit_text_unframed_multiline_legacy` 注释措辞（仅注释） | 卡号不变 | FU-04A Out of scope、DEFER-FU-16 |
| 2026-09-24 | FU-09 R1 Codex FAIL（1×P1） | 孤儿拒绝类型化为专用变体 `MegaError::OrphanChain`（显示文本保留 `Other error: Can not init directory under monorepo directory!`，ng 行逐字节不变；`monorepo.rs` 中同文本的 CL 分支错误仍为 `Other`，二者可区分）；写集补 `src/common/errors/mod.rs`；用例改为 `matches!` 断言变体 | 卡号不变 | FU-09 |
| 2026-09-24 | FU-09 R1 Claude PASS（7×P2） | 孤儿拒绝的描述按情形区分（新 tip：途中无可作 fork 的已知 commit；已知 tip：pack 链走到根即是，含已被其它 ref 引用的历史），`push_chain.rs` / `errors/mod.rs` 注释与 `trunk-push.md` 同步，并注明不证明历史未被引用；`from_known_tip` 文档注释补零 `old_id` 返回 `OrphanChain`；`docs/errors.md` 登记新变体（写集补）；`fu09_review_orphan_retry_text` 改走 `validate_incoming_push`；FU-10 交接：Description 注明 `is_orphan_chain_error` 的语义边界，Verification 增 `orphan_retry_same_rejection`（断言随码更新，VER 7/8）；既有的「再加一个 commit」绕过登记 `DEFER-FU-17`；`monorepo.rs` 中 ZERO 基线下已不可达的同文本分支保持不动（非本卡轴） | 卡号不变 | FU-09、FU-10、粒度审计表、DEFER |
| 2026-09-24 | FU-09 R2 Codex PASS（1×P2）+ Claude PASS（3×P2） | `orphan_chain_error` 注释「每次重试」限定为「对同一条链的原样重试」（额外 commit 绕过见 `DEFER-FU-17`）；FU-10 Out of scope 指向 `DEFER-FU-17`；兼容收口的 `docs/errors.md` 清单补 `MegaError::OrphanChain`（FU-09）；`errors.md` 为该变体单列小节；注释折行与 `trunk-push.md` 句序（仅文字） | 卡号不变 | FU-09、FU-10、兼容与文档收口 |
| 2026-09-24 | FU-10 执行（ER-10 本卡轴内） | 准入门以 `trunk_creation_path` 判定创建（`old_id` 为零、无 `main` 行、**无墓碑**（墓碑保留其自身拒绝）、根树中不可解析为目录），分类先于链解析；孤儿映射只作用于创建路径，已可解析 / 有行 / 有墓碑的路径仍得到 FU-09 的孤儿拒绝。B3 锁内再分类沿用既有失败类别 `PushFailure`（`push_queue_failure_enum` 无新值），拒绝经队列失败消息返回，`ng` 行为 `Other error: <CODE>: …`（码不在行首，仅竞态下出现，已写入 `trunk-push.md`）。写集补 `docs/errors.md`（`OrphanChain` 条目的 trunk 映射）；`DEFER-FU-17` 评估为不合入（见 FU-10 Out of scope）；手工证据改用本机 Libra 0.23.58（0.23.46 已不在本机）；既有 B3 单测 `tp12_create_n1_and_n2_and_multilevel` 用顶层新路径（`/p12c1`、`/p12c2`、`/a/b/c`）验证创建语义，正是本卡关闭的「创建新顶层」，测试数据改为 `/project/…`（断言不变），写集补 `mono_api_service.rs`（仅测试） | 卡号不变 | FU-10、DEFER |
| 2026-09-24 | FU-10 R1 Codex FAIL（1×P1 + 1×P2）+ Claude PASS（8×P2） | B3 竞态拒绝由 `finalize_trunk_push` 的 `typed_creation_rejection` 还原为类型化 `PathPolicyError`（队列消息恰为 `Other error: <同一分类错误>` 时），`ng` 行保持以码开头，`trunk-push.md` 同步；用例补：非创建路径（墓碑、可解析无行）上的孤儿仍为 `OrphanChain`、B3 行 `failure_type = PushFailure`、原始非零 `old_id` 推送改用合法第一父步并断言 B3 的 `cannot update missing path`；尾斜杠说明订正（客户端去尾斜杠，Monorepo 分派无服务端规范化 → `DEFER-FU-18`）；新增 `DEFER-FU-19`（文件路径上的创建）、`DEFER-FU-20`（嵌套 `import_dir` 严格祖先的 Git 面创建）；`DEFER-FU-14` 指向 `trunk-push.md` 新增说明；Description 补「无墓碑」，Verification 的 `root_dirs` 与原始推送描述、测试矩阵 Libra 版本、追溯表订正；注释与文档注释顺序；证据按终态完整重跑（P1） | 卡号不变 | FU-10、测试矩阵、追溯表、DEFER |
| 2026-09-24 | FU-10 R2 Codex PASS（无发现）+ Claude PASS（3×P2） | `fu10_b3_creation_reclassifies_under_lock` 改为经 `finalize_trunk_push` 端到端断言类型化 `NotAllowed` 并校验队列行 `error_message` 以码开头（去掉 `map_err` 接线时该用例失败，已实测）；可选项「识别 `Rejected` 形式的队列消息」不采纳：推送行只由等待中的推送者执行 B3，生产中无可达路径（评审员核实）；证据中 clippy 退出码由 C 组门记录 | 卡号不变 | FU-10 |
| 2026-09-24 | FU-11 执行（ER-10 本卡轴内） | 权威小节放在 `user-guide(.zh).md` 第 2.5 节（不重排既有节号，其它文档对「第 4.2 节」「第 6 节」等的引用不变）；quick-start 示例经 `docker compose exec mega2 mega2 path provision` 在评估栈容器内开通（容器内端口：macOS 版 8000、Linux 版 9000，沿用该文档按平台二选一的写法），并注明本机 CLI 与 `MEGA2_TOKEN` 的用法；英文初始化手册结构与中文不同（文档整合后），说明段落分别放在两者的「初始化后的根树」小节之后；`errors.md` 的 Git 面场景登记 `NOT_ALLOWED` / `UNINITIALIZED` / `INVALID`（`DEFER-FU-18`）并注明 `CONFLICT` 不在 Git 面出现（`DEFER-FU-19`） | 卡号不变 | FU-11 |
| 2026-09-24 | FU-11 R1 Codex FAIL（4×P1）+ Claude PASS（10×P2） | README 与 quick-start 的首推说法收窄为「从零开始的历史 / 尚不存在的 Monorepo 路径」（fork 型推送在允许的根下被接受）；quick-start 以 `case "$COMPOSE" in macos-*) PORT=8000 ;; *) PORT=9000 ;; esac` 选择容器内端口，并注明需要 0.39.4 及以上镜像；使用指南 2.5 节的错误码改为「码 + 动作」列表并链接 `errors.md`（不复制契约表），英文版注明两份契约页为中文、HTTP 细节另见运行时 OpenAPI；三类首推表：拒绝与原样重试同一拒绝、第二类含「原样推送另一路径的历史」、第三类要求至少新增一个 commit 并注明 `max_push_commits`（默认 250）限制；产品写与新增根的说法限定为「已位于根树中的根」；`CONFLICT` 标注只由开通与产品写返回；初始化手册限定白名单为 `root_dirs` 所列目录（不含 `.cedar/` 与 Buck 文件）并去掉与使用指南重复的新增根说明；`errors.md` 的 `UNINITIALIZED` 场景改为「链为孤儿（含原样推送已知历史）」。不采纳 Codex P1「Git URL 先规范化、`INVALID` 不在 Git 面出现」：`contract/git_protocol/path.rs` 的 `normalize_repo_path` 只去掉 `.git`，`canonicalize_mono_ref_path` 只在 ImportRepo 分派调用（`protocol/mod.rs:239-246`），实测向 `/project//fu11raw/git-receive-pack` 发送的原始 receive-pack 得到 `ng refs/heads/main MONO_PATH_INVALID: "/project//fu11raw": path is not canonical`，`errors.md` 相应补充代码位置。流程：本卡提交前在工作区开始了 FU-12（`src/common/errors/{api,mod}.rs`、`push_queue_service.rs`、`git_db_storage.rs`、`import_repo.rs`），已移出工作区暂存，本卡提交推送后恢复 | 卡号不变 | FU-11 |
| 2026-09-24 | FU-11 R2 Codex PASS + Claude PASS（4×P2） | `MONO_PATH_CONFLICT` 标注改为「只由开通返回（API 与 CLI）」（`Conflict` 只在开通计划 / 落地中构造）；中文 HTTP 条目补「运行时 OpenAPI（第 4.4 节）」；推送长度上限说明覆盖第二、三类情形（上限拒绝不带路径策略码、原样重试文本可能不同；新增的根无法开通时 clone 历史较短的路径再推送），表前重试句限定为两种路径策略拒绝；证据按终态重跑 Verification #1 | 卡号不变 | FU-11 |
| 2026-09-24 | FU-12 执行（ER-10 本卡轴内） | CAS 写原语为单条条件语句：`create_ref_if_absent`（`INSERT … ON CONFLICT (repo_id, ref_name) DO NOTHING`，依赖既有唯一索引 `uniq_ref_path_name`，冲突不中止事务）、`update_ref_if_unchanged`（`UPDATE … WHERE ref_git_id = old_id`），删除沿用 `remove_ref_if_unchanged`；分支批 CAS 失败按既有 `.gitkeep` 失败的方式回滚到 savepoint `b3_kind` 并以 `AttachFailure` 终态化，消息为 `IMPORT_REPO_STALE_REF` 原文；只含删除、不入队的分支批（`attach_to_monorepo_parent`）CAS 失败同样返回 `IMPORT_REPO_STALE_REF`（ADR-FU-08 第 2 条），既有用例 `attach_delete_stale_old_id_does_not_remove_moved_ref` 的断言随之改为该变体；经队列的分支批失败文本在 FU-13 之前仍被 `attach B3 did not complete successfully: …` 包裹（`errors.md` 如实登记） | 卡号不变 | FU-12 |
| 2026-09-24 | FU-12 R1 Codex FAIL（2×P1）+ Claude PASS（9×P2） | 分支 CAS 移到 `.gitkeep` 写入（对象存储与 `mega_blob` 行在 SAVEPOINT 之外）之前，陈旧批不留孤儿 blob；只含删除的分支批删除默认分支后按 B3 同一规则补默认分支（新增 `fu12_delete_only_keeps_a_default_branch`）；`Create` 冲突文本为 `already exists`；用例补：批内陈旧 `Delete`、`failure = AttachFailure`、无新增 `mega_blob` 行、tag 成功创建 / 精确更新 / 删除、六个变体全部字段的单行转义；`errors.md` 注明队列批失败文本为 Debug 转义且回放行另有包装；卡片描述订正为「单条原子条件语句」；`api.rs` 变量改名 `contract_status`；新增 `DEFER-FU-21`（unpack 失败仍写 tag）、`DEFER-FU-22`（`edit/save` 更新丢失，FU-13 前登记）；AGENTS.md 中 sea-orm 版本（实为 2.0.2）不在写集，未改 | 卡号不变 | FU-12、DEFER |
| 2026-09-24 | FU-12 R2 Codex FAIL（1×P1）+ Claude PASS（4×P2） | 评审证据补跑 AGENTS.md 三门（`source .env.test && cargo test --all`、`cargo build`、`cargo build --tests`，于 bump 前的树上；C 组仍在 bump 后重跑）；Verification 与兼容说明补批内陈旧 `Delete`、无新增 `mega_blob` 行、`already exists`、纯删除批的默认分支接任；`DEFER-FU-22` 点名 tag 删除按名称无条件；`errors.md` 的 StaleRef 含义补「或 API 写入」；`stale_ref_detail` 不复用 `is_protocol_zero_id`（错误模块不依赖协议工具，保留） | 卡号不变 | FU-12、DEFER |
| 2026-09-24 | FU-13 执行（ER-10 本卡轴内） | B3 attach 在 savepoint 之后按根树判定叶子：不存在 → 首次挂载，来源记录在 savepoint 内先写（建树、分支 CAS、`.gitkeep`、根 CAS 任一失败时与挂载一并回滚，`fu13_first_attach_records_provenance` 以批内陈旧分支注入）；已是目录且有来源记录，或只含 `.gitkeep` 且仓库已有分支（惰性回填来源记录）→ 只做分支 CAS 与默认分支补位、行以当前根 commit 终态 `Done`（`root_cas_writes=0`）；其余（普通目录、文件、只含 `.gitkeep` 但无分支）→ `IMPORT_REPO_PATH_OCCUPIED`、根树不变。物化预检失败保留其原有明细（I3 祖先 / 后代 / 目标已物化），不改为 `OCCUPIED`：它守护的是已物化 Monorepo 路径而非挂载归属，既有用例依赖其明细。客户端文本：队列只回传字符串，`attach_refusal` 以挂载路径与本次分支命令构造候选 `ImportRepoError`、取显示文本逐字相同者还原为类型化错误，其余为 `ImportRepo attach failed: <原因>`（无 Debug）。`log_audit` 委托新的 `log_audit_in_txn`；来源记录 `actor_type=human`、`actor_id=0`、`action=create`、`target_type=repository`、`metadata={kind:"import_repo.attach", path}`。手工证据改用本机 Libra 0.23.58 | 卡号不变 | FU-13 |
| 2026-09-24 | FU-13 R1 Codex PASS + Claude FAIL（1×P1 + 6×P2） | P1：Done 行是操作 id 的永久重放键，更新 / 强推 / 删除后重复出现的同一组命令被静默重放（客户端 ok、ref 不动）——`attach_to_monorepo_parent` 在 `Replayed` 时核对本次分支命令是否已生效，否则以带 UUID 的新操作 id 重新入队（至多一次），新增 `import_repo_repeated_transition_applies`（A→B、强推回 A、再 A→B；创建 / 删除 / 重建分支）与 `fu13_replayed_attach_rechecks_refs`；ADR-FU-08 第 1 条随之补写。P2：ADR-FU-08 第 1 条订正物化预检保留 I3 明细；Consequences 与第 6 条订正嵌套先子后父与带子仓的存量父挂载（→ `DEFER-FU-23`）；`errors.md` 场景补「后续推送也可能 OCCUPIED」与其余客户端文本；来源记录按 ADR 只含 `{kind, path}`（去掉恒为空的 `requester`），重新挂载不再重复写入；用例补：有分支无记录的普通目录（堵住去掉 `.gitkeep` 条件的变异）、文件叶子、父仓库在子仓挂载后更新、`attach_refusal` 纯函数用例、回填后根不变；评审证据补全量三门 | 卡号不变 | ADR-FU-08、FU-13、DEFER |
| 2026-09-24 | FU-13 R2 Codex FAIL（1×P1 + 1×P2）+ Claude PASS（3×P2） | 不采纳 Codex P1「全量须零失败零警告」：失败集恰为「执行检查必备需求」登记的 6 个本机基线环境用例（DEP-FU-05：宿主 `git-lfs` 3.8.0 与固定 3.7.1、Docker registry 凭据、S3 经 macOS 系统代理 502），`cargo build --tests` 的唯一提示是基线同有的 macOS `ld` `__eh_frame` 链接器提示；修复需要下载安装软件、配置凭据或修改系统代理（不在本代理可执行范围，已登记由用户处理），各卡一直按该口径执行。落实：父仓库在子仓挂载后的更新断言 ref 前进到 c3、无分支叶子拒绝前后根不变；`errors.md` 回落文本补 `Other error: ` 前缀；Verification 补 `ceres::pack::import_repo::tests::fu13_` 与新增用例说明（VER 7/8，审计表同步）；证据中沿用 R1 的块加标注 | 卡号不变 | FU-13、粒度审计表 |
| 2026-09-24 | FU-13 R3 Codex FAIL（1×P1） | Codex 认可基线环境项属 DEP-FU-05 登记例外；新 P1：`attach_refusal` 把未归类的 B3 失败文本（可能含存储 / DB 内部信息）原样转给客户端——改为只还原类型化错误与 `attach refused: … (I3)` 预检明细，其余为固定句 `ImportRepo attach failed (push_queue id <N>); retry the push` 并写服务端日志（`tracing::warn`）；ADR-FU-08 第 1 条与 `errors.md` 同步；单测加入含连接串的未知失败 | 卡号不变 | ADR-FU-08、FU-13 |
| 2026-09-24 | FU-13 R4 Codex FAIL（2×P1） | ①只含删除的分支批原先在 `attach_to_monorepo_parent` 内直写 `import_refs`（不入队），违反 GC-FU-03「ImportRepo 分支 ref 写只在 B3 事务内」——改为同样入队（队列行 `new_id` 为零 id），B3 在叶子存在时走与更新相同的归属门（有来源记录或存量形态 → 只写 ref；否则 `OCCUPIED`），叶子不存在时只做 ref CAS（未挂载不需要挂载、不写记录）；既有用例 `attach_delete_only_does_not_enqueue` 的前提被 GC-FU-03 否定，改为 `attach_delete_only_applies_through_queue`（一行 Done、根不变），新增 `fu13_delete_only_batch_gated`。②来源记录查询改为库内 `(metadata ->> 'kind') = $1 AND (metadata ->> 'path') = $2` + `LIMIT 1`（沿用 `artifact_storage` 的 PostgreSQL 写法），`log_audit_in_txn_rolls_back` 加入同目标的干扰行 | 卡号不变 | FU-13 |
| 2026-09-24 | FU-13 R5 Codex FAIL（3×P1） | ①来源记录查询：不新增迁移（改 schema 属迁移卡范围）。按 GC-10「写出数据规模和断言」：查询由 `idx_audit_logs_target`（`target_type, target_id`）限定到单个仓库的审计行，其来源只有该仓库的生命周期事件——挂载记录按路径去重至多一条，外加 FU-16/FU-17 的清理阶段行（每次清理个位数）；新增 `import_repo_attach_lookup_uses_target_index`（同目标 200 条干扰行 + 其它仓库行，`EXPLAIN` 断言计划使用该索引）。②重放核对不再读取仓库全部 ref：新增 `GitDbStorage::get_refs_by_names`（`ref_name IN (本次命令)`，受唯一索引约束，规模等于本次命令数），写集补 `git_db_storage.rs`。③拒绝原因不写日志，只留在队列行；队列表原样持久化失败文本是所有队列类型的既有行为，登记 `DEFER-FU-24` | 卡号不变 | FU-13、DEFER |
| 2026-09-24 | FU-13 R5 Claude PASS（3×P2） | 只含删除的分支批改为一律在 B3 内只写 ref、不经挂载归属判定：删除从不改树，判定不提供保护，却使无来源记录的存量父挂载（叶子下有嵌套子仓）上的 `git push :dev` 被拒——v0.40.1 可删，属回归（实测复现）；与 R4 Codex「删除也须经归属门」相左，按「不回归且不降低保护」取此方案并写入 ADR-FU-08 第 1 条；`fu13_delete_only_batch_refs_only` 断言无记录的目录叶子上删除落地、根不变；`attach_delete_only_applies_through_queue` 改名 `fu13_delete_only_applies_through_queue` 以落入 Verification 过滤器；证据与 Lifecycle 订正全量测试所在的树（R2 树，其后改动由 C 组覆盖）；`enqueue_and_wait` / `execute_b3` 的 `?` 错误直达客户端为既有行为，并入 `DEFER-FU-24` 说明 | 卡号不变 | ADR-FU-08、FU-13 |
| 2026-09-24 | FU-13 R6 Codex FAIL（1×P1 + 1×P2） | P1：B3 attach 以 `new_id != ZERO_ID`（40 个零）判断删除，SHA-256 / BLAKE3 仓库的删除携带 64 个零、被误判为非删除（无记录的目录叶子被拒为 `OCCUPIED`，或叶子不存在时以全零 id 查 tip commit）——`delete_only` 与 tip 查找两处改用 `is_protocol_zero_id`（40 / 64 位），新增 `fu13_delete_only_sha256_zero_id`（无记录目录叶子上的 64 零删除落地、根不变、不写记录；反向验证：恢复 40 零判定即失败）。P2：证据中残留已改名的 `fu13_delete_only_batch_refs_only` 旧名，证据按最终源码重跑 | 卡号不变 | FU-13 |
| 2026-09-24 | FU-13 R6 Claude PASS（3×P2） | ①写集补 `git_db_storage.rs` 后生产文件为 5：Granularity `prod-files=5`、粒度审计表 `4/5`、追溯表补该文件；②只含删除的分支批不再经物化预检（v0.40.1 直写删除不经预检，祖先已物化的 DEFER-FU-13/20 形态下删除会被 I3 拒绝，属回归）：`delete_only` 前移到预检之前、预检只对会挂载的批执行，新增 `fu13_delete_only_skips_materialization_precheck`（祖先已物化时删除落地、根不变；同一形态下的创建仍以 I3 拒绝；反向验证 G：删除批重新经预检即失败），ADR-FU-08 第 1 条与 `errors.md` 同步；③64 位零 id 与 Codex R6 P1 同一处，已修订 | 卡号不变 | ADR-FU-08、FU-13、粒度审计表、追溯表 |
| 2026-09-24 | FU-13 R7 Claude PASS（1×P2） | 首次挂载的 tip 查找改用 `is_protocol_zero_id` 后无用例覆盖：新增 `fu13_first_mount_tip_skips_sha256_delete`（首次挂载批 `[Delete <64 零>, Create <tip>]` → Done、挂载落地、记录写入、删除与创建都生效；反向验证 H：恢复 40 零判定即以 `commit 000…0 not found` 失败） | 卡号不变 | FU-13 |
| 2026-09-24 | FU-13 R7 Codex PASS（1×P2） | `log_audit_in_txn_rolls_back` 读回已提交的来源记录，逐字段断言 `actor_id=0`、`actor_type=human`、`action=create`、`target_type=repository`、`target_id` 与精确 `metadata={kind, path}` | 卡号不变 | FU-13 |
| 2026-09-24 | FU-14 执行（ER-10 本卡轴内） | 迁移按仓库既有写法（`m20260902_000100_add_oci_tables`）以原生 SQL 建表：`id bigint` 主键（= `cleanup_id`，不生成）、`state text` 加 `CHECK (state IN ('detached', 'swept'))`（不引入 PostgreSQL enum 类型，entity 以文本型 `CleanupState` 映射）、`rows_deleted jsonb` 可空、`created_at` 默认 `now()`；`down` 仅在表空时删除、有行时返回错误（「仅在本表无行时安全」落为代码守卫）。原语：`insert_cleanup_in_txn`、`pending_cleanups_by_path`（`CLEANUP_RESUME_BATCH = 16`）、`mark_cleanup_swept`（`WHERE id AND state='detached'`，返回是否本次推进）。迁移用例放在 `jupiter::migration::tests`（`mod.rs` 内联测试模块，与 Verification 路径一致），并断言登记在列表末尾、索引列序、`state` 约束与守卫式 `down`；`uses_index` 用例在 `enable_seqscan = off` 下断言计划为该索引的 Index Scan 且无 Sort（反向验证 A：索引改为 `(path, state)` 时规划器改走主键顺序扫描加过滤、用例失败） | 卡号不变 | FU-14 |
| 2026-09-24 | FU-14 R1 Codex FAIL（3×P1 + 1×P2）+ Claude PASS（3×P2） | ①`down` 先查后删有竞态（检查为空与 `DROP TABLE` 取锁之间可插入台账行而被删掉）：改为单条 `DO` 语句——`to_regclass` 守卫 → `LOCK TABLE … IN ACCESS EXCLUSIVE MODE` → 有行则 `RAISE EXCEPTION`、否则删表；迁移用例加两连接竞态（连接 A 未提交插入 → 连接 B 的 `down` 在 `pg_locks` 中排队等锁后 A 提交 → `down` 报错且行保留；反向验证 E：恢复先查后删即失败），并按 Claude P2 以 `pg_locks` 未授予锁轮询代替固定等待；②页大小断言改为字面量 16（反向验证 B：常量改为 17 即失败）；③证据按卡片原文以 `source .env.test &&` 前缀重跑三条 Verification；P2：已有表与索引时重复执行 `up` 成功。评审过程记录：Claude 评审者在共享工作树上做变异时以整文件回拷恢复，Codex R1 运行期间树上短暂存在其变异，且其恢复曾覆盖作者的一处修订（已发现并重新落实）；Codex 的发现与未变异代码一致，R2 证据在无并发变异的树上重跑 | 卡号不变 | FU-14 |
| 2026-09-24 | FU-15 执行（ER-10 本卡轴内） | 改写逻辑为 `canonicalize_import_repo_paths<C: ConnectionTrait>`（按 `id` 升序逐行；规范路径已被占用 → 保留原样并计 `collisions`，同一规范路径的多个别名由 `id` 最小者取得；无法规范化的路径（含 `..` / `\`）保留并另计 `invalid`，同样只记 `repo_id`），迁移以 `use_transaction = Some(true)` 固定单事务，汇总以 INFO 行 `canonicalized ImportRepo alias paths rewritten=… collisions=… invalid=…` 输出、逐行告警为 WARN；迁移用例放在 `jupiter::migration::tests`，FU-14 用例的「登记在末尾」断言改为「紧随 `m20260921_000100_fix_git_tag_unique`」（末尾位置由本卡用例断言）；进程级用例经「推送 → 停服务 → 把行改为别名并删除本迁移的 `seaql_migrations` 记录 → 重启（启动时 `apply_migrations` 执行本迁移）」模拟升级；`docs/deploy-trunk.md` 新增 §9.2 | 卡号不变 | FU-15 |
| 2026-09-24 | FU-15 R1 Codex FAIL（2×P1 + 1×P2）+ Claude FAIL（1×P1 + 6×P2） | ①并发写入：改写前先 `LOCK TABLE git_repo IN SHARE ROW EXCLUSIVE MODE`（同一事务），他实例未提交的插入要么先提交被扫描到、要么等改写提交；新增两连接用例（连接 A 未提交插入别名行 → 改写在 `pg_locks` 中排队 → A 提交 → 该别名被改写；反向验证 C：去掉加锁即失败）；②`deploy-trunk.md` §9.2 订正：冲突别名行并非「不再被服务」——Git 请求按规范路径解析，但 Web / API 的最长前缀查找（`find_git_repo_like_path`）仍命中以 `/` 或 `/.` 结尾的别名，后续清理也会看到它；冲突一律按「不手工改写、提交 issue」处理，`invalid` 另列（无规范对应行、按 `repo_id` 查看）并改为「例如含 `..` 段或 `\`」；卡片描述与 `DEFER-FU-10` 同步，FU-16 卡描述登记子仓检查须排除规范形式等于 P 的行；③`invalid` 分支加用例（`..` 段与反斜杠两行保留、`invalid=2`；反向验证 E：改为中止即失败）；④以线程内 `tracing` 订阅捕获 WARN，断言每个冲突一条且只含 `repo_id=`、`canonical=`，不含别名拼写（反向验证 D：WARN 加入别名即失败）；⑤进程级用例在重启前同时删除 FU-13 来源记录（真实的 TP-08 之前行没有它），迁移后推送经存量回填在规范路径写入记录，并以别名 URL（`/third-party//fu15-alias`）`ls-remote` 命中同一 `repo_id`。另：`find_git_repo_like_path` 以字符串拼接构造 SQL（既有问题、不在本卡写集），已另起任务 | 卡号不变 | FU-15、FU-16 描述、DEFER |
| 2026-09-24 | FU-15 R2 Codex PASS + Claude FAIL（1×P1 + 3×P2） | P1：WARN 捕获统计了同线程上的全部 WARN，负载下 sqlx 的慢语句 WARN 混入使计数断言偶发失败（评审者 20 次复现 2 次）——只统计本迁移 target 的事件；P2：子仓排除规则写入 ADR-FU-10 第 3 条（ADR-FU-09 第 2 条引用之），FU-16 / FU-17 的 Verification 各加「规范形式等于目标的别名行不是子仓」用例义务，`DEFER-FU-10` 措辞同步；进程级用例断言三条预置 SQL 各影响 1 行（来源记录确实被删、回填路径确实被走到）；两处 `pg_locks` 探测（含 FU-14 迁移用例）限定当前数据库 | 卡号不变 | ADR-FU-09/10、FU-15、FU-16 / FU-17 Verification、DEFER |
| 2026-09-24 | FU-15 R3 Codex PASS + Claude PASS（1×P2） | 卡片描述与 `deploy-trunk.md` §9.2 中「清理会看到冲突别名行」的措辞落后于 ADR-FU-10 第 3 条，改为「清理按规范路径精确查找、不删除这类别名行、不算作子仓」 | 卡号不变 | FU-15 |
| 2026-09-24 | FU-16 执行（ER-10 本卡轴内） | ①载荷字段 `op: AttachOp`（`attach` 缺省；`skip_serializing_if` 使 attach 行序列化后与既有行逐字节一致，`attach_payload_default_op` 断言），detach 行复用 `kind = attach`、`commands: []`、`new_id` 为零 id；`detach_operation_id` 带域前缀 `import_repo.detach\0`。②B3 detach 分支：SAVEPOINT 内 `FOR UPDATE` 锁自身行（行缺失或规范路径不符 → 无写 `Done`）→ 子仓检查（`LIKE escape_like(P) || '/%'` 绑定参数，逐行以 `canonicalize_mono_ref_path` 排除规范形式等于 P 的行；一页 64 行全为此类别名时视为有子仓——保守，不漏）→ 叶子归属沿用 FU-13 的记录 / 存量规则 → 新原语 `tree_ops::remove_import_leaf(chain, names, floor)`（`floor` = `import_dir` 组件深度：其下变空的目录剪除，`import_dir` 本身变空时补 `.gitkeep`）→ 根 commit `Remove ImportRepo <P>`（`format_commit_msg` 成帧）与同一根 CAS（陈旧 → `QueueBypassDetected` 同 attach）→ 删 `import_refs` / `git_repo` → 审计 + 台账（主键 = 队列行 id）；根移动时沿用 attach 的 authz outbox / C 段索引收尾，未移动时 `root_cas_writes = 0`。③本卡无产品入口：`import_repo.rs` 提供 `detach_import_repo`（入队 → 执行 → 只还原 `HAS_CHILDREN`，其余固定句）与 `#[doc(hidden)]` 集成测试钩子 `detach_for_integration_test`（以服务同一份配置自建 storage / redis / 对象库），经 `lib.rs` 的 `import_repo_ops` 再导出——写集补 `src/lib.rs`（prod-files 4）。④`fu16_detach_child_orderings` 以 `pg_blocking_pids` 观察 detach 在父行 `FOR SHARE`（FU-18 祖先栅栏的形态）上排队；注入失败点取台账插入（预置同 `cleanup_id` 的行，它是本轮最后一次写） | 卡号不变 | FU-16 |
| 2026-09-25 | FU-16 R1 Claude PASS（5×P2） | ①`detach_import_repo` 对 `Done` 重放不再照单全收：重放后若 `git_repo` 在规范路径上仍是同一 `repo_id`（FU-16 之前的二进制会把无 `op` 的 detach 行当作只含删除的 attach 执行为 `Done`），以加盐操作 id 再入队一次（同 attach 的重放核对），新增 `fu16_detach_replay_rechecks_live_repo`（预置这样的中毒 `Done` 行 → detach 仍落地）；②`import_dir` 变空补 `.gitkeep` 的对象库写入原本只有 `tree_ops` 单测覆盖：新增 `fu16_detach_restores_import_root_gitkeep`（去掉 `/third-party` 的 `.gitkeep` 后 detach 唯一挂载 → 叶子为 `GitkeepOnly`、`mega_blob` 在 detach commit 下有一行），Verification 另列 `tree_ops::tests::fu16_`（VER 4/8）；③`trunk-push.md` B3 伪码把 detach 条目移到 attach 专属条目之后并给 attach 条目加 `op = attach（缺省）` 标签；④B3 包装层的失败日志带 `op` 字段（队列 `failure_type` 枚举不改，仍为 `AttachFailure`）；⑤`IMPORT_REPO_REMOVE_KIND` 移到 `audit_storage.rs` 与 attach 的 kind 并列——写集补 `src/jupiter/storage/audit_storage.rs`（prod-files 5） | 卡号不变 | FU-16 |
| 2026-09-25 | FU-16 R1 Codex FAIL（3×P1 + 2×P2） | ①存量规则「仓库已有 ≥ 1 条分支 ref」原以 `list_branch_refs_in_txn(...).is_empty()` 判定，在全局写事务内读全部分支：改为有界 `SELECT EXISTS … WHERE repo_id = $1 AND ref_type = 'branch'`（`has_branch_ref_in_txn`），detach 与 FU-13 的 attach 存量判定两处同步（同一规则、同一文件，ER-10 轴内）；②`import_dir` 变空时的 `.gitkeep`：`save_blobs` 会在 SAVEPOINT 之外写 `mega_blob` 行，之后失败会留下孤儿行——改为字节仍写对象库（既定可接受），`mega_blob` 行改在 B3 事务内插入；注入用例加该形态（去掉 `/third-party` 的 `.gitkeep` 后注入失败 → 根不变、`mega_blob` 行数不变）；attach 的同一模式不在本卡轴内，登记 `DEFER-FU-26`；③「单测不清理 schema」不采纳按卡加守卫：`test_db_connection` 为全套件共用 helper，约 1700 个库用例同样不清理（本计划各卡的 `fu13_` / `cleanup_ledger_` / `import_repo_alias_` 用例亦然，历次评审未要求），按卡加守卫会分裂约定；根因在 helper，登记 `DEFER-FU-25` 并已另起任务由 helper 统一释放；④`lib.rs` 的 UN-35 注释归位到 `authz_audit_ops`，`import_repo_ops` 另注；⑤`fu16_detach_operation_identity` 加固定向量断言（`sha256("import_repo.detach\0" ‖ "7" ‖ "\0" ‖ "/third-party/x")` 的十六进制常量，路径改变则 id 改变） | 卡号不变 | FU-16、DEFER |
| 2026-09-25 | FU-16 R2 Codex FAIL（2×P1 + 1×P2） | ①清理 id 必须是台账行：`detach_import_repo` 改返回 `Option<i64>`——`Done` / 重放后以 `resolve_cleanup_id` 解析：该队列行自己的台账行，否则同仓库同路径最新一条台账行，都没有则 `None`（无可清理：仓库本就不在，或 `Done` 行早于 FU-16）；中毒 `Done` 行的重放不再把裸队列 id 交出去（用例改为严格断言 `again == Some(cleanup_id)`）；台账读取暂以 entity 内联在 `import_repo.rs`（`git_db_storage.rs` 由另一会话占用，FU-17 拥有台账读侧时收进存储原语）；②只有 `import_dir` 的严格后代才有挂载：`owned` 先要求 `repo_path` 严格位于 `import_dir` 之下，`floor` 固定为 `import_dir` 深度、去掉「叶子父目录」的回退——位于 `import_dir` 本身或其外的存量行（`DEFER-FU-09`）只删行、不动树，import 根永不被删；新增 `fu16_detach_import_root_row_keeps_tree`（`/third-party` 与 `/project/…` 两行各带来源记录 → `Done` 且 `root_cas_writes = 0`、根不变、行删除；无行且无台账 → `None`）；③Lifecycle 措辞「三条」订正为「四条」、回归计数 180 → 182（Claude R2 同一指出） | 卡号不变 | FU-16 |
| 2026-09-25 | FU-16 R3 Codex FAIL（2×P1）+ Claude PASS（1×P2） | Codex 两条 P1 都要求新增索引（`git_repo.repo_path text_pattern_ops`、`import_refs (repo_id, ref_type)`）：不采纳——改 schema 属迁移卡范围（FU-13 R5 同一处置），按 GC-10 写出规模并以用例钉住：①子仓检查读 `git_repo`，该表每个 ImportRepo 一行（规模为仓库数而非对象数，FU-15 已登记），且 detach 是运维级低频操作；IT 库排序规则为 `en_US.utf8`，`LIKE 'P/%'` 确实不走现有 B-tree（EXPLAIN 为顺序扫描 + `LIMIT 64`），代价为一次仓库数量级的扫描；②分支存在检查经 `repo_id` 索引（EXPLAIN：`Recheck Cond: (repo_id = $1)`），只触及该仓库自己的 ref（无分支、全是 tag 的仓库即扫该仓库的 tag 数，非全表）。新增 `fu16_lookups_bounded_at_scale`（1000 个无关仓库行 + 该仓库 1000 个 tag 且无分支：两项判定正确、EXPLAIN 断言分支检查走 `repo_id` 索引；加一个真子仓与一条分支后两项翻转）。两个索引登记 `DEFER-FU-27`，规模超出时以迁移卡补。Claude P2：把 `resolve_cleanup_id` 的台账内联查询收进 `GitDbStorage` 原语的义务写到 FU-17 卡（描述与写集） | 卡号不变 | FU-16、FU-17 描述、DEFER |
| 2026-09-25 | FU-16 R4 Codex FAIL（1×P1 + 1×P2） | P1：detach 在锁内 `DELETE FROM import_refs WHERE repo_id = $1` 删除该仓库全部 ref，行数为该仓库的 ref 数而非卡片预算写的「O(1) 行」——不采纳「把 ref 物理删除移到 FU-17 清扫」：ADR-FU-09 第 2 条要求 detach 事务内删 `import_refs` 与 `git_repo`（提交后不存在任何可 advertise 的 ref，不依赖清扫及时性），删除是一条经 `repo_id` 索引的语句，行数以该仓库自身的分支与 tag 数为界、不随仓库数或对象数增长；订正预算措辞，`fu16_lookups_bounded_at_scale` 加：EXPLAIN 断言该 DELETE 经 `repo_id` 索引（`Index Cond` / `Recheck Cond`），1000 个 tag 且无分支的仓库一轮 detach 后 `import_refs` 无残留；单仓 ref 数大到锁内删除可测时改由清扫分批删除登记 `DEFER-FU-28`。P2：`fu16_detach_removes_leaf_and_rows` 断言根 commit 内容为 `format_commit_msg("Remove ImportRepo <P>", None)`（反向验证 L：改消息即失败） | 卡号不变 | FU-16、DEFER |
| 2026-09-25 | FU-16 R5 Codex PASS（2×P2） | ①`fu16_detach_child_orderings` 的等锁判定加 `wait_event_type = 'Lock'` 并注明只有本用例的 detach 会被本连接阻塞（它锁的行在本用例自己的 schema 里）；②`DEFER-FU-25` 措辞订正：HEAD 的 helper 不释放 schema，独立任务已在另一会话实现 `TestSchemaGuard`（未提交），提交后关闭 | 卡号不变 | FU-16、DEFER |
| 2026-09-25 | 环境事实更新（FU-16 C 组） | 本机已同时运行用户的其它会话（mega2 的两个独立任务与 libra 仓库的测试），DEP-FU-05 的「失败集恰为 6 个基线用例」在并发负载下无法稳定复现：四次全量中每次额外失败都是 `integration_api_write_trunk` 种子 clone 的 `Connection reset by peer` 或 `tp17` 的等待预算超时，且第三次因 `git-cli` 容器被另一会话按默认 `/tmp/mega2-git` 重建而整批作废。在「本机基线环境失败」段落增加并发会话例外与其判定条件；本会话的 IT 工作目录改为与共享容器一致的 `/tmp/mega2-git` | 卡号不变 | 执行检查必备需求、FU-16 |
| 2026-09-25 | FU-17 实现设计定稿（ER-10 轴内选择） | ①写集补入 `src/jupiter/service/push_queue_service.rs`（`prod-files=3`）：子仓检查按卡片自身措辞与 ADR-FU-10 第 3 条「一个定义」收进 `GitDbStorage::import_repo_has_children<C: ConnectionTrait>`（`CHILD_CHECK_PAGE` 随之公开），B3 再检查与 FU-16 三处用例改为调用该方法，去掉 `_in_txn` 后缀（入口在池连接上做无写预检）；②清扫语句形态定为 `DELETE FROM t WHERE repo_id = $1 AND id = ANY(ARRAY(SELECT id FROM t WHERE repo_id = $1 LIMIT $2))`，四条字面量常量、只绑定参数（GC-FU-07），主键选行使并发 `update_pack_id` / `update_git_blob_filepaths` 移动 ctid 时仍删中同一行，外层冗余 `repo_id` 使故障恢复表「删除其它 `repo_id` 的行」在语法上不可能；③表完成判据为「新快照 `EXISTS` 探测为空」而非「本批少于 1000 行」：两个请求并发清扫同一台账行时后者的删除受阻后可能影响 0 行，若以此判完成会在仍有行时写 `swept`；探测是只读、不计入 100 批预算，每台账行探测数 ≤ 已用语句数 + 5，空仓库 0 语句即可标记 `swept`，「100 批 ≤ 100 000 行」精确成立；不引入 advisory lock 与逐行事务；④`rows_deleted` 跨请求累计：预算用尽且本次确有删除时以主键条件把累计值写回仍为 `detached` 的行（`record_cleanup_progress`），`mark_cleanup_swept` 写终值，`phase:"swept"` 审计行携带同一 JSON；崩溃或并发只影响证据计数、不影响状态；⑤结果语义：活仓库分支在自身台账行 `swept` 后返回 `removed`（同路径更早的待续行由后续 `path` 请求续做，`DEFER-FU-06`；FU-21 卡加注），无活仓库分支返回 `pending` 时携带最小仍为 `detached` 的行；每请求 16 条台账行的上限把本次 detach 计在内；整页 16 条全部处理后再读一次有界台账决定 `absent` / `pending`，恰好 16 条不会误报 `pending`；续做只处理该行、永不 detach；⑥`phase:"swept"` 审计行的 `requester` 为执行清扫的请求（或 `anonymous`），台账 `requester` 列保留 detach 者；⑦`resolve_cleanup_id` 改为调用 `cleanup_by_id` / `latest_cleanup_for`（任意状态、`id` 降序，`fu16_detach_operation_identity` 与 `fu16_detach_replay_rechecks_live_repo` 依赖）；⑧`fu17_sweep_budget_pending` 以一条 `generate_series` 插入 100 500 行 `git_blob` 在生产常量（100 × 1000）下驱动入口，不设可注入预算的入口变体；⑨证据订正：`escape_like` 为 `src/common/utils.rs:219-231`；`git_tag` 的 `repo_id` 前导索引来自 `m20260921_000100_fix_git_tag_unique.rs`（init 只覆盖 commit/tree/blob）；故障恢复表「detach 已提交、清扫前崩溃」的恢复改为按台账 `(path, state='detached', id)` 游标续做、`audit_logs` 只作证据；Verification 第 1 条前缀组增加 `fu17_child_query_escapes_and_excludes_aliases` 与 `fu17_ledger_reads_and_progress`；性能预算段补记探测数上界。设计经工作流产出：4 个读码 agent、3 个角度的独立设计（crash-first / budget-first / minimal-diff）、2 个评审打分（62 / 60 / 64）后综合 | 卡号不变 | FU-17 卡（写集、粒度、证据表、Verification、性能预算）、FU-21 描述、故障恢复表、粒度审计表、追溯表 |
| 2026-09-25 | FU-17 R1 Codex FAIL（1×P1 + 2×P2） | P1：预算耗尽返回 `pending` 前不重读台账，另一清扫者已把该行标为 `swept` 时会把已完成的行当作待续——`sweep_ledger_row` 在 OverBudget 前重读该行，已 `swept` 则按 `Swept` 返回（`record_cleanup_progress` 本就只写 `detached` 行），新增 `fu17_pending_rechecks_ledger_before_answering`（持陈旧快照、预算 0、另一清扫者已标 `swept` → 返回 `Swept`、不删行、不写审计）；P2：①共享 blob 用例改为把 Monorepo 的 `/third-party` 占位 blob 也登记在 A 下，清扫后 Monorepo 的 `mega_blob` 行与对象库字节仍可读，兄弟仓库的 commit / blob 数据流（upload-pack 所服务的）仍含共享 readme；②`latest_cleanup_for` 改为按 `(path, state, id)` 索引各状态倒序取 1 行再取较新者（EXPLAIN 断言 `Index Scan Backward` 且无 `Sort`），不加索引 | 卡号不变 | FU-17 |
| 2026-09-25 | FU-17 R1 Claude（工作流）FAIL（1×P1 + 11×P2） | P1：`EXISTS` 探测没有强制走 `repo_id` 前导索引的计划形态（评审者在 2.1 M 行的同形临时表上复现 generic 计划为顺序扫描）——探测改为 `SELECT <键> FROM t WHERE repo_id = $1 ORDER BY <键> LIMIT 1`（唯一索引上一步 top-1），用例以 EXPLAIN 与 `PREPARE` + `SET LOCAL plan_cache_mode = force_generic_plan` 钉住两种计划均走 `uniq_b_git_repo`、无顺序扫描。P2（11）：①共享 blob 用例未经读路径（与 Codex R1 P2① 同一条，已落实）；②16 条上限计本次 detach 与「自身 `swept` 即 `removed`」无覆盖 → `fu17_fresh_detach_resumes_older_rows`；③无并发清扫者 / 受阻 0 行批用例，D-2 的正确性论证只是散文 → `fu17_sweep_survives_a_blocked_batch`；④`mark_cleanup_swept == false` 分支未走到 → `fu17_swept_by_another_request_writes_no_second_audit`；⑤预算在台账行之间耗尽、预算 0 未测且共享预算未钉住 → `fu17_budget_exhausted_between_rows` 与存储用例预算 0 断言；⑥`git_tag` 删除字面量无用例执行 → 填充 7 个 tag、语句数 6；⑦预检后 B3 拒绝的类型化未覆盖（2/3 反驳者维持）→ `fu17_b3_refusal_surfaces_typed_error`；⑧`rows_deleted` 客户端累计在并发下非单调（2/3 维持）——按定稿④保持「证据、非状态」，措辞写入 `record_cleanup_progress` 与 `sweep_ledger_row` 注释；⑨故障恢复表禁止结局仍以审计指针表述 → 改为「该 `repo_id` 的元数据行存在而台账无对应 `detached` 行」；⑩性能预算段漏记 O(仓库数) 子仓预检且把计划器相关断言当事实 → 重写（探测索引名、预检顺序扫描 `LIMIT 64`、top-16 排序）；⑪`SweepCounts::from_json` 注释低估失败模式（2/3 维持）→ 注明任一畸形值整组归零并加混合用例 | 卡号不变 | FU-17 卡（Lifecycle、Verification、性能预算）、ADR-FU-09 第 6 条括注、故障恢复表 |
| 2026-09-25 | FU-17 R2 Codex PASS（1×P2）+ Claude（工作流）FAIL（1×P1 + R1 一条未闭环 + 5×P2） | Codex P2 与工作流「未闭环」为同一条：`latest_cleanup_for` 按 `repo_id` 过滤而 `(path, state, id)` 索引不能按该列定位，R1 的修订去掉了排序但未去掉扫描、4 行未 ANALYZE 的 EXPLAIN 也钉不住计划——不加索引（迁移卡范围，FU-13 R5 / FU-16 R3 先例），写出规模：一个 `repo_id` 至多一条台账行（台账行只在删除 `git_repo` 行的事务里写入），查询改为 detached 先、命中即返回；成本为该路径该状态段的一次索引范围读 + 至多一次 top-1 排序，只在 `resolve_cleanup_id` 的重放回退触发；用例在同路径 1000 `swept` + 200 `detached` 历史上取最旧行并以 `PREPARE` + `force_generic_plan` 钉住读 `idx_import_repo_cleanups_path_state_id`、不扫台账；`DEFER-FU-27` 增补台账 `repo_id` 索引。工作流 P1：分批子查询 `SELECT id … WHERE repo_id = $1 LIMIT $2` 与 R1 探测同一机制——高占比仓库的自定义计划为 `Limit → Seq Scan`，每批重读堆前缀与此前批次的死元组、末批扫全表——子查询加 `ORDER BY <索引第二列>`，用例对 91% 占比的诱饵仓库钉住 generic 计划走 `uniq_b_git_repo`、自定义计划无顺序扫描无排序（自定义计划在高占比时合法地选 `blob_id` 单列索引 + 过滤，扫描量 ≤ 1000/占比 条索引项）。P2：①续做「只处理该行」未钉住 → `fu17_continuation_never_touches_reimport` 加同路径更早行；②本次 detach 与更早行共用预算未钉住 → `fu17_budget_shared_with_older_rows`；③性能预算段把 `git_blob` 探测的钉住泛化到四表、探测断言可被 bitmap + sort 形态通过 → 措辞限定并断言 `Scan using uniq_b_git_repo` 与无 `Sort`；④Lifecycle 沿用 R1 的回归计数 → R3 树重跑；⑤受阻批用例 `3..=4` 含不可达值 → 恰为 3；另记 `detach_import_repo` 返回 `None` 的落空分支只经代码走读 | 卡号不变 | ADR-FU-09 第 4 条括注、FU-17 卡（Lifecycle、Verification、性能预算）、DEFER-FU-27 |
| 2026-09-25 | FU-17 R3 Codex PASS（1×P2）+ Claude（工作流）FAIL（R2 一条未闭环 + 8×P2） | 工作流首轮因模型用量上限中断（40 个 agent 失败），换模型后以同一 run 续跑完成。①R2 未闭环项：`detach_import_repo` 返回 `None` 的落空分支「需要测试钩子」的理由不成立（同一改动已有两处以行锁排序的用例）——新增 `fu17_detach_lost_race_falls_back_to_ledger`。②实质 P2（1 名反驳者判 P1）：R3 在分批与探测里加的 `ORDER BY <索引第二列>` 只钉住了 `git_blob`；`git_commit` / `git_tree` 另有单列 `repo_id` 索引，评审者在同形数据上复现 generic 计划为 `Sort → Index Scan using idx_ic_repo_id`，大仓库每批读完整个仓库再 top-N 排序（2123 vs 37 buffers）；未 ANALYZE 的 `git_blob` 也可为 `Sort → Bitmap Heap Scan`——计划器在「高估计 → 顺序扫描」与「低估计 → bitmap / 排序」之间没有与统计量无关的形态。改为每个清扫步骤一个短事务 + `SET LOCAL enable_seqscan = off; SET LOCAL enable_bitmapscan = off`（`SWEEP_PLANNER_SETTINGS` / `begin_sweep_step`，PostgreSQL 18 以「禁用节点数」优先比较，存在索引路径时禁用路径必败），探测与分批去掉 `ORDER BY`：`WHERE repo_id = $1 LIMIT n` 只剩 `repo_id` 前导索引上的索引扫描。钉住四表时又发现：小估计下外层 DELETE 选 `idx_ic_repo_id` 读完整个仓库再以 `id = ANY` 过滤——外层防护改为不可走索引的 `repo_id + 0 = $1`，主键成为外层唯一索引路径（语义不变：仍在语法上排除其它 `repo_id` 的行）。钉住：四表 × 探测/分批 × `force_custom_plan` / `force_generic_plan` × 四种统计状态（本用例 ANALYZE 前；ANALYZE 后 4.5% 目标、91% 诱饵、300 个单行仓库之一）的 EXPLAIN 均为 `repo_id` 前导索引扫描、无顺序扫描 / bitmap / 排序；外层事务里真实清扫诱饵 3 批后 `pg_stat_xact_user_tables` 四表顺序扫描 0 次（清扫绕过 `begin_sweep_step` 即失败）。③WF-R3-SQL-1（generic 钉住未绑定 InitPlan、首块缺 `Sort` 排除）随四表钉住一并落实：InitPlan 以 `<t>_1` 别名锚定，外层断言主键与 `Index Cond: (id = ANY`，所有块排除 `Sort`；P2 文字：`delete_sql` / `probe_sql` 注释不再声称「任何统计量下」而指向设置本身；`latest_cleanup_for` 注释与性能预算写明至多两次范围读、合计以两个状态段之和为界、custom 计划可顺序扫描台账；反向验证 O 的记录改为实际失败的 generic 断言；「≤ 1000/占比」上界随 `ORDER BY` 一并移除；诱饵行数注释随用例重写。④Codex P2：子仓检查整页 64 条都是目标别名时保守视为有子仓，Codex 认为违反 ADR-FU-10 第 3 条的别名排除——不采纳：第 3 条的排除针对 FU-15 冲突保留的别名行（`P/`、`P/.` 这类拼写，每路径个位数），64 行上限是 B3 锁内检查的有界性来源；逐页续读会把锁内读取变成与别名数成正比，而保守答案只拒绝、不删除，恢复路径是 `DEFER-FU-10` 的合并；卡片 Verification 早已写明「整页别名视为有子仓」，`DEFER-FU-10` 补记此后果 | 卡号不变 | ADR-FU-09 第 4 条括注、FU-17 卡（Lifecycle、Verification、性能预算）、`DEFER-FU-10` |
| 2026-09-25 | FU-17 R4 Codex PASS（2×P2）+ Claude（工作流）FAIL（R3 两条未闭环 + 8×P2） | 工作流首轮因会话用量上限中断（25 个 agent 失败），限额重置后以同一 run 续跑完成。①R3 未闭环两条（均为措辞）：`latest_cleanup_for` 的计划模式——评审者在同形表上复现：全为 `swept` 的 2 路径台账下 generic 计划即为顺序扫描，`plan_cache_mode=auto` 第 6 次执行即切换，custom 计划约在段占比 30–35% 时切换——注释与性能预算改为「采用索引时读两段之和，路径与状态不具选择性时可顺序扫描整个台账（每次 detach 一行）」，用例注释改为只钉住该历史形态下索引可用；回退不只在重放时触发（`Done` 且未 detach 的轮次亦然，即 `lost_race` 用例），`DEFER-FU-27` 改为两段之和并覆盖两种来源，R3 评审行「全部落实」加注。②外层事务模式（Codex P2①、工作流 SL-1 / PLAN-2 / CC-1）：`SET LOCAL` 在已释放的保存点里一直生效到外层事务结束，零顺序扫描断言只能抓到「全部步骤」绕过；且泛型签名允许调用方传事务——`sweep_import_repo_objects` 改为只收连接池（`&DatabaseConnection`），断言改为按生产方式：只有一个连接的池、每步一个事务、`pg_stat_force_next_flush()` 后读 `pg_stat_user_tables` 增量；新增反向验证 T2（批次在步骤事务之外执行、探测仍在内）。③Codex P2② / 工作流 PLAN-3：探测断言未要求 `Index Cond: (repo_id = …)`，把外层防护写法抄进探测会得到同一索引的全量 `Index Only Scan` 而通过——探测与分批的 InitPlan 均须有该 `Index Cond`，探测不得有 `Filter`（反向验证 W）。④PLAN-1：反向验证 S 的 R4 记录有误——用例把 300 个单行仓库放在唯一一次 ANALYZE 之前，从未访问「三个仓库时 ANALYZE 之后」的状态，而该状态下 S 计划为 `idx_b_git_id` + `repo_id` 过滤；改为三次统计快照（ANALYZE 前、三个仓库时 ANALYZE 后、加入单行仓库后再 ANALYZE）并重跑 S。⑤PLAN-4：「四种统计状态」实为两次快照、占比只对 `git_blob` 成立、诱饵约 90%——措辞订正。⑥SL-2：受阻批用例的「另一清扫者」不在计划器设置下执行，两者选行一致只靠 fixture 的插入顺序——改由 `begin_sweep_step` 开启。⑦DOC-1：入口「行在队列运行前消失」的注释不覆盖锁等待后无行与重放两种情形——改写。⑧另记：轮询锁等待用的 `pg_stat_activity` 在事务内是首次读取时的快照——两处 FU-17 用例每次轮询前 `pg_stat_clear_snapshot()`（`fu16_detach_child_orderings` 属已发布的 FU-16，未改）。⑨R3 记账：工作流 P2 实为 8 条、WF-R3-SQL-1 的处置补记。驳回：CP-R4-3（别名页不采纳的理由措辞）、WF-R4-AX-2（`pub(crate)` 可见性） | 卡号不变 | FU-17 卡（Lifecycle、Verification、性能预算）、`DEFER-FU-27`、R3 变更与评审行 |
| 2026-09-25 | FU-17 R5 Codex PASS（无发现）+ Claude（工作流）PASS（6×P2） | 双评审通过，P2 落实：①没有用例钉住「设置随步骤结束」——把 `SET LOCAL` 改为会话级 `SET` 全组仍通过而生产连接池会把设置带给后续查询；在按生产方式清扫后于同一连接断言 `enable_seqscan` / `enable_bitmapscan` 为 `on`（反向验证 X）。②`fu17_single_connection` 手工拼 URL、无默认 URL 回退与 FIX-05 超时——改为复用测试连接池的 sqlx 连接选项（schema 与后端标签随之）建一个连接的池，120 s 获取超时。③回退来源措辞「重放，或未 detach 的轮次」——detach 过的轮次（含其重放）由自身台账行应答，只有未 detach 的轮次（首次或重放）才到回退；代码注释、性能预算与 `DEFER-FU-27` 同步。④最坏情形措辞过窄——该段约占台账 30% 起即可顺序扫描，两次查询最坏两次全台账扫描。⑤`fu17_seq_scans` 注释误述刷新机制——改为「空闲且不在事务内时刷新，本自动提交调用即在语句完成之前」。⑥R4 变更行范围列补 Lifecycle。驳回：CP-R5-2、CP-R5-3、AX-R5-3 | 卡号不变 | FU-17 卡（Lifecycle、性能预算）、`DEFER-FU-27`、R4 变更行 |
| 2026-09-25 | FU-18 设计定稿（ER-03 写集修订 + ER-10 轴内选择） | 设计经工作流产出：4 个读码 agent（各带交叉核查）出代码地图，3 个角度的独立设计（correctness-first / minimal-diff / test-first），2 名评审打分（63 / 59 / 65），以 test-first 为底综合。①栅栏谓词取 ADR 字面 SQL，第二参数为调用方解析该行所用的路径（Git 面分派只在存储路径等于规范路径后才返回处理器）；原语只收 `&DatabaseTransaction`，无锁预检复用 `import_repo_is_live`。②B3 attach 的栅栏置于 detach 分派之后、`delete_only` / 物化预检 / `SAVEPOINT b3_kind` 之前（`IMPORT_REPO_REMOVED` 优先于 I3 文本），拒绝经新的 `b3_attach_fail_unsaved`。③关闭 `Done` 重放捷径：`attach_to_monorepo_parent` 的 `Replayed` 分支先做存活检查（否则仅删除推送重放已完成的操作 id 会在 detach 后答 ok）。④`save_entry` 每批一个事务：对象字节上传在事务外，四表按唯一键排序、固定表序，事务内无语句级重试（`40P01` 后事务已中止），整事务仅对 `MegaError::Db` 按 `next_insert_retry` 重试；签名增加 `repo_path`。⑤unpack 批的拒绝原样透传（`receiver_handler` 不再把 `MegaError::ImportRepo` 包成 `Other`），分支 `ng` 行保持稳定码。⑥tag 每 ref 一个事务，经生产 seam `write_tag_ref_in_txn`（锁 + 恰一条既有 CAS 语句）。⑦`file_path`：先无锁存活预检，`unwrap` 改错误，计算失败再检存活（`removed_or`），更新按 `blob_id` 排序、每块 ≤ 1000 行一个带锁事务；无栅栏的 `update_git_blob_filepaths` 保持原签名。⑧首次注册：同一事务内对全部严格祖先行按 `id` 顺序取 `FOR SHARE` 后插入（`MonoStorage::strict_non_root_ancestor_paths`），插入错误文本不变。⑨叶子校验核心依次拒绝 NUL、非规范形、`import_dir` 本身、不在其下；严格入口按 ADR-FU-10 第 1 条另拒 `\`、`..`、重复与结尾斜杠。⑩Git 面拒绝文本逐字（`GitError::CustomError(e.to_string())`），API 面保留 `[code:409]`。⑪AC 名不改，IT Verification 增加 `import_root_push_rejected` 过滤器。⑫不改 detach 代码与 `fu16_detach_child_orderings`，不改 schema、`errors/mod.rs`、`base_storage.rs`、`mono_storage.rs`。⑬写集修订（ER-03）：`src/ceres/pack/mod.rs`（透传，3 行）、`src/ceres/api_service/import_api_service.rs`（新签名调用点，一个参数）、`tests/integration_git_cli.rs`（本卡 AC 用例）；`prod-files` 6 → 8。⑭测试支撑置于 `git_db_storage.rs` 的 `#[cfg(test)] pub(crate) mod fu18_support`（`src/jupiter/tests.rs` 在写集外）；锁等待轮询在持锁者自己的事务上先 `pg_stat_clear_snapshot()`，每个用例至多用 2 个池连接加 1 个单连接池。另登记 `DEFER-FU-29..35`，`DEFER-FU-10` / `DEFER-FU-21` 补记；写集外文档漂移（`docs/refactoring/protocol.md` 的 import_dir upload-pack 404 → 400、`trunk-push.md` §1.9 仅删除不入队）作为 FU-22 文档卡的输入记录，由其 ER-03 复核决定 | 卡号不变 | FU-18 卡（Lifecycle、证据、写集、粒度、IT Verification）、粒度审计表、ADR-FU-09 第 5 条注记、`DEFER-FU-10` / `DEFER-FU-21`、`DEFER-FU-29..35` |
| 2026-09-25 | FU-18 A 组 smoke 配方修订（ER-10） | 卡片协议 smoke 的原配方在启动服务前 `source .env.test`，其 `MEGA_DATABASE__DB_URL` / `MEGA_DATABASE__DB_TYPE` 环境覆盖优先于配置文件，服务因此没有用配方创建的临时库 `mega2_fu18_smoke`，而是初始化了共享 IT 库 `mega2` 的 `public` schema（73 张表、22 个枚举类型、20 个序列，只含该次 smoke 的数据）；测试连接的 `search_path` 为 `<schema>,public`，于是 `jupiter::migration::tests::import_repo_cleanups_migration_applies` 在删掉自身 schema 的表后经 `to_regclass` 解析到 `public` 的同名表而失败。配方改为去掉 `source .env.test`、显式 `unset` 两个变量，并注明原因；从已 source 的 shell 重跑两例全绿，`public` 行数前后不变。`public` 中遗留对象的清理属破坏性操作，待用户确认 | 卡号不变 | FU-18 卡（Verification 的 smoke 配方、Lifecycle） |
| 2026-09-25 | FU-18 R1 Codex FAIL（1×P1 + 3×P2）；独立评审 R1 未运行（周用量上限） | P1：B3 首次挂载在持有 `MONO_WRITE_LOCK` 与新共享锁时经 `search_and_create_tree` 借用第二个池连接，池满且另一请求持池连接等 `MONO_WRITE_LOCK` 时停滞——不采纳：该调用在 HEAD 已存在（FU-18 之前的池耗尽风险），共享锁不参与等待环（只与 detach 冲突，二者在同一 `MONO_WRITE_LOCK` 下串行）；trunk-push.md 的不变量原文把 B3 也包括在内，收窄为「B3 之外的栅栏事务」，并登记 `DEFER-FU-36`。P2：①`txn.commit()` 的可重试错误原样返回——改为同样按 `next_insert_retry` 整事务重试；②`file_path` 预检的顺序无用例钉住（R4 存活）——`fu18_filepath_errors_not_panics` 增加：detach 后另一事务对 `git_commit` / `git_tree` 持 `ACCESS EXCLUSIVE` 锁，步骤须在 5 秒内答 `IMPORT_REPO_REMOVED`（无预检即阻塞，R4 重跑失败）；③`import_root_push_rejected` 只断言 `git_commit` 为空——四张对象表全部断言 | 卡号不变 | FU-18 卡（Lifecycle）、`DEFER-FU-36`、trunk-push.md 锁序说明 |
| 2026-09-25 | FU-18 R2 Codex PASS（1×P2）+ 独立评审 R1 PASS（12×P2） | Codex P2：Lifecycle 中 R4 的旧结论（存活）与重跑结论（失败）并存——只留最终结论。独立评审（工作流：5 维查找、每条 3 反驳者、裁决 agent 复跑卡片命令；首次因周用量上限全部失败，限额重置后重跑）12 条 P2：①`last_wins_filepaths` 注释称按 `blob_id` 排序即固定锁序，但 UPDATE 按计划顺序锁行——改注释（该步骤并发推送同一仓库时的死锁暴露为 FU-18 之前既有）；②整事务重试无用例——判定抽为纯函数 `batch_retry_backoff` 并加单测；③协议分派按原始路径前缀选择 ImportRepo 分支，SSH 相对写法不经叶子校验，而文档声称覆盖全部——文档限定范围并登记 `DEFER-FU-37`；④`removed_or` 的调用点无用例走到——新增 `fu18_filepath_removed_between_check_and_reads`；⑤根树与子树的 `unwrap` 改错误无用例——`fu18_filepath_errors_not_panics` 补两例；⑥共享锁用例只证明阻塞普通 UPDATE，排他锁同样通过——补并发同锁必须成功；⑦追溯表 FU-18 行漏文件与用例；⑧`errors.md` 的 SSH 数据阶段文本与客户端实际所见不符（未加 pkt-line 帧，客户端显示 `protocol error: bad line length character`）；⑨`reason` 只在可规范化分支给出规范形式；⑩ADR-FU-09 第 5 条、`DEFER-FU-30` / `DEFER-FU-35` 的行号锚点过时——改为函数锚点；⑪A 组规则仍称 FU-18 只改注册调用；⑫性能预算漏记祖先锁读与无锁存活读。驳回（2/3 反驳者）：着陆数、门禁重跑、trunk-push.md 栅栏范围。反向验证 R15–R19 全部失败 | 卡号不变 | FU-18 卡（Lifecycle、性能预算）、追溯表、ADR-FU-09 第 5 条、A 组规则、`DEFER-FU-30` / `DEFER-FU-35` / `DEFER-FU-37` |
| 2026-09-25 | FU-19 设计定稿（ER-03 写集修订 + ER-10 轴内选择；并入 DEFER-FU-33） | 设计经工作流产出：读码地图两份（交叉核查），3 个角度的独立设计（correctness-first / minimal-diff / test-first），2 名评审打分（32/31、30/30、33/34），以 test-first 为底综合。①栅栏谓词取 ADR 字面，API 面第二参数为分派所得行的存储路径；规范行清理后别名行可成为唯一行，Git 面改标签可致可重试的假 409（记风险，不重开 ADR）。②edit/save 两段：对象行经 FU-18 `save_entry`，默认分支 ref 在自己的带锁事务里以 `update_ref_in_txn` 写（去掉 `update_ref` 的 panic，`DEFER-FU-33` 第 3 项）；单事务方案记为备选。③ref 更新保持无条件（`DEFER-FU-22` 评估后延后）。④预读移入无写的 `plan_file_edit`，`get_root_tree` / `get_tree_by_hash` 的 `unwrap` 改 `NotFound`、`ObjectHash` 的 `unwrap` 改 `InvalidCommitObject`；预读失败再检存活（`removed_or`：无锁精确查找且 id 相同），不加入口预检（`DEFER-FU-33` 第 2 项）。⑤annotated tag 单事务：锁、`INSERT … RETURNING`、ref；去掉按名补偿删除；ref 冲突整体回滚，状态保持 500。⑥lightweight tag 锁后写 ref（`DEFER-FU-33` 第 1 项，ADR-FU-09 第 5 条补列）。⑦tag 删除单事务、去预读；存活仓库删不存在的 tag 仍 200，detach 后一律 409 且不改行。⑧tag 预读留在事务前并经 `removed_or`，REMOVED 优先于 404 目标 / 400 重名。⑨错误面经 `GitError::from` 保留 `[code:409]`，语句失败保留既有 `[code:500]` 文本；`map_ceres_error` 增 409 分支。⑩锁序：事务打开期间不取第二个池连接、不跨 `save_entry` 或写入队列；依赖 READ COMMITTED。⑪`update_ref` / `insert_tag` / `delete_tag` / `remove_ref` / `save_ref` 不改，FU-19 后无生产调用者（`DEFER-FU-31` 补记）。⑫测试 seam 为私有方法，复用 `fu18_support`；锁模式用 NOWAIT 探针判定。⑬写集修订：`src/common/errors/api.rs`、`docs/errors.md`、`docs/refactoring/trunk-push.md`；AC 7→8、VER 5→8、landing / prod-files 2→3。另登记 `DEFER-FU-38..40`，关闭 `DEFER-FU-33`，改写 `DEFER-FU-22` | 卡号不变 | FU-19 卡（Lifecycle、描述、Out of scope、证据、AC、Verification、写集、影响、性能、粒度）、ADR-FU-09 第 5 条、ADR-FU-03 第 4 条注记、GAP-FU-11、粒度审计表、追溯表、`DEFER-FU-22` / `31` / `33`、`DEFER-FU-38..40` |
| 2026-09-25 | FU-19 R1 独立评审 FAIL（1×P1 + 13×P2）；Codex R1 未运行（用量上限，22:28 重置后补跑） | 独立评审（工作流：5 维查找、每条 3 反驳者、裁决 agent 复跑卡片库测试命令）。P1：Verification 称四个写事务各自先持锁，`fu19_api_lock_serializes_with_detach` 只覆盖三个（缺 lightweight tag）——Part A 增 `light` 缝。P2：①errors.md `Removed` 行称 edit/save 被拒时对象行也不落，与两段式设计不符——改为「被拒绝的那次写不落行，两段之间遇 detach 时已提交的对象行留给清扫」；②兼容说明「tag 路由此前为 500」不实（此前 detach 后创建为 200 并写孤儿行、清扫后 404，删除为 200）且对读路径说多了——按实改写并指向 `DEFER-FU-40`；③`preview_router` 的 `delete_entry` 注释称 `map_ceres_error` 会把 409 变 500、`ImportRepoError::http_status` 注释称 `Removed` 只在 Git 面、`lock_live_import_repo` 注释只列 receive-pack——改注释（写集修订：两个文件仅注释、无行为变更，不计入 G-04 的落点与生产文件数）；④同名 tag 并发创建与删除在删除的两条语句之间的竞态（FU-19 前已存在，与清理互斥无关）——登记 `DEFER-FU-41`；⑤没有用例证明默认分支 ref、lightweight、删除的写落在带锁事务上——Part A 在提交前从另一连接断言写不可见（新反向验证 R20–R22：锁留在事务、写改走连接池即失败）；⑥生产 `save_file_edit` 的 ref 写调用点无用例走到——新增 Part C：持住默认分支 ref 行使生产 edit/save 停在 ref 写，此时 `FOR UPDATE NOWAIT` 必须失败（R23：该调用点改回连接池 `update_ref` 即失败）；⑦`get_root_tree` 根树 `NotFound` 无用例——(e) 增删根树一例（R24）；⑧tag 创建 / 删除缺「同路径重新导入后」阶段——两个用例补上（陈旧处理器 409，新仓库同名 tag 可建且不被陈旧删除波及）；⑨VER 按计数口径为 5 条命令 + 末项三门 = 8/8（设计定稿行的「VER 5→6」订正为「5→8」）；⑩ADR-FU-03 第 4 条与 errors.md 把 edit/save 对象批的 409 归到 FU-19——订正为 FU-18 起；⑪`DEFER-FU-22` 行多一格——合并；⑫兼容与文档收口清单的 trunk-push.md 缺 FU-19，设计定稿行的修订范围缺 Out of scope——补；⑬「记风险」的别名假 409 未落到任何登记——`DEFER-FU-10` 补注。另：首轮评审输入 diff 是在反向验证 R3 生效时生成的（源文件经逐字节比对已还原），已重新生成；证据按终态以 R1–R24 完整重跑 | 卡号不变 | FU-19 卡（Out of scope、Verification、写集、影响、粒度）、FU-19 设计定稿行（VER、修订范围订正）、粒度审计表、ADR-FU-03 第 4 条、兼容与文档收口、`DEFER-FU-10` / `22` / `41`、docs/errors.md |
| 2026-09-25 | FU-19 R2 独立评审 PASS（11×P2） | R1 的 P1 与 13 条 P2 中的 12 条经复核已关闭或有据延后（第 3 条的修订重新引入日期错误，作为本轮 ① 修正）（TX-1 → `DEFER-FU-41`）。P2 处置：①`ImportRepoError::http_status` 注释与写集说明把 `Removed` 到达 API 全归 FU-19——订正为对象批 FU-18、预读 / ref / tag 写 FU-19；②`map_ceres_error` 的 409 分支对已剥掉标记的文本再解析一次 `[code:`——不采纳：与既有 400 / 404 分支同一行为，仅当存储路径含 `[code:<数字>]` 时截断 `err_message`，属 `ApiError` 的共性；③edit/save 新 404 文本不含「not found」——不采纳：与 FU-18 已发布的 `NotFound` 文本（`commit <id>` / `tree <id>`）一致；④live tag 创建返回的 `TagInfo` 无断言——`fu19_tag_create_after_detach_rejected` 增加：annotated 与存储行逐字段一致、lightweight 以目标 commit 为 `tag_id` / `object_id`；⑤`delete_tag_in_txn` 的仓库过滤与 live lightweight 删除无用例——`fu19_tag_delete_after_detach_rejected` 增加同名 tag 的第二个仓库与 lightweight 删除（R25：去掉 `repo_id` 过滤即失败）；⑥edit/save 的写顺序（对象批在前、ref 在后）无用例——Part C 在 ref 写被阻塞时断言新 commit 行已提交（R26：两步对调即失败）；⑦`DEFER-FU-32` 只列推送 unpack 批——补 FU-19 的 API 共享锁持有者；⑧AC8 以「且」连接两个谓词——收为一个谓词；⑨仅注释的两个文件不计入 G-04——粒度与审计表订正为 landing=3、prod-files=3；⑩ADR-FU-03 第 4 条仍称 `Removed` 只出现在 Git 面——改写；⑪R1 行修订范围漏列「影响」与设计定稿行——补。证据按终态以 R1–R26 完整重跑 | 卡号不变 | FU-19 卡（AC、写集、粒度）、粒度审计表、ADR-FU-03 第 4 条、`DEFER-FU-32`、FU-19 R1 行 |
| 2026-09-25 | FU-19 Codex R1 PASS（无发现）；C 组 | Codex 用量上限于 22:28 重置后补跑，对终态 diff（9 个文件）无 P0/P1/P2。C 组在 `0.40.8` 干净副本与新建门禁库 `mega2_fu19_gate` 上运行：lib 1796 / 0 / 1，失败集为 6 个基线用例 + `path_provision_rejects_policy_violations`（临时端口就绪判定竞态，单独 3/3、整 target 62/62，按并发会话例外接受） | 卡号不变 | FU-19 卡（Lifecycle） |
| 2026-09-26 | FU-20 设计定稿（ER-03 写集修订 + ER-10 轴内选择；DEFER-FU-38/39 复核） | 设计经工作流产出：读码地图三份（HTTP / 鉴权 / OpenAPI、清理核心、测试与文档，交叉核查），3 个角度的独立设计（security-first / minimal-diff / test-first），2 名评审打分，以 test-first 为底综合。①固定体机制：`authorize_import_repo_removal` 在 `push_auth` 不为 `token` 时直接固定 403，否则包装 `authorize_trunk_api_write` 并经新增 `ApiError::status()` 改写（401 → `authentication required`，其余 → `forbidden`），原错误在进入响应与日志前丢弃（ADR-FU-10 第 4 条原样保留）。②顺序：`Json` 提取器 → `strict_import_repo_leaf_input` → 鉴权 → `remove_import_repo`（裸 `?`）；鉴权前只读请求与配置快照、handler 自身不写日志（语法 400 经 `ApiError` 的 error 级日志含调用方输入，`DEFER-FU-43`）。③「一律 403」只针对可解析、语法合法的请求（ADR 补注）。④只挂 storage-only（`storage_only_routers_with` 合并链），Review 不挂（`DEFER-FU-02`），以库测试锁定。⑤DTO `ImportRepoRemove{Request,Outcome,Result}` 进 `src/ceres/model/git.rs`，成功体为 `CommonResult.data`，四键恒在。⑥请求 `deny_unknown_fields`（拼错的 `cleanup_id` 不会变成新操作），`cleanup_id: null` 等同省略。⑦`.git` 为普通字符（答 `absent`）。⑧NUL 以外的控制字符不在本卡收紧（`DEFER-FU-44`）。⑨结局语义按已发布的 FU-17 写入 ADR-FU-10 第 5 条补注（`removed` 不等于排空、`absent` 可在本请求清扫之后、`pending` 可指名未触及的行）。⑩OpenAPI 声明 200/400/401/403/404/409/500（500 可重试），提取器的纯文本 4xx 不声明、契约页写明。⑪不新增日志行；无 `WWW-Authenticate`。⑫500 可重试、断连按崩溃点语义恢复（`DEFER-FU-42`）。⑬审计 requester 为 token 名。⑭无可注入预算：IT 以绑定参数 SQL 补 100 500 行 `git_blob` 触发 `pending`（首请求恰删 98 000 行），该组调用用 180 s 客户端；Verification「以测试预算触发」改为「生产常量下以数据量触发」。⑮AC 改为八个单谓词（六个 IT 名 + 两条文档），删去 Verification 中不在 AC 的 `unauthorized_no_disclosure`（并入 `requires_token`），VER 7→8（新增 errors.md 两行登记门）。⑯零命中守卫加宽到 `api_handler` / `ImportApiService` / `authorize_trunk_api_write` / `trunk_write_requester` / `map_ceres_error`，文件缺失即 ERROR。⑰库测试用 `Disconnected` 的 `Storage::mock()`：鉴权前任何实体查询都会 panic，覆盖 token 的请求在 `tokio::spawn` 中以 `Disconnected` panic 结束，证明鉴权后才到入口。⑱`DEFER-FU-38` 复核后继续延后；⑲`DEFER-FU-39` 重启条件已触发、复核后继续延后；⑳`DEFER-FU-10` 补注别名行残留。㉑写集修订：`src/ceres/pack/import_repo.rs`、`src/lib.rs` 仅注释（入口已有产品调用者、调用方前置条件），不计入 G-04；`tests/integration_git_cli.rs` 的同类注释交 FU-21。㉒errors.md 登记 `HasChildren` / `CleanupNotFound` 两行与清理端点的出现场景。㉓IT SQL 一律绑定参数。另登记 `DEFER-FU-42..44`；记录漂移：errors.md 结构块与类型表缺 ImportRepoError、`docs/refactoring/integration.md` 的 IT 清单 → FU-23；R4 行把不泄漏用例归 FU-18（R6 后应为 FU-20），不改历史行 | 卡号不变 | FU-20 卡（Lifecycle、描述、Out of scope、证据、AC、Verification、写集、影响、安全、性能、粒度）、粒度审计表、ADR-FU-10 Context / 第 1、4、5 条 / Consequences、`DEFER-FU-10` / `38` / `39` / `42..44`、默认覆盖行（errors.md 登记）、追溯表、GAP-FU-07、测试矩阵、风险登记、故障恢复矩阵、FU-21 描述 |
| 2026-09-26 | FU-20 R1 独立评审 FAIL（1×P1 + 12×P2）+ Codex R1 PASS（无发现） | 独立评审（工作流：5 维查找、每条 3 反驳者、裁决 agent 复跑卡片库测试）。P1：`import_repo_remove_pending_continuation` 中「属于另一路径的 `cleanup_id` 不改台账」在该行已 `swept` 之后才断言，无法失败——改到首个 `pending` 之后、重新导入之前（台账仍 `detached`、98 000 行已删），同时断言对象行不变（新反向验证：入口去掉路径归属条件即失败）。P2：①契约页、errors.md 与 OpenAPI 的 409 称「无写」，但写入队列锁内再检的 409 留下一行 `Failed` 队列行——三处改为「不写台账、审计、ref、对象与根树」并注明该行；②「丢失 `cleanup_id` 后只带 path 的请求以 `pending` 返回最小待续 id」不全——预算内清扫完答 `absent`（契约页与故障恢复矩阵）；③OpenAPI 的 `repo_id` / `cleanup_id` 不在 `required`——加 `#[schema(required = true)]`，`import_repo_remove_openapi_contract` 断言四键皆 required；④`populated_then_absent` 未先断言叶子存在——补；⑤Verification 称「任何查询都会 panic」——改为实体查询 panic、原始查询的错误传播为 500；⑥路由挂载只经 OpenAPI 锁定——新增库测 `import_repo_remove_live_surface`（Review 404、GET 405 且 `allow: POST`、超过 2 MiB 413）；⑦「首尾空白」只测了行首——库测与 IT 补结尾空白；⑧errors.md 新行 `\|\|` 未转义使表格错列——转义；⑨errors.md 称「只带 `cleanup_id` 的续做」——`path` 必填，改为「带 `cleanup_id` 的续做」；⑩契约页本卡改动句中的行号锚点改为函数名；⑪卡片安全说明与设计定稿行②称鉴权前「不写日志」——改为 handler 自身不写日志、语法 400 的 error 日志含调用方输入（`DEFER-FU-43`）；⑫「全部为绑定参数的精确查找」——子仓检查为转义前缀扫描、台账按 id 或 `(path, state)` 读取。Codex R1（`/Applications/ChatGPT.app` 自带的 codex-cli；npm 包缺平台二进制）对修订前的终态 diff 无发现。证据按终态以 R1–R25 完整重跑 | 卡号不变 | FU-20 卡（安全、Verification）、设计定稿行②、故障恢复矩阵、契约页、docs/errors.md |
| 2026-09-26 | FU-20 R2 独立评审 PASS（5×P2）+ Codex R2 PASS（无发现） | Codex R2 用 `/Applications/ChatGPT.app` 自带的 codex-cli 审终态 diff，无发现。独立评审 5 条 P2 全部落实：①`populated_then_absent` 删除后的叶子断言在 GET /tree 非 200 时也会通过——改用断言 200 的 `tree_names("/third-party")`；②没有用例钉住 handler 传给鉴权的是目标路径（覆盖 token 都覆盖 `/third-party`）——`import_repo_remove_authorizes_before_any_query` 增加只覆盖 `/third-party/fu20-leaf` 的 token：对该叶子到达入口、对其它路径得固定 403（新反向验证 R26：把 `import_dir` 传给鉴权即失败）；③R1 行 `\|\|` 未转义使表格错列——转义；④追溯表「lib 八例」→「lib 九例」；⑤R1 行「R1–R24」→「R1–R25」。证据按终态以 R1–R26 完整重跑 | 卡号不变 | FU-20 R1 行、追溯表 |
| 2026-09-26 | FU-20 C 组 | `0.40.9` 干净副本与新建门禁库 `mega2_fu20_gate`：lib 1805 / 0 / 1，18 个 target 全部运行，失败集恰为 6 个基线环境用例 | 卡号不变 | FU-20 卡（Lifecycle） |
| 2026-09-26 | FU-21 设计定稿（ER-03 写集修订 + ER-10 轴内选择；DEFER-FU-02/15/42/44 复核） | 设计经工作流产出：读码地图三份（CLI 注册与进程装配、入口语义、测试与证据，交叉核查），3 个角度的独立设计（safety-first / minimal-diff / test-first），2 名评审打分，以 safety-first 为底综合。①进程装配不经 `AppContext::new`、从不打开 vault（`config` 每次截断重写 `core_key.json`、`open_readonly` 会 chmod——用户约束禁止触碰 vault 密钥），不迁移（只读连接确认无待执行迁移）、不 `init_monorepo`、不启动后台任务；只写 FU-17 入口本来要写的行与 Redis 雪花租约键。②`LoadMode::ParsedExistingConfig`（`FullAppContext` 走会生成默认配置的 `load()`）；③配置须经 `--config` / `MEGA_CONFIG` 点名（拒绝 cwd / global 来源）。④纯校验先于任何 I/O：clap → 配置来源 → validate / 对象格式 → storage-only → 字面值凭据 → 严格路径。⑤`vault://` SecretRef 拒绝而不解析（`DEFER-FU-46`），`object_storage_needs_vault` 改 `pub(crate)` 复用。⑥只在 storage-only 执行（`DEFER-FU-02` 扩展）。⑦第 1 轮为新操作或 `--cleanup-id` 续做，其后只续做，一次调用至多 detach 一次；`--max-rounds` 计全部轮次。⑧排空选择（交 FU-22）：主链后按台账排空该路径其余 `detached` 行、永不 detach，替代「再跑 `--path` / 循环至 `absent`」（二者都会 detach 重新导入）。⑨结局行语义与 HTTP 相同，每行带 `cleanup_id`。⑩新增 `--cleanup-id`（`push_auth=none` 上唯一对重新导入安全的续做方式）。⑪stdout 恰一行结局且为末行（`current_thread` 运行时），`print_std=true` 时此前为日志。⑫stdout 路径控制字符转义。⑬退出码 0/1/2/3/130（ADR-FU-11 补注）。⑭SIGINT：写集修订 `src/cli.rs` 一处条件，`import-repo` 并入记录式处理（`DEFER-FU-15` 收窄）。⑮中断 / 失败后的续做句柄：先关闭本进程连接池，再在只读事务中取 `MONO_WRITE_LOCK` 屏障后读台账（10 s 超时），「无句柄」由此成为确切结论。⑯未类型化失败沿用 `MegaError` 文本，记录清理前退出码 1、之后 3（`DEFER-FU-42`）。⑰requester 每轮 `operator-cli`（`DEFER-FU-45`）。⑱`DEFER-FU-44` 复核后继续延后（收紧会改变 FU-20 已发布的 HTTP 行为）。⑲FU-16 用例注释改写，`src/lib.rs` 注释改为两个产品入口（仅注释，不计入 G-04）；记录漂移：`AGENTS.md` 的执行器签名与 `dead_code` 位置、`tests/common/mod.rs` 的说明 → FU-23。⑳AC 改为八个单谓词：`audit_requester` 的两段断言并入 `removes`（新 detach）与 `absent`（排空匿名 detach），新增 `pending` 与 `interrupted`；VER 4→5（零命中守卫）；手工证据配方为一次性 `push_auth=none` 栈、先 unset `MEGA_DATABASE__*`。另登记 `DEFER-FU-45` / `46` | 卡号不变 | FU-21 卡（Lifecycle、描述、Out of scope、证据、AC、Verification、写集、影响、安全、性能、粒度）、粒度审计表、ADR-FU-11 Decision / Consequences、ADR-FU-10 第 1 条补注、`DEFER-FU-02` / `15` / `42` / `44` 与新增 `45` / `46`、故障恢复矩阵、风险登记、测试矩阵、追溯表、FU-22 描述 |
| 2026-09-26 | FU-21 R1 Codex FAIL（1×P1、2×P2）+ Claude FAIL（1×P1、14×P2） | ①Codex P1：写连接原为 `database_connection`，会在只读确认之后再跑迁移并补 `queue_control` 种子行——改用 `postgres_connection`（ER-03 写集修订：`src/jupiter/storage/init.rs` 仅可见性 `pub(crate)`，landing 4、prod-files 5），`requires_yes` (g) 在服务停止后删去该行、`absent` 运行不补回，零命中守卫加 `\bdatabase_connection` / `ensure_queue_control_seed`；②Claude P1：排空轮没有能失败的测试（排空时无存活仓库）——`absent` 新增三行匿名 detach + 存活重新导入的阶段，`--max-rounds 1` 停于排空（顺带覆盖 P2 排空轮数）、`--cleanup-id` 排空其余而重新导入不动；③未类型化失败映射：`removes` 暂停写队列 → 退出码 1、无结局行、无写；④`pending` 句柄可能指向已清扫行：stderr 改为「该路径的清理在完成前停下」，续做该句柄本就安全；⑤`resume_handle` 注释改正机制（关闭连接池使被中断轮的连接关闭而非复用，屏障保证确切），并写明超时与 `live_before` 窄窗；⑥`assemble` 与卡描述写明 Redis 租约续期任务、不播种；卡「安全」改为日志打码用户信息、性能预算补 `cleanup_by_id` 与排空末次空读；⑦`cli.rs` FU-08 文档注释归位、位置参数用例带 `--path`；⑧`latest_cleanup_for` 注释补第二个调用方（仅注释）；⑨ADR-FU-11 ⑤、`DEFER-FU-42`、FU-22 交接 ④ 补「台账不可读」结局（设计定稿行 ⑮⑯ 同此补充）；⑩屏障、其余 SIGINT 分支、`Resume::Known` 失败与 `live_before` 窄窗登记 `DEFER-FU-47`，风险行改正；⑪FU-23 交接悬空：`AGENTS.md` / `tests/common` 漂移改登记 `DEFER-FU-48`；⑫Codex P2 case 目录：六例加作用域守卫，结束（含 panic）删除共享 Git 工作根下的 case 目录；⑬Codex P2 配置路径：不改——回显的是操作者自己点名的路径，GC-FU-05 补范围说明；反向验证增至 26 项 | 卡号不变 | FU-21 卡（描述、证据、Verification、写集、安全、性能、粒度）、粒度审计表、ADR-FU-11 Decision、GC-FU-05、`DEFER-FU-42` 与新增 `47` / `48`、风险登记、测试矩阵、追溯表、FU-22 描述 |
| 2026-09-26 | FU-21 R2 Codex PASS（1×P2）+ Claude PASS（6×P2） | ①`DEFER-FU-47` ② 原称单测覆盖 `Resume::Unknown` 的 stderr 文本而实际未断言：失败路径文本抽为 `ledger_unreadable`，`import_repo_remove_contract` 断言两处 Unknown 文本含 `check import_repo_cleanups`、不含「rerun the same command」，③ 补失败后台账不可读分支；②卡描述与性能预算的「仅租约续期」补连接池自身的维护任务（sqlx 连接回收、Redis 连接驱动），`assemble` rustdoc 同步；③`Fu21Hold` 加 `Drop`（在自身运行时回滚，panic 时不在运行时之外丢弃事务导致二次 panic），`Fu21Child` 加 `Drop`（kill + wait，panic 时不留 CLI 子进程；Codex 同一条）；④故障恢复矩阵补台账不可读时无句柄的处置；⑤排空对象是该路径「其余」`detached` 行（`--cleanup-id` 时可含更新的行）：FU-22 交接 ⑤ 与排空日志措辞改正；⑥零命中守卫补 `Migrator::(up|down|fresh|refresh|reset)` | 卡号不变 | FU-21 卡（描述、Verification、性能）、`DEFER-FU-47`、故障恢复矩阵、FU-22 描述 |
| 2026-09-26 | FU-21 C 组（rebase 前，作废） | `0.40.10` 干净副本与新建门禁库 `mega2_fu21_gate`：lib 1808 / 0 / 1，18 个 target 全部运行，失败集恰为 6 个基线环境用例；混合归属的 `src/context/mod.rs` 在副本中以「HEAD + 本卡可见性改动」替换 | 卡号不变 | FU-21 卡（Lifecycle） |
| 2026-09-26 | FU-21 发布前 rebase（版本重算） | 推送前 fetch 发现 origin/main 已前进 8 个提交（media 计划 `plan-20260913` MF-00..MF-08），且已发布 `v0.40.10`（`6836eb0`）；按「以开工时权威 `version` 重算」本卡改为 `0.40.11`、FU-23 改为 `0.40.12`（发布窗口顺序、M3 / M4）。本地未推送的 FU-21 提交 rebase 到 origin/main，无冲突（仅 `Cargo.toml` / `Cargo.lock` 相同的版本行）；远端改动与 FU-21 文件无交集，ER-05 结论不受影响。其它会话在工作树中的未提交改动先整份备份、rebase 后恢复（`src/jupiter/tests.rs` 以三方合并补上远端新增的 `media_paging_storage` 字段）。远端新增可选依赖 `fastcdc =3.2.1`，本机无缓存，离线无法解析；`Cargo.lock` 的 mega2 版本行手工改为 `0.40.11`。上一行 C 组作废，在 rebase 后的树上以新建门禁库重跑 | 卡号不变 | 发布窗口顺序、里程碑 M3 / M4、FU-21 卡（Lifecycle） |
| 2026-09-26 | FU-21 C 组（rebase 后） | `0.40.11` 干净副本（origin/main `6836eb0` + 本卡）与新建门禁库 `mega2_fu21_gate2`：clippy `--all-features` 含 `fastcdc`（锁定版本 3.2.1 经用户同意 `cargo fetch --locked` 取得），lib 1816 / 0 / 1，18 个 target 全部运行，失败集为 5 个基线环境用例（OCI 用例已随 media 发布修复） | 卡号不变 | FU-21 卡（Lifecycle） |
| 2026-09-26 | FU-22 执行（ER-10 本卡轴内） | 事实经只读工作流核对（3 份读码地图 + 交叉核查，逐条 file:line）。①权威小节放在 `user-guide(.zh).md` 新增的第 2.6 节「ImportRepo 生命周期」（更新语义、并发与失败粒度、嵌套、清理两个入口、运维 CLI 用法 / 前提 / 结局行与退出码表 / 续做 / 台账不可读 / 被杀后的恢复、保留策略、兼容性），不重排既有节号；另加第 4.6 节 HTTP 清理入口、第 7 节 CLI 表一行、第 8 节表述；运维 CLI 契约的文档归属由此确立（此前只在计划中）。②AC-9：与更新契约冲突的无范围表述收窄为 Monorepo 路径——`user-guide` 2.1 导语（中文第 31 行原无限定）、4.2 导语、2.5 中 `MONO_PATH_NOT_ALLOWED` 的括注（存活 ImportRepo 内的产品写不返回此码）、`quick-start` 第 51 行。③README 两份在 ImportRepo 句后加契约句，同时点明 HTTP 需 push token、`push_auth=none` 用 CLI（评估栈为 none，只写 HTTP 会误导）。④quick-start 迁移示例补再次推送与 CLI 清理（`exec -T -e MEGA_LOG__PRINT_STD=false`，0.40.11 版本门，示例代码块内不加 `# ` 注释行以保持标题计数）。⑤errors.md 三行补 CLI（PathInvalid「任何 I/O 之前」、HasChildren、CleanupNotFound，均退出码 1），清理出现场景补 CLI 一条。⑥卡描述 ① 更正：`MEGA_CONFIG` 由镜像设置，评估栈 compose 文件本身不设；「当前证据」锚点更新。⑦不写：写集外的陈旧表述（`config/config.toml` 注释、`docs/recipes(.zh).md`、`directory-entry-api.md:478`），记入 R1 评审提示。⑧实测：`0.40.11` 门禁副本的二进制在一次性 `push_auth=none` 栈上跑通首推、新提交与 annotated tag 的再次推送（新克隆可见）、陈旧克隆推送被拒、CLI 清理（stdout 末行 `removed …`、退出码 0）、upload-pack 404 与 clone 失败、重新导入、未导入路径 `absent`，vault 密钥文件不变；`docker compose exec` 的容器内形式未实跑（拉取镜像需下载许可），其前提（镜像的 `MEGA_CONFIG`、字面凭据、`push_auth=none`）经 compose 文件与 Dockerfile 核对 | 卡号不变 | FU-22 卡（Lifecycle、描述、当前证据） |
| 2026-09-26 | FU-22 R1 Codex FAIL（4×P1、3×P2）+ 独立评审 FAIL（3×P1、13×P2） | ①兼容性与嵌套补存量例外（两方 P1）：只含 `.gitkeep` 且有分支的存量挂载在下一次新建或更新分支的推送时补齐来源（`push_queue_service.rs` 2046-2062，只删除的批次不补）；升级前挂载且已有嵌套子仓的父仓库、没有分支的存量挂载以 `IMPORT_REPO_PATH_OCCUPIED` 拒绝（ADR-FU-08 第 6 条，`DEFER-FU-23`；后者有单测），此时先清理再重推；执行行 ⑦ 原称该边角「无测试」，已删去。②清理期间的推送（独立 P1）：只有摘除提交时仍在进行中的推送得到 `IMPORT_REPO_REMOVED`，摘除之后开始的推送即使清扫未完也导入为新仓库（`register_import_repo` 不查台账）。③`exec -T` 下的 Ctrl-C（独立 P1，评审以本机已有的 alpine 镜像复现）：只结束 compose 客户端，容器内命令继续运行；表中 130 限于前台直接运行，quick-start 同步。④HTTP 与 CLI 的 `removed`（Codex P1）：同一清理机制，`absent` 都表示已排空；CLI 的 `removed` 也表示已排空，HTTP 的 `removed` 只保证所指清理完成。⑤再次推送示例（Codex P1 + 独立 P2）：改为具体的新提交与 annotated tag，并说明 `--all` / `--tags` 只推本地 ref，跟随上游全部 ref 用 `--mirror` 克隆与 `git fetch --prune origin && git push --mirror mega2`（实测：新分支与 tag 同步、上游删除的分支随之删除）。⑥quick-start 的 `interrupted` 指引（Codex P1）：只对 `pending` 给出 `--cleanup-id`，其余结局指向使用指南。⑦P2：STALE_REF 与 `fetch first` 的先后；CAS 限于推送；`import_dir` 本身的 400 在 Git 客户端的显示；退出码 1 的前缀为示例（补 `Database error:`），1 / 2 无结局行、3 / 130 有；台账查询为空的含义；compose 占位符补 `-p`；裸机沿用服务的 `--profile` 与 `MEGA_*` 环境；2.6 链接错误模型；2.3 的 `none` 注明 HTTP 清理例外；前提补「服务正在运行」（中断遗留的队列行由服务回收）；quick-start 清理前回到 compose 文件目录、版本门补 0.40.2 与升级步骤；「一律 403」限于合法请求（400 / 422 在前）；errors.md 的 PathInvalid 改为「连接数据库、Redis 与对象存储之前」 | 卡号不变 | FU-22 执行行 |
| 2026-09-26 | FU-22 R2 Codex FAIL（3×P1、3×P2）+ 独立评审 FAIL（1×P1、4×P2） | ①存量兼容的补救（独立 P1）：detach 只移除属于该仓库的挂载（`push_queue_service.rs` 1624-1645，`fu16_detach_without_provenance_keeps_tree`），无分支存量挂载清理后占位目录保留、重推仍被拒——文档改为「改用其它路径」并登记 `DEFER-FU-49`；嵌套存量父仓库只需备份并清理子仓库，父仓库随后接受分支推送；被拒的只是新建或更新分支的推送（Tag 与只删除分支的推送不受影响）；「移除挂载点」限定为属于该仓库的挂载。②被拒后的恢复（Codex P1）：`git fetch mega2`、合并或变基后再推送，有意覆盖用 `--force`，Tag 冲突单独处理。③`.git` 后缀（Codex P1）：`--path` 按存储路径精确匹配，Git URL 去掉末尾 `.git` 而 `--path` 不去；卡描述 ③ 同步。④写入队列（Codex P1，AC-9）：第 1 节与 4.1 限定为 Monorepo 路径，存活 ImportRepo 内的 `edit/save` 直接写默认分支、不经队列、不做 ref 校验（`import_api_service.rs` 526-538，`DEFER-FU-22`），2.6 并发段同述。⑤P2：排空只在主清理完成之后，以 `pending` 结束时其余行可能未处理；2.3 的「一律 403」补「合法请求」；台账查询改为不按状态过滤的 Compose `psql` 形式与 `docker compose top` 判断运行是否结束，空结果的下一步（仍能 clone 则重跑）——两条命令在测试栈上按原样执行通过；`--mirror` 覆盖 / 删除 mega2 独有 ref 的提醒与 LFS 的 `git lfs fetch --all origin` | 卡号不变 | FU-22 卡描述、`DEFER-FU-49` |
| 2026-09-26 | FU-22 R3 Codex FAIL（1×P1、4×P2）+ 独立评审 FAIL（1×P1、3×P2） | ①嵌套存量父仓库的补救写成有序步骤（独立 P1）：备份并清理子仓库 → 向父仓库推一次新建或更新分支补齐来源记录（可用临时分支）→ 再推回子仓库，第 ② 步之前推回会再次被拒（`push_queue_service.rs` 2046-2066）。②`absent` 行（Codex P1）：不再列举「会答 `absent`」的输入，改为 `--path` 按原样精确匹配、不去 `.git`、不纠正拼写，执行前核对（例如先 clone）；卡描述 ③ 同步。③P2：摘除时进行中的推送——Tag 逐个写入，摘除前已写入的 Tag 随旧仓库清扫，此后要写的 ref 以 `IMPORT_REPO_REMOVED` 拒绝；台账无 `detached` 行而路径仍能 clone 时，可能是原仓库也可能是重新导入的新仓库，先核对再重跑；第 1 节限定为编辑保存与 Tag 写，4.1 补「新建不受支持（当前回 500）」（`import_api_service.rs` 63-71）；存量挂载补齐来源前勿删光分支（`DEFER-FU-49` 补此成因）；卡描述 ④ 区分带 id 与不带 id 的 `interrupted`；LFS 镜像同步补 `git lfs push --all mega2`（实测：`git lfs fetch --all origin`、`git lfs push --all mega2`、`git push --mirror mega2` 之后新克隆得到真实的 1 MiB 对象字节）；英文 139 行多余的前导空格 | 卡号不变 | FU-22 卡描述、`DEFER-FU-49` |
| 2026-09-26 | FU-22 R4 Codex FAIL（1×P1）+ 独立评审 FAIL（1×P1、2×P2） | ①两方同一 P1：`absent` 行「先 clone 核对」查不出 `.git` 情形（Git URL 去掉末尾 `.git`、`--path` 不去）——改为用「查询台账」的 `psql` 形式精确查询 `SELECT id, repo_path FROM git_repo WHERE repo_path = '<P>'`，确认路径与仓库 id（该查询在测试栈上按原样执行通过）；②P2：第 1 节只保留编辑保存并指向 4.1；LFS 同步写成有序的完整命令链 `git fetch --prune origin && git lfs fetch --all origin && git lfs push --all mega2 && git push --mirror mega2`（实测：上游新增的 LFS 对象按此顺序同步后，新克隆得到真实字节） | 卡号不变 | — |
| 2026-09-26 | FU-22 R5 Codex PASS（无发现）+ 独立评审 FAIL（1×P1） | R4 写成 `&&` 链的 LFS 同步在上游缺对象时（本文 brewfs 示例即如此）停在 `git lfs fetch`（退出码 2），两次推送都不执行——改为逐条列出四步，并说明 `git lfs fetch` 以非零退出属预期、按 brewfs 示例设置 `lfs.allowincompletepush` 后继续后两步（实测：上游缺一个 LFS 对象时 `git lfs fetch --all origin` 退出 2，设置后 `git lfs push --all mega2` 与 `git push --mirror mega2` 成功、mega2 的 `main` 与上游一致） | 卡号不变 | — |
| 2026-09-26 | FU-22 R6 Codex PASS + 独立评审 PASS | 两方均无发现；本卡进入 `locally-accepted`，C / D 组由 FU-23 覆盖 | 卡号不变 | FU-22 卡（Lifecycle） |
| 2026-09-26 | FU-23 执行 | ①两处索引登记本计划（「收口中」；D 组绿后改「已发布，完成门待 `DEP-FU-05`」，完成门补跑通过后改「已完成」——R2 起按用户决定），横幅同步；②Review log 补齐 FU-19..FU-22（13 行）；③`DEFER-FU-31` 原定「FU-23 收口时删除」死代码写入者，本卡为只改索引与版本的收口卡，改为移交新计划（R2 起 FU-20 设计定稿交来的 `errors.md` 结构块与 `integration.md` IT 清单同样改道，登记 `DEFER-FU-50`）；④手写 release note 由工作流起草、两路对抗核对（事实 11 项、完整性 13 项）后修订，另两处由作者按 FU-22 定稿改正（`--path` 精确匹配、HTTP `removed` 的续做）；⑤聚合守卫脚本从各卡 AC 与 Verification 的 `(new)` 抽取 181 项（150 个精确用例名与 31 个前缀组，R1 另补 1 项为 182 项），逐一在源码中定位后对最终树全量日志检查；⑥FU-22 的 C / D 组由本卡正式运行后取得（本卡评审 PASS 之后） | 卡号不变 | 横幅、Review log、`DEFER-FU-31`、FU-22 / FU-23 卡（Lifecycle） |
| 2026-09-26 | FU-23 评审前门禁（非 C 组覆盖） | `0.40.12` 最终树干净副本与新建门禁库 `mega2_fu23_gate`：lib 1816 / 0 / 1，18 个 target 全部运行，失败集为 5 个基线环境用例；聚合守卫 182 项全部通过。版本 bump 与本次门禁早于 ER-05，违反「C 组绝不早于评审 PASS」，只作评审前证据，PASS 后正式重跑 | 卡号不变 | FU-23 卡（Lifecycle） |
| 2026-09-26 | FU-23 R1 Codex FAIL（2×P1、1×P2）+ 独立评审 FAIL（3×P1、11×P2） | ①两方 P1：FU-22 / FU-23 在评审 PASS 与推送之前被记为 `remote-pending`，且横幅与卡片对 FU-22 的状态不一致——两卡回到 `locally-accepted`，横幅、索引与修订历史同步；本卡的版本 bump 与门禁早于评审，违反「C 组绝不早于评审 PASS」，改记为评审前证据，PASS 后在最终树上正式重跑 C 组。②不采纳 Codex P1「全量须零失败零警告」：失败集为「执行检查必备需求」`DEP-FU-05` 登记的本机基线环境用例的子集（5 个：git-lfs ×4、s3 smoke），`ld` `__eh_frame` 提示为基线同有，同口径自 FU-13 R3 起经 Codex 认可，并用于 FU-01..FU-21 的全部发布。③独立 P1：release note 称完成判据「已填」——改写（R2 起按用户决定：D 组绿后勾选除「计划完成门」外的各项）。④P2：聚合守卫计数改为 182 项（151 个精确用例名 + 31 个前缀组），补 FU-21 Lifecycle 标为 `(new)` 而 AC / Verification 未列名的 `import_repo_remove_contract`（全量日志中通过）；索引行改为 FU-22 随 v0.40.12 发布；Review log 的 FU-19 R2 改为「13 条 P2 中 12 条」（修订历史 FU-19 R2 行同步）、FU-21 R1 补反向验证范围 R1–R22、「R1 行」改为「修订历史 R1 行」；release note 的 N = 1 行补「签名推送之后」、竞态写按 ref 说明、`IMPORT_REPO_PATH_INVALID` 不是 `ng` 原因、CLI 输出行的例外与 `exec -T` 下的 Ctrl-C、`DEFER-FU-49` 的删光分支成因、未匹配路径答 `absent` 且不删除任何内容 | 卡号不变 | 横幅、索引、Review log、FU-22 / FU-23 卡（Lifecycle）、修订历史 FU-19 R2 行 / FU-23 执行行 / 评审前门禁行 |
| 2026-09-26 | FU-23 R2 Codex FAIL（1×P1、2×P2）+ 独立评审 FAIL（2×P1、5×P2）；用户决定 | ①两方 P1：完成判据「计划完成门」要求 `cargo test --all` 全绿与 `cargo build --tests` 0 警告，没有 `DEP-FU-05` 例外，而最终树有 5 个本机环境失败（宿主 git-lfs 3.8.0 ≠ 钉住的 3.7.1；RustFS PUT 经 macOS 系统代理返回 502——测试子进程先清空环境变量，shell 的代理变量不起作用，R3 更正）与 macOS `ld` 提示。**用户决定（2026-09-26）：按 `DEP-FU-05` 发布 v0.40.12 并关闭 FU-23，「计划完成门」保持未勾**，计划状态记为「已发布，完成门待 `DEP-FU-05`（用户环境）」，环境修好后补跑；完成判据其余各项在 D 组绿后勾选；release note 同步。②独立 P1：Review log 补 FU-23 R1 行（本轮起逐轮记录）。③P2：聚合守卫来源改为「AC / Verification 181 项 + FU-21 Lifecycle 1 项」；执行行 ⑤ 的「181 个具名用例」改为 181 项；R1 行的修订范围列补被改动的修订历史行；release note 的 SSH 接收阶段文本与实测范围（宿主二进制、查询在测试栈、compose 容器内形式未实跑）；FU-20 设计定稿交 FU-23 的 `errors.md` 结构块与 `integration.md` IT 清单改道 `DEFER-FU-50`；证据补去敏的失败摘录（原因与基线登记相同） | 卡号不变 | 完成判据（计划完成门的处理）、横幅、Review log、`DEFER-FU-50`、FU-23 卡、修订历史 FU-23 执行行 / FU-23 R1 行 |
| 2026-09-26 | FU-23 R3 Codex PASS（1×P2）+ 独立评审 PASS（5×P2） | P2 均落实：①执行行 ① 与里程碑 M4 改为 D 组绿后记「已发布，完成门待 `DEP-FU-05`」，完成门补跑通过后才记「已完成」；②S3 冒烟的原因更正为 macOS 系统代理（`isolated_command` 先 `env_clear()`，shell 代理变量不传入子进程），与基线登记一致；③macOS `ld` `__eh_frame` 提示归入 `DEP-FU-05`，release note 同步；④R2 行修订范围列补被改的修订历史行，「计划完成门」条目注明用户决定；⑤release note 的实测范围改为 quick-start 与使用指南示例 | 卡号不变 | 里程碑 M4、`DEP-FU-05`、完成判据（注记）、修订历史 FU-23 执行行 / R2 行 |
| 2026-09-26 | FU-23 C 组（评审 PASS 后正式运行） | `0.40.12` 最终树干净副本与新建门禁库 `mega2_fu23_gate2`：lib 1816 / 0 / 1，18 个 target 全部运行，失败集为 5 个基线环境用例（原因与登记相同），`ld` 提示归 `DEP-FU-05`；聚合守卫 182 项全部通过 | 卡号不变 | FU-23 卡（Lifecycle） |
| 2026-09-26 | FU-23 收口 | D 组绿：`docker.yml` run `36220401014` 的 `docker` job 对 `4bf6cc2` 为 success；FU-22、FU-23 标 `done` / `complete` 并勾选清单；完成判据除「计划完成门」外全部勾选（`Rollback mode` 一项注明未做回滚演练）；「兼容与文档收口」8 项逐条核对后勾选（`errors.md` 三个错误域均已登记、`config.toml` 形状注释、`import_repo_cleanups` 实体与两个迁移按序登记、全部 docs 相对链接可解析、索引已同步）；横幅与两处索引改为「已发布，完成门待 `DEP-FU-05`」（用户决定，完成门补跑通过后改「已完成」） | 卡号不变 | 横幅、完成判据、FU-22 / FU-23 卡、`docs/plan/README.md`、`docs/plan/plan-long.md` |
| 2026-09-26 | `DEP-FU-05` 进展（v0.40.13，计划外维护） | ①用户修复 Clash Verge：扩展配置里的 `prepend-rules` 在 2.x 不生效，改在订阅「编辑规则」加 `127.0.0.0/8` 等 DIRECT 前置规则后，经代理访问回环 / 局域网地址由 502 变为 200，S3 冒烟通过（mega2 的 hyper-util 在 macOS 不读系统代理例外列表、测试子进程又 `env_clear()`，故系统例外对它无效）。②按用户要求把 git-lfs 钉住版本由 `3.7.1` 上调为 `3.8.0`：两处测试断言、两个 runner Dockerfile（版本与 GitHub release digest 的 sha256）、compose 镜像标签与 healthcheck、`docs/refactoring/test-infra.md`；runner 镜像已重建。③`docs/development.md` 新增「调试汇总：本机环境导致的测试失败」。④v0.40.13 最终树全量 18 个 target 0 失败；`DEP-FU-05` 仅余 macOS `ld` `__eh_frame` 链接提示，「计划完成门」仍按用户决定保持未勾 | 卡号不变 | 横幅、「执行检查必备需求」`DEP-FU-05` 口径、依赖登记表 `DEP-FU-05` |
| 2026-09-26 | 计划完成门补跑（用户决定） | D 组绿：v0.40.13 `docker.yml` run `36226158231` 的 `docker` job 对 `5e1cbd0` 为 success。用户决定 macOS `ld` 的 `__eh_frame` 链接提示是平台噪音、不用处理——「计划完成门」据 v0.40.13 最终树的门禁运行勾选（fmt、clippy 0 警告，`cargo build` 0 警告，`cargo build --tests` 仅该提示，全量 `cargo test --all --no-fail-fast` 18 个 target 0 失败，crate 级 `#![allow]` 仍只有开工时的 `dead_code` 一处）；`DEP-FU-05` 关闭；横幅、两处索引改为「已完成」 | 卡号不变 | 横幅、完成判据、里程碑 M4、`DEP-FU-05`、`docs/plan/README.md`、`docs/plan/plan-long.md` |

> 说明：R1 修订发生在任何实现开工之前，按 G-09 以本表为闭环凭证整体重排卡号（旧编号未被任何提交或外部文档引用）。

## 已决议设计决策

实现时若需偏离本节，必须先修改计划并说明原因，不得在代码中静默改语义。

### ADR-FU-01: 派生消息 = 源 commit 正文；按字节级文法剥离额外头（#28）

- **Status:** Accepted
- **Context:** git-internal 把 committer 行后的一切放进 `Commit.message`。Mega2 在 N=1 层消息、squash 主题、物化 commit、ImportRepo attach 根消息四处把它当作纯消息复用（E9–E11）。
- **Decision:**
  1. 在 `src/common/utils.rs` 提供唯一 helper `split_commit_message(message: &str) -> CommitMessageParts<'_> { headers: Vec<(&str, String)>, body: &str }`（键借用自原消息，值为拼接后的续行），文法（按字节，不 trim、不改 CRLF）：
     - `message` 以 `\n` 开头 → `headers = []`，`body = message[1..]`。
     - 否则逐行（以 `\n` 结尾）解析额外头块：行以单个空格开头 → 续行，必须有前一个头，否则整块判定为「非头块」；行为 `key SP value`，`key` 由 `[A-Za-z0-9-]` 组成且非空 → 新头；遇到空行 → 头块结束，`body` = 其后全部字节；遇到其它行或文件结束仍无空行 → 整块判定为「非头块」。
     - 「非头块」回落：`headers = []`，`body = message`（原样；覆盖历史未成帧消息，如 `create new directory demo`）。
     - 签名头 = key 为 `gpgsig` 或 `gpgsig-sha256` 的头（PGP 或 SSH armor 均由续行文法覆盖；截断/畸形 armor 仍按续行确定性解析）。正文中以 `gpgsig` 开头的行（位于空行之后）属于正文。
     - 既有 `parse_commit_msg`（`trim_start`、不识别 `gpgsig-sha256`）由新 helper 取代，零调用后删除（GC-02）。
  2. 派生 commit 只携带正文：签名头与其它额外头（`encoding`、`mergetag`、未知头）均不带入 Mega2 自己合成的 commit（helper 仍返回全部头，不丢信息）。
  3. `TrunkProvenance::from_tip` 的 `n1_message` = tip 正文；`commit_subject` 在正文上取首个非空行（去首尾空白，仅用于列表展示）。
  4. 签名路径不变：`sign_commit_preserving_identities` 以正文为 message，`embed_gpgsig` 负责头/体空行。
  5. 未签名派生 commit 经 `format_commit_msg(…, None)` 成帧：物化 commit 取完整正文 `format_commit_msg(body, None)`；ImportRepo attach 根 commit 保持既有「只取主题行」语义（原 `format_message()` 即取首个非空行，只认 PGP），主题 = `commit_body_subject(body)`，即 `format_commit_msg(commit_body_subject(body), None)`，对 PGP / SSH / `gpgsig-sha256` 一致。
  6. 被推路径 P 在 N=1 时仍是客户端 commit 逐字落地。
- **Alternatives considered:** 只修显示层（拒绝：Git 同样显示错）；把客户端签名头保留在合成 commit 头部（拒绝：必然验签失败）；改写历史 commit（拒绝：身份承载）。
- **Consequences:** 升级后新合成的层/物化 commit 字节与 id 变化；无签名 tip 的层消息不再多一个前导空行；历史对象不变（`DEFER-FU-07`）。
- **Revisit when:** git-internal 把额外头拆为结构化字段（`DEP-FU-02`）。

### ADR-FU-02: 服务端合成 commit 必须有头/体空行

- **Status:** Accepted
- **Context:** `Commit::from_tree_id(tree, parents, "create new directory …")` 生成缺头/体空行的对象（E12）。
- **Decision:** 生产路径所有未签名合成调用（`Commit::from_tree_id` / `Commit::new`，含 `mono_api_service.rs`、`mono_storage.rs` 与 `ImportApiService::save_file_edit`（`import_api_service.rs:475`））传入的消息经 `format_commit_msg(msg, None)` 成帧，恰好一次；签名路径（`embed_gpgsig`）既有帧不变。
- **Alternatives considered:** 改 git-internal（拒绝：外部 crate）；读出时修补（拒绝：对象身份已固定）。
- **Consequences:** 新 API commit id 变化；历史错帧对象不改写，严格客户端仍会拒收含其历史的路径——`docs/deploy-trunk.md` 登记已知限制（`DEFER-FU-07`）。
- **Revisit when:** 出现存量错帧对象迁移需求。

### ADR-FU-03: 路径策略与 ImportRepo 错误域、稳定码

- **Status:** Accepted
- **Context:** `docs/errors.md` 扩展规则要求新领域错误进 `src/common/errors/mod.rs` 并经 `MegaError` 包装；Git report-status 只能携带字符串。
- **Decision:**
  1. `PathPolicyError`：`NotAllowed { path, allowed_roots, import_dir }`、`Uninitialized { path }`、`Invalid { path, reason }`、`Conflict { path, component }`；码 `MONO_PATH_NOT_ALLOWED` / `MONO_PATH_UNINITIALIZED` / `MONO_PATH_INVALID` / `MONO_PATH_CONFLICT`。
  2. `ImportRepoError`：`PathOccupied`、`StaleRef`、`Removed`、`PathInvalid`、`HasChildren`、`CleanupNotFound`；码 `IMPORT_REPO_PATH_OCCUPIED` / `IMPORT_REPO_STALE_REF` / `IMPORT_REPO_REMOVED` / `IMPORT_REPO_PATH_INVALID` / `IMPORT_REPO_HAS_CHILDREN` / `IMPORT_REPO_CLEANUP_NOT_FOUND`。FU-12 一次性定义完整错误域（变体、码、`Display`、`ApiError` 映射）；**每个码在首次对用户暴露它的卡中登记 `docs/errors.md`**（发布安全）：FU-12 `IMPORT_REPO_STALE_REF`、FU-13 `IMPORT_REPO_PATH_OCCUPIED`、FU-18 `IMPORT_REPO_REMOVED` 与 `IMPORT_REPO_PATH_INVALID`、FU-20 `IMPORT_REPO_HAS_CHILDREN` 与 `IMPORT_REPO_CLEANUP_NOT_FOUND`（FU-16/FU-17 的原语无用户入口，不暴露）。
  3. 两者 `Display` = `"<CODE>: <人读消息>"`；`MegaError::PathPolicy(#[from] PathPolicyError)` 与 `MegaError::ImportRepo(#[from] ImportRepoError)` 用 `#[error("{0}")]`（无 `Other error:` 前缀）。同一文本进 Git `ng` 行与 API `err_message`。
  4. `ApiError` 映射：`NotAllowed` / `Invalid` / `PathInvalid` → 400；`CleanupNotFound` → 404；`Conflict` / `HasChildren` / `PathOccupied` / `StaleRef` → 409；`Uninitialized` 只出现在 Git 面（若到达 API 按 409）；`Removed` 在 Git 面出现，FU-18 起经 `edit/save` 的对象批、FU-19 起还经 `edit/save` 的预读与默认分支 ref 写以及 tag 写到达 API，均按 409。
  5. `NotAllowed` 列出允许的根（`/<name>`，排序）与 ImportRepo 目录；任何消息不含配置文件路径、`base_dir`、数据库/对象存储地址或凭据。根名称已可经 `GET /api/v1/tree?path=/` 与 clone 读取；`push_auth=token` 下推送者在分类前已认证。
  6. `Uninitialized` 点名开通动作：`mega2 path provision --server <url> <path>` 与 `POST /api/v1/path/provision`，随后 clone、在其上提交、推送。
- **Alternatives considered:** 继续 `MegaError::Other` + `[code:xxx]`（拒绝：`docs/errors.md:77` 标为过渡）；只给 HTTP 加 JSON `code` 字段（拒绝：Git 面无法携带）。
- **Consequences:** 码是公开契约，改名需 minor + 文档。
- **Revisit when:** 统一的数值错误码注册表落地。

### ADR-FU-04: `root_dirs` 形状校验 + 「创建」白名单；import 目录优先

- **Status:** Accepted
- **Context:** #29 要求根外目标返回稳定策略错误；`root_dirs` 条目在 `init_trees` 中逐字作为根树项名，含 `/`、重复、`.`/`..`、空串的条目今日生成非法根树；默认配置同时把 `third-party` 列入 `root_dirs` 并设 `import_dir="/third-party"`。
- **Decision:**
  1. 配置校验（`config validate` 与服务启动同一路径）：`root_dirs` 每项非空、不含 `/` 或 `\`、不等于 `.` 或 `..`、不含 NUL、互不重复、无首尾空白（环境变量列表解析不 trim），且不等于 `init_trees` 自带的根条目名（`converter.rs::INIT_ROOT_RESERVED_NAMES`：`.mega_cedar.json`、`.cedar`、`.buckroot`、`.buckconfig`，否则根树重复条目）或 `.git`（不区分大小写）；`import_dir` 必须是规范绝对路径（`canonicalize_mono_ref_path(import_dir) == import_dir`）、≠ `/`、不含 NUL 与 `\`（`canonicalize_mono_ref_path` 本身接受 NUL，`utils.rs:165`，故单独校验），且其**首组件必须属于 `root_dirs`**（`init_trees` 只预建 `root_dirs`，`converter.rs:428-443`；否则首次 ImportRepo attach 会经 `search_and_create_tree` 新建顶层树，违反「不由 Git push 创建新顶层根」）。违反即校验失败并点名字段（无 secret）。`config/config.toml` 与两份 storage-only 样例配置的注释同步写明上述约束。
  2. 分类函数 `classify_creation_path(config, canonical_path)`（唯一实现，开通 API、产品写与 receive-pack 共用）输入必须已是规范路径：import 目录（组件级 `starts_with(import_dir)`）→ `NotAllowed`（附「ImportRepo 由推送创建」提示，**import 优先**，即使 `root_dirs` 含同名项）；`/` → `Invalid`；首段 ∉ `root_dirs` → `NotAllowed`；否则 `Allowed`。规范化分两种入口：**客户端 JSON 输入**（开通 API；清理 API 与运维 CLI 见 ADR-FU-10）先显式拒绝 NUL 与 `\`，再要求原始输入满足 `input == canonicalize_mono_ref_path(input)`（重复斜杠、尾斜杠、`.`/`..` 段、相对路径均判 `Invalid`；`canonicalize_mono_ref_path` 会静默规范化别名且接受 NUL，`utils.rs:160-190`）；**Git 协议 URL 路径**沿用 TP-08 的「先规范化再使用」（`protocol/mod.rs:236-262`；Git/Libra 客户端会发送带尾斜杠的远端 URL，不得因此拒绝），规范化失败或含 NUL 时拒绝。
  3. 分类只作用于**创建**动作：开通 API；trunk 下 `old_id=ZERO` 且 P 在当前根树中不可解析的推送。已可解析的路径不重新校验。
- **Alternatives considered:** 所有推送都校验首段（拒绝：会拒绝既有非 `root_dirs` 顶层目录，如 `.cedar`）；只改文案（拒绝：#29 AC1 需要稳定策略面）。
  4. 分类同样作用于**产品写**：`resolve_trunk_land_path` 找不到非根 tip 时先分类写路径，且 import 命名空间守卫无条件先行（ADR-FU-06），使 Git 与 API 对根外路径与 import 目录返回同一码。API 面三类情形的对应：「根外」→ 同一 `MONO_PATH_NOT_ALLOWED`；「合法根下未开通」→ 不是错误（产品写与开通 API 本身就是开通动作）；「真实 NFF」→ 不适用：产品写不携带客户端基线 commit，冲突由 MonoWriteQueue CAS 重排内部解决（`DEFER-FU-08` 登记理由）。
  5. B3 push 的真创建分支（`path_row` 缺失且 P 在根树不可解析）在锁内再调用一次分类（纵深防御）；`path_row` 缺失且 `old_id≠ZERO` 已由 B3 以 `cannot update missing path` 拒绝（`push_queue_service.rs:1791-1799`），因此创建只可能来自 `old_id=ZERO`。
- **Consequences:** 关闭未文档化的「fork 型创建新顶层」——FU-10 `minor`；非法 `root_dirs` 配置从「生成坏根树」变为「启动前失败」。运维新增根：改 `root_dirs` + 重启，再经 `git push` 创建该根（开通 API 不能在 `/` 落地，`DEFER-FU-14`）。
- **Revisit when:** 需要运行时增删根目录。

### ADR-FU-05: 开通操作 = 幂等 HTTP API + 薄 CLI；按最高新建组件授权

- **Status:** Accepted
- **Context:** #25 要求受支持、可发现、幂等的开通，旅程不需手写 HTTP；保留「无父提交不得静默成为任意子树」。
- **Decision:**
  1. `POST /api/v1/path/provision`，请求 `{ "path": "/project/workbuddy/demo" }`，只挂 storage-only 写路由。`mkdir -p` 语义：先 `classify_creation_path`；任一已存在组件不是目录 → `MONO_PATH_CONFLICT`；整条路径已是目录 → `200 { path, created: false, commit_id: null }`，零写；否则一次 commit 补齐全部缺失层（叶子带 `.gitkeep`），经 `commit_tree_update` → MonoWriteQueue → `200 { path, created: true, commit_id }`。建树由开通专用、绑定单一根树快照的构建器完成（FU-07 R1 起不复用 create-entry 的子串式缺失层推导）：落地前以同一快照重算最高新建组件并与已鉴权的计划比对，落点 tip 的 tree 与快照不一致时重来（见本计划变更记录 FU-07 R1）。
  2. 授权：所需范围 = 本次请求将新建的**最高**路径（第一个缺失组件）；无需新建时 = 目标路径。以该路径调用 `authorize_trunk_api_write`。每次 prepare 重新计算（落地 CAS 失败重 prepare 时重新授权），防止 TOCTOU 扩大写范围。
  3. 并发：落地因 CAS/重排失败或 prepare 期间路径被他人创建时，重读；已成为目录则返回 `created:false`。
  4. CLI `mega2 path provision --server <URL> <PATH>`：`LoadMode::None`（不读配置）；token 只从环境变量 `MEGA2_TOKEN` 读取并以 `Authorization: Bearer` 发送；无 argv token 选项；不跟随跨主机重定向；超时 30 s；输出一行（`created <path> (<commit>)` / `already exists <path>`），退出码 0；服务端错误原样打印 `<CODE>: …` 到 stderr，退出码 1。
  5. 无父首推到未开通路径继续拒绝（`MONO_PATH_UNINITIALIZED`）。
- **Alternatives considered:** 放开无父首推（拒绝：违背 issue 不变量）；Git push-option 显式开通（拒绝：未实现 `push-options`，Libra 0.23.46 无入口）；让 create-entry 自身幂等（拒绝：Libra pin 契约）；按目标路径授权（拒绝：窄 token 可创建全局可见的祖先容器）。
- **Consequences:** 新增一个写端点与一个 CLI 子命令；Libra 原生入口经 `DEP-FU-03` 移交。
- **Revisit when:** Libra 提供原生开通命令。

### ADR-FU-06: 全新栈产品写落点回落到惰性物化的一级根

- **Status:** Accepted
- **Context:** `resolve_trunk_land_path` 只接受已有 `main` ref 的非根祖先（E5）。
- **Decision:** 无候选时先对写路径调用 `classify_creation_path`：`NotAllowed` / `Invalid` 直接返回对应 `PathPolicyError`（HTTP 400，文本与 Git 面一致；写路径为 `/` 时按 `NotAllowed` 处理——API 不创建新顶层根）；`Allowed` 时对 `/<首段>` 调用既有 `materialize_path_refs`（与 advertise 同一原语，幂等）后返回该路径。**永不**物化 `import_dir` 或其子路径（分类已把它判为 `NotAllowed`；否则 attach 祖先预检会拒绝全部后续导入，`mono_storage.rs:843-882`），也**永不**物化嵌套 `import_dir`（如 `/third-party/vendor`）的严格祖先（`path_policy::is_import_dir_ancestor`，同一预检理由）：回落落点若是这样的祖先，则不物化、返回 `MONO_PATH_UNINITIALIZED`（先经开通动作建立更深的非 import 路径）。另设**无条件的 ImportRepo 命名空间守卫**：凡经 `MonoApiService` 的产品写（create / edit-save / delete / move / 开通），**每一个**被改写的规范路径操作数（move 的源与目的都算）组件级位于 `import_dir` 之下（含 `import_dir` 本身）时，在落点解析之前一律返回 `MONO_PATH_NOT_ALLOWED`，不论 `main@/third-party` 是否曾被物化、不论该路径是否刚被清理（有存活 `git_repo` 行的路径仍由 `api_handler` 分派给 `ImportApiService`，不受影响）。其它已有非根 tip 的写路径不经分类，行为不变。
- **Alternatives considered:** 落在 `/`（拒绝：B0 拒绝根路径写）；要求先 clone（拒绝：#25 痛点）。
- **Consequences:** create-entry / edit-save / delete-entry / move-entry 在全新栈上可用；根外路径的产品写从拓扑错误变为 `MONO_PATH_NOT_ALLOWED`（#29 跨面一致）。
- **Revisit when:** B0 允许根路径 API 写。

### ADR-FU-07: 孤儿链拒绝具有黏性

- **Status:** Accepted
- **Context:** 孤儿拒绝因对象已入库而漂移（E3/E4）。
- **Decision:** `PushChain::resolve` 在 `old_id=ZERO` 且第一父链走到无父根时，无论 tip 新旧都返回同一类型化孤儿错误（内部变体）；`PushChain::from_known_tip` 在 `old_id=ZERO` 走到根时同样返回它。孤儿错误对外文案保持 `Can not init directory under monorepo directory!`（review 形态最终文案；trunk 形态由 FU-10 映射为路径策略码）。`old_id≠ZERO` 的一切拒绝文案与对齐提示不变。
- **Alternatives considered:** 在 finalize 前按对象已知性分支（拒绝：正是漂移来源）。
- **Consequences:** 重试文案从 `push chain is broken` 回到首推文案——缺陷修复，与 plan-20260827 黏性原则一致。
- **Revisit when:** N/A。

### ADR-FU-08: ImportRepo = 可增量更新的普通 Git 仓库（#26 选项 1）

- **Status:** Accepted
- **Context:** 四份文档承诺多分支、客户端 tag、持续跟随上游；`edit/save` 已能直接推进 ImportRepo ref；attach 挂载只是 `.gitkeep` 占位；`import_dir` 下树内容只由 attach 产生（Monorepo 推送与产品写不在 import 目录落地，ADR-FU-06 进一步保证不物化）。
- **Decision:**
  1. B3 attach 挂载幂等，以**持久的挂载来源记录**为据：首次挂载成功时在同一事务写一行 `audit_logs`（`action=create`、`target_type=repository`、`target_id=repo_id`、`metadata={kind:"import_repo.attach", path}`，经 `idx_audit_logs_target` 查询）。后续推送目标已是目录时，只有该仓库对该路径存在来源记录才走「跳过 `search_and_create_tree` 与根 commit、只写 ref」（队列行 `landed_commit_id` 取当前根 commit）；**存量挂载**（升级前无来源记录）按确定性规则惰性回填：叶子恰为只含一个 `.gitkeep` blob 的树，且该仓库已有 ≥1 条分支 ref → 视为既有挂载并在同一事务写入来源记录；其余情形（普通目录、文件、只含 `.gitkeep` 但仓库无分支）→ `IMPORT_REPO_PATH_OCCUPIED`，根树不变；物化预检失败保留其 I3 明细（它守护已物化的 Monorepo 路径，与挂载归属无关；客户端文本 `ImportRepo attach failed: <明细>`）；其余未归类失败只返回固定句 `ImportRepo attach failed (push_queue id <N>); retry the push`，原因只留在队列行 `push_queue.error_message`、不写日志（FU-13 R3 / R5）。写入队列把 Done 行当作其操作 id 的永久重放键，而同一组命令在强推、删除后可以合法地再次出现：因此 Done 重放只有在本次分支命令已生效（Create / Update 的 ref 等于 `new_id`、Delete 的 ref 不存在）时才视为幂等重试，否则以新的操作 id 重新入队、由 B3 的 CAS 裁决（FU-13 R1）。只含删除的分支批（以 `is_protocol_zero_id` 判定，40 / 64 位零 id）同样入队、在 B3 事务内只做 ref CAS（GC-FU-03），不经物化预检与挂载归属判定——删除从不改树，二者不提供保护，却会拒绝 v0.40.1 可删的存量形态与祖先已物化的形态（FU-13 R4 / R5 / R6）。
  2. 分支 ref（B3 事务内）与 tag ref（`update_refs` 直写，条件语句）都按标准 receive-pack 语义 CAS：`Create` 要求 ref 不存在；`Update` 要求当前值 = `old_id`；`Delete` 维持既有 `remove_ref_if_unchanged`。失败 → `IMPORT_REPO_STALE_REF`；分支 CAS 失败回滚到 savepoint 并终态化队列行 `Failed`。
  3. 不做服务端 `denyNonFastForwards`：客户端 `--force` 的非 ff 更新按普通 Git 接受。
  4. 成败粒度：tag 命令逐 ref 独立（unpack 后直写，先于分支处理，与分支结果无关）；同一 push 内的**分支**命令作为一个批在同一 B3 事务内应用——任一分支 CAS/校验失败则本批全部分支 `ng`、无一更新（比 stock Git 的逐 ref 更严格，避免部分分支前进；`smart.rs:605-617` 现有「finalize 失败标记全部仍 ok 的分支」语义保持不变，不改协议层）。未广告 `atomic`。在用户文档声明。
  5. 客户端文案去掉 `attach B3 did not complete successfully: {Debug}`，改为 `ImportRepoError` 的 `<CODE>: …`；未知失败回落为不含 Debug 结构的通用句。
  6. 兼容：存量已挂载 ImportRepo 无需数据迁移即可接受后续推送（存量别名路径由 FU-15 规范化；叶子下已有嵌套子仓的存量父挂载不是只含 `.gitkeep` 的形态，得到 `IMPORT_REPO_PATH_OCCUPIED`，见 `DEFER-FU-23`）；首推失败遗留的 `git_repo` 行（无分支 ref、无叶子）按首推处理。
  7. **import 根不是 ImportRepo：** 协议分派（`repo_handler_with_commands`）在 TP-08 规范化之后、任何 `git_repo` 查找或创建之前，调用叶子校验核心 `check_import_repo_leaf(config, canonical_path)`（拒绝含 NUL、不严格位于 `import_dir` 之下——即等于 `import_dir`——的路径）；路径等于 `import_dir` 的 Git 请求被拒（upload-pack 与 receive-pack 均为 400 `IMPORT_REPO_PATH_INVALID`），不产生行、ref、对象或根改写。TP-08 的旧别名行回退与自愈保持不变；存量别名行由 FU-15 迁移一次性规范化。升级前已存在的 `import_dir` 本身的 `git_repo` 行从此不再被服务（惰性，`DEFER-FU-09` 登记清除）。
- **Alternatives considered:** 选项 2「一次性导入 + `IMPORT_REPO_IMMUTABLE`」（拒绝：与四份文档和 `edit/save` 现状矛盾）；绕开队列写分支 ref（拒绝：失去 MonoWriteQueue 串行化与 reaper/收养语义）。
- **Consequences:** 更新推送不产生 Monorepo 根 commit；嵌套 ImportRepo 先父后子可导入，父仓库随后仍可更新（其来源记录认领含子仓的目录）；先子后父时父路径已是含子仓的普通目录，得到 `IMPORT_REPO_PATH_OCCUPIED`（`DEFER-FU-23`）；清理由 ADR-FU-10 的子仓检查约束。
- **Revisit when:** 需要服务端强制 ff、保护分支或 `atomic`。

### ADR-FU-09: ImportRepo 清理 = 原子摘除（带栅栏与事务内审计）+ 锁外可续清扫

- **Status:** Accepted
- **Context:** #27 要求授权、可审计、幂等、之后不可 advertise/clone；允许延迟 GC。叶子只写根 ref，因此摘除走同一 attach 机制；Codex R1 指出 attach/detach 的队列身份、陈旧 attach、审计事务性与续做关联必须显式定义。
- **Decision:**
  1. **操作身份：** attach payload 增加 `op: AttachOp`（`Attach` | `Detach`，serde `default = Attach`，存量行兼容，无迁移）。detach 入队用 `detach_operation_id = sha256("import_repo.detach\0" + repo_id + "\0" + canonical_path)`（域分离；attach 的 `attach_operation_id` 不含该前缀）。同一 `repo_id` 的重复 detach 按 `(kind, path, operation_id)` 重放；重新导入得到新 `repo_id` → 新 id。
  2. **B3 detach（同一 `MONO_WRITE_LOCK` 事务，savepoint 包裹）：** 校验 `git_repo` 行 `id = payload.repo_id` 且规范 `repo_path = payload.repo_path`（否则按 `absent` 终态 `Done`，无写）；先以 `SELECT id FROM git_repo WHERE id=$1 FOR UPDATE` 锁住 P 自身的行，再在同一事务内检查子仓（`repo_path LIKE escape_like(path) || '/%' ESCAPE '\'`，绑定参数；排除规则见 ADR-FU-10 第 3 条），存在即 `IMPORT_REPO_HAS_CHILDREN` 终态 `Failed`、无写。**祖先生命周期栅栏**（与第 5 条同属 FU-18）：子仓 `git_repo` 行的注册（`repo_handler_with_commands` 的 ReceivePack 分支，`protocol/mod.rs:269-277`）改为在同一事务内先对其全部祖先 ImportRepo 行取 `FOR SHARE`（按组件枚举祖先路径，绑定参数 `repo_path IN (...)`）再插入。两把行锁互斥，因此只有两种串行结局：子仓注册先提交 → detach 取得行锁后必看到子仓 → `HAS_CHILDREN`；detach 先取得行锁 → 子仓注册等待其提交后看到父行已删除 → 作为与父无关的独立新导入注册（等同清理之后的全新导入，以自己的叶子挂载）。叶子缺失（首推失败遗留）时 detach 跳过树改写，仍删除行并审计；仅当该仓库对该路径存在挂载来源记录（或满足 ADR-FU-08 第 1 条的存量规则）时，从根树移除叶子（新根 commit，ADR-FU-02 成帧），否则不改根树、只删行（普通目录永不被清理删除）；若 `import_dir` 之下的父目录因此变空则一并移除，`import_dir` 本身为空时保留 `.gitkeep`；删除该 `repo_id` 的 `import_refs` 与 `git_repo`；插入审计行（第 3 条）。任一步失败回滚到 savepoint、终态化 `Failed`，四类状态均不变。
  3. **审计：** `AuditStorage::log_audit_in_txn<C: ConnectionTrait>(conn, …)`（FU-13 引入，`log_audit` 改为委托它）。行值：`actor_type=human`、`actor_id=0`（保留值：storage-only 无数值用户 id）、`action=delete`、`target_type=repository`、`target_id=repo_id`、`metadata={kind:"import_repo.remove", cleanup_id, path, requester, phase}`；`cleanup_id` = 该 detach 的 `push_queue` 行 id；`requester` = token 名或 `anonymous`；不含 token。detach 行 `phase="detached"`（事务内）；清扫完成写 `phase="swept"` + 各表删除行数（锁外）。
  4. **清扫（锁外）：** 按 `repo_id` 分批删除 `git_commit` / `git_tree` / `git_blob` / `git_tag`（每条语句 ≤ 1000 行，依 `repo_id` 前导索引：每步在自己的短事务里 `SET LOCAL enable_seqscan = off` 与 `enable_bitmapscan = off`，`WHERE repo_id = $1 LIMIT n` 于是只剩 `repo_id` 前导索引上的索引扫描，与统计量无关地在 n 个活行后停止；外层按主键删除，`repo_id` 防护写成不可走索引的 `repo_id + 0 = $1`；表完成以同一形态的 `LIMIT 1` 探测判定），受第 6 条的每请求预算约束；首次清理请求在 detach 后立即清扫，超出预算时返回 `pending`。
  5. **存活栅栏（覆盖全部 ImportRepo 元数据写入，含对象行）：** 统一原语 `lock_live_import_repo(txn, repo_id, canonical_path)` = `SELECT id FROM git_repo WHERE id=$1 AND repo_path=$2 FOR SHARE`（绑定参数；第二个参数是调用方解析该行所用的路径，Git 面上即规范路径，FU-18 设计定稿）。以下每一次写都在自己的事务内先取该锁，行不存在 → `IMPORT_REPO_REMOVED`（「推送期间该 ImportRepo 已被清理，请重新推送以重新导入」），本次写不落任何行：`ImportRepo::traverses_tree_and_update_filepath` 的 `git_blob.file_path` 更新（`import_repo.rs` 的 `finalize_receive_pack` → `traverses_tree_and_update_filepath` / `filepath_pairs` / `collect_git_blob_filepaths`；先做一次存活检查，失败即在解引用任何对象之前返回，计算完成后在同一事务内取锁并更新，该函数中的 `unwrap()` 改为错误返回）；`ImportService::save_entry` 的每一批 `git_commit` / `git_tree` / `git_blob` / `git_tag` 插入（receive-pack unpack 与 `ImportApiService::save_file_edit` 共用，`import_service.rs` 的 `save_entry` / `insert_objects_in_txn`）；B3 attach（含更新模式）；`update_refs` 的 tag 写；`attach_to_monorepo_parent` 的仅删除分支写；`ImportApiService` 的 `edit/save` 默认分支 ref 更新（对象行先经 `save_entry`，ref 在其后自己的带锁事务里写）、annotated tag 创建（`git_tag` 行 + ref，同一事务）、lightweight tag 创建（ref）、tag 删除（ref + `git_tag` 行，同一事务）（`import_api_service.rs` 的 `save_file_edit` / `create_tag` / `delete_tag`，FU-19；API 面第二个参数为 `find_git_repo_like_path` 所得行的存储路径；预读失败时再检存活，仓库已被清理即 `IMPORT_REPO_REMOVED`；这些事务同样遵守锁序：打开期间不取第二个池连接、不跨 `save_entry` 或写入队列）。行锁与 detach 的 `FOR UPDATE` / `DELETE FROM git_repo` 互斥：先取得共享锁的写事务提交后 detach 才能删除（`import_refs` 行由 detach 自身删除，对象行随后由第 4 条清扫删除）；detach 提交之后任何写都取锁失败而不落行。因此**不存在 detach 之后写入的元数据行**，`phase="swept"` 是终态，进程在任意时刻崩溃都不会留下清扫遗漏；对象存储中的 blob 字节在元数据写之前写入，按第 7 条保留。
  6. **续做（清理台账）：** 新表 `import_repo_cleanups`（FU-14 迁移）：`id`（= `cleanup_id` = detach 队列行 id，主键）、`path`、`repo_id`、`state`（`detached` | `swept`）、`requester`、`rows_deleted`（json）、`created_at`、`swept_at`；索引 `(path, state, id)`，续做查询固定为 `WHERE path = $1 AND state = 'detached' ORDER BY id ASC LIMIT 16`（按 `(path, state, id)` 索引读取，最多对该路径的待续行做 top-16 排序，与台账累计规模无关）。detach 在同一 B3 事务插入 `state=detached` 行（与审计行一起回滚）；清扫完成后按主键条件更新为 `swept`（`WHERE id=$1 AND state='detached'`，幂等）。清理入口在目标路径无存活 `git_repo` 行时，按 `(path, state='detached')` 索引查询待续做台账行（有界：每行对应一次 detach），按上述查询按 `id` 升序分页续做，**每个请求的工作预算固定**：至多处理 16 条台账行、至多执行 100 批清扫语句（≤ 100 000 行）；预算内完成则返回 `absent`，预算用尽仍有剩余则返回 `pending`（台账行保持 `detached`，下一次请求从最小 `id` 继续——台账本身即持久续做游标）；多次「清理 → 重新导入 → 清理」循环各有独立台账行。`audit_logs` 只作证据，不作运营查询。后台续做（reaper）仍为 `DEFER-FU-06`。
  7. 对象存储 blob 字节**不删除**（内容寻址、与 Monorepo 共享），文档声明保留策略（`DEFER-FU-01`）。
- **Alternatives considered:** 锁内同步删全部元数据（拒绝：成本随仓库规模增长，阻塞全局写）；`git_repo.deleted_at` 软删除列（拒绝：迁移 + 所有查找点加过滤）；改键到保留路径做墓碑（拒绝：隐式保留命名空间）；按 `audit_logs` JSON 字段续做（拒绝：无索引、随审计增长无界扫描，Codex R10）。
- **Consequences:** 清理不可撤销；detach 与清扫之间崩溃留下可续做的元数据行（同路径下次请求续做；后台续做 `DEFER-FU-06`）。
- **Revisit when:** Git 命名空间 GC 落地。

### ADR-FU-10: ImportRepo 清理 HTTP 契约（精确查找）

- **Status:** Accepted
- **Context:** 需要有鉴权、可发现的产品操作；`find_git_repo_like_path` 无组件边界、字符串拼接（Codex R1 P0）。（FU-20 注：`find_git_repo_like_path` 其后已改为组件边界、绑定参数的最长前缀查找，但仍解析到祖先行与尾斜杠别名行；第 2 条的精确查找要求不变。）
- **Decision:** `POST /api/v1/import-repo/remove`，请求 `{ "path": "/third-party/<owner>/<repo>" }`，只挂 storage-only 写路由，handler **不经** `api_handler` / `ImportApiService` 分派。
  1. ImportRepo 叶子校验（FU-18 引入于 `src/ceres/pack/path_policy.rs`，唯一实现）：核心 `check_import_repo_leaf(config, canonical_path)` 要求不含 NUL 且组件级**严格**位于 `import_dir` 之下（≠ `import_dir`）；协议分派在 TP-08 规范化后调用核心；清理 API 与运维 CLI 调用严格入口 `strict_import_repo_leaf_input(config, raw)`：先拒绝 NUL 与 `\`，再要求 `raw == canonicalize_mono_ref_path(raw)`（拒绝 `..`、重复斜杠、尾斜杠等别名），再调用核心 → 否则 `IMPORT_REPO_PATH_INVALID`（400）。（FU-20 补注：严格入口不拒绝 NUL 以外的控制字符（`DEFER-FU-44`）；`.git` 为普通字符——`/third-party/x.git` ≠ Git 面剥掉一个 `.git` 后的 `/third-party/x`，答 `absent`。FU-21 ER-03 复核：严格入口不收紧（`DEFER-FU-44`），CLI 对 stdout 回显做控制字符转义。）
  2. （鉴权通过后）仓库查找只用 `find_git_repo_exact_match(canonical)`（sea-orm 绑定参数等值）；禁止 `find_git_repo_like_path` 与任何字符串拼接 SQL。
  3. 子仓检查：`repo_path LIKE escape_like(canonical) || '/%' ESCAPE '\'`（绑定参数）存在行 → `IMPORT_REPO_HAS_CHILDREN`（409），无写；规范形式等于 `canonical` 本身的行（FU-15 冲突保留的别名行，如 `canonical/`、`canonical/.`）不是子仓，检查排除它们（与同一分裂身份的处理见 `DEFER-FU-10`；FU-15 R2）。FU-16 的 B3 再检查与 FU-17 的服务入口查询共用此定义。
  4. 鉴权：在第 1 条的**语法**校验之后、第 2–3 条的任何仓库查询之前执行清理专用的 `authorize_import_repo_removal(git, headers, canonical)`（`src/api/api_write_auth.rs`）：`push_auth=token` 时要求有效且覆盖目标路径的 token（401/403）；`push_auth=none` 或缺失时**一律 403**（HTTP 面不提供匿名破坏性操作，#27 排除项；无鉴权部署改用 ADR-FU-11 的运维 CLI）；端点把鉴权失败改写为固定响应体（401 `authentication required`、403 `forbidden`，不回显路径；需要 `ApiError::status()` 访问器，`src/common/errors/api.rs`），未授权调用方对「不存在 / 叶子 / 有子仓的父」得到逐字节相同的响应，不泄漏存在性或拓扑。（FU-20 补注：「一律 403」针对可解析、语法合法的请求——顺序为 `Json` 提取器 → 第 1 条 → 鉴权 → FU-17 入口，前两步只依赖请求与配置；`authorize_import_repo_removal` 在 `push_auth` 不为 `token` 时直接返回固定 403，否则复用 `authorize_trunk_api_write` 并经 `ApiError::status()` 改写：401 → `authentication required`，其余一律 → `forbidden`，原错误在进入响应与日志之前丢弃；无 `WWW-Authenticate`，响应头除 `Date` 与按请求的 `x-request-id` 外一致。）
  5. 请求 `{ path, cleanup_id? }` 两种语义，由请求显式区分：**新操作**（只给 `path`）——若 `path` 有存活仓库则 detach 它（新 `cleanup_id`），并在预算内清扫它与该路径其它待续台账；**续做**（给出上一次响应中的 `cleanup_id`）——只处理该台账行（必须属于该 `path`，按 `path` 鉴权），**永不** detach 任何存活仓库；台账行不存在或不属于该路径 → 404 `IMPORT_REPO_CLEANUP_NOT_FOUND`，已 `swept` → 200 `removed`（幂等）。输出 `200 { path, outcome, repo_id, cleanup_id }`，`outcome` ∈ `removed` / `pending`（已 detach 但清扫超出本次预算，客户端须带 `cleanup_id` 续做）/ `absent`（新操作时无存活仓库且无待续台账）。这样「R1 待续清扫期间同路径重新导入 R2，随后续做 R1」不会触及 R2。（FU-20 补注，按已发布的 FU-17 实现、在请求结束时判定：**新操作且有存活仓库**——无写子仓预检（409，不入队）→ detach（新 `cleanup_id`）→ 先清扫本请求自己的台账行：已 `swept` 答 `removed`（带本行 id；剩余预算续做同路径更早的 `detached` 行，但其结果不改变答复，残留留给之后只带 path 的请求，`DEFER-FU-06`），超预算答 `pending`（带本行 id）；**新操作且无存活仓库**——在 100 条语句内按 id 续做至多 16 行 `detached`：已无剩余答 `absent`（两 id 为 `null`，即使本请求做了清扫），否则答 `pending` 并指名最小的剩余行（超过 16 行时可能是本请求未触及的行）；**续做**——只处理该台账行、永不 detach：未知或属于另一路径 404（同一文本），已 `swept` 或本次完成答 `removed`（幂等），否则 `pending`（同 id）；`repo_id` 恒为该台账行的仓库。客户端协议：遇 `pending` 带 `cleanup_id` 续做至 `removed`（对重新导入安全）；要排空路径则重复只带 path 的请求至 `absent`（会 detach 当时存活的仓库，含重新导入）。输出为 `CommonResult` 的 `data`，四键恒在，`absent` 时两 id 为 `null`；`repo_id` 为 64 位、可超过 2^53；`cleanup_id: null` 等同省略；未知字段 422；500 可重试。）
- **Alternatives considered:** 扩展 `delete-entry`（拒绝：混淆 ImportRepo 内部删移契约）；`DELETE` + 路径参数（拒绝：多段路径需编码）。
- **Consequences:** 新端点进运行时 OpenAPI；review 形态不挂（`DEFER-FU-02`）；`push_auth=none` 部署的 HTTP 清理不可用，由 ADR-FU-11 覆盖。未授权调用方只见由状态码决定的固定体；清理后被清理路径上的 tag 写与子仓路径的 API 分派见 `DEFER-FU-38` / `DEFER-FU-39`（FU-20）。
- **Revisit when:** 需要可恢复的归档语义。

### ADR-FU-11: 运维 CLI `mega2 import-repo remove`

- **Status:** Accepted
- **Context:** HTTP 清理要求 token（ADR-FU-10）；#25–#27 的试用栈与默认评估栈是 `push_auth=none`，若无其它入口将无法清理（#27 AC1「授权的运维者」）。
- **Decision:** 新增子命令 `mega2 --config <path> import-repo remove --path <P> --yes`：`LoadMode::FullAppContext`（需要可读配置与数据库凭据——即服务器运维权限，这就是授权边界）；缺 `--yes` 拒绝执行（退出码 2、无写）；路径校验与服务入口与 HTTP 相同（ADR-FU-10 第 1–3 条，调用 FU-17 `remove_import_repo`）；审计 `requester="operator-cli"`；遇 `pending` 在进程内以返回的 `cleanup_id` 续做（每轮受同一预算约束，至多 `--max-rounds`，默认 1000 轮；续做永不 detach 存活仓库），最终输出 `removed <path> (repo_id=…)` / `absent <path>`，轮数用尽仍为 `pending` 则输出 `pending <path>` 并以退出码 3 结束；错误打印 `<CODE>: …`，退出码 1。（FU-21 补注，2026-09-26 设计定稿：①`LoadMode::ParsedExistingConfig`——`cli.rs` 中的 `FullAppContext` 只是走 `load()`、会生成默认 `etc/config.toml` 的配置标签；本命令自行装配、不用 `AppContext::new`；「可读配置与数据库凭据」仍是授权边界，且配置须经 `--config` / `MEGA_CONFIG` 点名。②纯校验先于任何 I/O（缺 `--yes` 由 clap 拒绝，退出码 2；其它用法错误同为 2）；只接受 storage-only；`redis.url` 与 S3 凭据须为字面值（从不打开 vault：`config` 重写密钥文件、`open_readonly` 会 chmod）；只读连接确认无待执行迁移，从不迁移；写连接用 `postgres_connection`，也不补 `queue_control` 种子行（R1）。③第 1 轮为新操作或 `--cleanup-id` 续做，其后只续做；主链后按台账排空该路径其余 `detached` 行，永不 detach；`--max-rounds`（≥1）计全部轮次。④stdout 恰一行结局且为末行：`removed <path> (repo_id=R, cleanup_id=C)`（C 为主链首答所指台账行，与 HTTP 同义，可为更早的仓库）/ `absent <path>` / `pending <path> (repo_id=R, cleanup_id=C)` / `interrupted <path>[ (repo_id=R, cleanup_id=C)]`；路径控制字符转义；`print_std=true` 时此前各行为日志。⑤退出码：0 removed / absent（该路径已排空）；1 本次未记录清理（类型化 `<CODE>: …`、`import-repo remove: …` 前置拒绝，或 `Other error:` 等可重试失败，`DEFER-FU-42`）——例外：中断 / 失败后的台账查询出错或超时（10 s）时无从判定，stderr 要求先查 `import_repo_cleanups`，失败为 1、中断为 130，此时 detach 可能已提交；2 用法错误；3 已记录未完成（轮数用尽或其后失败），stdout 为续做句柄；130 SIGINT（中断后在 `MONO_WRITE_LOCK` 屏障之后读台账给出句柄）。⑥requester 每轮 `operator-cli`。）
- **Alternatives considered:** 允许 `push_auth=none` 下匿名 HTTP 清理（拒绝：#27 排除）；为 none 形态引入单独的 admin token（拒绝：新配置面，超出本计划）。
- **Consequences:** 新子命令；需要服务器访问（`docker compose exec mega2 mega2 --config … import-repo remove …`）。FU-21：调用形如 `docker compose exec -T mega2 mega2 --config /etc/mega2/config.toml import-repo remove --path <P> --yes`（或加 `-e MEGA_LOG__PRINT_STD=false`）；须以服务同一镜像 / 二进制、在服务运行时执行（孤儿队列行由服务 reaper 终态化；schema 不符拒绝）。
- **Revisit when:** 出现无服务器访问的运维者需求。

## 全局工程约束

继承 `plan-template.md` 的 GC-01..GC-12（VCS 为 **Libra**，按 `AGENTS.md`）。补充：

- **GC-FU-01:** 消息分解与成帧只有一个 helper（`src/common/utils.rs`）；各合成点不得各自写正则或字符串切片。
- **GC-FU-02:** 创建路径分类只有一个函数（ADR-FU-04）；开通 API、产品写落点回落与 receive-pack 共用；不得复制根目录判断。
- **GC-FU-03:** 不得绕过 MonoWriteQueue 改 `mega_refs` 或根树；ImportRepo 分支 ref 写只在 B3 attach/detach 事务内；tag 写只在 `update_refs` 或 `ImportApiService` 的单事务条件语句中。
- **GC-FU-04:** 永不物化 `import_dir`、其子路径或（嵌套 `import_dir` 时）其严格祖先的 `main` ref。
- **GC-FU-05:** 错误消息与审计 metadata 不含 token、口令、配置文件路径、`base_dir`、数据库/对象存储地址。（FU-21 R1 范围说明：约束的是服务返回给调用方的错误与审计 metadata；运维 CLI 在本机 stderr 回显操作者自己经 `--config` / `MEGA_CONFIG` 给出的配置路径——配置加载失败时的共用加载器文本——不在此列。）
- **GC-FU-06:** 新增或修改的测试遵守 ER-13；进程级黑盒使用各自隔离库。
- **GC-FU-07:** ImportRepo 仓库定位只用绑定参数的等值查找或转义后的组件边界前缀查找。
- **GC-FU-08:** 每条 ImportRepo 元数据写路径（含 `save_entry` 对象行）都先经 `lock_live_import_repo`（对象行与 receive-pack 自 FU-18 起，`ImportApiService` 自 FU-19 起）。

## 执行检查必备需求（强制）

继承 ER-01..ER-13。本地化：

- **开工：** `libra status --short --branch`（禁止 `git status`）；`test -f .env.test`；规范测试栈 `docker compose -p mega2-it -f docker/docker-compose.test.yml --profile git up -d --wait`（先 `mkdir -p` 并 `chmod 1777` 共享 git 工作根；导出 `MEGA2_IT_GIT_WORKDIR`、`MEGA2_IT_GIT_UID`、`MEGA2_IT_GIT_GID`，`docs/refactoring/test-infra.md`）。
- **本机基线环境失败（`DEP-FU-05`）：** C 组 ③ 的全量测试以 `source .env.test && cargo test --all --no-fail-fast` 运行；失败集必须是「事实基线 → 基线全量测试」所列 6 个用例的子集，且每个失败的原因与基线逐字同类（版本断言 `git-lfs/3.8.0`、`docker push failed: unauthorized`、S3 PUT `502 Bad Gateway`）；任何其它失败、或上述用例的原因漂移，即判红。不得 `#[ignore]`、跳过或修改这些用例；**并发会话例外（2026-09-25，FU-16 C 组登记）：** 本机同时运行其它会话的 `cargo test`（含其它仓库）时，依赖临时端口服务启动或固定等待预算的用例会偶发 `Connection reset by peer` / `push wait abandoned` 类失败；此类失败不判红的条件是：报错为该类签名、失败点在被测行为之前、单独复跑 3/3 且所在 target 整体复跑通过、并至少有一次全量的 lib 阶段全绿；每次都要在卡片 Lifecycle 写明各轮全量的失败集与复跑证据，且共享 compose 栈（`git-cli` 容器的 `/work` 挂载）被其它会话重建的那一轮作废重跑。环境修复属用户动作，修复后恢复全绿口径。**进展（2026-09-26）：** `docker push` 失败随 v0.40.10 的 OCI 用例修复消失；用户在 Clash Verge 订阅「编辑规则」中把 `127.0.0.0/8` 等设为 DIRECT 后 S3 冒烟通过；git-lfs 钉住版本在 v0.40.13 上调为 `3.8.0` 与宿主一致（上调钉住版本而非降级宿主）。v0.40.13 最终树的全量 `cargo test --all --no-fail-fast` 18 个 target 0 失败，仅余 macOS `ld` `__eh_frame` 链接提示，用户决定视为平台噪音、不计入门禁，`DEP-FU-05` 关闭。排查汇总见 `docs/development.md`「调试汇总：本机环境导致的测试失败」。
- **C 组（每张独立发布的 `implementation`、`migration` 或 `release` 卡——含 FU-14、FU-15、FU-23——顺序强制）：** ① 版本面 parity 预检：`rg -n '^version' Cargo.toml` 与 `find . -name Cargo.toml -not -path './target/*' -not -path './.libra/*'`（预期各一处；不得对含 `target/` 的全仓做 `rg -l` 扫描——FU-01 执行时该扫描超时）→ ② 按本卡 `Version increment` bump `Cargo.toml`，`cargo build` 刷新 `Cargo.lock` → ③ 在已 bump 树上 `cargo +nightly fmt --all --check`、`cargo clippy --all-targets --all-features -- -D warnings`、`source .env.test && cargo test --all --no-fail-fast`（全部 target 必须都已运行，再按「本机基线环境失败」口径比对失败集；环境修复后失败集必须为空） → ④ `cargo build`、`cargo build --tests` 0 错误 0 警告 → ⑤ 暂存前快照 `libra diff --staged --name-only`：非空（他人已暂存的工作）即停止并登记交接，不提交；为空才 `libra add <本卡路径>`，并校验暂存集 ⊆ 本卡写集 + 版本面，然后 `libra commit -s -m "v<version>: <summary>"` → ⑥ `libra push origin main`，并以 `libra --json status` 确认 `ahead=0` → ⑦ `libra tag -m "v<version>: <summary>" v<version>` + `libra push origin refs/tags/v<version>` → ⑧ 基于最终 diff 手写 release note（Highlights、用户可见变更、兼容/配置/迁移说明、验证结果、已知限制），`gh release create v<version> -R gitmono-dev/mega2 --title "v<version>" --notes-file <file>`（禁止 `--generate-notes`）。
- **D 组（每张 bump 卡，推送 tag 后）：**
  ```bash
  SHA=$(libra rev-parse HEAD)   # 在打 tag 的同一提交上取得
  RUN_ID=""
  for _ in $(seq 1 60); do
    RUN_ID=$(gh run list -R gitmono-dev/mega2 --workflow docker.yml --event push --limit 30 \
      --json databaseId,headSha,headBranch \
      --jq ".[] | select(.headSha==\"$SHA\" and .headBranch==\"v<version>\") | .databaseId" | head -1)
    [ -n "$RUN_ID" ] && break
    sleep 10
  done
  test -n "$RUN_ID" || { echo "TIMEOUT: no docker.yml run for v<version> at $SHA within 10 min"; exit 1; }
  gh run watch "$RUN_ID" -R gitmono-dev/mega2 --exit-status
  test "$(gh run view "$RUN_ID" -R gitmono-dev/mega2 --json jobs --jq '.jobs[] | select(.name=="docker") | .conclusion')" = "success"
  ```
  绿灯前 `Acceptance=remote-pending`；红灯按 ER-10 前滚修复。
- **`docs` 卡：** 不 bump、不打 tag，`libra commit -s -m "docs(<scope>): <summary>"` + `libra push origin main`；C/D 覆盖按卡内声明继承（FU-11 ← FU-12，FU-22 ← FU-23）。
- **`release` 卡（FU-23）：** 执行完整 C 组与 D 组（与实现卡相同步骤），为计划最终发布点。
- **A 组：** 触及 `src/api/**` 的卡（FU-07、FU-20）加 `source .env.test && cargo test -p mega2 --lib 'api::'` 与运行时 `/api/openapi.json` 断言用例；触及 `src/commands/**` / `src/cli.rs` 的卡（FU-08、FU-21）加 `source .env.test && cargo test -p mega2 --lib 'cli::tests'` 与 `source .env.test && cargo test -p mega2 --lib 'commands::'`；触及 `src/config/**` 的卡（FU-04）加 `cargo run -p mega2 -- --config config/config.toml config validate`。除 FU-18 对 `src/ceres/protocol/mod.rs` 的改动（注册改调祖先栅栏原语、分派前的叶子校验——`import_dir` 上的响应由 404 变为 400）外，本计划不触及 `src/ceres/protocol/**`、`src/contract/git_protocol/**`、LFS 或 `http_server.rs` 协议握手；FU-18 因此加 `scripts/git_protocol_smoke_storage_only.sh` 本地等价门（卡内写出完整命令）；其它卡若实现中必须触及，按 ER-03 先改卡再加该门。
- **顺序（ER-04 唯一转移路径）：** A 组 + B 组通过 → `locally-accepted` → ER-05 评审字面 `VERDICT: PASS` → C 组 → D 组；评审修复后必须重跑受影响的 A/B 门，C 组（bump、提交、推送、tag、Release）绝不早于评审 `PASS`。
- **ER-05 评审：** 每卡本地验收后执行 Codex 只读评审：`codex exec -s read-only -C /Volumes/Data/GitMono/mega2 --skip-git-repo-check -o <review-file> -`（stdin 为评审提示：本卡 diff + 本卡正文 + 相关 ADR），必须得到字面 `VERDICT: PASS`；另由一个无共享上下文的 Claude 子代理独立只读评审（`AGENTS.md`「dual review」）。P0/P1 必须关闭并重跑相关验收。Codex 不可用时按 `DEP-FU-04` 回落并登记。
- **ER-11：** 验收证据只记 sanitized 摘要；测试口令、token 与签名 armor 不入证据。
- **计数口径（G-03）：** 每条 AC 是「具名用例 `X` 通过」或一个单谓词（文档 AC 以单一文件为单位）；具名用例的输入矩阵与断言清单写在对应 Verification 行说明中，不另计。Verification 每条命令或手工证据计 1。

## 实施顺序

- `FU-01 -> FU-02`
- `FU-02 -> FU-03`
- `FU-03 -> FU-04`
- `FU-04 -> FU-05`
- `FU-05 -> FU-06`
- `FU-06 -> FU-07`
- `FU-07 -> FU-08`
- `FU-08 -> FU-04A`
- `FU-04A -> FU-09`
- `FU-09 -> FU-10`
- `FU-10 -> FU-11`
- `FU-11 -> FU-12`
- `FU-12 -> FU-13`
- `FU-13 -> FU-14`
- `FU-14 -> FU-15`
- `FU-15 -> FU-16`
- `FU-16 -> FU-17`
- `FU-17 -> FU-18`
- `FU-18 -> FU-19`
- `FU-19 -> FU-20`
- `FU-20 -> FU-21`
- `FU-21 -> FU-22`
- `FU-22 -> FU-23`

边的理由：FU-01/02 共写 `src/common/utils.rs` 与 `trunk_provenance`/`materialize` 测试；FU-03 与 FU-06/07 共写 `mono_api_service.rs`；FU-04 的配置形状是 FU-05 分类前提；FU-05 提供 `PathPolicyError` 与分类函数（FU-06、FU-07、FU-10 消费）；FU-06 全新栈落点是 FU-07 前提；FU-08 调用 FU-07；FU-09/10 共写 `push_chain.rs`/`monorepo.rs`，FU-10 文案点名 FU-07/08；FU-11 文档覆盖 FU-04..FU-10；FU-12..FU-19 共写 `push_queue_service.rs`、`import_repo.rs`、`git_db_storage.rs`、`import_api_service.rs`；FU-20 端点必须在 FU-18/FU-19 栅栏之后发布；FU-22 文档覆盖 FU-12..FU-20；FU-23 收口；FU-04A 与 FU-03/FU-06/FU-07 共写 `tests/integration_api_write_trunk.rs`，按用户决定插入 FU-08 与 FU-09 之间（`FU-08 -> FU-04A -> FU-09`）。

### 依赖登记表

| ID | direction | 类型 | 对象 | Owner | 产物与可用性判据 | 证据 | 超时与失败策略 |
|---|---|---|---|---|---|---|---|
| DEP-FU-01 | incoming | 需求来源 | GitHub issues #25–#29 | 维护者（genedna） | issue 正文与 AC 为需求基线；如被编辑，开工日重读并登记修订历史 | `gh issue view 25..29 -R gitmono-dev/mega2`，2026-09-23 | issue 关闭或需求反转 → 对应卡改为 `DEFER-*` 并登记 |
| DEP-FU-02 | incoming | 上游 revision | git-internal `0.10.2` 的 `Commit::from_bytes` / `to_data` | git-internal 维护者 | 额外头保留在 `message`，`to_data` 不补空行；FU-01 文法单测锁定该假设 | `Cargo.toml:45`；registry 源 `commit.rs:233-330`，核对 2026-09-23 | 升级改变行为 → 文法单测失败即停，先修 helper |
| DEP-FU-03 | outgoing | 跨仓移交 | `../libra`：可选的原生开通 / ImportRepo 清理子命令 | Libra maintainers | 本计划交付 HTTP 契约（`directory-entry-api.md` 新节）后 Libra 自行消费 | 移交日为 FU-20 发布日 | Libra 未接手不阻断；mega2 CLI 与 HTTP 已满足 #25/#27 |
| DEP-FU-05 | incoming | 外部环境 | 本机测试环境：宿主 `git-lfs` 版本、macOS 系统代理、Docker registry 凭据；macOS `ld` 的 `__eh_frame` 链接提示（平台链接器输出，非代码警告）同属此项，影响「计划完成门」的 0 警告条件（FU-23 R3 补记） | 用户 | 6 个基线环境失败消失（全量 `cargo test --all` 全绿） | 事实基线「基线全量测试」行，2026-09-23 | 修复前按「本机基线环境失败」口径执行 C 组 ③ 并逐卡记录；修复后恢复全绿口径（2026-09-26 已解决：6 个失败全部消除，v0.40.13 全量全绿；`ld` 链接提示按用户决定视为平台噪音） |
| DEP-FU-04 | incoming | 外部服务 | Codex CLI（`codex-cli 0.155.1`）用于 ER-05 评审 | 本机 | `codex exec` 可运行并输出 `VERDICT:` 行 | 2026-09-23 `codex --version` | 重试 ≤ 5 次 / 30 分钟（ER-10）；仍失败 → 两个独立 Claude 子代理评审并在 Review log 登记 |

### 发布分组与并发窗口

无家族卡、无 `REL-*`；每张实现卡独立发布切片。

**并发声明:** 全串行（写集沿单链相交）。

**发布者:** 本计划执行代理（单一），负责每卡 C 组 bump、构建、精确暂存、提交、推送、tag、手写 GitHub Release 与 D 组 `docker` job 跟踪。

**发布窗口顺序:** 按实施顺序单链。同一时刻至多一张卡处于「已 bump 未完成推送」。预期版本（以开工时权威 `version` 重算）：FU-01 `0.38.22`、FU-02 `0.38.23`、FU-03 `0.38.24`、FU-04 `0.39.0`（minor）、FU-05 `0.39.1`、FU-06 `0.39.2`、FU-07 `0.39.3`、FU-08 `0.39.4`、FU-04A `0.39.5`（用户决定插入）、FU-09 `0.39.6`、FU-10 `0.40.0`（minor）、FU-11 N/A、FU-12 `0.40.1`、FU-13 `0.40.2`、FU-14 `0.40.3`、FU-15 `0.40.4`、FU-16 `0.40.5`、FU-17 `0.40.6`、FU-18 `0.40.7`、FU-19 `0.40.8`、FU-20 `0.40.9`、FU-21 `0.40.11`、FU-22 N/A、FU-23 `0.40.12`（2026-09-26 重算：远端 media 计划 `plan-20260913` 已发布 `0.40.10`）。

### Phase 0: 基线冻结

**目标:** 本计划经 Codex 计划评审 PASS。**进入条件:** 事实基线与 E1–E12 已登记。**退出条件:** Review log 计划评审末轮 `PASS`。

### Phase 1: 合成 commit 正确性（#28 + 帧）

**目标:** 派生消息剥离签名头；API 合成 commit 成帧。**进入条件:** Phase 0 完成。**退出条件:** FU-01..FU-03 `done`/`complete`。

### Phase 2: 首次使用路径（#25 / #29）

**目标:** 配置校验、错误域与分类、全新栈落点与产品写分类、开通 API + CLI、孤儿黏性、首推分类、用户文档。**进入条件:** FU-03 完成。**退出条件:** FU-04..FU-11（含 FU-04A）`done`/`complete`。

### Phase 3: ImportRepo 生命周期（#26 / #27）

**目标:** 增量推送、ref CAS、原子摘除、清扫续做、全路径存活栅栏、清理 API 与运维 CLI、用户文档。**进入条件:** FU-11 完成。**退出条件:** FU-12..FU-22 `done`/`complete`。

### Phase 4: 收口

**目标:** 计划索引同步与最终树计划完成门。**进入条件:** FU-22 完成。**退出条件:** FU-23 `done`/`complete`；完成判据全部勾选。

## 任务卡

有效卡遵守 G-01..G-11。ER-04 强制门不计入 Verification 分母；计数口径见「执行检查必备需求」。

#### 字段全局默认与例外

- **Release boundary 默认:** `independent`（`docs` 卡为 `no-release`）。
- **Task type 默认:** `implementation`。
- **Rollback mode 默认:** `immutable-release`（已推送只能前滚新版本；代码层可 revert 后再发补丁版本）。FU-14、FU-15 为 `forward-only`（见默认覆盖）。
- **Migration and rollback 默认:** `N/A`：除 FU-14（新表）与 FU-15（存量别名路径改写，down no-op、不可逆）两个有序迁移外，其余卡无 schema 或数据迁移（见默认覆盖与卡内说明）。
- **Security and privacy 默认:** 继承 GC-07、GC-11、GC-FU-05。
- **Performance budget 默认:** 继承 GC-10。
- **Docs and compatibility impact 默认:** 实现卡同步本轴的契约/参考文档（`docs/refactoring/*.md`、`docs/deploy-trunk.md`、`docs/configuration(.zh).md`、`docs/errors.md` 中本卡首次产生的码）；跨多卡的用户旅程文档（README、quick-start、user-guide 与初始化手册）由 FU-11（#25/#29）与 FU-22（#26/#27）两张 `docs` 卡收口——两者各自是独立可恢复的「用户旅程」行为轴（聚合多个轴、单独 revert 不影响任何实现）。

**默认覆盖：**

| 任务 | 偏离的字段 | 取值与理由 |
|---|---|---|
| FU-04 | Version increment | `minor`：此前可通过校验的非法 `root_dirs` / `import_dir` 配置改为启动前失败 |
| FU-14 | Task type / Rollback mode / Migration and rollback | `migration` / `forward-only` / 见卡内（新表，无存量数据） |
| FU-15 | Task type / Rollback mode / Migration and rollback | `migration` / `forward-only` / 见卡内（存量别名行改写，down no-op） |
| FU-10 | Version increment | `minor`：关闭 fork 型创建新顶层（ADR-FU-04） |
| FU-11、FU-22 | Task type / Release boundary / Rollback mode / Version increment | `docs` / `no-release` / `revert` / `N/A` |
| FU-23 | Task type | `release`：计划最终发布点，不引入新行为 |
| FU-13..FU-20 | Docs and compatibility impact | `ImportRepoError` 各码在首次对用户暴露它的卡中登记 `docs/errors.md`（FU-13 `PATH_OCCUPIED`、FU-18 `REMOVED`/`PATH_INVALID`、FU-20 `HAS_CHILDREN` / `CLEANUP_NOT_FOUND`）；`PathPolicyError` 的 Git 面出现场景登记由 FU-11 承接 |

**规则 waiver：** 无 `EX-*`。

#### 任务卡粒度审计表

| 任务 | type | axis | recovery | complete | self-contained | AC | VER | landing / prod-files | scope | deps | writeset | release | split-from | exception |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| FU-01 | implementation | trunk 层消息与 squash 主题取源正文 | 前滚补丁版本 | yes | yes | 7/8 | 7/8 | 2/2 | S | none | 序列化于 FU-02 前 | independent | N/A | N/A |
| FU-02 | implementation | 物化与 attach 根消息取源正文并成帧 | 前滚补丁版本 | yes | yes | 6/8 | 5/8 | 2/2 | S | FU-01 | 序列化于 FU-01 | independent | FU-01（R1） | N/A |
| FU-03 | implementation | API/续接合成 commit 成帧 | 前滚补丁版本 | yes | yes | 6/8 | 5/8 | 2/3 | S | FU-02 | 序列化于 FU-02 | independent | N/A | N/A |
| FU-04 | implementation | `root_dirs`/`import_dir` 配置形状校验 | 前滚 minor 版本 | yes | yes | 7/8 | 6/8 | 1/2 | M | FU-03 | 序列化于 FU-03 | independent | N/A | N/A |
| FU-04A | implementation | blame 展示取源正文 | 前滚补丁版本 | yes | yes | 8/8 | 5/8 | 1/1 | S | FU-08 | 序列化于 FU-08 | independent | FU-03（R1 Claude P2，用户决定） | N/A |
| FU-05 | implementation | 路径策略判定与错误契约 | 前滚补丁版本 | yes | yes | 8/8 | 5/8 | 2/4 | M | FU-04 | 序列化于 FU-04 | independent | FU-04（R1） | N/A |
| FU-06 | implementation | 产品写在无非根 tip 时的分类与落点回落 | 前滚补丁版本 | yes | yes | 8/8 | 3/8 | 1/2 | M | FU-05 | 序列化于 FU-05 | independent | FU-03（R1） | N/A |
| FU-07 | implementation | 幂等路径开通 HTTP API | 前滚补丁版本（端点下线） | yes | yes | 8/8 | 7/8 | 3/4 | M | FU-06 | 序列化于 FU-06 | independent | FU-04（R1） | N/A |
| FU-08 | implementation | 开通操作的 CLI 客户端 | 前滚补丁版本（子命令下线） | yes | yes | 7/8 | 5/8 | 1/2 | M | FU-07 | 序列化于 FU-07 | independent | FU-05（R1） | N/A |
| FU-09 | implementation | 孤儿拒绝在重试间一致 | 前滚补丁版本 | yes | yes | 6/8 | 4/8 | 1/2 | M | FU-04A | 序列化于 FU-04A | independent | FU-06（R1） | N/A |
| FU-10 | implementation | trunk 首推路径策略诊断 | 前滚 minor 版本 | yes | yes | 8/8 | 7/8 | 2/2 | M | FU-09 | 序列化于 FU-09 | independent | FU-06（R1） | N/A |
| FU-11 | docs | 首次使用用户旅程文档 | revert 文档 | yes | yes | 13/20 | 6/20 | 0/0 | M | FU-10 | 序列化于 FU-10 | no-release | FU-05（R1） | N/A |
| FU-12 | implementation | ImportRepo ref 更新的并发语义 | 前滚补丁版本 | yes | yes | 8/8 | 4/8 | 4/5 | M | FU-11 | 序列化于 FU-11 | independent | FU-07（R1） | N/A |
| FU-13 | implementation | 已挂载 ImportRepo 的后续推送 | 前滚补丁版本 | yes | yes | 8/8 | 7/8 | 4/5 | M | FU-12 | 序列化于 FU-12 | independent | FU-07（R1） | N/A |
| FU-14 | migration | 清理台账的持久形态 | 前滚版本停止写入（表保留） | yes | yes | 6/8 | 3/8 | 3/5 | M | FU-13 | 序列化于 FU-13 | independent | FU-17（R10） | N/A |
| FU-15 | migration | 存量 ImportRepo 路径标识的规范化 | 前滚版本（改写不可逆） | yes | yes | 7/8 | 5/8 | 1/2 | S | FU-14 | 序列化于 FU-14 | independent | FU-18（R18） | N/A |
| FU-16 | implementation | ImportRepo 叶子的原子摘除（含事务内子仓再检查、按来源记录移树） | 前滚补丁版本（原语无入口即休眠） | yes | yes | 8/8 | 4/8 | 3/5 | M | FU-15 | 序列化于 FU-15 | independent | FU-08（R1） | N/A |
| FU-17 | implementation | ImportRepo 清理的完成与续做 | 前滚补丁版本 | yes | yes | 8/8 | 4/8 | 2/3 | M | FU-16 | 序列化于 FU-16 | independent | FU-08（R1） | N/A |
| FU-18 | implementation | receive-pack 与对象行写入对清理的互斥（含祖先生命周期栅栏） | 前滚补丁版本 | yes | yes | 8/8 | 7/8 | 4/8 | M | FU-17 | 序列化于 FU-17 | independent | FU-16（R2） | N/A |
| FU-19 | implementation | 产品 API 写路径对清理的互斥 | 前滚补丁版本 | yes | yes | 8/8 | 8/8 | 3/3 | M | FU-18 | 序列化于 FU-18 | independent | FU-18（R4） | N/A |
| FU-20 | implementation | ImportRepo 叶子清理的机器接口 | 前滚补丁版本（端点下线） | yes | yes | 8/8 | 8/8 | 4/6 | M | FU-19 | 序列化于 FU-19 | independent | FU-09（R1） | N/A |
| FU-21 | implementation | 服务器侧运维清理入口 | 前滚补丁版本（子命令下线） | yes | yes | 8/8 | 5/8 | 4/5 | M | FU-20 | 序列化于 FU-20 | independent | FU-20（R6） | N/A |
| FU-22 | docs | ImportRepo 用户旅程文档 | revert 文档 | yes | yes | 11/20 | 6/20 | 0/0 | M | FU-21 | 序列化于 FU-21 | no-release | FU-09（R1） | N/A |
| FU-23 | release | 计划收口与发布证据 | 前滚版本（索引可 revert） | yes | yes | 9/12 | 10/12 | 0/0 | S | FU-22 | 本计划 + README 索引 + plan-long + 版本面 | independent | FU-10（R1） | N/A |

### Task FU-01: trunk 层消息与 squash 主题取源正文（#28）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 通过；ER-05 Codex PASS + Claude PASS；C 组在 bump 后的 `0.38.22` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；提交 `46db4aa`、tag `v0.38.22` 与 GitHub Release 已发布；D 组 `docker.yml` run `35886956298` 的 `docker` job 对 `46db4aa` 为 success）

**Description:** 按 ADR-FU-01 第 1–4、6 条，新增 `split_commit_message` helper（取代 `parse_commit_msg`），并让 `TrunkProvenance` 的 N=1 层消息与 squash 列表主题使用源 commit 正文。唯一行为轴是「trunk 合成 commit 的消息不携带源签名头」。

**Out of scope:**

- 物化与 attach 根消息 —— 由 FU-02 承接。
- API 合成 commit 帧 —— 由 FU-03 承接。
- 改写历史 commit —— 永久非目标（`DEFER-FU-07`）。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| `n1_message = tip.message.clone()`；N≤1 原样返回 | `src/ceres/pack/trunk_provenance.rs:38-90` |
| `commit_subject` 取首个非空行 | `trunk_provenance.rs:216-223` |
| 既有 `parse_commit_msg`（`trim_start`、不识别 sha256，零调用） | `src/common/utils.rs:76-90` |
| 单测锁定「逐字」语义 | `trunk_provenance.rs:430` `n1_layer_message_is_verbatim` |
| 复现 | E9、E10 |

**Acceptance criteria:**

- [x] 具名用例 `split_commit_message_grammar` 通过。
- [x] 具名用例 `n1_layer_message_is_body` 通过（取代 `n1_layer_message_is_verbatim`）。
- [x] 具名用例 `squash_subject_skips_signature` 通过。
- [x] 具名用例 `signed_push_subpath_control` 通过（#28 AC1/AC2/AC4 子路径对照）。
- [x] 具名用例 `signed_push_first_level_root_control` 通过（#28 AC1 根对照）。
- [x] 手工证据 `FU01-LIBRA` 记录两个对照下 Libra 0.23.46 与 Git 的单行输出一致（#28 AC3）。
- [x] `docs/refactoring/trunk-push.md` 3.1–3.2 节订正「N=1 层消息 = tip 正文（额外头剥离）」并链接本计划。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'common::utils::test::split_commit_message_grammar'`（`(new)`；输入矩阵：PGP `gpgsig` 多行、`gpgsig-sha256`、SSH armor、截断 armor、`\n` 开头无头、正文首行为 `gpgsig`、未知头 + 签名头、无空行的历史消息回落、CRLF 正文逐字、空正文）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::trunk_provenance::tests'`（`(new)` `n1_layer_message_is_body`、`squash_subject_skips_signature`）
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 signed_push_subpath_control`（`(new)`：手工构造带多行 armored `gpgsig` 头与非空主题的 commit 推 `/project/<x>/<y>`；断言 P 的 `main` = 客户端 id 且原始对象逐字；每个祖先层原始字节恰一个 `gpgsig` 头、正文无 armor、`git log --format=%s` = 主题、`git fsck --strict` 通过）
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 signed_push_first_level_root_control`（`(new)`：手工构造带多行 armored `gpgsig` 头与非空主题的 commit 推一级根 `/project`；断言 `main@/project` = 客户端 id 且其原始对象逐字（含客户端 `gpgsig` 头与主题）；祖先层 `/` 的原始字节恰一个 `gpgsig` 头、正文不含 `-----BEGIN PGP SIGNATURE-----`、`git log --format=%s` = 主题、`git fsck --strict` 通过）
- [x] 零命中守卫（旧逐字赋值已移除）：
  ```bash
  if rg -n "n1_message: tip.message.clone\(\)" src/ceres/pack/trunk_provenance.rs; then
    echo "FAIL: forbidden pattern found"; exit 1
  else
    rc=$?
    if [ "$rc" -ne 1 ]; then echo "ERROR: rg failed with exit $rc"; exit "$rc"; fi
    echo "OK: zero hits"
  fi
  ```
- [x] 零命中守卫（旧 helper 已删除）：
  ```bash
  if rg -n "fn parse_commit_msg" src/common/utils.rs; then
    echo "FAIL: forbidden pattern found"; exit 1
  else
    rc=$?
    if [ "$rc" -ne 1 ]; then echo "ERROR: rg failed with exit $rc"; exit "$rc"; fi
    echo "OK: zero hits"
  fi
  ```
- [x] 手工证据 `FU01-LIBRA`（sanitized）：本地 storage-only 栈，Libra 签名 commit 分别推 `/project` 与 `/project/<x>/<y>`，记录 P 与祖先路径的 `libra log --oneline -1` 与 `git log --oneline -1`

**Dependencies:** 无（Phase 0 计划评审 PASS 为开工前置）。

**Deliverables:** N/A

**Implementation write set:** `src/common/utils.rs`；`src/ceres/pack/trunk_provenance.rs`；`tests/integration_git_cli.rs`；`docs/refactoring/trunk-push.md`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** `docs/refactoring/trunk-push.md`；新写入的层 commit id 变化，历史对象不变。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 不改签名 key 与验签；测试用伪造 armor，不引入私钥。

**Performance budget:** helper O(消息长度)，无新增 I/O。

**Estimated scope:** `S`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=trunk 层消息与 squash 主题取源正文; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=7/8; VER=7/8; landing=2; prod-files=2; scope=S; deps=none; writeset=序列化于 FU-02 前; release=independent; split-from=N/A; exception=N/A`

### Task FU-02: 物化与 attach 根消息取源正文并成帧（#28）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 通过；ER-05 R1 Codex FAIL 3×P1 已修订、Claude PASS 6×P2 已落实；R2 Codex PASS；C 组在 bump 后的 `0.38.23` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；手工证据：签名推送 `/project` 后首次 clone 未物化 `/project/sub` 得 `N <真实主题>`、无 `gpgsig` 头、`fsck --strict` 通过；提交 `3f55cd3`、tag `v0.38.23` 与 GitHub Release 已发布；D 组 `docker.yml` run `35892851175` 的 `docker` job 对 `3f55cd3` 为 success）

**Description:** 按 ADR-FU-01 第 5 条，`persist_walked_refs` 改用 `split_commit_message` 的完整正文、ImportRepo attach 根 commit 改用正文主题行（`commit_body_subject`，保持既有只取主题行语义），均经 `format_commit_msg(…, None)` 成帧。唯一行为轴是「未签名派生 commit 不复制源签名头」。

**Out of scope:**

- trunk 层消息 —— 已由 FU-01 交付。
- 历史物化 commit —— 永久非目标（`DEFER-FU-07`）。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 物化用根 commit 原始 `message` | `src/ceres/pack/materialize.rs:249-277` |
| attach 根消息用只认 PGP 的 `format_message()` | `src/jupiter/service/push_queue_service.rs:1437-1449` |
| 复现 | E11 |

**Acceptance criteria:**

- [x] 具名用例 `fu02_materialize_strips_root_signature` 通过。
- [x] 具名用例 `fu02_materialize_message_framed` 通过。
- [x] 具名用例 `attach_root_message_uses_body_subject` 通过。
- [x] 具名用例 `fu02_attach_root_commit_uses_signed_tip_subject` 通过（经 `attach_to_monorepo_parent` 真实 B3 attach，断言落库根 commit）。
- [x] 既有 `ceres::pack::monorepo::tests::tp` 前缀用例全部通过。
- [x] `docs/refactoring/trunk-push.md` 惰性物化小节登记「物化 commit 消息 = 根 commit 正文，不复制签名头」。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::monorepo::tests::fu02_'`（`(new)`：签名根 commit 后首次物化的 commit 无 `gpgsig` 头、主题 = 根正文主题；原始字节头/体空行存在）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::monorepo::tests::tp'`（既有 `tp09_*` / `tp10_*`）
- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::service::push_queue_service::tests::attach_root_message_uses_body_subject'`（`(new)`：SSH 签名 tip 的 attach 根 commit 消息为正文首行）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::import_repo::tests::fu02_'`（`(new)`：SSH 签名、多行正文的导入 tip 经真实 attach 落库，根 commit 消息 = `\n<主题>`、原始字节无 `gpgsig`、头/体空行存在；把生产调用改回 `format_message()` 该用例失败）
- [x] 手工证据（sanitized）：签名推送后首次 clone 未物化路径，`git log --format='%G? %s' -1` 为 `N <真实主题>`

**Dependencies:** FU-01（`split_commit_message` helper）。

**Deliverables:** N/A

**Implementation write set:** `src/ceres/pack/materialize.rs`；`src/jupiter/service/push_queue_service.rs`（仅 attach 根消息一处与其测试）；`src/ceres/pack/monorepo.rs`（仅测试模块）；`src/ceres/pack/import_repo.rs`（仅测试模块）；`docs/refactoring/trunk-push.md`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** 新物化 commit id 变化（物化行 `WHERE NOT EXISTS` 首写者胜，跨版本无冲突）。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 物化 commit 不再携带对其不可验证的签名头。

**Performance budget:** N/A

**Estimated scope:** `S`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=物化与 attach 根消息取源正文并成帧; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=6/8; VER=5/8; landing=2; prod-files=2; scope=S; deps=FU-01; writeset=序列化于 FU-01; release=independent; split-from=FU-01（R1）; exception=N/A`

### Task FU-03: API/续接合成 commit 成帧

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 通过；ER-05 R1 Codex PASS（1×P2 已修）+ Claude PASS（4×P2：3 项已修，blame 摘要为既有缺陷另起任务 → FU-04A）；C 组在 bump 后的 `0.38.24` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；提交 `d5a056d`、tag `v0.38.24` 与 GitHub Release 已发布；D 组 `docker.yml` run `35899405125` 的 `docker` job 对 `d5a056d` 为 success）

**Description:** 按 ADR-FU-02，把 `mono_api_service.rs`、`mono_storage.rs` 与 `import_api_service.rs`（`save_file_edit`）生产路径未签名合成调用的消息经 `format_commit_msg` 成帧。唯一行为轴是「服务端未签名合成 commit 有头/体空行」。

**Out of scope:**

- 签名路径帧 —— 永久非目标（已正确）：`process_ref_updates_cl_only`（`mono_api_service.rs:964`）构造后立即 `sign_commit`，`embed_gpgsig` 自带头/体空行，再成帧会多出一个空行，故不在成帧范围；Buck 上传（`buck_tree_builder.rs:195`）同为签名路径。
- 存量错帧对象 —— 永久非目标（`DEFER-FU-07`）。
- create-entry 重名 500 —— `DEFER-FU-04`。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 生产调用点（未签名） | `src/ceres/api_service/mono_api_service.rs:885`（review CL merge `process_ref_updates`）、`:1121`（`edit/save`）、`:2045`（`commit_tree_update`：create/delete/move-entry 共用）；`src/jupiter/storage/mono_storage.rs:700`（`DescendantCommitStyle::Legacy` 续接）；`src/ceres/api_service/import_api_service.rs:475`（ImportRepo `save_file_edit`）。`:964` 为签名路径（见 Out of scope） |
| `to_data` 不补空行 | git-internal `commit.rs:300-322` |
| 复现 | E12 |

**Acceptance criteria:**

- [x] 具名用例 `monorepo_api_commits_strict_fsck` 通过。
- [x] 具名用例 `import_repo_edit_save_commit_strict_fsck` 通过。
- [x] 具名用例 `api_history_strict_clone` 通过。
- [x] 具名用例 `api_commit_subject_visible` 通过。
- [x] 具名用例 `fu03_review_and_legacy_sites_framed` 通过。
- [x] `docs/deploy-trunk.md` 登记升级前写入的 API commit 仍可能被严格客户端拒收及规避。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'common::utils::test::format_commit_msg_frames_body'`（`(new)`）
- [x] `source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1 _strict_`（`(new)`：`monorepo_api_commits_strict_fsck`——create-entry、edit/save、delete-entry、move-entry 各一次后 `git fsck --strict` 无 `unterminatedHeader`；`import_repo_edit_save_commit_strict_fsck`——ImportRepo `edit/save` 后同断言；`api_history_strict_clone`——`git -c transfer.fsckObjects=true clone` 成功）
- [x] `source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1 api_commit_subject_visible`（`(new)`：`git log --format=%s` = `create new directory <name>`）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::api_service::mono_api_service::tests::fu03_review_and_legacy_sites_framed'`（`(new)`）
- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::storage::mono_storage::tests'`（续接回归）

**Dependencies:** FU-02（`src/common/utils.rs` 与共享测试基建）。

**Deliverables:** N/A

**Implementation write set:** `src/ceres/api_service/mono_api_service.rs`；`src/ceres/api_service/import_api_service.rs`（仅 `save_file_edit` 成帧）；`src/jupiter/storage/mono_storage.rs`；`src/common/utils.rs`（仅测试）；`tests/integration_api_write_trunk.rs`；`docs/deploy-trunk.md`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** `docs/deploy-trunk.md`；新 API commit id 变化；既有用例 `tp16_review_merge_keeps_from_tree_id_shape` 的消息断言随成帧改为 `\ncl merge generated commit`（其保护的「review merge 仍为未签名 `from_tree_id` 形态、无 `Mono-Squash`」不变）。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** N/A（无鉴权面变化）

**Performance budget:** 每次合成一次字符串拼接。

**Estimated scope:** `S`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=API/续接合成 commit 成帧; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=6/8; VER=5/8; landing=2; prod-files=3; scope=S; deps=FU-02; writeset=序列化于 FU-02; release=independent; split-from=N/A; exception=N/A`

### Task FU-04: `root_dirs` / `import_dir` 配置形状校验（#29）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 通过；ER-05 R1 Codex FAIL / Claude FAIL 已修订；R2 Codex PASS、Claude PASS（4×P2：3 项已修，Git 特殊名登记 `DEFER-FU-11`）；C 组在 bump 后的 `0.39.0` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；CLI：三份自带配置 `config valid`，`root_dirs=["project"]`+`import_dir="/vendor"` 非零退出并点名字段；提交 `433197a`、tag `v0.39.0` 与 GitHub Release 已发布；D 组 `docker.yml` run `35906307137` 的 `docker` job 对 `433197a` 为 success）

**Description:** 按 ADR-FU-04 第 1 条，在 `src/config/validate.rs` 校验 `root_dirs` 条目为唯一的单组件名（拒绝 `/`、`\`、`.`、`..`、空串、NUL、重复、首尾空白、根树保留名与 `.git`），`import_dir` 为不含 NUL/`\` 的规范绝对非根路径且首组件属于 `root_dirs`。唯一行为轴是「路径策略配置的形状校验」。

**Out of scope:**

- 运行时分类 —— 由 FU-05 承接。
- 运行时热改根目录 —— 永久非目标（需重启，`reload.rs:640-647`）。
- 其余 Git 特殊名（`.gitmodules` / `.gitattributes`、NTFS 别名）—— `DEFER-FU-11`。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 校验只要求非空 | `src/config/validate.rs:450-458` |
| 条目逐字作为根树项名 | `src/jupiter/utils/converter.rs:420-445` |
| 默认配置 | `config/config.toml:64-71`；`src/config/model.rs:442-458` |

**Acceptance criteria:**

- [x] 具名用例 `monorepo_root_dirs_rejects_invalid_entries` 通过。
- [x] 具名用例 `monorepo_import_dir_shape` 通过。
- [x] 具名用例 `monorepo_shape_error_names_field_without_secret` 通过。
- [x] 具名用例 `shipped_configs_pass_monorepo_shape` 通过（`config/config.toml`、`config/config-storage-only.toml`、`config/config-storage-only.none.toml`）。
- [x] 具名用例 `monorepo_shipped_config_comments` 通过。
- [x] `docs/configuration.md` 描述 `root_dirs` / `import_dir` 形状规则与 import 优先。
- [x] `docs/configuration.zh.md` 同结构描述同一规则。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib -- 'config::validate::tests::monorepo_' 'config::validate::tests::shipped_configs_pass_monorepo_shape'`（`(new)` 前缀组：重复、含 `/`、含 `\`、`.`、`..`、空串、NUL；`import_dir` 非规范 / `/` / 相对 / 含 NUL / 含 `\` / 首组件不在 `root_dirs`（`root_dirs=["project"]`、`import_dir="/vendor"` 必须非零退出）；错误点名字段且不含 secret；`shipped_configs_pass_monorepo_shape` 读取三份自带配置的原始 TOML、只对 `[monorepo]` 段做形状校验（不展开 `${file:…}` 等与本卡无关的 secret 占位符）；`monorepo_shipped_config_comments` 断言 `config/config.toml`、`config/config-storage-only.toml`、`config/config-storage-only.none.toml` 中 `root_dirs` / `import_dir` 附近的注释含「单组件」「唯一」「import 优先」约束说明）
- [x] `cargo run -p mega2 -- --config config/config.toml config validate`
- [x] storage-only 样例的宿主校验（校验配置形状，不解析 secret；只替换与本卡无关的 `${file:…}` 占位符，不改 `[monorepo]`）：
  ```bash
  set -euo pipefail
  T=$(mktemp -d); trap 'rm -rf "$T"' EXIT
  python3 - "$T" <<'PY'
  import sys
  s = open("config/config-storage-only.toml").read()
  old = 'token = "${file:/run/secrets/mega2-push-token}"'
  assert old in s
  open(sys.argv[1] + "/c.toml", "w").write(s.replace(old, 'token = "placeholder-not-a-secret"', 1))
  PY
  cargo run -p mega2 -- --config "$T/c.toml" config validate
  ```
- [x] `cargo run -p mega2 -- --config config/config-storage-only.none.toml config validate`
- [x] `rg -n "root_dirs" docs/configuration.md docs/configuration.zh.md`（锚点定位用，非判据）
- [x] 手工核对：两份配置指南同结构描述形状规则与 import 优先（AC-6、AC-7）

**Dependencies:** FU-03（串行发布链）。

**Deliverables:** N/A

**Implementation write set:** `src/config/validate.rs`；`config/config.toml`；`config/config-storage-only.toml`；`config/config-storage-only.none.toml`（仅注释）；`docs/configuration.md`；`docs/configuration.zh.md`；`src/config/reload.rs`（仅测试数据：候选 `root_dirs` 保留 `third-party`）；`src/jupiter/utils/converter.rs`（仅新增 `INIT_ROOT_RESERVED_NAMES` 常量）；`docs/manual/monorepo-init.md` / `docs/manual/monorepo-init.zh.md`（校验描述随行为更新）；`tests/integration_vault.rs`（仅 `integration_config_hot_reload` 测试数据：`import_dir` 改为合法根下的 `/project/hot-reload-restart-required`）；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** 非法 `root_dirs` 由「生成坏根树」变为启动前失败；此前可启动的 `import_dir`（尾斜杠如 `/third-party/`、首组件不在 `root_dirs` 如 `/tmp/...`、非规范形态）同样变为启动前失败；样例配置注释同步；热重载候选配置同样经 `validate()`，非法形状由「restart-required」变为「watcher 拒绝」，两个既有用例的测试数据改为合法形状（判据不变）。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 错误只点名字段。

**Performance budget:** N/A

**Estimated scope:** `M`

**Version increment:** `minor`（此前可通过校验的非法配置改为启动前失败，属兼容性变化）

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=路径策略配置形状校验; recovery=前滚 minor 版本; complete=yes; self-contained=yes; AC=7/8; VER=6/8; landing=1; prod-files=2; scope=M; deps=FU-03; writeset=序列化于 FU-03; release=independent; split-from=N/A; exception=N/A`

### Task FU-04A: blame 提交消息与摘要取源正文（#28 展示面）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 通过：6 个具名单测、`import_repo_blame_summary_framed`、`api::` 回归通过；零命中守卫 rc=1；反向验证——恢复旧 `clean_commit_message` 时单测 6 例中 5 例失败（`unframed_legacy` 为不变对照），集成用例得到 `commit_summary=""`；手工证据：ImportRepo 未签名推送后 blame 摘要为主题；ER-05 R1 Codex FAIL（4×P1）+ Claude FAIL（1×P1 + 5×P2）已修订；R2 Codex PASS（无发现）+ Claude PASS（2×P2 措辞已落实）；C 组在 bump 后的 `0.39.5` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；推送时 origin/main 已含用户的文档整合合并 `512c86b`，经用户同意 rebase 到其上（计划文件仅追溯表 FU-04 行冲突：保留上游行并接 FU-04A 行），在 rebase 后的树上重跑 C 组同样全绿；提交 `4f6d8e3`、tag `v0.39.5` 与 GitHub Release 已发布；D 组 `docker.yml` run `35946294891` 的 `docker` job 对 `4f6d8e3` 为 success）

**Description:** 用户决定（2026-09-24）把 FU-03 R1 Claude 评审发现的 blame 缺陷作为独立卡插在 FU-04 之后，按发布链串行发布（实际发布位于 FU-08 之后、FU-09 之前，因 FU-05..FU-08 已发布）。`blame_ops.rs` 的 `commit_message` / `commit_summary` 改由 `blame_commit_text` 经 `split_commit_message(..).body` 与 `commit_body_subject`（FU-01 的唯一 helper）取得，替换只识别 PGP 装甲、只处理以 `gpgsig ` 开头消息的 `clean_commit_message`。blame 只有一个实现（`blame_ops::get_file_blame`，Monorepo 与 ImportRepo 的 `ApiHandler` 共用）。唯一行为轴是「blame 展示的提交消息与摘要取源正文」。实现由独立会话完成，本会话按 ER-12（单一发布者）负责评审、门禁与发布。

**Out of scope:**

- 其它展示面：tree / 最新 commit 信息（`src/ceres/model/git.rs:85,123`）、CL commit 行（`src/jupiter/storage/cl_storage.rs:544`，已落库）、CL 标题（`src/ceres/code_edit/model.rs:322`）。它们用 git-internal 的 `format_message()`，只按 PGP 装甲的结束行剥离，SSH 签名、`encoding` 头以及与 `gpgsig` 同时出现的 `mergetag` 会外露；不在本卡轴内 —— `DEFER-FU-16`。
- 存量对象 —— 不改写（展示层修正对存量对象同样生效）。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 成帧的未签名消息以 `\n` 开头 → `lines().next()` 为空串，摘要为空 | 修复前 `src/ceres/api_service/blame_ops.rs:724-725` |
| 只剥 PGP 装甲（SSH 签名吞掉全部正文）、只认 `gpgsig ` 前缀（`gpgsig-sha256` 原样外露） | 修复前 `clean_commit_message`（`blame_ops.rs:849-882`） |
| 客户端普通推送的未签名 commit（ImportRepo）为成帧消息 → 旧 helper 摘要为空；trunk 路径的 blame 归因到服务端 PGP 签名的层 commit，旧 helper 已能剥 PGP（仅末尾换行不同） | 本卡反向验证与手工证据（2026-09-24）；FU-03 R1 Claude P2 |

**Acceptance criteria:**

- [x] 具名用例 `blame_commit_text_framed_unsigned` 通过。
- [x] 具名用例 `blame_commit_text_strips_pgp_signature` 通过。
- [x] 具名用例 `blame_commit_text_strips_ssh_signature` 通过。
- [x] 具名用例 `blame_commit_text_strips_gpgsig_sha256` 通过。
- [x] 具名用例 `blame_commit_text_unframed_legacy` 通过。
- [x] 具名用例 `blame_commit_text_unframed_multiline_legacy` 通过。
- [x] 具名用例 `import_repo_blame_summary_framed` 通过。
- [x] `api::` 既有用例全部通过（本卡前 `blame_ops` 无专项用例）。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::api_service::blame_ops::tests::blame_commit_text'`（`(new)` 6 例：成帧未签名、PGP、SSH、`gpgsig-sha256`、未成帧单行历史消息、未成帧多行历史消息（首行按 ADR-FU-01 文法读作头，与 Git 对该对象的读法一致）；反向验证：恢复旧 `clean_commit_message` 时 5 例失败——PGP 例只因旧 helper 去掉末尾换行而失败——`unframed_legacy` 为不变对照）
- [x] `source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1 import_repo_blame_summary_framed`（`(new)`：客户端普通推送一个未签名 commit 到 `/third-party/<repo>`，`GET /api/v1/blame` 的 `commit_summary` 为主题、`commit_message` 为 `主题\n`；反向验证：旧 helper 下 `commit_summary=""`、`commit_message` 带前导空行）
- [x] `source .env.test && cargo test -p mega2 --lib 'api::'`（回归）
- [x] 零命中守卫（旧 helper 已删除）：
  ```bash
  if rg -n "fn clean_commit_message" src; then
    echo "FAIL: forbidden pattern found"; exit 1
  else
    rc=$?
    if [ "$rc" -ne 1 ]; then echo "ERROR: rg failed with exit $rc"; exit "$rc"; fi
    echo "OK: zero hits"
  fi
  ```
- [x] 手工证据（sanitized）：本地 storage-only 全新栈（`push_auth=none`），宿主 `git push` 一个未签名 commit 到 `/third-party/fu04a` 后，`GET /api/v1/blame?path=/third-party/fu04a/f.txt` 的 `commit_summary` 为 `fu04a plain push subject`、`commit_message` 为 `fu04a plain push subject\n`（原始对象为标准成帧消息）

**Dependencies:** FU-08（串行发布链；用户决定插入 FU-08 与 FU-09 之间）。所用 helper 来自已发布的 FU-01。

**Deliverables:** N/A

**Implementation write set:** `src/ceres/api_service/blame_ops.rs`；`tests/integration_api_write_trunk.rs`（仅新增 `import_repo_blame_summary_framed`）；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** blame API 的 `commit_message` 为源正文——成帧消息不再带前导空行、签名块与 `mergetag` / `encoding` 等额外头不再外露（PGP 签名消息此前去掉末尾换行，现保留正文原样的末尾换行）；`commit_summary` 为正文首个非空行（此前成帧消息与 SSH 签名消息为空串、`gpgsig-sha256` 消息为 `gpgsig-sha256 -----BEGIN …`、带 `mergetag` / `encoding` 头的消息为该头行）。FU-03 之前 `edit/save` 写入的未成帧多行消息（如 `Update README.md\n\nMore details`）的首行按 ADR-FU-01 文法读作头，展示改为其后的正文（`More details`；正文为空时摘要为空串），与 Git 对该对象的读法一致。无 schema 变化；无文档页描述这两个字段的取源，无需同步文档。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** N/A（签名块不再外露于 blame 响应）

**Performance budget:** N/A

**Estimated scope:** `S`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=blame 展示取源正文; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=8/8; VER=5/8; landing=1; prod-files=1; scope=S; deps=FU-08; writeset=序列化于 FU-08; release=independent; split-from=FU-03（R1 Claude P2，用户决定独立成卡）; exception=N/A`

### Task FU-05: 路径策略错误域与创建路径分类原语（#29）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 通过；ER-05 R1 Codex FAIL 1×P1、Claude PASS 10×P2 已修订；R2 Codex PASS（1×P2 证据命令说明已补）；C 组在 bump 后的 `0.39.1` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；提交 `0c9e22e`、tag `v0.39.1` 与 GitHub Release 已发布；D 组 `docker.yml` run `35911629044` 的 `docker` job 对 `0c9e22e` 为 success）

**Description:** 按 ADR-FU-03 第 1、3–6 条与 ADR-FU-04 第 2 条，新增 `PathPolicyError`、`MegaError::PathPolicy`、`ApiError` 映射（裸 / 包装 / `GitError` 三条通道，文本原样、单行）与唯一的 `classify_creation_path`，并导出供调用方复用的 `in_import_namespace`、`is_import_dir_ancestor`、`not_allowed`（GC-FU-02）。本卡无入口，发布后休眠（FU-06、FU-07、FU-10 消费）。唯一行为轴是「路径策略判定与其错误契约」。

**Out of scope:**

- 产品写、开通 API、receive-pack 接线 —— 由 FU-06、FU-07、FU-10 承接。
- `ImportRepoError` —— 由 FU-12 承接。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| `MegaError` 定义与包装规则 | `src/common/errors/mod.rs:40-75`；`docs/errors.md:68-77` |
| `ApiError` 映射 | `src/common/errors/api.rs:150-190` |
| 规范化 | `src/common/utils.rs` `canonicalize_mono_ref_path` |

**Acceptance criteria:**

- [x] 具名用例 `classify_import_dir_precedence` 通过。
- [x] 具名用例 `classify_outside_roots_not_allowed` 通过。
- [x] 具名用例 `classify_allowed_root` 通过。
- [x] 具名用例 `classify_invalid_paths` 通过。
- [x] 具名用例 `path_policy_display_codes` 通过。
- [x] 具名用例 `path_policy_api_status` 通过。
- [x] 具名用例 `path_policy_message_redaction` 通过。
- [x] `docs/errors.md` 含 `PathPolicyError` 小节。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::path_policy::tests'`（`(new)` 模块：import 目录优先于同名 `root_dirs` 项；首段 ∉ `root_dirs`；首段 ∈ `root_dirs`（含自定义 `["apps"]`）；`/` 判 `Invalid`；JSON 严格入口 `strict_creation_path_input` 对相对、`..`、重复斜杠、尾斜杠别名、含 NUL、含 `\` 均判 `Invalid`（违反 `input == canonicalize_mono_ref_path(input)` 或显式字符拒绝））
- [x] `source .env.test && cargo test -p mega2 --lib 'common::errors::tests::path_policy'`（`(new)`：四个 `Display` 以码加 `: ` 开头；400/409 映射；`NotAllowed` 列出根名且不含配置路径、`base_dir`、URL）
- [x] `test -f docs/errors.md && rg -n "MONO_PATH_NOT_ALLOWED" docs/errors.md`（锚点定位用）+ 人工核对小节含四个码、HTTP 映射与 Git 面文本格式

**Dependencies:** FU-04（配置形状已校验）。

**Deliverables:** N/A

**Implementation write set:** `src/common/errors/mod.rs`；`src/common/errors/api.rs`；`src/ceres/pack/path_policy.rs`（新）与 `src/ceres/pack/mod.rs`（模块声明）；`docs/errors.md`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** `docs/errors.md`；无运行时行为变化。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 消息脱敏由具名用例断言。

**Performance budget:** O(路径组件数)。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=路径策略判定与错误契约; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=8/8; VER=5/8; landing=2; prod-files=4; scope=M; deps=FU-04; writeset=序列化于 FU-04; release=independent; split-from=FU-04（R1）; exception=N/A`

### Task FU-06: 产品写在无非根 tip 时的分类与落点回落（#25 / #29）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 通过；ER-05 R1 Codex FAIL / Claude FAIL 已修订；R2 Codex PASS、Claude PASS；R3 Codex PASS（复核 R2 后的代码改动，2×P2 已落实）；C 组在 bump 后的 `0.39.2` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；提交 `e97ed48`、tag `v0.39.2` 与 GitHub Release 已发布；D 组 `docker.yml` run `35920551975` 的 `docker` job 对 `e97ed48` 为 success）

**Description:** 按 ADR-FU-06 与 ADR-FU-04 第 4 条，`MonoApiService` 产品写先过无条件的 import 命名空间守卫；`resolve_trunk_land_path` 无候选时再 `classify_creation_path`：违规返回 `PathPolicyError`；合法时对一级根调用 `materialize_path_refs` 后以其为落点（一级根若是嵌套 `import_dir` 的严格祖先——`path_policy::is_import_dir_ancestor`——则不物化、返回 `MONO_PATH_UNINITIALIZED`，GC-FU-04）。守卫与分类只调用 `path_policy` 的导出函数，不复制判断（GC-FU-02）：守卫即 `path_policy::check_write_operands`（按组件判定、只拒 `..`、名字可含 `\`，本卡新增并单测）；回落对用户写的路径（`policy_path`：create / delete 的条目路径、move 的目的、edit 的文件）取一级根分类，错误点名该路径。唯一行为轴是「产品写在无非根 tip 时的策略与落点」。

**Out of scope:**

- 开通 API —— 由 FU-07 承接。
- 在 `/` 落地 —— 永久非目标。
- 已有非根 tip 的写 —— 永久非目标（行为不变）。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 无非根 tip → `[code:400] no non-root path tip …` | `src/ceres/api_service/mono_api_service.rs:2412-2427` |
| 物化原语 | `src/ceres/pack/materialize.rs:69-160` |
| attach 祖先预检 | `src/jupiter/storage/mono_storage.rs:843-882` |
| 复现 | E5 |

**Acceptance criteria:**

- [x] 具名用例 `create_entry_fresh_stack_without_clone` 通过（含落地 tip 第一父为物化 commit 的历史连续断言）。
- [x] 具名用例 `api_write_custom_root_dirs` 通过。
- [x] 具名用例 `api_write_outside_roots_path_policy` 通过。
- [x] 具名用例 `api_write_nested_root_fresh_stack` 通过。
- [x] 具名用例 `api_write_import_namespace_guard` 通过。
- [x] 具名用例 `import_attach_after_import_dir_api_write` 通过。
- [x] 具名用例 `fresh_stack_concurrent_writes` 通过。
- [x] `docs/deploy-trunk.md` 删除「需先 clone 祖先」的隐含前提并登记根外写的新错误码。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1 fresh_stack_`（`(new)` 前缀组 + `create_entry_fresh_stack_without_clone`：全新栈 create-entry 成功；`main@/project` tip 第一父为物化 commit；并发两写（落在两个不同的一级根 `/project` 与 `/doc`，同路径并发受 ADR-TP-10 约束，见 `DEFER-FU-12`）均落地）
- [x] `source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1 api_write_`（`(new)` 前缀组：根外路径与 `/` 下新顶层返回 400 且 `err_message` 以 `MONO_PATH_NOT_ALLOWED:` 开头；`api_write_custom_root_dirs`——`root_dirs=["apps", "third-party"]`（FU-04 要求 `import_dir` 首组件列在 `root_dirs` 中）下 `/apps/x` 落地、`/project/x` 返回 `MONO_PATH_NOT_ALLOWED`；`/project/a/b` 在全新栈落地（`api_write_nested_root_fresh_stack` 另含嵌套 `import_dir="/third-party/vendor"` 栈：`/third-party/tools` 返回 409 `MONO_PATH_UNINITIALIZED`、`/third-party/vendor/x` 返回 `MONO_PATH_NOT_ALLOWED`，且无 `main@/third-party*`、根不变）；`api_write_import_namespace_guard`——(a) 全新栈上 import 目录写返回 `MONO_PATH_NOT_ALLOWED` 且不产生 `main@/third-party*`；(b) 先导入 ImportRepo 并删除其 `git_repo` 行（等价于清理之后），再人为物化 `main@/third-party` 后，对该叶子的 create / edit-save / delete / 改名均返回 `MONO_PATH_NOT_ALLOWED`（无守卫时这些写会落在该 tip 上），对另一个存活叶子从父目录的 delete / 改名同样返回 400，且根树与该子树不变；(c) 把 `/project` 下的普通文件与目录 move 到 `/third-party/x` 返回 `MONO_PATH_NOT_ALLOWED`，源保留、目的不存在、根 commit 不变；`import_attach_after_import_dir_api_write`：其后新 ImportRepo 首推成功）
- [x] `source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1`（既有 create/delete/move 回归）

**Dependencies:** FU-05（分类与错误域）。

**Deliverables:** N/A

**Implementation write set:** `src/ceres/api_service/mono_api_service.rs`；`tests/integration_api_write_trunk.rs`；`docs/deploy-trunk.md`；`docs/refactoring/directory-entry-api.md`（跨顶层 move / 删除顶层目录文本与错误表随行为更新）；`src/ceres/pack/path_policy.rs`（新增 `check_write_operands`、`operand_path` 与其单测）；`docs/errors.md`（`Invalid` 行注明产品写落点 `/` 按 `NotAllowed`）；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** `docs/deploy-trunk.md`、`docs/refactoring/directory-entry-api.md`；根外产品写、在 `/` 落地的写（`/` 下新建顶层、跨顶层 move、删除顶层目录）的错误文本从 B0 拓扑错误 `no non-root path tip …` 变为 `MONO_PATH_NOT_ALLOWED`（同为 400，既有用例 `move_entry_reject_root` 断言随之更新）；目的地为存活 ImportRepo 的 move 保留既有 409（先于守卫判定，与源分派到 `ImportApiService` 的 409 对称），其余 import 命名空间操作数一律 400。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 鉴权不变（落点解析之前按写路径判定）；永不物化 import 目录（GC-FU-04）。

**Performance budget:** 仅无候选时额外一次分类 + 一次物化（O(depth) 树读 + 一次锁内短事务）。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=产品写在无非根 tip 时的策略与落点; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=8/8; VER=3/8; landing=1; prod-files=2; scope=M; deps=FU-05; writeset=序列化于 FU-05; release=independent; split-from=FU-03（R1）; exception=N/A`

### Task FU-07: 幂等路径开通 HTTP API（#25）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 通过；ER-05 R1 Codex FAIL / Claude FAIL、R2 Codex FAIL 均已修订；R2 Claude PASS；R3 Codex PASS（无发现）；C 组在 bump 后的 `0.39.3` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；手工证据：两次 `POST /api/v1/path/provision` 分别 `created:true` / `created:false`；提交 `50a8c33`、tag `v0.39.3` 与 GitHub Release 已发布；D 组 `docker.yml` run `35929463965` 的 `docker` job 对 `50a8c33` 为 success）

**Description:** 按 ADR-FU-05 第 1–3 条挂载 `POST /api/v1/path/provision`（`mkdir -p`、幂等、按最高新建组件授权、经 MonoWriteQueue）。唯一行为轴是「幂等路径开通的机器接口」。

**Out of scope:**

- CLI —— 由 FU-08 承接。
- 用户旅程文档 —— 由 FU-11 承接。
- create-entry 重名语义 —— `DEFER-FU-04`。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| create-entry 树构建与落地 | `mono_api_service.rs:1993-2100,2127-2387` |
| 写鉴权 | `src/api/api_write_auth.rs:27-49`；`src/api/router/preview_router.rs:57-63,475-485` |
| 分类原语 | FU-05 `src/ceres/pack/path_policy.rs` |
| 复现 | E5、E6 |

**Acceptance criteria:**

- [x] 具名用例 `path_provision_creates_missing_levels` 通过。
- [x] 具名用例 `path_provision_is_idempotent` 通过。
- [x] 具名用例 `path_provision_rejects_policy_violations` 通过。
- [x] 具名用例 `path_provision_conflict_on_file_component` 通过。
- [x] 具名用例 `path_provision_token_scope` 通过。
- [x] 具名用例 `path_provision_concurrent_same_path` 通过。
- [x] 具名用例 `path_provision_openapi` 通过。
- [x] `docs/refactoring/directory-entry-api.md` 含开通 API 小节。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'api::'`（A 组）
- [x] `source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1 path_provision_`（`(new)` 前缀组：全新栈 `created:true`、一次 commit、目标可读；重复 `created:false` 且 tip 不变；默认/自定义 `root_dirs`、import 目录、非法路径 → 400 对应码；文件组件 → 409 `MONO_PATH_CONFLICT`；最高新建组件授权的 401/403/200；两并发恰一个 `created:true`；运行时 OpenAPI 含路由并声明 400/401/403/409）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::api_service::mono_api_service::tests::fu07_'`（`(new)`：最高新建组件计算、重 prepare 重授权）
- [x] `test -f docs/refactoring/directory-entry-api.md && rg -n "path/provision" docs/refactoring/directory-entry-api.md`（锚点定位用）+ 人工核对小节含请求、响应、错误码、授权规则
- [x] 手工证据（sanitized）：两次 `POST /api/v1/path/provision` 的响应体

**Dependencies:** FU-06（全新栈落点与分类）。

**Deliverables:** N/A

**Implementation write set:** `src/ceres/api_service/mono_api_service.rs`（开通服务）；`src/ceres/model/git.rs`（DTO）；`src/api/router/preview_router.rs`（路由与 OpenAPI 注解）；`src/api/api_router.rs`（只在 `storage_only_routers_with` 合并开通路由）；`tests/integration_api_write_trunk.rs`；`docs/refactoring/directory-entry-api.md`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** 新端点；契约页新节。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 只挂 storage-only；最高新建组件授权；每次 prepare 重新授权。

**Performance budget:** 一次开通 = O(depth) 树读 + 至多一次落地；已存在时零写。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=幂等路径开通 HTTP API; recovery=前滚补丁版本（端点下线）; complete=yes; self-contained=yes; AC=8/8; VER=7/8; landing=3; prod-files=4; scope=M; deps=FU-06; writeset=序列化于 FU-06; release=independent; split-from=FU-04（R1）; exception=N/A`

### Task FU-08: `mega2 path provision` CLI（#25）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 通过；ER-05 R1 Codex FAIL 已修订、Claude PASS（P2 已落实）；R2 Codex PASS（1×P2：测试服务线程可回收，已落实）；C 组在 bump 后的 `0.39.4` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；手工证据：Libra 0.23.46 在开通路径上 clone、两次增量 push，`libra log` / `git log` 一致；提交 `0f4e446`、tag `v0.39.4` 与 GitHub Release 已发布；D 组 `docker.yml` run `35933879820` 的 `docker` job 对 `0f4e446` 为 success）

**Description:** 按 ADR-FU-05 第 4 条新增 `mega2 path provision` 子命令（`LoadMode::None` 的薄 HTTP 客户端）及其 Git 进程级旅程回归。唯一行为轴是「开通操作的 CLI 客户端」。

**Out of scope:**

- 服务端 API —— 已由 FU-07 交付。
- quick-start / user-guide 叙述 —— 由 FU-11 承接。
- Libra 原生命令 —— `DEP-FU-03`。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 子命令三处注册；`LoadMode::None` | `src/commands/mod.rs:22-30,92-124` |
| `reqwest` 已是依赖 | `Cargo.toml:72` |
| 写鉴权接受 Bearer | `src/api/api_write_auth.rs:1-60` |

**Acceptance criteria:**

- [x] 具名用例 `path_provision_parses` 通过。
- [x] 具名用例 `path_command_registered` 通过。
- [x] 具名用例 `path_provision_cli_created` 通过。
- [x] 具名用例 `path_provision_cli_exists` 通过。
- [x] 具名用例 `path_provision_cli_rejects` 通过。
- [x] 具名用例 `path_provision_cli_token_env_only` 通过。
- [x] 具名用例 `path_provision_cli_then_two_pushes` 通过。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'cli::tests'`（A 组；`(new)` `path_provision_parses`：参数解析，argv 无 token 选项）
- [x] `source .env.test && cargo test -p mega2 --lib 'commands::'`（A 组；`(new)` `path_command_registered`：`builtin()`、`builtin_exec()`、`load_mode()` 三处，`LoadMode::None`）
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 path_provision_cli_`（`(new)` 前缀组，`CARGO_BIN_EXE_mega2`：无 `--config` 首次退出码 0 且输出 `created`；重复退出码 0 且输出 `already exists`；根外退出码 1 且 stderr 以 `MONO_PATH_NOT_ALLOWED:` 开头；`push_auth=token` 栈仅经 `MEGA2_TOKEN` 成功且输出不含 token；开通 → clone → commit → push → commit → push，重新 clone 可见两个 commit）
- [x] `source .env.test && cargo test -p mega2 --lib 'commands::path::tests'`（`(new)`：不跟随跨主机重定向、超时配置）
- [x] 手工证据（sanitized）：Libra 0.23.46 在开通路径上 clone、两次增量 push

**Dependencies:** FU-07（开通 API）。

**Deliverables:** N/A

**Implementation write set:** `src/commands/path.rs`（新）；`src/commands/mod.rs`；`src/cli.rs`（仅测试）；`tests/integration_git_cli.rs`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** 新子命令（用户文档由 FU-11）。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** token 只经环境变量；不跟随跨主机重定向；错误输出不回显请求头。

**Performance budget:** 单次 HTTP 请求，超时 30 s。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=开通操作的 CLI 客户端; recovery=前滚补丁版本（子命令下线）; complete=yes; self-contained=yes; AC=7/8; VER=5/8; landing=1; prod-files=2; scope=M; deps=FU-07; writeset=序列化于 FU-07; release=independent; split-from=FU-05（R1）; exception=N/A`

### Task FU-09: 孤儿链拒绝黏性（#25）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 通过；ER-05 R1 Codex FAIL（1×P1：孤儿错误未真正类型化）已修订为 `MegaError::OrphanChain`，Claude PASS（7×P2 已落实，额外 commit 绕过登记 `DEFER-FU-17`）；R2 Codex PASS（1×P2）+ Claude PASS（3×P2），均已落实（仅注释与文档）；C 组在 bump 后的 `0.39.6` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；提交 `63a66a9`、tag `v0.39.6` 与 GitHub Release 已发布；D 组 `docker.yml` run `35949358975` 的 `docker` job 对 `63a66a9` 为 success）

**Description:** 按 ADR-FU-07，`PushChain::resolve` 与 `from_known_tip` 在 `old_id=ZERO` 且链走到无父根时返回同一类型化孤儿错误，对外文案保持首推文案。唯一行为轴是「孤儿拒绝在重试间保持一致」。

**Out of scope:**

- trunk 路径策略码 —— 由 FU-10 承接。
- `old_id≠ZERO` 拒绝 —— 永久非目标（保持现状）。
- 孤儿拒绝后基于被拒 commit 再加一个 commit 的绕过（既有行为）—— `DEFER-FU-17`。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 孤儿拒绝与漂移 | `src/ceres/pack/push_chain.rs:171-176,272-303,476-481` |
| trunk Noop 桥 | `push_chain.rs` `from_known_tip`；`src/ceres/pack/monorepo.rs:1146-1220` |
| 既有孤儿单测 | `push_chain.rs:1115-1136` |
| 复现 | E3、E4 |

**Acceptance criteria:**

- [x] 具名用例 `orphan_rejection_is_sticky_for_known_tip` 通过。
- [x] 具名用例 `from_known_tip_zero_old_id_orphan` 通过。
- [x] 具名用例 `orphan_retry_same_rejection` 通过。
- [x] 具名用例 `fu09_review_orphan_retry_text` 通过。
- [x] 既有 `ceres::pack::push_chain::tests` 全部通过。
- [x] `docs/refactoring/trunk-push.md` 登记孤儿拒绝黏性。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::push_chain::tests'`（`(new)` `orphan_rejection_is_sticky_for_known_tip`：新 tip 与已知 tip 同一孤儿错误；`from_known_tip_zero_old_id_orphan`；既有 `old_id≠ZERO` 用例）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::monorepo::tests::fu09_review_orphan_retry_text'`（`(new)`：review 形态经 `validate_incoming_push`（产生 `ng` 行的准入门）首推与重试文案均为 `Can not init directory under monorepo directory!`）
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 orphan_retry_same_rejection`（`(new)`：真实 `git push` 重试同一无父 commit 与首推得到相同 `ng` 文案，不含 `is not on the first-parent chain`）
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 --exact integration_git_cli_trunk_n_gt1_squash_sideband_and_nff_align`（NFF 回归）

**Dependencies:** FU-04A（串行发布链）。

**Deliverables:** N/A

**Implementation write set:** `src/ceres/pack/push_chain.rs`；`src/common/errors/mod.rs`（仅新增 `MegaError::OrphanChain` 变体）；`src/ceres/pack/monorepo.rs`（仅测试）；`tests/integration_git_cli.rs`；`docs/refactoring/trunk-push.md`；`docs/errors.md`（登记新变体）；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** 重试文案回到首推文案。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** N/A

**Performance budget:** N/A（不增加 DB 读）

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=孤儿拒绝在重试间一致; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=6/8; VER=4/8; landing=1; prod-files=2; scope=M; deps=FU-04A; writeset=序列化于 FU-04A; release=independent; split-from=FU-06（R1）; exception=N/A`

### Task FU-10: trunk 首推路径策略分类（#29 / #25）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 通过：`fu10_` 单测 5 例、`path_policy_` 集成用例 6 例、`orphan_retry_same_rejection` 与 NFF 回归；`ceres::` + 推送队列库回归 512 例与 `integration_git_cli` 全部 38 例按终态重跑通过；反向验证——关闭准入分类与 B3 再分类后新行为用例失败、两个对照通过，去掉 `map_err` 接线后 B3 端到端用例失败；手工证据：本机 Libra 0.23.58 对根外与未开通子路径首推与重试分别显示 `MONO_PATH_NOT_ALLOWED` / `MONO_PATH_UNINITIALIZED`；ER-05 R1 Codex FAIL（1×P1 + 1×P2）+ Claude PASS（8×P2）已修订；R2 Codex PASS + Claude PASS（3×P2 已处置）；C 组在 bump 后的 `0.40.0` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行，失败集为 6 个基线环境用例（原因同类）外加一次瞬时失败 `integration_api_write_trunk::move_entry_reject_import_repo`（seed 阶段 `git clone /project` 得到 connection reset，读路径，与本卡无关；同一棵树上单独重跑 3/3 通过、整个 target 62/62 通过）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；提交 `e290279`、tag `v0.40.0` 与 GitHub Release 已发布；D 组 `docker.yml` run `35957528383` 的 `docker` job 对 `e290279` 为 success）

**Description:** 按 ADR-FU-03 第 5–6 条与 ADR-FU-04 第 3、5 条，trunk 下 `Monorepo::validate_incoming_push` 对「`old_id=ZERO` 且路径无 `main` 行、无墓碑且在根树不可解析」的推送调用 `classify_creation_path`：`NotAllowed` 直接拒绝；`Allowed` 且链为孤儿 → `MONO_PATH_UNINITIALIZED`；`Allowed` 且 fork 型 → 原 B3 创建语义；B3 真创建分支锁内再分类。唯一行为轴是「trunk 首推路径策略诊断」。孤儿错误来自 FU-09 的 `is_orphan_chain_error`；它对已知 tip 的链不证明历史未被引用（例如把另一路径的 clone 原样推到新路径同样得到孤儿错误，FU-09 R1 Claude P2），分类文案不得断言「历史未被引用」。

**Out of scope:**

- 孤儿黏性 —— 已由 FU-09 交付。
- 孤儿拒绝后「再加一个 commit」的绕过 —— 已按 `DEFER-FU-17` 评估，不合入：修正需把 fork 判定从「已入库」改为「可从存活 ref 或根树到达」（遍历存活 ref 历史或新增可达性索引），语义与读取成本都超出本卡轴；本卡之后根外创建一律被拒，该绕过只能在允许的根下创建以孤儿为根的新路径，保持延后。
- review 形态 —— 永久非目标（trunk-push 硬约束 8）。
- 放开无父首推 —— 永久非目标（issue 不变量）。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 准入门 | `src/ceres/pack/monorepo.rs:1076-1128` |
| 对齐提示仅匹配 NFF/broken | `monorepo.rs:91-99`；`src/ceres/pack/api_tip_lander.rs:25-34` |
| B3：无行且 `old_id≠ZERO` 已拒绝；真创建分支 | `src/jupiter/service/push_queue_service.rs:1775-1811,1910-1928` |
| 复现 | E1、E2 |

**Acceptance criteria:**

- [x] 具名用例 `path_policy_outside_roots_not_allowed` 通过。
- [x] 具名用例 `path_policy_uninitialized_child` 通过。
- [x] 具名用例 `integration_git_cli_trunk_n_gt1_squash_sideband_and_nff_align` 通过（含新增「拒绝文案不含 `MONO_PATH_`」断言）。
- [x] 具名用例 `path_policy_custom_root_dirs` 通过。
- [x] 具名用例 `path_policy_fork_creation_valid_root_lands` 通过。
- [x] 具名用例 `path_policy_fork_creation_outside_roots_rejected` 通过。
- [x] 具名用例 `path_policy_raw_nonzero_old_id_unresolved_root_rejected` 通过。
- [x] `docs/refactoring/trunk-push.md` 创建语义小节订正（无父链拒绝、`root_dirs` 白名单、锁内再分类）。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::monorepo::tests::fu10_'`（`(new)` 前缀组：接线单测；`fu10_b3_creation_reclassifies_under_lock`）
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 path_policy_`（`(new)` 前缀组：无父首推与重试均 `MONO_PATH_NOT_ALLOWED:` 并列出根；未开通子路径首推与重试均 `MONO_PATH_UNINITIALIZED:` 并点名 CLI 与 API；`root_dirs=["apps","third-party"]`（FU-04 要求 `import_dir` 首组件在 `root_dirs` 中）下 `/apps/x` 与 `/project/x`；fork 型创建落地与根外拒绝；原始 receive-pack 以已知非零 `old_id`（合法的第一父步）推根外未解析路径，被 B3 `cannot update missing path` 拒绝且根 ref 与根树不变；带尾斜杠的远端 URL（Libra 默认形式）由客户端在构造 receive-pack URL 时去掉尾斜杠，服务端按规范路径分类，不被判为 `MONO_PATH_INVALID`；Monorepo 分派不做服务端规范化，见 `DEFER-FU-18`）
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 --exact integration_git_cli_trunk_n_gt1_squash_sideband_and_nff_align`
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 orphan_retry_same_rejection`（FU-09 的 trunk 栈用例；本卡把其首推与重试断言改为对应的 `MONO_PATH_*` 码，两者仍逐字相同）
- [x] `rg -n "MONO_PATH_UNINITIALIZED" docs/refactoring/trunk-push.md`（锚点定位用）+ 人工核对订正内容
- [x] 手工证据（sanitized）：Libra（本机 0.23.58）对根外与未开通子路径显示同样的码

**Dependencies:** FU-09（孤儿错误已类型化）。

**Deliverables:** N/A

**Implementation write set:** `src/ceres/pack/monorepo.rs`；`src/jupiter/service/push_queue_service.rs`（仅 B3 真创建分支再分类）；`tests/integration_git_cli.rs`（含 FU-09 `orphan_retry_same_rejection` 断言随码更新）；`src/ceres/api_service/mono_api_service.rs`（仅测试数据：`tp12_create_n1_and_n2_and_multilevel` 的创建路径移入 `/project` 之下）；`docs/refactoring/trunk-push.md`；`docs/errors.md`（`OrphanChain` 条目补 trunk 映射）；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** 推送拒绝文案变化；关闭 fork 型创建新顶层（ADR-FU-04）。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 只列根名称；`push_auth=token` 下分类在认证之后；B3 锁内纵深防御。

**Performance budget:** 仅 `old_id=ZERO` 推送多一次 O(depth) 根树解析。

**Estimated scope:** `M`

**Version increment:** `minor`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=trunk 首推路径策略诊断; recovery=前滚 minor 版本; complete=yes; self-contained=yes; AC=8/8; VER=7/8; landing=2; prod-files=2; scope=M; deps=FU-09; writeset=序列化于 FU-09; release=independent; split-from=FU-06（R1）; exception=N/A`

### Task FU-11: 首次使用与路径策略用户旅程文档（#25 / #29）

**Task type:** `docs`

**Lifecycle / Acceptance:** `done` / `complete`（A/B：锚点定位与逐条核对、相对链接可解析、中英标题计数一致；quick-start 新示例的流程在本地 storage-only 栈（`0.40.0` 构建，与 `e290279` 同树）上以本机构建的 CLI 实测：开通 `created` / 重复 `already exists`、clone、提交、推送成功，孤儿推送新路径得到 `MONO_PATH_UNINITIALIZED`；`docker compose exec` 的容器内形式未实跑（拉取镜像需下载许可），其二进制路径与容器内监听端口经评审核对；ER-05 R1 Codex FAIL（4×P1，其中 1 条经代码与实测不采纳）+ Claude PASS（10×P2）已修订；R2 Codex PASS（无发现）+ Claude PASS（4×P2 已落实：`CONFLICT` 只由开通返回、中文 HTTP 条目补运行时 OpenAPI、长度上限覆盖第二三类并说明新根做法、证据按终态重跑）；C 组覆盖已由 FU-12 在 `0.40.1` 树上取得（该树含本卡最终变更，三门全绿、失败集恰为 6 个基线环境用例）；提交 `67c6545` 已推送；承接的 D 组：FU-12 的 `docker.yml` run `35972612578` 的 `docker` job 对 `97c111b`（含本卡变更）为 success）

**Description:** 写出 #29 AC6 要求的唯一权威首次使用小节，并让 README、quick-start 链接它；quick-start 写出无 curl 的建仓旅程；登记 `PathPolicyError` 的 Git 面出现场景。唯一行为轴是「首次使用用户旅程文档」。

**Out of scope:**

- 任何代码或配置 —— 永久非目标（docs 卡）。
- ImportRepo 文档 —— 由 FU-22 承接。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| quick-start 无首次建仓旅程 | `docs/quick-start.md:26-80` |
| user-guide 章节 | `docs/user-guide.md:21,63,89,110` |
| README 文档表 | `README.md:101-106` |

**Acceptance criteria:**

- [x] `docs/user-guide.md` 含唯一权威小节「Monorepo path policy and first use」（允许根的来源、三类首推情形与下一步、开通 API、CLI）。
- [x] `docs/user-guide.zh.md` 含同结构中文小节。
- [x] 英文权威小节列出四个 `MONO_PATH_*` 码并链接 `errors.md`。
- [x] 中文权威小节列出四个 `MONO_PATH_*` 码并链接 `errors.md`。
- [x] `docs/user-guide.md` §7 CLI 速查登记 `mega2 path provision`。
- [x] `docs/user-guide.zh.md` §7 登记 `mega2 path provision`。
- [x] `docs/quick-start.md` 含「在新路径建仓库」小节（`mega2 path provision` → clone → push，无 curl），链接权威小节。
- [x] `docs/quick-start.zh.md` 含同结构中文小节。
- [x] `README.md` 链接英文权威小节。
- [x] `README.zh.md` 链接中文权威小节。
- [x] `docs/manual/monorepo-init.zh.md` 的目录结构章节链接到使用指南权威小节，并注明 `root_dirs` 为创建白名单；英文手册同步至 `docs/manual/monorepo-init.md`。
- [x] `docs/errors.md` 的 `PathPolicyError` 小节登记 Git 面出现场景（`ng` 行文本格式）。
- [x] 本卡改动的文档中相对链接全部可解析。

**Verification:**

- [x] `rg -n "path provision|path/provision|MONO_PATH_UNINITIALIZED" README.md README.zh.md docs/quick-start.md docs/quick-start.zh.md docs/user-guide.md docs/user-guide.zh.md docs/manual/monorepo-init.md docs/manual/monorepo-init.zh.md docs/errors.md`（锚点定位用）+ 人工逐条核对 AC-1..12
- [x] 相对链接可解析：
  ```bash
  for f in README.md README.zh.md docs/quick-start.md docs/quick-start.zh.md docs/user-guide.md docs/user-guide.zh.md docs/manual/monorepo-init.md docs/manual/monorepo-init.zh.md docs/errors.md; do
    d=$(dirname "$f")
    rg -o --no-filename '\]\(([^)#\s]+)' -r '$1' "$f" | rg -v '^[a-z]+:' | while read -r t; do
      test -e "$d/$t" || { echo "BROKEN: $f -> $t"; exit 1; }
    done || exit 1
  done
  echo "OK: links resolve"
  ```
- [x] 卡范围暂存守卫（暂存前快照为空才继续；只暂存本卡 Deliverables；暂存增量必须是其子集；其它工作区改动保持未暂存并在记录中报告）：
  ```bash
  pre=$(libra diff --staged --name-only) || { echo "ERROR: libra diff failed"; exit 2; }
  if [ -n "$pre" ]; then echo "STOP: pre-staged paths not owned by this card (recorded as handoff, no commit):"; printf '%s\n' "$pre"; exit 3; fi
  libra add README.md README.zh.md docs/quick-start.md docs/quick-start.zh.md docs/user-guide.md docs/user-guide.zh.md docs/manual/monorepo-init.md docs/manual/monorepo-init.zh.md docs/errors.md docs/plan/plan-20260923.md
  staged=$(libra diff --staged --name-only) || { echo "ERROR: libra diff failed"; exit 2; }
  allowed=" README.md README.zh.md docs/quick-start.md docs/quick-start.zh.md docs/user-guide.md docs/user-guide.zh.md docs/manual/monorepo-init.md docs/manual/monorepo-init.zh.md docs/errors.md docs/plan/plan-20260923.md "
  printf '%s\n' "$staged" | while read -r f; do
    [ -z "$f" ] && continue
    case "$allowed" in *" $f "*) ;; *) echo "FAIL: undeclared staged file $f"; exit 1;; esac
  done || exit 1
  echo "OK: staged set ⊆ Deliverables（其它工作区改动保持未暂存并在记录中报告）"
  ```
- [x] 中英结构一致：
  ```bash
  for pair in "docs/user-guide.md docs/user-guide.zh.md" "docs/quick-start.md docs/quick-start.zh.md" "README.md README.zh.md"; do
    set -- $pair
    test "$(rg -c '^#{1,6} ' "$1")" = "$(rg -c '^#{1,6} ' "$2")" || { echo "MISMATCH: $1 vs $2"; exit 1; }
  done
  echo "OK: heading counts match"
  ```
- [x] 手工核对：README、quick-start、user-guide 指向同一个权威小节（中文链中文、英文链英文）

**Dependencies:** FU-10。

**Deliverables:** `README.md`；`README.zh.md`；`docs/quick-start.md`；`docs/quick-start.zh.md`；`docs/user-guide.md`；`docs/user-guide.zh.md`；`docs/manual/monorepo-init.md`；`docs/manual/monorepo-init.zh.md`；`docs/errors.md`；本计划文件。

**Implementation write set:** 同 Deliverables。

**Release write set:** `N/A`

**Files likely touched:** 同上

**Docs and compatibility impact:** 用户文档。

**Rollback mode:** `revert`

**Migration and rollback:** N/A

**Security and privacy:** 示例不含真实 token（用 `MEGA2_TOKEN=<token>` 占位）。

**Performance budget:** N/A

**Estimated scope:** `M`

**Version increment:** `N/A`（随本卡 `libra commit -s` + `libra push origin main` 进入仓库）

**Release boundary:** `no-release`

**C/D coverage from:** `FU-12`（其 C 组三门运行的树包含本卡最终变更；继承其 D 组）

**Granularity:** `type=docs; axis=首次使用用户旅程文档; recovery=revert 文档; complete=yes; self-contained=yes; AC=13/20; VER=6/20; landing=0; prod-files=0; scope=M; deps=FU-10; writeset=序列化于 FU-10; release=no-release; split-from=FU-05（R1）; exception=N/A`

### Task FU-12: ImportRepo 分支与 tag ref CAS（#26）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 按终态重跑：`fu12_` 7 例与 `import_repo_error_domain` 通过；ImportRepo / 推送队列 / 错误 / `git_db` / `import_api_service` 库回归 79 例、`integration_git_cli` 38 例、`integration_api_write_trunk` 62 例通过；fmt 与 clippy rc=0；反向验证三组：去掉 CAS 条件 → 5 个 CAS 用例失败；分支 CAS 放回 `.gitkeep` 写入之后 → 批用例因新增 blob 行失败；去掉纯删除批的默认分支补位 → 其用例失败；ER-05 R1 Codex FAIL（2×P1）+ Claude PASS（9×P2）已修订；R2 Codex FAIL（1×P1：证据缺 AGENTS.md 三门）+ Claude PASS（4×P2 已落实）；bump 前树上三门补跑：首跑另有 3 个环境失败（IT Postgres `/dev/shm` 被累积的测试 schema 统计撑满、`tp17` 负载偶发、端口竞争，单独重跑均 3/3 通过），重置 IT Postgres 统计文件后重跑失败集恰为 6 个基线用例；R3 Codex PASS（无发现）；C 组在 bump 后的 `0.40.1` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` 链接器提示；该树包含 FU-11 的最终变更（C 覆盖承接）；提交 `97c111b`、tag `v0.40.1` 与 GitHub Release 已发布；D 组 `docker.yml` run `35972612578` 的 `docker` job 对 `97c111b` 为 success）

**Description:** 按 ADR-FU-08 第 2–4 条，先于更新路径上线 ref 并发保护：把 B3 attach 的分支命令应用抽为 `apply_import_branch_commands_in_txn`（`Create` 要求不存在、`Update` 要求当前值 = `old_id`、`Delete` 沿用 CAS；任一失败整批回滚到 savepoint），`update_refs` 的 tag 写改为单条原子条件语句（逐 ref，不开事务；FU-18 需为存活栅栏显式开事务）；失败返回 `IMPORT_REPO_STALE_REF`。一次性定义完整 `ImportRepoError` 错误域。唯一行为轴是「ImportRepo ref 更新的并发语义」。本卡发布时第二次推送仍被挂载拒绝（由 FU-13 开放），因此不存在无 CAS 的更新窗口。

**Out of scope:**

- 挂载幂等与后续推送开放 —— 由 FU-13 承接。
- `atomic` 推送与逐分支独立 —— `DEFER-FU-05`。
- 服务端强制 ff —— 永久非目标。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 分支 `Create/Update` 无 CAS | `src/jupiter/service/push_queue_service.rs:1481-1555` |
| tag `Create/Update` 无 CAS，`Delete` 已 CAS | `src/ceres/pack/import_repo.rs:356-394` |
| 未广告 `atomic` | E1 抓包 |

**Acceptance criteria:**

- [x] 具名用例 `fu12_branch_update_stale` 通过。
- [x] 具名用例 `fu12_branch_create_existing` 通过。
- [x] 具名用例 `fu12_branch_batch_atomic` 通过。
- [x] 具名用例 `fu12_tag_update_stale` 通过。
- [x] 具名用例 `fu12_tag_create_existing` 通过。
- [x] 具名用例 `fu12_tag_delete_stale` 通过。
- [x] 具名用例 `import_repo_error_domain` 通过。
- [x] `docs/errors.md` 登记 `IMPORT_REPO_STALE_REF`。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::service::push_queue_service::tests::fu12_'`（`(new)`：对 `apply_import_branch_commands_in_txn` 直接构造命令——陈旧 `Update`、已存在 `Create` 均 `IMPORT_REPO_STALE_REF` 且 ref 不变；两分支一陈旧（`Update` 或批内 `Delete`）时两者均不更新、调用方行终态 `Failed`（`AttachFailure`）且无新增 `mega_blob` 行（分支 CAS 先于 `.gitkeep` 写入））
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::import_repo::tests::fu12_'`（`(new)`：tag 陈旧更新、已存在创建（`already exists`）、陈旧删除均 `IMPORT_REPO_STALE_REF`，tag 不变，相符的更新 / 新建 / 删除照常生效；只含删除的分支批删除默认分支后由剩余分支接任默认）
- [x] `source .env.test && cargo test -p mega2 --lib 'common::errors::tests::import_repo_error_domain'`（`(new)`：六个变体的码、`Display` 前缀、`ApiError` 状态）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::import_repo::tests'`（既有 attach 回归）

**Dependencies:** FU-11（串行发布链）。

**Deliverables:** N/A

**Implementation write set:** `src/jupiter/service/push_queue_service.rs`；`src/ceres/pack/import_repo.rs`；`src/jupiter/storage/git_db_storage.rs`（事务内 CAS 写原语）；`src/common/errors/mod.rs` 与 `src/common/errors/api.rs`（完整 `ImportRepoError` 与映射）；`docs/errors.md`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同 Implementation write set

**Docs and compatibility impact:** 并发覆盖改为拒绝（普通 Git 语义）；只含删除的推送删掉默认分支后，最早的剩余分支成为默认（此前不留默认、广告的 HEAD 为零 id）；`docs/errors.md`。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** CAS 防并发覆盖。

**Performance budget:** 每个 ref 命令一次条件写。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=ImportRepo ref 更新的并发语义; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=8/8; VER=4/8; landing=4; prod-files=5; scope=M; deps=FU-11; writeset=序列化于 FU-11; release=independent; split-from=FU-07（R1）; exception=N/A`

### Task FU-13: ImportRepo 后续推送（带挂载来源记录的幂等挂载）（#26）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 按终态重跑：`fu13_` 11 例（`push_queue_service` 8、`import_repo` 3）、`log_audit_in_txn_rolls_back`（逐字段断言来源记录）与 `import_repo_attach_lookup_uses_target_index` 通过；ImportRepo / 推送队列 / 审计 / `git_db` / 错误 / `import_api_service` 库回归 176 例、`integration_git_cli` 的 `import_repo_` 4 例、`integration_api_write_trunk` 62 例通过；fmt 与 clippy rc=0；反向验证八组：A 关闭更新路径 → 更新与回填单测及 3 个集成用例失败；B 首次挂载不写来源记录 → 来源记录用例失败；C 恢复 Debug 文案 → 占用单测与批集成用例失败；D Done 重放不核对 ref → 两个重放用例失败；E 恢复只含删除批的直写 → 入队用例失败；F 删除判定只认 40 位零 → `fu13_delete_only_sha256_zero_id` 失败；G 删除批重新经物化预检 → `fu13_delete_only_skips_materialization_precheck` 失败；H tip 查找只认 40 位零 → `fu13_first_mount_tip_skips_sha256_delete` 失败；手工证据：本机 Libra 0.23.58 对同一 ImportRepo 第二次推送成功、新 clone 为 v2 且含两个 commit；ER-05 七轮评审（R1–R6 各项处置见修订历史与 Review log）：R7 Codex PASS（1×P2 已落实）+ Claude R7 PASS（1×P2 已落实）；C 组在 bump 后的 `0.40.2` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行、1914 通过且失败集恰为 6 个基线环境用例（`git-lfs/3.8.0` 版本断言 ×4、`docker push failed: unauthorized`、S3 PUT `502 Bad Gateway`，原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` `__eh_frame` 链接器提示；提交 `f99b533`、tag `v0.40.2` 与 GitHub Release 已发布；D 组 `docker.yml` run `35995328647` 的 `docker` job 对 `f99b533` 为 success）

**Description:** 按 ADR-FU-08 第 1、5、6 条，首次挂载在同一事务写挂载来源记录（引入 `AuditStorage::log_audit_in_txn`）；后续推送在来源记录（或存量规则惰性回填）证明归属时跳过树改写只写 ref（CAS 已由 FU-12 提供）；否则 `IMPORT_REPO_PATH_OCCUPIED`；客户端文案去 Debug。唯一行为轴是「已挂载 ImportRepo 的后续推送」。

**Out of scope:**

- ref CAS —— 已由 FU-12 交付。
- 摘除、清理、栅栏 —— 由 FU-16..FU-21 承接。
- 用户旅程文档 —— 由 FU-22 承接。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 每次分支推送都入队 attach | `src/ceres/pack/import_repo.rs:503-600` |
| 叶子已存在即失败 | `src/ceres/api_service/tree_ops.rs:159-164`；`src/jupiter/service/push_queue_service.rs:1397-1421` |
| Debug 文案 | `import_repo.rs:652-654` |
| `audit_logs` 与 `idx_audit_logs_target`；`log_audit` 自有连接 | `src/jupiter/migration/m20260306_121829_create_bots_related_table.rs:239-270,350-370`；`src/jupiter/storage/audit_storage.rs:33-55` |
| 复现 | E7 |

**Acceptance criteria:**

- [x] 具名用例 `import_repo_incremental_updates` 通过。
- [x] 具名用例 `import_repo_ref_cas_force_non_ff` 通过。
- [x] 具名用例 `import_repo_branch_batch_atomic_tag_independent` 通过。
- [x] 具名用例 `fu13_update_keeps_root_ref` 通过。
- [x] 具名用例 `fu13_first_attach_records_provenance` 通过。
- [x] 具名用例 `fu13_directory_collision_occupied` 通过（含失败文案为 `IMPORT_REPO_PATH_OCCUPIED:` 且不含 `cannot attach leaf` / `Failed { id`）。
- [x] 具名用例 `fu13_legacy_mount_backfilled` 通过。
- [x] `docs/errors.md` 登记 `IMPORT_REPO_PATH_OCCUPIED`。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 import_repo_`（`(new)`：`import_repo_incremental_updates`——第二次 ff 推送后 `ls-remote` 为新 tip、新 clone 为 v2，之后新增分支后 `ls-remote` 列出两个分支；`import_repo_ref_cas_force_non_ff`——`--force` 非 ff 被接受；`import_repo_branch_batch_atomic_tag_independent`——同一 push 两分支（其一陈旧）+ 一个 tag → 两分支均 `ng` 且不前进、tag 成功；`import_repo_repeated_transition_applies`——A→B、强推回 A、再 A→B 后 main 为 B，分支创建 / 删除 / 以同一 commit 重建后存在）
- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::service::push_queue_service::tests::fu13_'`（`(new)`：更新推送 `main@/` 不变；首次挂载同事务写来源记录、注入失败时来源记录与挂载一并回滚；`import_dir` 下预置普通目录（非只含 `.gitkeep`）的首推返回 `IMPORT_REPO_PATH_OCCUPIED` 且根树不变；只含 `.gitkeep` 且仓库已有分支 ref 的存量叶子被接受并回填来源记录；`fu13_directory_collision_occupied` 的失败文案以 `IMPORT_REPO_PATH_OCCUPIED:` 开头且不含 `cannot attach leaf` / `Failed { id`，文件叶子同样 `OCCUPIED`；有分支但无来源记录的普通目录 `OCCUPIED`；嵌套子仓挂载后父仓库更新仍落地且 ref 前进；只含删除的分支批经 B3、`root_cas_writes=0`，不经归属判定（无来源记录的目录叶子同样可删））
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::import_repo::tests::fu13_'`（`(new)`：同一组分支命令在 ref 移走后再次推送时不被 Done 重放吞掉、真正的重试不新增行；`attach_refusal` 把占用 / 陈旧文本还原为类型化错误，其余为不含 Debug 的通用句）
- [x] `rg -n "IMPORT_REPO_PATH_OCCUPIED" docs/errors.md`（锚点定位用，非判据）+ 人工核对登记内容
- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::storage::audit_storage::tests::log_audit_in_txn_rolls_back'`（`(new)`）
- [x] 手工证据（sanitized）：Libra（本机 0.23.58）对同一 ImportRepo 第二次推送并 clone

**Dependencies:** FU-12（CAS 必须先上线）。

**Deliverables:** N/A

**Implementation write set:** `src/jupiter/service/push_queue_service.rs`；`src/ceres/pack/import_repo.rs`；`src/ceres/api_service/tree_ops.rs`（存在性与 `.gitkeep`-only 判定）；`src/jupiter/storage/audit_storage.rs`（`log_audit_in_txn`、来源记录查询）；`src/jupiter/storage/git_db_storage.rs`（仅新增按名查询 ref 的 `get_refs_by_names`，供重放核对）；`tests/integration_git_cli.rs`；`docs/errors.md`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同 Implementation write set

**Docs and compatibility impact:** 存量 ImportRepo 无需迁移（首次后续推送惰性回填来源记录）；用户文档由 FU-22。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A（无 schema 变更；来源记录复用 `audit_logs`）

**Security and privacy:** 普通目录不被误认为挂载；来源记录不含凭据。

**Performance budget:** 更新推送少一次树重写与根 CAS；多一次按 `idx_audit_logs_target` 的来源记录查询。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=已挂载 ImportRepo 的后续推送; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=8/8; VER=7/8; landing=4; prod-files=5; scope=M; deps=FU-12; writeset=序列化于 FU-12; release=independent; split-from=FU-07（R1）; exception=N/A`

### Task FU-14: ImportRepo 清理台账（entity + 迁移 + storage）（#27）

**Task type:** `migration`

**Lifecycle / Acceptance:** `done` / `complete`（A/B：Verification 三条命令通过——`jupiter::migration::` 44 例（含 `import_repo_cleanups_migration_applies`）、`cleanup_ledger_` 4 例；`git_db_storage` 模块回归 16 例；fmt、clippy rc=0，`cargo build` 0 警告；反向验证五组（R2 树上重跑）：A 索引改为 `(path, state)` → 计划改走主键扫描、`uses_index` 失败；B 页大小改为 17 → 同用例失败；C 去掉 `state='detached'` 条件 → 幂等用例失败；D 插入改走连接池而非调用方事务 → 回滚用例失败；E 恢复先查后删的 `down` → 迁移用例竞态断言失败；ER-05 R1 Codex FAIL（3×P1 + 1×P2）+ Claude PASS（3×P2）已修订；R2 Codex PASS + Claude PASS（均无发现）；C 组在 bump 后的 `0.40.3` 树上全绿：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行、1919 通过且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` `__eh_frame` 链接器提示；提交 `d613ab8`、tag `v0.40.3` 与 GitHub Release 已发布；D 组 `docker.yml` run `36002157603` 的 `docker` job 对 `d613ab8` 为 success）

**Description:** 按 ADR-FU-09 第 6 条新增表 `import_repo_cleanups` 与索引 `(path, state, id)`、callisto entity、`src/jupiter/migration/` 迁移及 `migrations()` 注册，并在 `git_db_storage.rs` 提供事务内插入、按 `WHERE path=$1 AND state='detached' ORDER BY id ASC LIMIT 16` 分页查询、`detached → swept` 条件更新三个原语。本卡无调用方，发布后休眠。唯一行为轴是「清理台账的持久形态」。

**Out of scope:**

- detach 写入台账 —— 由 FU-16 承接。
- 清扫与续做使用台账 —— 由 FU-17 承接。
- 历史清理的回填 —— 永久非目标（本计划之前不存在清理）。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 迁移注册列表尾 | `src/jupiter/migration/mod.rs:138,155-262` |
| `audit_logs` 无 JSON 字段索引 | `src/jupiter/migration/m20260306_121829_create_bots_related_table.rs:350-370` |
| entity 目录 | `src/callisto/mod.rs` |

**Acceptance criteria:**

- [x] 新迁移登记在 `migrations()` 列表末尾。
- [x] 具名用例 `import_repo_cleanups_migration_applies` 通过（`apply_migrations(&db, true)` 后表与 `(path, state, id)` 索引存在）。
- [x] 具名用例 `cleanup_ledger_insert_in_txn_rolls_back` 通过。
- [x] 具名用例 `cleanup_ledger_pending_by_path_uses_index` 通过（在 ≥ 1000 条同路径 `detached` 行上 `EXPLAIN` 显示 Index Scan on `(path, state, id)` 且计划中无 Sort 节点）。
- [x] 具名用例 `cleanup_ledger_mark_swept_idempotent` 通过。
- [x] 具名用例 `cleanup_ledger_primary_key_is_cleanup_id` 通过。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::migration::'`（迁移注册与 `apply_migrations` 回归）
- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::storage::git_db_storage::tests::cleanup_ledger_'`（`(new)` 前缀组：事务内插入回滚、按索引查询、条件更新幂等、主键）
- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::migration::tests::import_repo_cleanups_migration_applies'`（`(new)`）

**Dependencies:** FU-13（串行发布链）。

**Deliverables:** N/A

**Implementation write set:** `src/callisto/import_repo_cleanups.rs`（新）；`src/callisto/mod.rs`；`src/jupiter/migration/m20260923_000100_import_repo_cleanups.rs`（新）；`src/jupiter/migration/mod.rs`；`src/jupiter/storage/git_db_storage.rs`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同 Implementation write set

**Docs and compatibility impact:** 新表（运维说明随 FU-22）；无存量数据变化。

**Rollback mode:** `forward-only`

**Migration and rollback:** sea-orm 迁移 up 建表与索引；down 删除表（仅在本表无行时安全）。运行期没有 `migrate down` 入口，按 forward-only 处理：若需撤回，发布前滚版本停止写入，表保留。数据不变量：每个 `id` 对应一次 detach；`state` 只从 `detached` 单向变为 `swept`。恢复验证：`apply_migrations` 用例 + 台账原语用例。用户影响：无。

**Security and privacy:** 台账只含路径、`repo_id`、请求者名与计数（GC-FU-05）。

**Performance budget:** 续做查询按 `(path, state, id)` 索引顺序读取至多 16 行，与台账累计规模无关。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=migration; axis=清理台账的持久形态; recovery=前滚版本停止写入（表保留）; complete=yes; self-contained=yes; AC=6/8; VER=3/8; landing=3; prod-files=5; scope=M; deps=FU-13; writeset=序列化于 FU-13; release=independent; split-from=FU-17（R10）; exception=N/A`

### Task FU-15: ImportRepo 存量别名路径规范化迁移（#26 / #27 兼容）

**Task type:** `migration`

**Lifecycle / Acceptance:** `done` / `complete`（A/B：Verification 前三条命令通过——`jupiter::migration::` 48 例、`import_repo_alias_` 4 例、`integration_git_cli` 的 `import_repo_alias_row_served_after_migration`（重启前删除来源记录；重启时迁移日志 `rewritten=1 collisions=0`；同一 `repo_id` 的 clone / push / fetch 与别名 URL `ls-remote`、无第二行、推送后在规范路径回填来源记录）；第四条 `rg` 命中 `docs/deploy-trunk.md` §9.2，人工核对迁移、计数含义与分裂身份处理；fmt、clippy rc=0，`cargo build` 0 警告；反向验证五组（R2 树上重跑）：A 改写语句不命中行 → 4 个单测与进程级用例失败；B 去掉占用检查 → 撞 `uniq_ir_path` 唯一约束、冲突用例失败；C 去掉加锁 → 冲突用例的并发断言失败；D WARN 加入别名拼写 → 冲突用例失败；E 无法规范化即中止 → 冲突用例失败；ER-05 R1 Codex FAIL（2×P1 + 1×P2）+ Claude FAIL（1×P1 + 6×P2）已修订；R2 Codex PASS + Claude FAIL（1×P1：WARN 捕获混入 sqlx 事件；3×P2）已修订——只统计本迁移 target 的事件（冲突用例连续 5 次通过，反向验证 D 在新树上仍失败）；R3 Codex PASS + Claude PASS（负载下冲突用例 30/30，1×P2 措辞已落实）；C 组在 bump 后的 `0.40.4` 树上全绿——该树即本卡提交的树：工作区另有一个会话未提交的 `git_db_storage.rs` 改动（不属本卡、不入提交），C 组因此在去掉该改动（恢复为 HEAD）的干净副本中运行：fmt、clippy 0 警告、`cargo test --all --no-fail-fast` 18 个 target 全部运行、1924 通过且失败集恰为 6 个基线环境用例（原因同类）、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 macOS `ld` `__eh_frame` 链接器提示；提交 `eb9dafd`、tag `v0.40.4` 与 GitHub Release 已发布；D 组 `docker.yml` run `36019013309` 的 `docker` job 对 `eb9dafd` 为 success）

**Description:** 在任何「按规范路径精确查找」的清理面上线之前，一次性把**全部** `git_repo` 行中 `repo_path != canonicalize_mono_ref_path(repo_path)` 的旧别名值（重复斜杠、尾斜杠等 TP-08 之前写入的形式）改写为规范路径并保持 `repo_id`——与配置无关：SeaORM 迁移拿不到 `monorepo.import_dir`，而 `git_repo` 表只由 ImportRepo 协议分派写入（`protocol/mod.rs:275`；`create_repo_and_save_ref` 无调用者），因此按行本身判定即可覆盖任意（含非默认）`import_dir`；若规范路径已被另一行占用（身份已分裂），不改写别名行、记录告警并在迁移输出中计数（该别名行此后不被 Git 请求服务；以 `/` 或 `/.` 结尾的别名仍被 Web / API 的最长前缀查找命中；清理按规范路径精确查找仓库、不删除这类别名行，子仓检查也不把它们算作子仓（ADR-FU-10 第 3 条）——登记 `DEFER-FU-10`，FU-15 R1 / R3）；无法规范化的路径同样保留并另计 `invalid`。唯一行为轴是「存量 ImportRepo 路径标识的规范化」。

**Out of scope:**

- 协议层 TP-08 规范化与别名回退/自愈 —— 保持不变（永久兼容路径）。
- 合并已分裂的两个身份 —— 尚未排期，重启条件：出现身份分裂的用户报告（`DEFER-FU-10`）。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| TP-08 规范化 + 旧别名行回退并自愈 | `src/ceres/protocol/mod.rs:236-262`；`src/jupiter/storage/git_db_storage.rs:428-445` |
| 规范化函数 | `src/common/utils.rs:160-190` `canonicalize_mono_ref_path` |
| `git_repo` 唯一插入点是 ImportRepo 协议分派 | `src/ceres/protocol/mod.rs:275`；`src/jupiter/storage/git_db_storage.rs:34-55`（无调用者）、`:428-445`（TP-08 改名） |
| 迁移只拿到数据库连接，无配置 | `src/jupiter/migration/runner.rs`；`src/jupiter/migration/mod.rs:155` |

**Acceptance criteria:**

- [x] 新迁移登记在 `migrations()` 列表末尾（位于 FU-14 迁移之后）。
- [x] 具名用例 `import_repo_alias_rows_canonicalized` 通过（别名行改写为规范路径且 `repo_id` 不变）。
- [x] 具名用例 `import_repo_alias_collision_left_untouched` 通过（规范路径已占用时别名行不变、告警计数为 1）。
- [x] 具名用例 `import_repo_alias_migration_idempotent` 通过（重复执行无变化）。
- [x] 具名用例 `import_repo_alias_row_served_after_migration` 通过（迁移后按规范 URL clone / fetch / push 使用同一 `repo_id`）。
- [x] 具名用例 `import_repo_alias_non_default_import_dir` 通过（`import_dir="/vendor"` 下的别名行被改写，按规范路径的精确查找 `find_git_repo_exact_match` 命中原 `repo_id`）。
- [x] `docs/deploy-trunk.md` 登记该迁移、告警含义与分裂身份的处理建议。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::migration::'`（迁移注册与 `apply_migrations` 回归）
- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::migration::tests::import_repo_alias_'`（`(new)` 前缀组：改写、冲突保留与告警计数、幂等、非默认 `import_dir`（`/vendor`）别名行改写后精确查找命中原 `repo_id`）
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 import_repo_alias_row_served_after_migration`（`(new)`：预置别名 `repo_path` 与 ref 的仓库，迁移后以规范 URL clone、fetch、push 均命中原 `repo_id`）
- [x] `rg -n "import_repo_alias" docs/deploy-trunk.md`（锚点定位用，非判据）+ 人工核对说明

**Dependencies:** FU-14（迁移顺序）。

**Deliverables:** N/A

**Implementation write set:** `src/jupiter/migration/m20260923_000200_canonicalize_import_repo_paths.rs`（新）；`src/jupiter/migration/mod.rs`；`tests/integration_git_cli.rs`；`docs/deploy-trunk.md`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同 Implementation write set

**Docs and compatibility impact:** 存量别名行改写为规范路径（`repo_id` 不变）；冲突行保留并告警。

**Rollback mode:** `forward-only`

**Migration and rollback:** up 在单事务内逐行改写（处理全部 `repo_path != canonical` 的 `git_repo` 行，与配置无关）；down 为 no-op（原别名形式不可逆且无意义），运行期无 `migrate down` 入口。数据不变量：改写前后 `repo_id` 与其 `import_refs` / 对象行不变；每个规范路径至多一行被改写到它。恢复验证：三个迁移用例 + 进程级用例。用户影响：旧别名 URL 仍由 TP-08 规范化后命中同一仓库。

**Security and privacy:** 迁移日志只记录 `repo_id` 与规范路径，不含凭据。

**Performance budget:** 一次性 O(`git_repo` 行数)（该表只含 ImportRepo，规模为仓库数而非对象数），逐行比较规范化结果，只改写需要的行。

**Estimated scope:** `S`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=migration; axis=存量 ImportRepo 路径标识的规范化; recovery=前滚版本（改写不可逆，TP-08 兼容路径保留）; complete=yes; self-contained=yes; AC=7/8; VER=5/8; landing=1; prod-files=2; scope=S; deps=FU-14; writeset=序列化于 FU-14; release=independent; split-from=FU-18（R18）; exception=N/A`

### Task FU-16: ImportRepo 原子摘除 B3 原语（#27）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B：Verification 四条命令通过——`fu16_` 10 例、`attach_payload_default_op`、`integration_git_cli` 的 `import_repo_detach_then_clone_404`（钩子 detach 后 upload-pack 为 404 `Repository not found.`、clone 失败）；`tree_ops::tests::fu16_remove_import_leaf_prunes_below_the_import_root`；ImportRepo / 推送队列 / 审计 / `git_db` / `tree_ops` / `import_api_service` 库回归 184 例；fmt、clippy rc=0，`cargo build` 0 警告；反向验证五组：A 去掉自身行 `FOR UPDATE` → 顺序用例失败；B 把 `P/` 别名算作子仓 → 顺序用例失败；C 去掉归属判定 → 无记录用例失败（普通目录被删）；D 审计行写在事务外 → 注入用例失败；E `import_dir` 本身像普通目录一样剪除 → `tree_ops` 单测失败（服务级用例因 `init_monorepo` 在 `import_dir` 留有 `.gitkeep` 观察不到）；ER-05 R1 Claude PASS（5×P2）已落实：`fu16_` 8 例（新增重放核对与 `.gitkeep` 服务级用例）；R1 Codex FAIL（3×P1 + 2×P2）已处置——分支存在改为有界 EXISTS（attach 存量规则同步）、`.gitkeep` 的 `mega_blob` 行改入事务（注入用例加该形态）、`lib.rs` 注释归位、操作 id 固定向量；单测 schema 不清理属全套件 helper 既有约定，不采纳按卡守卫（`DEFER-FU-25`，另起任务）；R2 Codex FAIL（2×P1 + 1×P2）已处置——清理 id 以台账行解析（`Option<i64>`，反向验证 K：直接交出重放 id 即失败）、只有 `import_dir` 严格后代才移树（反向验证 J：恢复父目录回退即失败）；R3 Claude PASS（1×P2 已落实）+ Codex FAIL（2×P1：要求新增索引——不采纳，GC-10 规模 + `fu16_lookups_bounded_at_scale`，`DEFER-FU-27`）；R4 Codex FAIL（1×P1：`import_refs` 删除以该仓库 ref 数为界而非 O(1)——保留 ADR-FU-09 第 2 条的事务内删除，订正预算措辞并在规模用例中以 EXPLAIN 断言删除经 `repo_id` 索引、1000 个 tag 的仓库一轮 detach 后无残留，`DEFER-FU-28`；1×P2：根 commit 消息断言已加）；`fu16_` 10 例；R5 Codex PASS（2×P2 已落实）+ Claude PASS（2×P2 已落实：规模用例的 EXPLAIN 断言不再依赖 `enable_seqscan = off`）；C 组在 bump 后 `0.40.5` 的干净副本（HEAD + 本卡 10 个文件；工作区另有其它会话未提交的 13 个路径，均恢复为 HEAD）上执行：fmt、clippy 0 警告、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 `ld` `__eh_frame` 提示；全量测试在其它会话并发跑 mega2 / libra 测试的负载下共跑四次（18 个 target 全部运行）：①1935 通过，6 基线 + `tp17_twenty_concurrent…`（等待预算）+ `path_provision_openapi`（临时端口）；②1936 通过、lib 阶段 1753 全绿，6 基线 + `delete_entry_file_success`（种子 clone 连接被重置）；③作废——`git-cli` 容器被另一会话在运行中按默认挂载重建，git / ssh / lfs 用例整批 `chdir /work/case-…` 失败；④1936 通过、lib 阶段 1753 全绿（557 秒），6 基线 + `move_entry_reject_into_own_subtree`（同一连接重置签名）。每个额外失败单独复跑 3/3 通过，`integration_api_write_trunk` 整 target 62/62 两次通过，失败点均在被测行为之前；按「并发会话例外」口径接受。提交 `44e1b09`、tag `v0.40.5` 与 GitHub Release 已发布；推送时本地 main 上已有其它会话的两个提交（`22299f1` `find_git_repo_like_path` 绑定参数修复、`ff51c42` 文档）随之进入 origin，tag 树因此含它们——已在 tag 树 `44e1b09` 的干净副本上补跑 C 组：fmt、clippy 0 警告、`cargo build` 0 警告、`cargo build --tests` 仅 `ld` 提示、全量 18 个 target 1938 通过、失败集 = 6 基线 + `tp17`（`push wait abandoned`，单独复跑 3/3）；D 组 `docker.yml` run `36061915317` 的 `docker` job 对 `44e1b09` 为 success）

**Description:** 按 ADR-FU-09 第 1–3 条实现 `AttachOp` 枚举、`detach_operation_id`、B3 detach 分支（单事务：存活与子仓再检查、按挂载来源记录移叶子并剪空父目录、删 `import_refs` 与 `git_repo`、事务内审计（复用 FU-13 的 `log_audit_in_txn`）并插入 `state=detached` 清理台账行（FU-14 原语））。子仓再检查按 ADR-FU-10 第 3 条排除规范形式等于 P 本身的行（FU-15 冲突保留的别名行，如 `P/`；`fu16_` 用例组须含「`P/` 兄弟行不是子仓」）。本卡无外部入口，发布后休眠。唯一行为轴是「ImportRepo 叶子的原子摘除」。

**Out of scope:**

- 清扫、续做、服务入口 —— 由 FU-17 承接。
- 存活栅栏 —— 由 FU-18 承接。
- HTTP 入口 —— 由 FU-20 承接。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| attach 事务骨架 | `src/jupiter/service/push_queue_service.rs:1295-1664` |
| 队列去重与终态重试复制 payload | `src/jupiter/storage/push_queue_storage.rs:150-213` |
| `attach_operation_id` 无域前缀 | `push_queue_service.rs:47-53` |
| `log_audit` 自有连接 | `src/jupiter/storage/audit_storage.rs:33-55` |

**Acceptance criteria:**

- [x] 具名用例 `fu16_detach_removes_leaf_and_rows` 通过。
- [x] 具名用例 `fu16_detach_fault_injection_rolls_back` 通过。
- [x] 具名用例 `fu16_detach_writes_audit_in_txn` 通过。
- [x] 具名用例 `import_repo_detach_then_clone_404` 通过。
- [x] 具名用例 `fu16_detach_without_provenance_keeps_tree` 通过。
- [x] 具名用例 `fu16_detach_operation_identity` 通过。
- [x] 具名用例 `fu16_detach_child_orderings` 通过。
- [x] `docs/refactoring/trunk-push.md` 登记 attach payload `op` 与 detach 语义。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::service::push_queue_service::tests::fu16_'`（`(new)` 前缀组：规范形式等于 P 的别名行（`P/`）不算子仓；根树无叶子、空父目录剪除、`import_dir` 为空时保留 `.gitkeep`；`git_repo` / `import_refs` 无该 `repo_id`；提交前注入失败时树、行、审计不变且队列行 `Failed`；同事务一行 `phase:"detached"` 审计（`actor_type=human`、`actor_id=0`、`cleanup_id`=队列行 id、无 token）与一行 `state=detached` 台账；`fu16_detach_operation_identity`：detach id 与同仓库 attach id 不同且同一 detach 重试重放 `Done`；`fu16_detach_without_provenance_keeps_tree`：无挂载来源记录且不满足存量规则的仓库被 detach 时根树不变、只删行；`fu16_detach_child_orderings`：detach 先 `FOR UPDATE` 锁自身行再查子仓；已注册子仓（无论其 attach 是否已执行）→ `IMPORT_REPO_HAS_CHILDREN`、父子均不变；叶子缺失的首推失败仓库可被 detach）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::api_service::tree_ops::tests::fu16_'`（`(new)`：`remove_import_leaf` 的剪枝与 `import_dir` 补 `.gitkeep` 规则，纯树运算）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::import_repo::tests::attach_payload_default_op'`（`(new)`，属 `fu16_detach_operation_identity` 规格：不含 `op` 的存量 payload 反序列化为 `AttachOp::Attach`）
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 import_repo_detach_then_clone_404`（`(new)`：经服务层测试钩子触发 detach 后 clone 返回 404 `Repository not found.`）

**Dependencies:** FU-15（存量路径已规范化，精确查找可靠；FU-14 台账原语与 FU-13 的 `log_audit_in_txn` 经链已先发布）。

**Deliverables:** N/A

**Implementation write set:** `src/ceres/pack/import_repo.rs`；`src/jupiter/service/push_queue_service.rs`；`src/ceres/api_service/tree_ops.rs`（叶子移除原语）；`src/lib.rs`（集成测试钩子的 `#[doc(hidden)]` 再导出，FU-16 执行时补入）；`src/jupiter/storage/audit_storage.rs`（`IMPORT_REPO_REMOVE_KIND` 常量，R1 补入）；`tests/integration_git_cli.rs`；`docs/refactoring/trunk-push.md`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** `push_queue` attach payload 新增可选字段（缺省兼容）。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A（无 schema 变更）

**Security and privacy:** 审计 metadata 只含 `cleanup_id`、`path`、`repo_id`、请求者名、`phase`（GC-FU-05）。

**Performance budget:** 锁内两条按 `repo_id` 索引的删除语句（`import_refs` 删除的行数 = 该仓库的分支与 tag 数，`git_repo` 1 行；FU-16 R4 订正原「O(1) 行删除」措辞：常数条语句，行数以该仓库自身的 ref 数为界，不随仓库数或对象数增长）+ O(depth) 树重写 + 一次根 CAS；无按对象删除。单仓 ref 数大到锁内删除可测时改由清扫分批删除（`DEFER-FU-28`）。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=ImportRepo 叶子的原子摘除; recovery=前滚补丁版本（原语无入口即休眠）; complete=yes; self-contained=yes; AC=8/8; VER=4/8; landing=3; prod-files=5; scope=M; deps=FU-15; writeset=序列化于 FU-15; release=independent; split-from=FU-08（R1）; exception=N/A`

### Task FU-17: ImportRepo 元数据清扫、续做与清理服务入口（#27）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B：Verification 四条命令通过——`git_db_storage::tests::fu17_` 4 例、`import_repo::tests::fu17_` 14 例、`fu16_` 10 例、`cleanup_ledger_` 4 例；ImportRepo / 推送队列 / 审计 / `git_db` / `tree_ops` / `import_api_service` / 错误域库回归 225 例（R5 树重跑），`integration_git_cli` 的 `import_repo_` 6 例（R5 树重跑；detach 钩子契约不变）；fmt、clippy rc=0，`cargo build` 0 警告；反向验证六组：A 表完成改为「本批少于 1000 行」而非新快照探测 → 语句数断言失败；B 去掉入队前的无写子仓预检 → `has_children_no_writes` 的队列行数断言失败；C 续做不校验台账行的路径 → 外路径 id 用例失败；D 整页后不再读一次 → 17 条待续返回 `absent`、分页用例失败；E `rows_deleted` 不跨请求累计 → 预算用例终值失败；F `phase:"swept"` 审计的 `requester` 取 detach 者 → 崩溃续做用例失败；ER-05 R1 Codex FAIL（1×P1 + 2×P2）已修订——OverBudget 前重读台账、共享 blob 用例经 Monorepo 与兄弟数据流核实、`latest_cleanup_for` 索引倒序无排序；ER-05 R1 Claude（工作流：5 维查找、每条发现 3 名反驳者、裁决 agent 复跑卡片命令）FAIL（1×P1 + 11×P2）已修订——P1 表完成探测改为 `repo_id` 前导唯一索引上的一步 top-1 索引读（`SELECT <键> … ORDER BY <键> LIMIT 1`），`fu17_sweep_bounded_and_complete` 以 EXPLAIN 钉住自定义计划与 `PREPARE` + `SET LOCAL plan_cache_mode = force_generic_plan` 的 generic 计划都走 `uniq_b_git_repo` 且无顺序扫描；P2 新增 `fu17_sweep_survives_a_blocked_batch`、`fu17_fresh_detach_resumes_older_rows`、`fu17_swept_by_another_request_writes_no_second_audit`、`fu17_budget_exhausted_between_rows`、`fu17_b3_refusal_surfaces_typed_error`，既有用例补 `git_tag` 7 行（语句数 6）、预算 0 零语句与混合畸形 JSON；`rows_deleted` 仅为证据的语义写入 `record_cleanup_progress` / `sweep_ledger_row` 注释；计划性能预算段、ADR-FU-09 第 6 条括注与故障恢复表措辞订正；反向验证 G–L：G 探测改回 `EXISTS` → EXPLAIN 索引断言失败；H 表完成改为「本批少于 1000 行」→ 受阻批用例以 `complete: true, git_blob: 0` 失败；I 去掉 OverBudget 前的重读 → `pending_rechecks_ledger` 失败；J 16 条上限不计本次 detach → `fresh_detach_resumes_older_rows` 失败；K 每台账行独立预算 → `budget_exhausted_between_rows` 失败；L `mark_cleanup_swept` 落败仍写审计 → `no_second_audit` 失败；ER-05 R2 Codex PASS（1×P2）+ Claude（工作流）FAIL（1×P1 + R1 一条未闭环 + 5×P2）已修订——P1 分批子查询加 `ORDER BY <索引第二列>`，对 91% 占比的诱饵仓库钉住 generic 计划走 `uniq_b_git_repo`、自定义计划无顺序扫描无排序；未闭环项（Codex R1 P2 与 Codex R2 P2 同一条）`latest_cleanup_for`：一个 `repo_id` 至多一条台账行，改为 detached 先、命中即返回，同路径 1000 `swept` + 200 `detached` 历史上取最旧行仍正确且 generic 计划为 `(path, state, id)` 索引范围读（至多对该段做 top-1 排序）、不扫台账，不加索引的理由与规模写入本卡与 `DEFER-FU-27`；P2 续做只处理该行（同路径更早行在两次续做后仍 `detached`、无审计，之后的路径请求才续做它）、本次 detach 与更早行共用 100 批预算（`fu17_budget_shared_with_older_rows`：90 + 10 批，第 11 行留待下次）、探测钉住限定为 `git_blob` 且断言 `Scan using uniq_b_git_repo` 与无 `Sort`、受阻批用例语句数恰为 3、回归计数在 R3 树重跑；反向验证 M–O 与 H 重跑：M 续做分支也续做更早行 → 续做用例失败；N 更早行取新预算 → 共用预算用例失败；O 子查询去掉 `ORDER BY` → 诱饵 generic 计划的 `uniq_b_git_repo` 断言失败（自定义计划断言未到达）；H 同前；ER-05 R3 Codex PASS（1×P2）+ Claude（工作流）FAIL（R2 一条未闭环 + 8×P2，其中一条 2/3 维持 P2、1 名反驳者判 P1）已修订——实质项：R3 的 `ORDER BY` 让 `git_commit` / `git_tree` 在小估计的 generic 计划下可走单列 `repo_id` 索引 + 全量排序（每批读完整个仓库），且计划只钉住了 `git_blob`——改为每个清扫步骤在自己的短事务里 `SET LOCAL enable_seqscan = off` 与 `enable_bitmapscan = off`（`SWEEP_PLANNER_SETTINGS`，经 `begin_sweep_step`），探测与分批去掉 `ORDER BY`，只剩 `repo_id` 前导索引上的索引扫描；钉住时又发现小估计下外层 DELETE 会沿 `idx_ic_repo_id` 读完整个仓库再按 `id = ANY` 过滤，外层防护改为不可走索引的 `repo_id + 0 = $1`；`fu17_sweep_bounded_and_complete` 对四表 × 探测/分批 × custom/generic 在本用例 ANALYZE 之前与之后（4.5% 目标、91% 诱饵、300 个单行仓库之一）钉住计划，并在外层事务里真实清扫诱饵、以 `pg_stat_xact_user_tables` 断言零顺序扫描；R2 未闭环项新增 `fu17_detach_lost_race_falls_back_to_ledger`（另一事务删除 `git_repo` 行、B3 行锁等待后提交 → `Done` 无台账、入口从台账续做并 `absent`）；`latest_cleanup_for` 注释与性能预算写明至多两次范围读、custom 计划可顺序扫描台账；Codex P2（整页 64 条别名保守视为有子仓）不采纳，理由见变更记录；反向验证 P–U 与 H 重跑：P 设置去掉 `enable_seqscan` → `git_commit` 自定义计划外层 `Seq Scan` 失败；Q 去掉 `enable_bitmapscan` → `git_commit` 自定义计划 `Bitmap Heap Scan` 失败；R 外层防护改回可走索引的 `repo_id = $1` → 外层 `idx_ic_repo_id` + 过滤失败；S 在设置下给 `git_blob` 子查询加回 `ORDER BY blob_id` → R4 存活（R4 的解释有误：用例从未访问「三个仓库时 ANALYZE 之后」的状态，该状态下 S 计划为 `idx_b_git_id` + `repo_id` 过滤）；T 清扫步骤绕过 `begin_sweep_step` → `pg_stat_xact_user_tables` 顺序扫描断言失败；U 落空分支直接返回 `absent`、不读台账 → `lost_race` 用例失败；H 同前；ER-05 R4 Codex PASS（2×P2）+ Claude（工作流）FAIL（R3 两条未闭环 + 8×P2）已修订——`sweep_import_repo_objects` 只收连接池，零顺序扫描断言改为按生产方式（一个连接的池、每步一个事务、`pg_stat_force_next_flush()` 后读 `pg_stat_user_tables` 增量），计划钉住改为三次统计快照并要求 `Index Cond: (repo_id = …)`、探测无 `Filter`，受阻批的另一清扫者在同一计划器设置下，两处锁等待轮询先 `pg_stat_clear_snapshot()`，台账回退与 `DEFER-FU-27` 措辞、入口注释、R3 记账订正（详见变更记录）；R5 反向验证九组全部失败：P（`git_commit` 外层 `Seq Scan`）、Q（`Bitmap Heap Scan`）、R（外层 `idx_ic_repo_id` + 过滤）、S（三仓库 ANALYZE 后 `git_blob` 分批为 `idx_b_git_id` + 过滤）、T（全部步骤无设置 → bitmap）、T2（批次在步骤事务之外、探测仍在内 → 顺序扫描增量断言失败）、W（`git_blob` 探测写成 `repo_id + 0 = $1` → 同一索引的全量 `Index Only Scan` + `Filter`，`Index Cond` 断言失败）、U、H；回归 225 例、`integration_git_cli` 的 `import_repo_` 6 例在 R5 树重跑通过；ER-05 R5 Codex PASS（无发现）+ Claude（工作流）PASS（6×P2，R4 全部闭环），P2 已落实——设置随步骤结束的断言（反向验证 X：`SET LOCAL` 改为会话级 `SET` → 断言失败）、单连接池改为复用测试连接池的 sqlx 连接选项（T2 在其上重跑仍失败）、台账回退的来源（仅未 detach 的轮次）与最坏情形（约 30% 起、至多两次全台账扫描）措辞、统计刷新注释、R4 变更行范围列；C 组在 bump 后的 `0.40.6` 树的干净副本上（HEAD + 本卡 4 个文件 + 版本号；其它会话的未提交文件按 HEAD 还原）：fmt、clippy 0 警告、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 `ld` `__eh_frame` 提示；`cargo test --all --no-fail-fast` 18 个 target 全部运行，lib 阶段 1773 通过 / 0 失败 / 1 忽略，失败集为 6 个基线环境用例 + `integration_git_cli_trunk_requester_token_name`（种子 clone 在临时端口上 `Connection reset by peer`，运行期间另一会话的重负载使 15 分钟平均负载达 56）；该用例单独复跑 3/3 通过、`integration_git_cli` 整 target 44/44 通过，失败点在被测行为之前，按「并发会话例外」口径接受；干净副本的 HEAD 测试助手不删 schema，本次运行留下的 786 个 `mega2_test_75412_*`（进程已退出）按名删除。提交 `4f2459b`、tag `v0.40.6` 与 GitHub Release 已发布；D 组 `docker.yml` run `36103769857` 的 `docker` job 对 `4f2459b` 为 success）

**Description:** 按 ADR-FU-09 第 4、6、7 条与 ADR-FU-10 第 3 条实现锁外分批清扫、台账 `detached → swept` 与 `phase:"swept"` 审计、按台账 `(path, state, id)` 索引分页续做（每请求至多 16 条台账行、100 批清扫）、子仓检查，以及服务入口 `remove_import_repo(canonical_path, requester, continuation: Option<cleanup_id>) -> Removed | Pending | Absent`（新操作与续做按 ADR-FU-10 第 5 条区分；本卡无外部入口）。FU-16 的 `resolve_cleanup_id`（`import_repo.rs`）暂以 entity 内联读台账，本卡拥有台账读侧时须把它收进 `GitDbStorage` 原语（FU-16 R3 登记）。唯一行为轴是「ImportRepo 清理的完成与续做」。

**Out of scope:**

- 存活栅栏与陈旧会话回收 —— 由 FU-18 承接。
- HTTP 入口与路径校验、鉴权 —— 由 FU-20 承接。
- 对象存储字节回收 —— `DEFER-FU-01`；后台续做 —— `DEFER-FU-06`。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 无删除工具 | `src/jupiter/storage/git_db_storage.rs` |
| `repo_id` 前导索引 | `src/jupiter/migration/m20250314_025943_init.rs:384,435,486`（commit / tree / blob）；`git_tag` 的 `(repo_id, tag_id)` 来自 `src/jupiter/migration/m20260921_000100_fix_git_tag_unique.rs:31-40` |
| `escape_like` | `src/common/utils.rs:219-231` |
| blob 共享命名空间 | `src/jupiter/service/git_service.rs:59-66` |

**Acceptance criteria:**

- [x] 具名用例 `fu17_sweep_bounded_and_complete` 通过。
- [x] 具名用例 `fu17_swept_ledger_and_audit` 通过。
- [x] 具名用例 `fu17_remove_resumes_after_crash` 通过。
- [x] 具名用例 `fu17_continuation_never_touches_reimport` 通过（R1 待续期间同路径重新导入 R2，以 R1 的 `cleanup_id` 续做只清扫 R1，R2 仍可 clone；未知 `cleanup_id` → `IMPORT_REPO_CLEANUP_NOT_FOUND`）。
- [x] 具名用例 `fu17_remove_has_children_no_writes` 通过。
- [x] 具名用例 `fu17_remove_keeps_shared_blob_and_sibling` 通过。
- [x] 具名用例 `fu17_resume_budget_paginates` 通过。
- [x] 具名用例 `fu17_sweep_budget_pending` 通过。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::storage::git_db_storage::tests::fu17_'`（`(new)` 前缀组：`fu17_sweep_bounded_and_complete`——清扫后四表（含 `git_tag` 7 行）无该 `repo_id` 行且每条语句 ≤ 1000 行；四张表的探测与分批在清扫步骤的事务里（`SWEEP_PLANNER_SETTINGS`）以 `PREPARE` + `plan_cache_mode = force_custom_plan` / `force_generic_plan` 两种计划 EXPLAIN，取三次统计快照（本用例 ANALYZE 之前——自动 analyze 可能已运行；三个仓库时 ANALYZE 之后：`git_blob` 中约 4.5% 的目标与约 90% 的诱饵；再加 300 个单行仓库后 ANALYZE：目标、诱饵与单行仓库之一），均为 `repo_id` 前导索引上以 `Index Cond: (repo_id = …)` 检索的索引扫描（探测无 `Filter`；分批外层为主键 `Index Cond: (id = ANY …)`），无顺序扫描、无 bitmap、无排序；按生产方式（只有一个连接的池、每步一个事务）真实清扫诱饵 3 批，以 `pg_stat_force_next_flush()` 刷新后 `pg_stat_user_tables` 四表顺序扫描增量为 0；预算 0 零语句、预算截断与空表零语句；`fu17_sweep_survives_a_blocked_batch`——另一连接在同一计划器设置下持一批未提交删除，清扫等待（`pg_blocking_pids` 观察到）后提交，清扫仍完成、总数 1500 且语句数恰为 3；`fu17_child_query_escapes_and_excludes_aliases`——子仓查询对 `%`、`_`、兄弟前缀 `/a` vs `/ab` 正确转义，且按 ADR-FU-10 第 3 条不把规范形式等于目标的别名行（`/a/`）当作子仓、整页别名视为有子仓；`fu17_ledger_reads_and_progress`——`cleanup_by_id` / `latest_cleanup_for`（一个 `repo_id` 至多一条台账行，detached 先；同路径 1000 条 `swept` + 200 条 `detached` 历史上取最旧一条仍正确，generic 计划读 `idx_import_repo_cleanups_path_state_id`、不扫台账）/ `record_cleanup_progress` 只写仍为 `detached` 的行）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::import_repo::tests::fu17_'`（`(new)` 前缀组：台账 `detached → swept` 与 `phase:"swept"` 审计行一致；模拟 detach 完成、清扫未执行后同路径调用续清扫并返回 `absent`；以 R1 的 `cleanup_id` 续做时同路径重新导入的 R2 不受影响，未知 `cleanup_id` 返回 `IMPORT_REPO_CLEANUP_NOT_FOUND`；续做只读台账、不扫描 `audit_logs`；有子仓返回 `IMPORT_REPO_HAS_CHILDREN` 且无写；共享 blob 经 Monorepo 路径仍可读、兄弟 ImportRepo 仍可 clone；同一路径 17 条待续台账行 → 首次返回 `pending` 且只处理 16 条，再次返回 `absent`；清扫超出 100 批预算 → `pending`，再次调用完成；活仓库删除后把同路径更早的待续行一并续做且 16 条上限计入本次 detach（16 条更早行留 1 条 → 再次 `absent`）；持陈旧快照、另一清扫者已标 `swept` → 不返回 `pending`；`mark_cleanup_swept` 落败不写第二条审计、胜者计数保留；预算在两台账行之间恰好耗尽 → `pending` 指向第二行且不写进度；预检后注册的子仓由 B3 拒绝并以 `IMPORT_REPO_HAS_CHILDREN` 类型化返回、无台账行、队列行 `Failed`；续做只处理该台账行：同路径更早的待续行在两次续做后仍 `detached`、无审计，之后的路径请求才续做它；本次 detach 与更早行共用 100 批预算：detach 的仓库恰好耗 90 批（87 501 blob）后 11 条更早行只续做 10 条，再次请求 `absent`。预检之后另一事务删除该仓库的 `git_repo` 行、B3 的行锁等待它（`pg_blocking_pids` 观察到）后提交 → detach 轮次 `Done` 且无台账行（`detach_import_repo` 返回 `None`），入口落到台账续做，同路径更早行被续做并返回 `absent`）
- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::service::push_queue_service::tests::fu16_'`（FU-16 回归）
- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::storage::git_db_storage::tests::cleanup_ledger_'`（FU-14 回归）

**Dependencies:** FU-16（detach 原语、审计原语）。

**Deliverables:** N/A

**Implementation write set:** `src/ceres/pack/import_repo.rs`（服务入口；收回 `resolve_cleanup_id` 的内联台账查询）；`src/jupiter/storage/git_db_storage.rs`（清扫、子仓查询、台账读原语）；`src/jupiter/service/push_queue_service.rs`（B3 再检查与 FU-16 用例改为调用 `GitDbStorage::import_repo_has_children`，ADR-FU-10 第 3 条「一个定义」；实现时补入）；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** 用户文档由 FU-22。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 子仓与仓库查询只用绑定参数（GC-FU-07）。

**Performance budget:** 每请求固定预算：≤ 16 条台账行（本次 detach 计在内）、≤ 100 批清扫语句（每批 ≤ 1000 行，故 ≤ 100 000 行）；表完成以新快照探测为空判定——探测与分批都在清扫步骤自己的短事务里执行，`SET LOCAL enable_seqscan = off` 与 `enable_bitmapscan = off` 之后 `WHERE repo_id = $1 LIMIT n` 只剩 `repo_id` 前导索引（`uniq_c_git_repo_id` / `idx_ic_repo_id`、`uniq_t_git_repo` / `idx_t_repo_id`、`uniq_b_git_repo`、`uniq_gtag_repo_tag`）上的索引扫描，读到 n 个活行（外加该仓库此前批次留下、尚未回收的死索引项）即停，与统计量无关（四表 × 探测/分批 × custom/generic × 三次统计快照以 EXPLAIN 钉住，按生产方式的真实清扫以 `pg_stat_user_tables` 零顺序扫描增量钉住）；分批外层按主键删除，`repo_id` 防护为不可走索引的 `repo_id + 0 = $1`（否则小估计下外层会沿 `repo_id` 索引读完整个仓库再过滤）；探测只读、不计入预算，每台账行探测数 ≤ 已用语句数 + 5（每请求 ≤ 100 + 5 × 16 次）；入口的无写子仓预检为 `git_repo` 上一次 `LIMIT 64` 的顺序扫描（规模 = 仓库数，`DEFER-FU-27`），活仓库请求连同 B3 再检查共两次；`resolve_cleanup_id` 的回退查询（仅对未 detach 任何东西的轮次，首次或重放皆然——如 B3 发现仓库已不在，见 `fu17_detach_lost_race_falls_back_to_ledger`，或 FU-16 之前的行；detach 过的轮次由其自身的台账行应答）至多两次（`detached` 段先读）；计划器采用 `(path, state, id)` 索引时各读该路径一个状态段、合计以两段之和为界，该段占台账相当比例时（约 30% 起）可改为顺序扫描台账——最坏两次全台账扫描（台账每次 detach 一行）（一个 `repo_id` 至多一条台账行；不加 `repo_id` 索引，`DEFER-FU-27`）；续做查询按台账 `(path, state, id)` 索引读取（`ORDER BY id LIMIT 16`，最多对该路径的待续行做 top-16 排序），与台账累计规模无关；超出预算返回 `pending` 由后续请求继续。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=ImportRepo 清理的完成与续做; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=8/8; VER=4/8; landing=2; prod-files=3; scope=M; deps=FU-16; writeset=序列化于 FU-16; release=independent; split-from=FU-08（R1）; exception=N/A`

### Task FU-18: ImportRepo receive-pack 写路径存活栅栏（#27）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B：Verification 七条通过——`push_queue_service::tests::fu18_` 4 例、`import_repo::tests::fu18_` 5 例、`import_service::tests::fu18_object_writes_fenced_after_detach`、`path_policy::tests::import_repo_leaf` 3 例、`git_db_storage::tests::fu18_child_registration_fenced_by_parent`（另 `fu18_lock_live_import_repo_holds_share_lock` 随全量运行）、`integration_git_cli` 的 `import_repo_` + `import_root_push_rejected` 7 例、storage-only 协议 smoke 两例（HTTP clone、HTTP trunk push）；fmt、clippy rc=0，`cargo build` 0 警告；ImportRepo / 推送队列 / 存储 / 协议库回归 455 通过，唯一失败 `jupiter::migration::tests::import_repo_cleanups_migration_applies` 系环境污染（见下）；反向验证十四组：R1 tag 写不取锁 → `receive_pack_writes_fenced` 与 `tag_lock_serializes` 失败；R2 `Done` 重放不做存活检查 → `receive_pack_writes_fenced` 失败；R3 B3 attach 不取锁 → `push_queue_service` 的 4 例失败；R4 `file_path` 去掉无锁预检 → `filepath_errors_not_panics` 失败（detach 后另一事务对 `git_commit` / `git_tree` 持 `ACCESS EXCLUSIVE` 锁，无预检即阻塞在对象读上、5 秒超时；R1 之前该组无此断言、R4 曾存活，见 R1 变更行）；R5 分块写不取锁 → `receive_pack_writes_fenced` 失败；R6 头 commit 改回 `unwrap` → `filepath_errors_not_panics` 失败；R7 去掉 `removed_or` → 同上失败；R8 `save_entry` 批不取锁 → `object_writes_fenced_after_detach` 与 `unpack_refusal_keeps_code` 失败；R9 unpack 拒绝包成 `Other` → `unpack_refusal_keeps_code` 失败；R10 `attach_refusal` 无 `Removed` → `attach_refusal_rebuilds_removed` 与 `receive_pack_writes_fenced` 失败；R11 注册不锁祖先 → `child_registration_fenced_by_parent` 失败；R12 分派去掉叶子校验 → `import_repo_leaf_dispatch_serves_canonical_path` 失败；R13 核心去掉规范形守卫 → `import_repo_leaf_core` 失败；R14 存活读去掉 `FOR SHARE` → `lock_live_import_repo_holds_share_lock`、`object_writes_fenced_after_detach`、`tag_lock_serializes` 失败。环境事件：卡片 smoke 原配方先 `source .env.test`，其导出的 `MEGA_DATABASE__DB_URL` 覆盖了配置文件里的临时库，服务于是初始化了共享 IT 库 `mega2` 的 `public` schema（73 张表，只含本次 smoke 数据），`search_path = <schema>,public` 使迁移用例的 `to_regclass` 解析到 `public`；配方已改为显式 `unset MEGA_DATABASE__DB_URL MEGA_DATABASE__DB_TYPE`，在已 source 的 shell 中重跑两例全绿且共享库未被触碰；`public` 的清理待用户确认后执行，C 组须在清理之后；ER-05 R1 Codex FAIL（1×P1 + 3×P2）已处置——P1 不采纳（既有、轴外，`DEFER-FU-36`，trunk-push.md 的不变量收窄到 B3 之外的栅栏事务），P2 落实：提交时的可重试错误同样整事务重试、预检顺序以表锁钉住（R4 转为失败）、IT 断言四张对象表为空；独立评审 R1 因周用量上限首次未运行、限额重置后完成：PASS（无 P0/P1，12×P2）；ER-05 R2 Codex PASS（1×P2：R4 记录前后矛盾，已改为最终结论）；独立评审的 12 条 P2 已落实——整事务重试的判定抽为纯函数 `batch_retry_backoff` 并以 `fu18_batch_retry_only_on_database_conflicts` 钉住（只重试 `MegaError::Db` 的死锁 / 串行化失败、至多 5 次、类型化拒绝不重试）；新增 `fu18_filepath_removed_between_check_and_reads`（预检通过后仓库在对象读之前消失，经表锁排序，`removed_or` 的调用点答 `IMPORT_REPO_REMOVED`）；`fu18_filepath_errors_not_panics` 增加根树与子树缺失；`fu18_lock_live_import_repo_holds_share_lock` 增加另一事务并发取同一锁必须成功（共享锁模式）；`last_wins_filepaths` 注释不再声称固定锁序；文档：SSH 数据阶段的实际表现、`reason` 措辞、叶子校验只作用于进入 ImportRepo 分支的路径（相对 SSH 写法 `DEFER-FU-37`）；计划：追溯表、ADR-FU-09 第 5 条与 `DEFER-FU-30` / `DEFER-FU-35` 的锚点、A 组规则措辞、性能预算；反向验证 R15–R19 全部失败：R15 `file_path` 调用点去掉 `removed_or`、R16 / R17 根树 / 子树改回 `unwrap`、R18 锁模式改为 `FOR UPDATE`、R19 对非数据库错误也重试；C 组在 bump 后的 `0.40.7` 树的干净副本上（HEAD + 本卡 12 个文件 + 版本号，其它会话的未提交文件按 HEAD 还原），测试库改用新建的空库 `mega2_fu18_gate`（`MEGA_DATABASE__DB_URL` 指向它，集成测试经它自建各自的库；共享库 `mega2` 的 `public` 已被原 smoke 配方初始化、清理待用户确认，不再阻塞门禁）：fmt、clippy 0 警告、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 `ld` `__eh_frame` 提示；`cargo test --all --no-fail-fast` 18 个 target 全部运行，lib 阶段 1790 通过 / 0 失败 / 1 忽略（含 `import_repo_cleanups_migration_applies`），失败集为 6 个基线环境用例 + `integration_api_write_trunk` 的 `api_write_custom_root_dirs` 与 `tag_root_token_lifecycle`（向刚启动的临时端口服务发请求 `error sending request`，失败点在被测行为之前）；二者各单独复跑 3/3 通过、整 target 62/62 通过，按「并发会话例外」口径接受；本次运行留下的测试 schema 都在门禁库内。提交 `edabfa9`、tag `v0.40.7` 与 GitHub Release 已发布；D 组 `docker.yml` run `36122387632` 的 `docker` job 对 `edabfa9` 为 success）

**Description:** 按 ADR-FU-09 第 5 条，引入 `lock_live_import_repo`（`SELECT … FOR SHARE`，绑定参数），并在 `ImportService::save_entry` 的每批对象行插入、`traverses_tree_and_update_filepath` 的 `file_path` 更新（先存活检查再解引用对象，其 `unwrap()` 改为错误）与 receive-pack 的三条 ref 写路径（B3 attach 含更新模式、`update_refs` tag 写、`attach_to_monorepo_parent` 仅删除分支写）的写事务内先取锁；失败返回 `IMPORT_REPO_REMOVED` 且不落行。另把 ReceivePack 首次注册 `git_repo` 行改为「同一事务内对全部祖先 ImportRepo 行取 `FOR SHARE` 后插入」（祖先生命周期栅栏），并在协议分派的 TP-08 规范化之后、任何查找/创建之前调用新引入的叶子校验核心 `check_import_repo_leaf`（拒绝 `import_dir` 本身与 NUL，ADR-FU-08 第 7 条；同时引入 API/CLI 用的严格入口 `strict_import_repo_leaf_input`）。唯一行为轴是「receive-pack 写路径对清理的互斥」。

**Out of scope:**

- detach / 清扫本身 —— 已由 FU-16 / FU-17 交付。
- `ImportApiService` 的 ref / tag 直写 —— 由 FU-19 承接（其对象行经 `save_entry`，由本卡覆盖）。
- HTTP 入口 —— 由 FU-20 承接（必须在 FU-19 之后发布）。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| ReceivePack 在 unpack 前注册 `git_repo` 行（HTTP 在 `info/refs` 通告时即注册） | `src/ceres/protocol/mod.rs:239-278`；`src/ceres/protocol/smart.rs:92-93` |
| `file_path` 更新在 attach 之前、含 `unwrap()` | `src/ceres/pack/import_repo.rs:115-143,438-515`；`src/jupiter/storage/git_db_storage.rs:404-437` |
| `save_entry` 按批插入对象行（无事务、语句级重试） | `src/jupiter/service/import_service.rs:50-125`；unpack 批错误在 `src/ceres/pack/mod.rs:174-187` 被包成 `Other` |
| tag 直写不经队列 | `src/ceres/pack/import_repo.rs:367-410`；`src/ceres/protocol/smart.rs:564-571` |
| 仅删除分支写经 B3（FU-13 起），`Done` 重放捷径不经 B3 | `import_repo.rs:551-561,642-662` → `src/jupiter/service/push_queue_service.rs:1974-1977,2019-2023` |
| `import_refs` 无指向 `git_repo` 的外键 | `src/jupiter/migration/m20250314_025943_init.rs:283-320` |

**Acceptance criteria:**

- [x] 具名用例 `fu18_receive_pack_writes_fenced` 通过（含 detach 后陈旧 attach 不重新挂载叶子）。
- [x] 具名用例 `fu18_tag_lock_serializes_with_detach` 通过。
- [x] 具名用例 `fu18_object_writes_fenced_after_detach` 通过（detach + 清扫之后的陈旧 `save_entry` 返回 `IMPORT_REPO_REMOVED` 且四表零新增行；同路径重新导入不受影响）。
- [x] 具名用例 `fu18_child_registration_fenced_by_parent` 通过。
- [x] 具名用例 `import_root_push_rejected` 通过。
- [x] 本地 storage-only 协议 smoke 全绿（A 组：本卡触及 `src/ceres/protocol/**`）。
- [x] `docs/refactoring/trunk-push.md` 登记 receive-pack 写路径栅栏与互斥语义。
- [x] `docs/errors.md` 登记 `IMPORT_REPO_REMOVED` 与 `IMPORT_REPO_PATH_INVALID`。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::service::push_queue_service::tests::fu18_'`（`(new)` 前缀组：detach 后执行的陈旧 attach 返回 `IMPORT_REPO_REMOVED`、不写 ref、不重新挂载叶子——`fu18_stale_attach_after_detach_is_removed`（未清扫、对象仍在的首次挂载，根与审计不变）、`fu18_stale_attach_after_reimport_is_removed`（同路径重新导入后旧 `repo_id` 的 attach，新仓库不受影响）、`fu18_stale_delete_only_after_detach_is_removed`、`fu18_removed_outranks_materialization_precheck`（`IMPORT_REPO_REMOVED` 先于 I3 文本）；队列行 `Failed` / `AttachFailure`、`error_message` 为同一原文）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::import_repo::tests::fu18_'`（`(new)` 前缀组：`fu18_receive_pack_writes_fenced`——detach 后 tag 写、仅删除分支写与 `file_path` 更新均 `IMPORT_REPO_REMOVED`，`file_path` 路径在对象已被清扫时不 panic、不更新任何行（另含：已完成的仅删除轮次在 detach 后被重放时不经 B3 也答 `IMPORT_REPO_REMOVED`、不新增队列行，陈旧首次挂载不重新挂载叶子）；`fu18_tag_lock_serializes_with_detach`——持锁 tag 事务先提交时 detach 等待并随后删除该 tag）
- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::service::import_service::tests::fu18_object_writes_fenced_after_detach'`（`(new)`：detach 与清扫完成后以旧 `repo_id` 调用 `save_entry` → `IMPORT_REPO_REMOVED`、`git_commit`/`git_tree`/`git_blob`/`git_tag` 零新增；并发批事务持锁时 detach 等待、其行随后被清扫；重新导入的新 `repo_id` 写入正常）
- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::pack::path_policy::tests::import_repo_leaf'`（`(new)`：核心对 `import_dir` 本身、之外、含 NUL 返回 `IMPORT_REPO_PATH_INVALID`、严格后代通过；严格入口另对 `..`、重复斜杠、尾斜杠、含 `\` 返回 `IMPORT_REPO_PATH_INVALID`；协议分派对带尾斜杠的 URL 仍按规范路径服务）
- [x] `source .env.test && cargo test -p mega2 --lib 'jupiter::storage::git_db_storage::tests::fu18_child_registration_fenced_by_parent'`（`(new)`：两个连接交错——子仓注册事务持父行 `FOR SHARE` 时 detach 等待并随后返回 `IMPORT_REPO_HAS_CHILDREN`；detach 持父行 `FOR UPDATE` 时子仓注册等待，随后作为独立导入注册且父仓库仍已清理）
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 import_repo_ import_root_push_rejected`（FU-12..FU-16 进程级回归；`(new)` `import_root_push_rejected`：对 `/third-party` 本身的 receive-pack 返回 400 `IMPORT_REPO_PATH_INVALID`，无 `git_repo` 行、无 ref/对象、根不变，`/third-party/<repo>` 的分派不受影响；随后对 `/third-party/<owner>/<repo>` 首推成功时根树顶层名集合不变，只在已存在的 `import_dir` 之下新增中间目录与叶子）
- [x] 协议 smoke（A 组，fail-closed）：
  ```bash
  set -euo pipefail
  cargo build
  # The service must use the throwaway database below: `.env.test` (or a shell
  # that sourced it) exports MEGA_DATABASE__* overrides that point at the shared
  # IT database, whose public schema would then be initialized.
  unset MEGA_DATABASE__DB_URL MEGA_DATABASE__DB_TYPE
  PG=$(docker compose -p mega2-it -f docker/docker-compose.test.yml ps -q postgres); test -n "$PG"
  W=$(mktemp -d); PORT=19180; DB=mega2_fu18_smoke; PID=""
  cleanup() {
    if [ -n "$PID" ]; then kill "$PID" 2>/dev/null || true; wait "$PID" 2>/dev/null || true; fi
    docker exec "$PG" psql -U mega2 -d mega2 -qc "DROP DATABASE IF EXISTS $DB" >/dev/null 2>&1 || true
    rm -rf "$W"
  }
  trap cleanup EXIT
  docker exec "$PG" psql -U mega2 -d mega2 -qc "DROP DATABASE IF EXISTS $DB" -c "CREATE DATABASE $DB"
  python3 - "$W" "$DB" <<'PY'
  import sys
  w, db = sys.argv[1:3]
  s = open("config/config-storage-only.none.toml").read()
  for old, new in [
      ('base_dir = "/tmp/.mono"', f'base_dir = "{w}/mono"'),
      ('db_url = "postgres://localhost:5432/mono"', f'db_url = "postgres://mega2:mega2_test_password@127.0.0.1:15432/{db}"'),
      ('url = "redis://127.0.0.1:6379"', 'url = "redis://127.0.0.1:16379"'),
      ('storage_type = "s3compatible"', 'storage_type = "local"\n[object_storage.local]\nroot_dir = "${base_dir}/objects"'),
  ]:
      assert old in s, old
      s = s.replace(old, new, 1)
  open(f"{w}/config.toml", "w").write(s)
  PY
  mkdir -p "$W/megabase" "$W/megacache" "$W/smoke"
  MEGA_BASE_DIR="$W/megabase" MEGA_CACHE_DIR="$W/megacache" ./target/debug/mega2 --config "$W/config.toml" service init --yes
  MEGA_BASE_DIR="$W/megabase" MEGA_CACHE_DIR="$W/megacache" ./target/debug/mega2 --config "$W/config.toml" \
    service http --host 127.0.0.1 -p "$PORT" > "$W/service.log" 2>&1 &
  PID=$!
  for _ in $(seq 1 90); do
    curl -sf -o /dev/null "http://127.0.0.1:$PORT/api/openapi.json" && break
    kill -0 "$PID" 2>/dev/null || { tail -50 "$W/service.log"; exit 1; }
    sleep 2
  done
  curl -sf -o /dev/null "http://127.0.0.1:$PORT/api/openapi.json"
  for CASE in 'HTTP clone' 'HTTP trunk push (none)'; do
    MEGA2_HTTP_REPO_URL="http://127.0.0.1:$PORT/" MEGA2_GIT_SMOKE_PUSH=1 MEGA2_SMOKE_CASE="$CASE" \
      MEGA2_GIT_SMOKE_WORKDIR="$W/smoke" scripts/git_protocol_smoke_storage_only.sh 2>&1 | tee "$W/smoke.log"
    rg -q 'storage_only summary: [1-9][0-9]* passed, 0 failed' "$W/smoke.log"
  done
  ```

**Dependencies:** FU-17（清扫原语）。

**Deliverables:** N/A

**Implementation write set:** `src/ceres/pack/import_repo.rs`；`src/jupiter/service/push_queue_service.rs`；`src/jupiter/service/import_service.rs`（`save_entry` 每批事务内取锁）；`src/jupiter/storage/git_db_storage.rs`（`lock_live_import_repo`、带祖先栅栏的注册原语、带栅栏的 `file_path` 分块写）；`src/ceres/protocol/mod.rs`（注册改调栅栏原语、分派前调用叶子校验）；`src/ceres/pack/path_policy.rs`（`check_import_repo_leaf`、`strict_import_repo_leaf_input`）；`src/ceres/pack/mod.rs`（设计定稿修订：`receiver_handler` 原样透传 `MegaError::ImportRepo`，3 行）；`src/ceres/api_service/import_api_service.rs`（设计定稿修订：`save_entry` 新签名的调用点，一个参数）；`tests/integration_git_cli.rs`（`import_root_push_rejected`，测试文件）；`docs/errors.md`；`docs/refactoring/trunk-push.md`；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** 推送期间被清理的 ImportRepo 返回 `IMPORT_REPO_REMOVED`。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 绑定参数；行锁与 detach 删除互斥。

**Performance budget:** 每个元数据写事务（含 `save_entry` 每批、每个 tag、`file_path` 每块、B3 attach）多一次按主键的 `FOR SHARE` 读；首次注册另有一次按 `repo_path IN (严格祖先)` 的唯一索引读并共享锁住命中的祖先行，读量以路径深度为界；`file_path` 步骤在读对象之前多一次无锁存活读（`removed_or` 在出错路径上再读一次）。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=receive-pack 写路径对清理的互斥; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=8/8; VER=7/8; landing=4; prod-files=8; scope=M; deps=FU-17; writeset=序列化于 FU-17; release=independent; split-from=FU-16（R2）; exception=N/A`

### Task FU-19: ImportApiService 写路径存活栅栏（#27）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 按终态重跑：Verification 五条命令通过——`fu19_` 6 例、FU-18 栅栏与存储回归 26 例、`tag_router` 3 例、`integration_api_write_trunk` 的 `delete_entry_reject_import_repo_409` / `import_repo_edit_save_commit_strict_fsck` / `api_write_import_namespace_guard` 3 例与 `tag_` 8 例；末项文档锚点与人工核对通过；fmt、clippy rc=0，`cargo build` / `cargo build --tests` rc=0（仅基线同有的 `ld` `__eh_frame` 提示）；ImportRepo / 推送队列 / 存储 / 错误 / API 库回归 436 通过，唯一失败 `jupiter::migration::tests::import_repo_cleanups_migration_applies` 系共享库 `public` 被 FU-18 原 smoke 配方污染（清理待用户确认）；反向验证 26 组（每组只改一个生产缝、跑对应用例组，源文件逐字节还原）全部失败：R1 edit/save 预读去掉 `removed_or`、R2 `removed_or` 去掉 `[code:409]` 标记、R3 只比路径不比 id、R4 不做存活检查即改写、R5–R7 与 R24 默认分支 / commit / 子树 / 根树改回 `unwrap`、R8–R11 四个写事务去掉锁、R12 tag 预检去掉 `removed_or`、R13 `map_ceres_error` 去掉 409 分支、R14 锁改 `FOR UPDATE`、R15 锁在写事务之前取并释放、R16 `git_tag` 在连接池插入、R17 锁用规范化路径、R18 `save_entry` 批不取锁、R19 默认分支经连接池 `update_ref`（HEAD 写法，panic）、R20–R22 锁留在事务而 lightweight ref / `git_tag` 删除 / 默认分支写改走连接池、R23 生产 `save_file_edit` 的 ref 写改回连接池 `update_ref`、R25 tag 删除去掉仓库过滤、R26 edit/save 先写 ref 后写对象批；ER-05 独立评审 R1 FAIL（1×P1 + 13×P2）已处置、R2 PASS（11×P2：9 条落实、2 条有据不采纳），见修订历史；另注：R1 的评审输入 diff 曾在反向验证 R3 生效时生成，已按还原后的树重新生成；Codex R1 首次因用量上限未运行，重置后于 22:30 补跑：PASS（无发现）；C 组在 bump 后的 `0.40.8` 树的干净副本上（HEAD + 本卡 9 个文件 + 版本号，其它会话的 11 个未提交文件按 HEAD 还原、未跟踪的 `scripts/drop_test_schemas.sh` 从副本删除），测试库为新建的空库 `mega2_fu19_gate`：fmt、clippy 0 警告、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 `ld` `__eh_frame` 提示；`cargo test --all --no-fail-fast` 18 个 target 全部运行，lib 阶段 1796 通过 / 0 失败 / 1 忽略，失败集为 6 个基线环境用例 + `integration_api_write_trunk::path_provision_rejects_policy_violations`（启动后第一条对本用例库的查询报 `relation "mega_refs" does not exist`：就绪判定只是向预留后释放的临时端口 TCP 连通，被测服务尚未完成迁移即被判定就绪，属临时端口类；与本卡改动无关）；该用例在同一副本与门禁库上单独复跑 3/3 通过、整 target 62/62 通过，按「并发会话例外」口径接受；本次运行留下的 805 个测试 schema 都在门禁库内。提交 `0945f3d`、tag `v0.40.8` 与 GitHub Release 已发布；D 组 `docker.yml` run `36148786334` 的 `docker` job 对 `0945f3d` 为 success）

**Description:** 按 ADR-FU-09 第 5 条，把 `ImportApiService` 的 `edit/save` 默认分支更新、tag 创建（`git_tag` 行 + ref）、tag 删除（ref + `git_tag` 行）改为单事务：先 `lock_live_import_repo`，再写 `import_refs` / `git_tag` 行；失败返回 `IMPORT_REPO_REMOVED`（该请求的对象行经 `save_entry`，已由 FU-18 在写入时栅栏）。edit/save 的对象行经 FU-18 `save_entry`、默认分支 ref 在其后自己的带锁事务里写；annotated tag 的 `git_tag` 行与 ref、lightweight tag 的 ref、tag 删除的 ref 与 `git_tag` 行各一事务；预读失败时再检存活（`removed_or`），仓库已被清理即 `IMPORT_REPO_REMOVED`；tag 路由的 `map_ceres_error` 映射 409。唯一行为轴是「产品 API 写路径对清理的互斥」。

**Out of scope:**

- receive-pack 写路径 —— 已由 FU-18 交付。
- `ImportService::save_entry` 的对象行栅栏 —— 已由 FU-18 交付。
- HTTP 清理入口 —— 由 FU-20 承接（必须在本卡之后发布）。
- 默认分支 ref 的 CAS 与快照一致的建树 —— `DEFER-FU-22`（本卡评估后延后）；分派前已被清理的路径落到 Monorepo 处理器 —— `DEFER-FU-38`；子仓被清理后的最长前缀分派 —— `DEFER-FU-39`；读路径剩余的 panic —— `DEFER-FU-40`；存活仓库上同名 tag 的并发创建与删除 —— `DEFER-FU-41`；`POST /api/v1/repo/clone` —— `DEFER-FU-29`。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| `ImportApiService` 直写 ref 与 `git_tag` | `src/ceres/api_service/import_api_service.rs`：`delete_tag`（预读 + 按名删）、`save_file_edit`（预读 `get_root_tree` 的三处 `unwrap`、`get_tree_by_hash` 的 `unwrap`、`ObjectHash` 的 `unwrap`、`save_entry`、无条件 `update_ref`）、`create_tag` 的预读、`create_annotated_tag` + `write_import_ref_with_rollback`（按名补偿删除）、`create_lightweight_tag`（`save_ref`） |
| 存储写原语 | `src/jupiter/storage/git_db_storage.rs`：`update_ref`（`unwrap().unwrap()`）、`update_ref_in_txn`（无调用者、返回错误）、`save_ref_in_txn`、`remove_ref_in_txn`、`insert_tag`（池回读）、`delete_tag` |
| tag 路由的错误映射只认 400 / 404 | `src/api/router/tag_router.rs` 的 `map_ceres_error` 调用 → `src/common/errors/api.rs` 的 `map_ceres_error` |
| API 分派按最长前缀取存储路径；无行时落到 `MonoApiService` | `src/api/mod.rs` 的 `api_handler` |
| 栅栏原语 | FU-18 `lock_live_import_repo`（`src/jupiter/storage/git_db_storage.rs`） |

**Acceptance criteria:**

- [x] 具名用例 `fu19_edit_save_after_detach_rejected` 通过。
- [x] 具名用例 `fu19_tag_create_after_detach_rejected` 通过。
- [x] 具名用例 `fu19_tag_delete_after_detach_rejected` 通过。
- [x] 具名用例 `fu19_api_lock_serializes_with_detach` 通过。
- [x] 具名用例 `fu19_edit_save_after_detach_writes_no_rows` 通过（对象行与 ref 均零新增）。
- [x] 具名用例 `fu19_tag_create_rolls_back_atomically` 通过（`git_tag` 行与 ref 同事务，失败时两者皆无）。
- [x] `docs/refactoring/directory-entry-api.md` 登记 ImportRepo 产品写在清理期间返回 `IMPORT_REPO_REMOVED`。
- [x] `docs/errors.md` 的 `IMPORT_REPO_REMOVED` 出现场景把 `edit/save`（预读与默认分支 ref 写）、tag 创建与 tag 删除三个 API 登记为 409。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'ceres::api_service::import_api_service::tests::fu19_'`（`(new)` 六例：detach 后（未清扫 / 已清扫 / 同路径重新导入后）的陈旧处理器 `edit/save`、annotated 与 lightweight tag 创建、tag 删除（含不存在的名字）均 `IMPORT_REPO_REMOVED`（409）、不 panic、不写 `import_refs` / `git_tag` 行（被拒的删除保留既有 `git_tag` 行给清扫）；存活仓库缺默认分支 / commit / 根 tree / 子 tree 为 404 而非 409；FU-15 别名行在规范行清理后仍可写；四个写事务（默认分支 ref、annotated tag、lightweight tag、tag 删除）各自以共享锁（`FOR UPDATE NOWAIT` 失败、`FOR SHARE NOWAIT` 成功）先持锁、提交前其写对其它连接不可见，detach 等待并随后删除其行；生产 `edit/save` 到达默认分支 ref 写时持有共享锁；detach 先持行时生产入口等待后 409、零行；`save_entry` 提交后、ref 写前被清理时 ref 写为 409；annotated tag 在 ref 写失败时 `git_tag` 行同时回滚、胜者的行不受影响）
- [x] `source .env.test && cargo test -p mega2 --lib -- 'jupiter::service::import_service::tests::' 'jupiter::storage::git_db_storage::tests::'`（FU-18 栅栏与存储回归）
- [x] `source .env.test && cargo test -p mega2 --lib 'api::router::tag_router::'`（tag 路由回归，`map_ceres_error` 改动）
- [x] `source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1 --exact delete_entry_reject_import_repo_409 import_repo_edit_save_commit_strict_fsck api_write_import_namespace_guard`（既有：409 标记剥离；存活 ImportRepo 的 edit/save 仍 200 且严格 fsck；清理后分派为 400）
- [x] `source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1 tag_`（Monorepo tag wire 不变）
- [x] `test -f docs/refactoring/directory-entry-api.md && rg -n "IMPORT_REPO_REMOVED" docs/refactoring/directory-entry-api.md docs/errors.md docs/refactoring/trunk-push.md`（锚点定位用）+ 人工核对

**Dependencies:** FU-18（栅栏原语与清扫接线）。

**Deliverables:** N/A

**Implementation write set:** `src/ceres/api_service/import_api_service.rs`；`src/jupiter/storage/git_db_storage.rs`（事务内 tag 写原语 `insert_tag_in_txn` / `delete_tag_in_txn`）；`src/common/errors/api.rs`（设计定稿修订：`map_ceres_error` 增 409 分支）；`docs/refactoring/directory-entry-api.md`；`docs/errors.md`（设计定稿修订）；`docs/refactoring/trunk-push.md`（设计定稿修订：锁序说明补列 API 写事务）；`src/api/router/preview_router.rs` 与 `src/common/errors/mod.rs`（R1 评审修订，仅注释：`map_ceres_error` 已识别 409；`Removed` 经 edit/save 对象批自 FU-18 起、经 edit/save 预读与默认分支 ref 写及 tag 写自 FU-19 起到达 API；无行为变更，不计入 G-04）；本计划文件。

**Release write set:** Inherited

**Files likely touched:** 同 Implementation write set

**Docs and compatibility impact:** 清理期间的 ImportRepo 产品写（edit/save、tag 创建、tag 删除）返回 409 `IMPORT_REPO_REMOVED`。此前：detach 后、清扫前的 tag 创建答 200 并写下孤儿 `git_tag` / `import_refs` 行，清扫后答 404（目标 commit 不存在）；detach 后的 tag 删除答 200 并删掉清扫的 `git_tag` 行；edit/save 的预读与 ref 写 panic（对象批自 FU-18 起为 409）。tag 创建的 `git_tag` 行与 ref 原子化，并发同名创建的落败者不再删掉胜者的 `git_tag` 行（状态仍为 500）。存活 ImportRepo 缺默认分支 / commit / tree 时，经 `get_root_tree` / `get_tree_by_hash` 的路径（edit/save 与目录树浏览）返回 404（此前 panic）；blame / history 等读路径的 panic 仍在（`DEFER-FU-40`）。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 绑定参数；行锁与 detach 删除互斥。

**Performance budget:** 每个 API 写事务恰一次按主键的 `FOR SHARE`，edit/save 因此两次（FU-18 对象批与默认分支 ref 事务各一）；预读失败时多一次按 `repo_path` 唯一索引的无锁读；annotated tag 的回读由连接池移入事务（`RETURNING`）；tag 删除少一次预读；detach 等待 API 写事务的时长以锁后至多两条语句为界。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=产品 API 写路径对清理的互斥; recovery=前滚补丁版本; complete=yes; self-contained=yes; AC=8/8; VER=8/8; landing=3; prod-files=3; scope=M; deps=FU-18; writeset=序列化于 FU-18（与 FU-20 共写 src/common/errors/api.rs、docs/errors.md、docs/refactoring/directory-entry-api.md，由 FU-19 -> FU-20 排序）; release=independent; split-from=FU-18（R4）; exception=N/A`

### Task FU-20: ImportRepo 清理 HTTP API（#27）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 按终态重跑：Verification 六项通过——A 组 `api::` 库测 264 例（含 `(new)` 九例）、`import_repo_remove_` IT 六例、`delete_entry_reject_import_repo_409`、零命中守卫 `OK: zero hits`、契约页锚点与人工核对、errors.md 两行登记门；fmt、clippy rc=0，`cargo build` / `cargo build --tests` rc=0（仅基线同有的 `ld` `__eh_frame` 提示）；ImportRepo / 推送队列 / 存储 / 错误 / API / 路径策略库回归 445 通过，唯一失败 `jupiter::migration::tests::import_repo_cleanups_migration_applies` 系共享库 `public` 被 FU-18 原 smoke 配方污染（清理待用户确认；中间一轮另有 `push_queue_reaper::tests::tp05_kill9_running_reaped_immediately` 时序偶发，单独 3/3 通过、终态轮未复现）；反向验证 26 组（每组只改一个生产缝、跑对应库测或 IT，源文件逐字节还原）全部失败：R1–R3 鉴权闸去掉 `push_auth` 预检 / 去掉固定体改写 / 一律改写为 403、R4 `status()` 返回常量、R5 / R25 路由也挂到 Review（OpenAPI 与真实请求）、R6 storage-only 不挂、R7 / R22 OpenAPI 缺 404 / 500、R8 请求去掉 `deny_unknown_fields`、R9 结局去掉小写命名、R10 `Pending` 映射为 `Removed`、R11 先鉴权后校验、R12 只用核心叶子校验、R13 鉴权前精确查找、R14 以固定结局代替清理入口、R15 不传 requester、R16 null id 被省略、R17 续做当新操作转发、R18 类型化错误压平为 500、R19 剥掉 `.git`、R20 鉴权前按存在性作答、R21 鉴权前记录 path、R23 入口去掉续做的路径归属条件（FU-17）、R24 `repo_id` 不再 required、R26 把 `import_dir` 而非目标路径交给鉴权；ER-05：设计定稿后 R1 独立评审 FAIL（1×P1 + 12×P2）已处置、Codex R1 PASS；R2 独立评审 PASS（5×P2 已落实）、Codex R2 PASS（均无发现；npm 版 codex 缺平台二进制，改用 `/Applications/ChatGPT.app` 自带的 codex-cli），见修订历史；C 组在 bump 后的 `0.40.9` 树的干净副本上（HEAD + 本卡 12 个文件 + 版本号，其它会话的 11 个未提交文件按 HEAD 还原、未跟踪的 `scripts/drop_test_schemas.sh` 从副本删除），测试库为新建的空库 `mega2_fu20_gate`：fmt、clippy 0 警告、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 `ld` `__eh_frame` 提示；`cargo test --all --no-fail-fast` 18 个 target 全部运行，lib 阶段 1805 通过 / 0 失败 / 1 忽略，`integration_api_write_trunk` 68/68，失败集恰为 6 个基线环境用例；本次运行留下的 805 个测试 schema 都在门禁库内。提交 `39bee2b`、tag `v0.40.9` 与 GitHub Release 已发布；D 组 `docker.yml` run `36175109452` 的 `docker` job 对 `39bee2b` 为 success）

**Description:** 按 ADR-FU-10 挂载 `POST /api/v1/import-repo/remove`：规范化与命名空间校验、绑定参数精确查找、写鉴权、调用 FU-17 入口、稳定输出。唯一行为轴是「ImportRepo 叶子清理的机器接口」。顺序固定：axum `Json` 提取器（纯文本 400/413/415/422）→ `strict_import_repo_leaf_input`（400，先于鉴权）→ `authorize_import_repo_removal`（包装 `authorize_trunk_api_write`，经 `ApiError::status()` 改写为固定体 401 `authentication required` / 403 `forbidden`；`push_auth=none` 或缺失一律 403）→ FU-17 `remove_import_repo(…, Some(token 名), cleanup_id)`（裸 `?`，全部查询为绑定参数）；handler 在鉴权通过前只读请求与配置快照；输出 `CommonResult<{path, outcome, repo_id, cleanup_id}>`，结局语义见 ADR-FU-10 第 5 条补注。

**Out of scope:**

- 摘除/清扫/栅栏语义与结局语义 —— 已由 FU-16..FU-19 交付（FU-17 定稿⑤；本卡只暴露到 HTTP 并补注 ADR-FU-10 第 5 条）。
- review 形态 —— `DEFER-FU-02`。
- ImportRepo 内部文件删移 —— 永久非目标（既有 409 契约）。
- 运维 CLI —— FU-21；用户旅程文档 —— FU-22。
- 后台续做 —— `DEFER-FU-06`；`import_dir` 本身的存量行 —— `DEFER-FU-09`；别名行合并 —— `DEFER-FU-10`。
- 被清理路径上的 Monorepo tag 写 —— `DEFER-FU-38`（本卡 ER-03 复核：继续延后）；子仓清理后子路径的 API 分派到父仓 —— `DEFER-FU-39`（重启条件已触发，复核后继续延后）。
- 可重试失败的类型化状态码 —— `DEFER-FU-42`；严格入口的输入回显长度 / 控制字符 —— `DEFER-FU-43` / `DEFER-FU-44`。
- 可注入清扫预算 —— 永久非目标（FU-17 定稿⑧）。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| storage-only 挂载 | `src/api/api_router.rs` 的 `routers_for` 与 `storage_only_routers_with`（合并链）；`src/api/router/preview_router.rs` 的 `storage_only_write_routers` |
| 清理入口与结局（不做叶子校验、自行查找） | `src/ceres/pack/import_repo.rs` 的 `remove_import_repo` 与 `RemoveOutcome` |
| 严格叶子入口 | `src/ceres/pack/path_policy.rs` 的 `strict_import_repo_leaf_input` |
| 最长前缀查找（组件边界、绑定参数，仍解析祖先与尾斜杠别名，清理不可用）；API 分派 | `src/jupiter/storage/git_db_storage.rs` 的 `find_git_repo_like_path`；`src/api/mod.rs` 的 `api_handler` |
| 精确查找 / 子仓检查 | `git_db_storage.rs` 的 `find_git_repo_exact_match` / 子仓查询（FU-17） |
| 既有写鉴权（none 放行为 anonymous、403 回显路径、未配置 401） | `src/api/api_write_auth.rs` 的 `authorize_trunk_api_write` |
| `ApiError` 无状态访问器、`into_response` 以 error 级记录 `err_message` | `src/common/errors/api.rs` |
| 复现 | E8（FU-06 起 import 叶子的 delete-entry 为 400 `MONO_PATH_NOT_ALLOWED`） |

**Acceptance criteria:**

- [x] 具名用例 `import_repo_remove_populated_then_absent` 通过。
- [x] 具名用例 `import_repo_remove_pending_continuation` 通过。
- [x] 具名用例 `import_repo_remove_invalid_paths` 通过。
- [x] 具名用例 `import_repo_remove_exact_match_only` 通过。
- [x] 具名用例 `import_repo_remove_requires_token` 通过。
- [x] 具名用例 `import_repo_remove_openapi` 通过。
- [x] `docs/refactoring/directory-entry-api.md` 含 ImportRepo 叶子清理小节。
- [x] `docs/errors.md` 的 ImportRepoError 表登记本卡暴露的两个码（`IMPORT_REPO_HAS_CHILDREN`、`IMPORT_REPO_CLEANUP_NOT_FOUND`）。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'api::'`（A 组；`(new)` 九例：`api::api_write_auth::tests::import_repo_removal_auth_matrix`、`common::errors::api::tests::api_error_status_matches_response`、`api::router::tests::import_repo_remove_is_storage_only`、`api::router::import_repo_router::tests::` 下 `import_repo_remove_openapi_contract` / `import_repo_remove_result_wire_shape` / `import_repo_remove_validates_before_auth` / `import_repo_remove_authorizes_before_any_query` / `import_repo_remove_extractor_rejections_precede_auth` / `import_repo_remove_live_surface`（Review 形态 404、GET 405 且 `allow: POST`、超过 2 MiB 413）；库连接为 `Disconnected` 的 `Storage::mock()`：401/403/400/422 在任务内得出、任何实体查询都会 panic、原始查询的错误传播为 500，覆盖 token 的请求在 `tokio::spawn` 中以 `Disconnected` panic 结束，证明鉴权前零查询、鉴权后才到入口）
- [x] `source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1 import_repo_remove_`（`(new)` 六例：`import_repo_remove_populated_then_absent`——已填充仓库 200 `removed`（`repo_id` / `cleanup_id`、台账与审计 requester 为 token 名、不含 token 值）、之后 upload-pack 404、clone 失败、根树无叶子；重复 200 `absent`（两 id 为 `null`、无写）；带 `cleanup_id` 的续做幂等 `removed`；同路径重新导入得到新 `repo_id` 并可再次清理；`import_repo_remove_pending_continuation`——生产常量下以数据量触发 `pending`（绑定参数 SQL 为存活仓库补 100 500 行 `git_blob`，首请求恰删 98 000 行；该组调用用 180 s 客户端），续做期间同路径重新导入的仓库不受影响，带返回的 `cleanup_id` 续做至 `removed`，台账行仍待续时，未知 `cleanup_id` 与属于另一路径的 `cleanup_id` → 404 `IMPORT_REPO_CLEANUP_NOT_FOUND`（同一文本、不改台账与对象行），只带 path 的请求 detach 当时存活的仓库，再一次为 `absent`；`import_repo_remove_invalid_paths`——`import_dir` 本身、`import_dir` 之外、跨组件前缀、相对路径、`..`、`.`、重复斜杠、尾斜杠、首尾空白、`\`、JSON `\u0000`（NUL）均 400 `IMPORT_REPO_PATH_INVALID`（无凭据 / 越权 / 覆盖三种凭据逐字节相同，规范化到存活叶子的拼写也不删除它），畸形 JSON、缺 Content-Type、缺 `path`、未知字段 `cleanupId`、字符串 `cleanup_id` 为 axum 纯文本 400/415/422，无写；`import_repo_remove_exact_match_only`——`.git` 拼写、子路径、兄弟前缀、大小写变体答 `absent`，含 `_` / `%` 的兄弟与后代诱饵不受影响、目标照常 `removed`（转义子仓检查、别名行不算子仓且保留），有子仓的父 409 `IMPORT_REPO_HAS_CHILDREN` 且无写，先清子仓后父仓可清；`import_repo_remove_requires_token`——`push_auth=token` 栈：无凭据 / 未知 token 对不存在 / 叶子 / 有子仓的父 × 新操作 / 续做得到逐字节相同的 401（固定体 `authentication required`，响应头除 `Date` 外一致、无 `WWW-Authenticate`），越权 token 得到逐字节相同的 403（固定体 `forbidden`），带固定请求 id 的服务日志行不含路径与 token，无写；覆盖 token 200；`push_auth=none` 栈一律 403 且仓库仍可 clone，`import_dir` 本身仍为 400；`import_repo_remove_openapi`——运行时 OpenAPI 含该路由、只有 `post`、声明 200/400/401/403/404/409/500、请求体 `additionalProperties: false`、`outcome` 枚举为 `removed` / `pending` / `absent`）
- [x] `source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1 --exact delete_entry_reject_import_repo_409`（既有回归）
- [x] 零命中守卫（清理路径不用最长前缀查找、不经 API 分派、不用放行匿名的写鉴权、不用去掉逐字码的映射；文件缺失时 rg 退出 2 → ERROR）：
  ```bash
  if rg -n "find_git_repo_like_path|api_handler|ImportApiService|authorize_trunk_api_write|trunk_write_requester|map_ceres_error" src/api/router/import_repo_router.rs src/ceres/pack/import_repo.rs; then
    echo "FAIL: forbidden pattern found"; exit 1
  else
    rc=$?
    if [ "$rc" -ne 1 ]; then echo "ERROR: rg failed with exit $rc"; exit "$rc"; fi
    echo "OK: zero hits"
  fi
  ```
- [x] `test -f docs/refactoring/directory-entry-api.md && rg -n "import-repo/remove" docs/refactoring/directory-entry-api.md`（锚点定位用）+ 人工核对小节含请求、响应与结局语义、客户端协议、判定顺序、错误码、保留策略、已知限制
- [x] errors.md 两行登记：
  ```bash
  test "$(rg -c '^\| `(HasChildren \{ path \}|CleanupNotFound \{ path, cleanup_id \})` \| `IMPORT_REPO_(HAS_CHILDREN|CLEANUP_NOT_FOUND)` \| 40[49] \|' docs/errors.md)" = 2
  ```

**Dependencies:** FU-19（全部栅栏必须先发布）。

**Deliverables:** N/A

**Implementation write set:** `src/api/router/import_repo_router.rs`（新）；`src/api/router/mod.rs`；`src/api/api_router.rs`；`src/api/api_write_auth.rs`（`authorize_import_repo_removal`）；`src/ceres/model/git.rs`（DTO）；`src/common/errors/api.rs`（`ApiError::status()` 访问器）；`tests/integration_api_write_trunk.rs`；`docs/errors.md`；`docs/refactoring/directory-entry-api.md`；本计划文件；`src/ceres/pack/import_repo.rs`、`src/lib.rs`（设计定稿写集修订，仅注释：入口已有产品调用者、调用方前置条件；无行为变更，不计入 G-04）。`src/api/api_write_auth.rs` 的 `authorize_import_repo_removal` 包装 `authorize_trunk_api_write`。

**Release write set:** Inherited

**Files likely touched:** 同上

**Docs and compatibility impact:** 新端点 `POST /api/v1/import-repo/remove`（仅 storage-only）；运行时 OpenAPI 新路径与 `ImportRepoRemove{Request,Outcome,Result}`；契约页新节（DEP-FU-03 于本卡发布日移交；Libra pin 小节不改）；`docs/errors.md` 登记 `IMPORT_REPO_HAS_CHILDREN` / `IMPORT_REPO_CLEANUP_NOT_FOUND`；无配置、无迁移、无依赖。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 仅 storage-only；handler 在鉴权通过前只读请求与配置（不读库；handler 自身不写日志，语法 400 与固定体 401 / 403 经 `ApiError` 的 error 级日志记录——400 含调用方输入（`DEFER-FU-43`），401 / 403 只含固定文本）；只接受覆盖目标路径的 token；`push_auth=none` 或未配置对可解析、语法合法的请求一律 403；未授权响应体只由状态码决定（401 `authentication required` / 403 `forbidden`），三类路径逐字节相同，error 日志只含固定文本，请求体中的 path 不进 trace span；语法 400 先于鉴权，只回显调用方输入与公开的 `import_dir`；绑定参数精确查找、转义子仓检查；续做只处理所答台账行；未知字段 422；审计 requester 为 token 名、不含 token 值。

**Performance budget:** 未授权与语法错误请求零查询；授权后同 FU-16/FU-17：精确查找 1 次、子仓预检 1 次（`DEFER-FU-27`）、至多一次 detach（一个写入队列轮次）、≤ 100 条清扫语句与 ≤ 16 条台账行；API 层无额外扫描；无服务端超时（`DEFER-FU-32`）。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=ImportRepo 叶子清理的机器接口; recovery=前滚补丁版本（端点下线）; complete=yes; self-contained=yes; AC=8/8; VER=8/8; landing=4; prod-files=6; scope=M; deps=FU-19; writeset=序列化于 FU-19（设计定稿：import_repo.rs、lib.rs 仅注释）; release=independent; split-from=FU-09（R1）; exception=N/A`

### Task FU-21: 运维 CLI `mega2 import-repo remove`（#27）

**Task type:** `implementation`

**Lifecycle / Acceptance:** `done` / `complete`（A/B 按终态重跑：Verification 五项通过——A 组 `cli::tests` 11 例（含 `(new)` `import_repo_remove_cli_parses`）、`commands::` 90 例（含 `(new)` `import_repo_command_registered` 与 `import_repo_remove_contract`）、`integration_git_cli` 的 `import_repo_remove_cli_` 六例、零命中守卫 `OK: zero hits`、手工证据（一次性 `push_auth=none` 栈与新建空库：缺 `--yes` 退出码 2、stdout 为空；清理退出码 0、stderr 为空、stdout 末行 `removed … (repo_id=<n>, cleanup_id=<n>)`；随后 upload-pack 404、clone 失败；vault 密钥文件前后一致（sha256 / inode / 权限 / mtime / ctime / 目录清单）、未生成 `etc/config.toml`；重新推送后可 clone；未导入路径 `absent`、退出码 0）；fmt、clippy rc=0，`cargo build` / `cargo build --tests` rc=0（仅基线同有的 `ld` `__eh_frame` 提示）；回归：`integration_git_cli` 的 `import_repo_` / `import_root_push_rejected` / `path_provision_cli_` 18 例通过，`cli::` / `commands::` / `config::` / `import_repo` / `jupiter::storage::init` 库回归 359 通过，唯一失败 `jupiter::migration::tests::import_repo_cleanups_migration_applies` 系共享库 `public` 被 FU-18 原 smoke 配方污染（清理待用户确认；C 组新建门禁库上通过）；反向验证 26 组（每组只改一个生产缝、跑对应库测或 IT，源文件逐字节还原）全部失败：R1 `--yes` 非必需、R2 `--max-rounds` 接受 0、R3 默认轮数改变、R4 `FullAppContext` 加载模式、R5 未注册执行器、R6 接受 cwd 配置、R7 去掉只读 schema 确认、R8–R10 去掉 storage-only / Redis SecretRef / S3 SecretRef 检查、R11 跳过严格路径、R12 后续轮按路径、R13 不排空、R14 不传 `operator-cli`、R15 控制字符原样输出、R16 `pending` 退出码 1、R17 `--cleanup-id` 当新操作、R18 `cli.rs` 一次性 SIGINT 处理、R19 句柄查询回落到任意待续行、R20 中断后不恢复句柄、R21 结局写到 stderr、R22 经 `AppContext::new` 装配（密钥文件被重写）、R23 排空轮按路径（detach 存活的重新导入）、R24 排空不受 `--max-rounds` 约束、R25 写连接迁移并补种子行、R26 detach 前的未类型化失败报为 `absent`；ER-05：设计定稿后 R1 Codex FAIL（1×P1、2×P2）+ 独立评审 FAIL（1×P1、14×P2）已处置；R2 Codex PASS（1×P2）+ 独立评审 PASS（6×P2），P2 均已落实，见修订历史；C 组在 rebase 到 origin/main（`6836eb0`，media 计划的 `v0.40.10`）并 bump 后的 `0.40.11` 树的干净副本上（HEAD = origin/main + 本卡提交；其它会话的 11 个未提交文件按 HEAD 还原——`src/context/mod.rs` 的 HEAD 已含本卡可见性改动——未跟踪的 `scripts/drop_test_schemas.sh` 从副本删除），测试库为新建的空库 `mega2_fu21_gate2`：fmt、clippy（`--all-features`，含远端新增的 `fastcdc` feature）0 警告、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 `ld` `__eh_frame` 提示；`cargo test --all --no-fail-fast` 18 个 target 全部运行，lib 阶段 1816 通过 / 0 失败 / 1 忽略，`integration_git_cli` 51/51，失败集为 5 个基线环境用例（git-lfs ×4、s3 smoke），⊆ 基线（基线中的 `integration_oci_docker_gated` 随 media 发布的修复已通过）；本次运行留下的 811 个测试 schema 都在门禁库内（rebase 前在 `0.40.10` 树与 `mega2_fu21_gate` 上的一轮同样通过，见修订历史）。提交 `3c05232`、tag `v0.40.11` 与 GitHub Release 已发布；D 组 `docker.yml` run `36208117731` 的 `docker` job 对 `3c05232` 为 success）

**Description:** 按 ADR-FU-11（FU-21 补注）新增 `mega2 --config <path> import-repo remove --path <P> --yes [--cleanup-id <ID>] [--max-rounds <N>]`，唯一行为轴是「服务器侧运维清理入口」。`LoadMode::ParsedExistingConfig`，配置须经 `--config` / `MEGA_CONFIG` 点名。不经 `AppContext::new`、从不打开 vault（不读、不写、不 chmod `<MEGA_BASE_DIR>/vault/core_key.json`），不迁移、不补种子行、不 `init_monorepo`，除 Redis 雪花租约续期与连接池自身的维护任务（sqlx 连接回收、Redis 连接驱动）外不启动后台任务。纯校验先于任何 I/O：clap（`--yes`，缺失退出码 2）→ 配置来源 → `validate` / 对象格式 → storage-only → 凭据须为字面值 → `strict_import_repo_leaf_input`。I/O：只读连接确认无待执行迁移 → Redis 雪花租约 → 写连接（`postgres_connection`：不迁移、不播种）→ 对象存储 → `Storage::new_with_connection`（`current_thread` 运行时）。第 1 轮为新操作或 `--cleanup-id` 续做，其后只续做（一次调用至多 detach 一次）；主链结束后按台账排空该路径其余 `detached` 行（永不 detach）——这是 FU-17 定稿要求的排空选择，替代「再跑 `--path` / 循环至 `absent`」，交 FU-22 写入用户文档。stdout 恰一行结局且为末行（路径控制字符转义）；退出码 0/1/2/3/130；SIGINT 经 `src/cli.rs` 记录式处理，在 `MONO_WRITE_LOCK` 屏障之后读台账给出续做句柄。FU-20 输入的处置：「no product entry yet」注释改写；`DEFER-FU-44` 复核后继续延后；调用方前置条件满足（先严格校验，服务器访问即授权）。

**Out of scope:**

- HTTP 入口 —— 已由 FU-20 交付。
- 远程（无服务器访问）清理 —— 永久非目标（需 token 的 HTTP 入口已覆盖）。
- 用户文档 —— 由 FU-22 承接（本卡在 FU-22 描述中登记运维 CLI 契约）。
- review 形态（`DEFER-FU-02`，CLI 同样拒绝）；vault SecretRef 凭据的解析（`DEFER-FU-46`）；其它一次性命令的 SIGINT 与 SIGTERM / SIGHUP（`DEFER-FU-15`）；类型化可重试退出码（`DEFER-FU-42`）；严格入口的控制字符（`DEFER-FU-44`，继续延后）；后台续做（`DEFER-FU-06`）；保留 requester 名（`DEFER-FU-45`）。
- 可注入预算与进程内 reaper —— 永久非目标（孤儿队列行归服务 reaper）。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 注册与加载模式 | `src/commands/mod.rs` 的 `builtin` / `builtin_exec` / `load_mode` 与 `LoadMode` |
| 加载与信号 | `src/cli.rs` 的 `service_sigint_receiver`、记录式 / 一次性 Ctrl-C 处理、`load_config_existing`；`src/config/loader.rs` 的 `ConfigSource`、`load()` 生成默认配置 |
| 退出与打印 | `src/main.rs`；`src/common/errors/mod.rs` 的 `process_exit_code` / `cli_exit` |
| 服务入口 | `src/ceres/pack/import_repo.rs` 的 `remove_import_repo` 与 `RemoveOutcome` |
| 严格输入 | `src/ceres/pack/path_policy.rs` 的 `strict_import_repo_leaf_input` |
| 轻量装配 | `src/jupiter/storage/init.rs` 的 `postgres_connection`（R1 改 `pub(crate)`；`database_connection` 会迁移并补 `queue_control` 种子行）/ `read_only_database_connection`；`src/jupiter/redis/mod.rs` 的 `init_connection`；`Storage::new_with_connection`；`src/context/mod.rs` 的 `object_storage_needs_vault`；`push_queue_storage.rs` 的 `MONO_WRITE_LOCK_SQL` |
| 避开的 vault 副作用 | `AppContext::new`（`src/context/mod.rs`）；`vault_core.rs` 的 `replace_core_key` / `read_core_key`（每次打开截断重写或 chmod 密钥文件） |
| 台账读取 | `git_db_storage.rs` 的 `find_git_repo_exact_match` / `pending_cleanups_by_path` / `cleanup_by_id` / `latest_cleanup_for` |
| 待改注释 | `tests/integration_git_cli.rs` 的 FU-16 用例注释；`src/lib.rs` 的 `import_repo_ops` 注释 |

**Acceptance criteria:**

- [x] 具名用例 `import_repo_remove_cli_parses` 通过。
- [x] 具名用例 `import_repo_command_registered` 通过。
- [x] 具名用例 `import_repo_remove_cli_requires_yes` 通过。
- [x] 具名用例 `import_repo_remove_cli_invalid_path` 通过。
- [x] 具名用例 `import_repo_remove_cli_removes` 通过。
- [x] 具名用例 `import_repo_remove_cli_absent` 通过。
- [x] 具名用例 `import_repo_remove_cli_pending` 通过。
- [x] 具名用例 `import_repo_remove_cli_interrupted` 通过。

**Verification:**

- [x] `source .env.test && cargo test -p mega2 --lib 'cli::tests'`（A 组；`(new)` `import_repo_remove_cli_parses`：完整 argv 与缺 `--yes` / 缺 `--path` / 缺子命令 / `--max-rounds 0` / `--cleanup-id 0` 或非数字 / `--config` 放在子命令之后 / 位置参数均为 clap 退出码 2）
- [x] `source .env.test && cargo test -p mega2 --lib 'commands::'`（A 组；`(new)` `import_repo_command_registered`：`builtin()`、`builtin_exec()`、`load_mode()` 三处，`LoadMode::ParsedExistingConfig`，精确命令列表含 `import-repo`；模块内纯单测覆盖结局行、控制字符转义、配置来源与前置拒绝）
- [x] `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 import_repo_remove_cli_`（`(new)` 六例：CLI 子进程由 `full_config_command()` + `trunk_boot_env()` 构造，与该用例的服务共用数据库、Redis、对象根、`MEGA_BASE_DIR` 与 `MEGA_CACHE_DIR`，`PRINT_STD=false`，300 s 看门狗，每次运行断言 `vault/core_key.json` 的字节 / inode / 权限 / mtime / ctime / 目录清单不变，SQL 绑定参数，每例结束（含 panic）删除共享 Git 工作根下的 case 目录（ER-13）；`requires_yes`——缺 `--yes` 退出码 2 且不读配置、无配置来源 / 未点名配置 / 未迁移库均退出码 1、不生成配置不建表，服务停止且删去 `queue_control` 行后 `absent` 运行不补种子行；`invalid_path`——非法路径矩阵与 review / vault SecretRef 部署在任何 I/O 前退出码 1、stderr 恰一行；`removes`——含 100 500 行 blob 的存活仓库经进程内续做 `removed`（台账 `swept`、`git_blob` 100 501、队列 / 台账 / 两段审计 requester 为 `operator-cli`），有子仓的父 409 文本退出码 1、先清子仓后可清父，重新推送后可 clone，写队列暂停时未类型化失败退出码 1、无结局行、无写；`absent`——未导入路径、`print_std=true` 时末行、控制字符转义输出为 `absent`，第 1 轮 detach 新导入后按台账排空匿名 detach 留下的行，再跑一次 `absent` 且无写；三行匿名 `detached` 且重新导入存活时，`--cleanup-id C3 --max-rounds 1` 在排空处停下、以 C4 退出码 3，`--cleanup-id C4` 排空 C5，重新导入的仓库、对象行、队列行与 detach 行数不变且可 clone；`pending`——`--max-rounds 1` 退出码 3 并给出句柄，台账行仍待续时未知 / 异路径 `--cleanup-id` 退出码 1 且不改台账，重新导入之后 `--cleanup-id` 续做至 `removed` 而重新导入的仓库不受影响；`interrupted`——detach 提交后 SIGINT 退出码 130 并给出句柄，提交前 SIGINT 退出码 130、无句柄、仓库仍存活，随后 `--cleanup-id` 续做与最终清理均成功）
- [x] 零命中守卫（CLI 不经应用上下文与 vault、不迁移不播种、不直接 detach、不用最长前缀查找、不直接退出进程或 `println!`；文件缺失时 rg 退出 2 → ERROR）：
  ```bash
  if rg -n "AppContext|VaultCore|vault_core|open_readonly|bootstrap_monorepo|ReadOnlyContext|init_monorepo|spawn_background|apply_migrations|Migrator::(up|down|fresh|refresh|reset)|\bdatabase_connection|ensure_queue_control_seed|detach_import_repo|detach_for_integration_test|find_git_repo_like_path|process::exit|println!" src/commands/import_repo.rs; then
    echo "FAIL: forbidden pattern found"; exit 1
  else
    rc=$?
    if [ "$rc" -ne 1 ]; then echo "ERROR: rg failed with exit $rc"; exit "$rc"; fi
    echo "OK: zero hits"
  fi
  ```
- [x] 手工证据（sanitized，一次性 `push_auth=none` 栈、`.env.test` 覆盖已 unset）：缺 `--yes` 退出码 2；清理退出码 0、stdout 末行为 `removed … (repo_id=<n>, cleanup_id=<n>)`；随后 upload-pack 404、clone 失败；vault 密钥文件前后一致、未生成 `etc/config.toml`；重新推送后 clone 通过；未导入路径答 `absent`

**Dependencies:** FU-20（串行发布链；共享服务入口已稳定）。

**Deliverables:** N/A

**Implementation write set:** `src/commands/import_repo.rs`（新）；`src/commands/mod.rs`；`src/cli.rs`（测试 + 设计定稿写集修订：`import-repo` 并入记录式 SIGINT 处理，一处条件）；`src/context/mod.rs`（设计定稿写集修订，仅可见性：`object_storage_needs_vault` → `pub(crate)`）；`src/jupiter/storage/init.rs`（R1 写集修订，仅可见性：`postgres_connection` → `pub(crate)`）；`tests/integration_git_cli.rs`；本计划文件；`src/lib.rs` 与 `src/jupiter/storage/git_db_storage.rs`（仅注释，不计入 G-04）。

**Release write set:** Inherited

**Files likely touched:** 同 Implementation write set

**Docs and compatibility impact:** 新子命令（`mega2 --help` 列出）、`--cleanup-id`、结局行格式与退出码 0/1/2/3/130 为公开契约（ADR-FU-11 补注；用户文档由 FU-22）；`src/cli.rs` 信号处理变化只作用于 `import-repo`；无配置、迁移、依赖、HTTP 变化；无新错误码（`docs/errors.md` 不变）。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** 授权边界 = 服务器上可读、被点名的配置及其中数据库 / Redis / 对象存储凭据；从不打开 vault（不读写、不 chmod 密钥文件、不初始化 vault），拒绝 vault SecretRef 凭据；`--yes` 在解析层强制；只在 storage-only（`enforcement=off`，不在 CLI 重放 authz outbox）；审计 requester `operator-cli`、不含凭据；stdout 路径控制字符转义，stderr 沿用 Debug 转义的 `<CODE>:` 文本，配置加载失败时回显操作者自己点名的配置路径（GC-FU-05 范围说明）；日志中的数据库地址经 `redact_db_url` 打码用户信息，成功路径不记 Redis URL；一次调用至多在第 1 轮 detach 一次，续做与排空永不 detach；从不迁移、不补种子行（只读连接确认 schema，写连接用 `postgres_connection`）。

**Performance budget:** 每轮同 FU-16/FU-17（≤100 条清扫语句，≤16 条台账行）；每次调用 ≤ `--max-rounds` 轮（默认 1000），另加 1 次只读迁移状态读、1 次精确查找（`--cleanup-id` 时为 1 次台账行读）、每个排空轮 1 次台账读、排空结束 1 次空读；第 1 轮 detach 排队等待 ≤300 s，Running 后无上界（`DEFER-FU-32`）；中断后的句柄查询 ≤10 s（含 `MONO_WRITE_LOCK` 屏障）；无业务后台循环，仅租约续期与连接池自身的维护任务，租约槽位在退出后 ≤30 s 释放。

**Estimated scope:** `M`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=implementation; axis=服务器侧运维清理入口; recovery=前滚补丁版本（子命令下线）; complete=yes; self-contained=yes; AC=8/8; VER=5/8; landing=4; prod-files=5; scope=M; deps=FU-20; writeset=序列化于 FU-20（设计定稿：cli.rs 一处条件、context/mod.rs 可见性、lib.rs 仅注释；R1：init.rs 可见性、git_db_storage.rs 仅注释）; release=independent; split-from=FU-20（R6）; exception=N/A`

### Task FU-22: ImportRepo 契约与生命周期用户文档（#26 / #27）

**Task type:** `docs`

**Lifecycle / Acceptance:** `done` / `complete`（A/B：锚点定位与逐条核对、相对链接可解析（另按 GitHub slug 校验 12 个锚点片段）、中英标题计数与行号一致、零命中守卫；实测：`0.40.11` 门禁副本的二进制在一次性 `push_auth=none` 栈上跑通首推、新提交与 annotated tag 的再次推送、陈旧克隆被拒、`--mirror` 同步（上游新分支与 tag 同步、上游删除的分支随之删除）、LFS 镜像同步（首次、增量、上游缺对象时按文档设置 `lfs.allowincompletepush` 后继续）、CLI 清理（`removed`、退出码 0）、upload-pack 404 与 clone 失败、重新导入、未导入路径 `absent`，vault 密钥文件不变；文档中的台账查询、`git_repo` 查询与 `docker compose top` 在测试栈上按原样执行通过；`docker compose exec` 的容器内形式未实跑（拉取镜像需下载许可），其前提经 compose 文件与 Dockerfile 核对。ER-05：R1–R5 共五轮修订（R1 Codex FAIL + 独立 FAIL、R2 两方 FAIL、R3 两方 FAIL、R4 两方 FAIL、R5 Codex PASS + 独立 FAIL，均已处置，见修订历史），R6 Codex PASS + 独立评审 PASS（均无发现）。提交 `8e11572` 已推送；C 组覆盖已由 FU-23 在评审 PASS 后于 `0.40.12` 最终树正式取得（该树含本卡最终变更，失败集为 5 个基线环境用例、原因与登记相同）；承接的 D 组：FU-23 的 `docker.yml` run `36220401014` 的 `docker` job 对 `4bf6cc2`（含本卡变更）为 success）

**Description:** 写出 ImportRepo 唯一、无歧义的更新契约与清理/保留策略，同步 README、quick-start 与 user-guide（错误码已由各实现卡登记 `docs/errors.md`）。唯一行为轴是「ImportRepo 用户旅程文档」。 运维 CLI 契约（FU-21 定稿，本卡写入用户文档）：①调用——compose 用 `docker compose exec -T mega2 mega2 import-repo remove --path <P> --yes`（镜像已设 `MEGA_CONFIG`，评估栈 compose 文件本身不设；干净 stdout 加 `-e MEGA_LOG__PRINT_STD=false` 或取 stdout 末行），裸机用 `mega2 --config <path> import-repo remove …`（`--config` 在 `import-repo` 之前），须用服务同一镜像 / 二进制且服务在运行；②退出码 0/1/2/3/130 与 stdout / stderr 分工；③结局行——无存活仓库时 `removed` 可指更早的仓库，`absent` 表示该路径已排空；`--path` 按原样精确匹配存储的仓库路径（不去掉 `.git`、不纠正拼写，执行前须核对），该路径上既无存活仓库也无未完成清理时答 `absent`、退出码 0；④续做——`pending`（3）或带 id 的 `interrupted`（130）后用 `--cleanup-id <C>`，即使路径已重新导入也安全，不带 id 的 `interrupted` 按 stderr 处理；未类型化的退出码 1 失败后重跑同一命令，但 stderr 称台账不可读时（退出码 1 或 130，detach 可能已提交）先查 `import_repo_cleanups (path, state='detached')`；被 kill 后按 `import_repo_cleanups (path, state='detached')` 取 id；⑤排空语义——CLI 按台账排空该路径其余 `detached` 清理（`--cleanup-id` 时可含更新的行）、期间从不 detach，HTTP 客户端按 ADR-FU-10 第 5 条补注的协议；⑥前置条件——仅 storage-only；`redis.url` 与 S3 凭据在本次运行须为字面值（`vault://` 被拒，用 `MEGA_*` 覆盖）；勿为本次运行固定 `MEGA_ID_GENERATOR_WORKER_ID`；CLI 二进制与数据库 schema 不符时拒绝；⑦`docs/errors.md` 的 `HasChildren` / `CleanupNotFound` 行补「也由 `mega2 import-repo remove` 打印（退出码 1）」。

**Out of scope:**

- 任何代码或配置 —— 永久非目标（docs 卡）。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| ImportRepo 描述 | `README(.zh).md:27`；`docs/quick-start(.zh).md` 的「迁移现有 Git 仓库」（L104-124）与第 51 行的推送规则；`docs/user-guide(.zh).md` 第 1 节（L14）、2.1（L29-33）、2.5（L58、L79）、4.2（L98）、第 7 节 CLI 表（L143-154）；`docs/errors.md` 的 ImportRepoError 表（L145-150）与清理端点出现场景（L159-163）（FU-22 执行时复核，原锚点 `README.md:18` 等已漂移） |
| 待写入的事实 | 更新语义：`push_queue_service.rs` 更新推送只写 ref（1846-1881）、CAS（`errors/mod.rs` 243-247）、`smart.rs` 报告与 tag / 分支粒度（555-617）、ADR-FU-08；清理：`import_repo_router.rs`、`api_write_auth.rs`、`src/commands/import_repo.rs`、契约页 `refactoring/directory-entry-api.md`「ImportRepo 叶子清理」；保留：契约页「保留策略」、ADR-FU-09；compose：`Dockerfile`（`MEGA_CONFIG`）、`linux-mega2-compose.yml` 与 `macos-orbstack-mega2-compose.yml`（`push_auth=none`、字面 Redis / S3、`MEGA_LOG__PRINT_STD=true`） |

**Acceptance criteria:**

- [x] `README.md` 含一句无歧义契约「ImportRepo 接受后续推送（分支与 tag），并可经 `POST /api/v1/import-repo/remove` 清理」。
- [x] `README.zh.md` 含同义中文句。
- [x] `docs/quick-start.md` ImportRepo 小节含第二次推送与清理示例。
- [x] `docs/quick-start.zh.md` 含同结构示例。
- [x] `docs/user-guide.md` 含 ImportRepo 生命周期小节（更新语义、tag 逐 ref / 分支批量原子的成败粒度、HTTP 清理需 token、`push_auth=none` 部署用 `mega2 import-repo remove`、恢复路径）。
- [x] `docs/user-guide.zh.md` 含同结构小节。
- [x] `docs/user-guide.md` 与 `docs/user-guide.zh.md` 登记保留策略（blob 字节保留、元数据清扫、无 GC、续做方式）。
- [x] `docs/user-guide.md` 与 `docs/user-guide.zh.md` 登记兼容说明（存量 ImportRepo 无需迁移）。
- [x] 四份指南中不存在「一次性导入」或与更新契约冲突的表述。
- [x] 本卡改动的文档中相对链接全部可解析。
- [x] 本卡暂存集是其 Deliverables 的子集（不含 `src/**`、`tests/**`、`config/**`、`Cargo.toml`、`Cargo.lock`）。

**Verification:**

- [x] `rg -n "import-repo/remove|IMPORT_REPO_" README.md README.zh.md docs/quick-start.md docs/quick-start.zh.md docs/user-guide.md docs/user-guide.zh.md docs/user-guide.md docs/errors.md`（锚点定位用）+ 人工逐条核对 AC-1..10
- [x] 相对链接可解析：
  ```bash
  for f in README.md README.zh.md docs/quick-start.md docs/quick-start.zh.md docs/user-guide.md docs/user-guide.zh.md docs/user-guide.md docs/errors.md; do
    d=$(dirname "$f")
    rg -o --no-filename '\]\(([^)#\s]+)' -r '$1' "$f" | rg -v '^[a-z]+:' | while read -r t; do
      test -e "$d/$t" || { echo "BROKEN: $f -> $t"; exit 1; }
    done || exit 1
  done
  echo "OK: links resolve"
  ```
- [x] 卡范围暂存守卫（暂存前快照为空才继续；只暂存本卡 Deliverables；暂存增量必须是其子集；其它工作区改动保持未暂存并在记录中报告）：
  ```bash
  pre=$(libra diff --staged --name-only) || { echo "ERROR: libra diff failed"; exit 2; }
  if [ -n "$pre" ]; then echo "STOP: pre-staged paths not owned by this card (recorded as handoff, no commit):"; printf '%s\n' "$pre"; exit 3; fi
  libra add README.md README.zh.md docs/quick-start.md docs/quick-start.zh.md docs/user-guide.md docs/user-guide.zh.md docs/user-guide.md docs/errors.md docs/plan/plan-20260923.md
  staged=$(libra diff --staged --name-only) || { echo "ERROR: libra diff failed"; exit 2; }
  allowed=" README.md README.zh.md docs/quick-start.md docs/quick-start.zh.md docs/user-guide.md docs/user-guide.zh.md docs/user-guide.md docs/errors.md docs/plan/plan-20260923.md "
  printf '%s\n' "$staged" | while read -r f; do
    [ -z "$f" ] && continue
    case "$allowed" in *" $f "*) ;; *) echo "FAIL: undeclared staged file $f"; exit 1;; esac
  done || exit 1
  echo "OK: staged set ⊆ Deliverables（其它工作区改动保持未暂存并在记录中报告）"
  ```
- [x] 中英结构一致：
  ```bash
  for pair in "docs/user-guide.md docs/user-guide.zh.md" "docs/quick-start.md docs/quick-start.zh.md" "README.md README.zh.md"; do
    set -- $pair
    test "$(rg -c '^#{1,6} ' "$1")" = "$(rg -c '^#{1,6} ' "$2")" || { echo "MISMATCH: $1 vs $2"; exit 1; }
  done
  echo "OK: heading counts match"
  ```
- [x] 零命中守卫（无「一次性导入」表述）：
  ```bash
  if rg -n -i "one-shot|import-once|一次性导入" README.md README.zh.md docs/quick-start.md docs/quick-start.zh.md docs/user-guide.md docs/user-guide.zh.md docs/user-guide.md; then
    echo "FAIL: forbidden pattern found"; exit 1
  else
    rc=$?
    if [ "$rc" -ne 1 ]; then echo "ERROR: rg failed with exit $rc"; exit "$rc"; fi
    echo "OK: zero hits"
  fi
  ```

**Dependencies:** FU-21。

**Deliverables:** `README.md`；`README.zh.md`；`docs/quick-start.md`；`docs/quick-start.zh.md`；`docs/user-guide.md`；`docs/user-guide.zh.md`；`docs/errors.md`；本计划文件。

**Implementation write set:** 同 Deliverables。

**Release write set:** `N/A`

**Files likely touched:** 同上

**Docs and compatibility impact:** 用户文档。

**Rollback mode:** `revert`

**Migration and rollback:** N/A

**Security and privacy:** 示例不含真实 token。

**Performance budget:** N/A

**Estimated scope:** `M`

**Version increment:** `N/A`

**Release boundary:** `no-release`

**C/D coverage from:** `FU-23`（最终发布卡在包含本卡变更的最终树上执行完整 C 组，并继承其 D 组）

**Granularity:** `type=docs; axis=ImportRepo 用户旅程文档; recovery=revert 文档; complete=yes; self-contained=yes; AC=11/20; VER=6/20; landing=0; prod-files=0; scope=M; deps=FU-21; writeset=序列化于 FU-21; release=no-release; split-from=FU-09（R1）; exception=N/A`

### Task FU-23: 计划收口发布（索引 + 最终树完成门）

**Task type:** `release`

**Lifecycle / Acceptance:** `done` / `complete`（A/B：两处索引登记（`rg -n "plan-20260923"` 命中 `docs/plan/README.md` 与 `docs/plan/plan-long.md`，状态「收口中」与横幅一致）；各卡 Lifecycle：FU-01..FU-23 与 FU-04A 均 `done` / `complete`（FU-22、本卡于收口时）；Review log 补齐 FU-19..FU-22 的全部评审轮次；`DEFER-FU-31` 的承接由本卡改为新计划（本卡不删代码）；三份计划文档相对链接可解析；手写 release note 汇总 FU-01..FU-22（含 AC-7 所列兼容 / 迁移项与 `DEFER-FU-*` 已知限制），经两路对抗核对（事实与完整性）共 24 项修订。评审前证据（C 组须在 ER-05 PASS 之后正式运行，本轮的版本 bump 与门禁早于评审，只作评审前证据，PASS 后在最终树上重跑）：聚合守卫共 182 项——从各卡 AC 与 Verification 的 `(new)` 抽取 181 项（150 个精确用例名与 31 个前缀组），另加 FU-21 Lifecycle 标为 `(new)` 的 `import_repo_remove_contract`（库 121、`integration_git_cli` 32、`integration_api_write_trunk` 29），在最终树全量运行中全部通过，无缺失、无失败；门禁在 bump 后的 `0.40.12` 树的干净副本上（HEAD `8e11572` + 本卡索引 / 计划 / 版本号；其它会话的 11 个未提交文件按 HEAD 还原、未跟踪的 `scripts/drop_test_schemas.sh` 从副本删除），测试库为新建的空库 `mega2_fu23_gate`：fmt、clippy（`--all-features`）0 警告、`cargo build` 0 警告、`cargo build --tests` 仅基线同有的 `ld` `__eh_frame` 提示；`cargo test --all --no-fail-fast` 18 个 target 全部运行，lib 1816 通过 / 0 失败 / 1 忽略，`integration_git_cli` 51/51，`integration_api_write_trunk` 68/68，失败集为 5 个基线环境用例（git-lfs ×4、s3 smoke），⊆ 基线；本次运行留下的 811 个测试 schema 都在门禁库内。ER-05：R1 Codex FAIL + 独立 FAIL、R2 Codex FAIL + 独立 FAIL（完成门交用户决定）、R3 Codex PASS + 独立评审 PASS（P2 均落实），见 Review log。C 组在评审 PASS 之后正式运行：同一最终树（HEAD `8e11572` + 本卡索引 / 计划 / 版本号，其它会话的 11 个未提交文件按 HEAD 还原、未跟踪脚本从副本删除）、新建空库 `mega2_fu23_gate2`：fmt、clippy（`--all-features`）0 警告、`cargo build` 0 警告、`cargo build --tests` 仅 `ld` `__eh_frame` 提示（`DEP-FU-05`）；`cargo test --all --no-fail-fast` 18 个 target 全部运行，lib 1816 / 0 / 1，`integration_git_cli` 51/51，`integration_api_write_trunk` 68/68，失败集为 5 个基线环境用例且原因与登记相同（git-lfs 钉住版本断言 ×4、RustFS PUT 经 macOS 系统代理 502）；聚合守卫 182 项全部通过；811 个测试 schema 在门禁库内。提交 `4bf6cc2`、tag `v0.40.12` 与 GitHub Release 已发布；D 组 `docker.yml` run `36220401014` 的 `docker` job 对 `4bf6cc2` 为 success。「计划完成门」按用户决定保持未勾，待 `DEP-FU-05`）

**Description:** 本计划的最终发布点：在 `docs/plan/README.md` 与 `docs/plan/plan-long.md` 登记本计划、回填各卡状态与 Review log，并在包含 FU-22 与本卡全部变更的最终树上执行完整 C 组（bump、三门、构建、提交、推送、tag、手写 Release）与 D 组。不引入新行为；为 FU-11 之外的最后一张 `no-release` 卡 FU-22 提供 C/D 覆盖。唯一行为轴是「计划收口与发布证据」。

**Out of scope:**

- 任何新行为、代码或配置 —— 永久非目标（release 卡）。
- 关闭 GitHub issue —— 维护者动作。

**Current evidence:**

| 事实 | 证据 |
|---|---|
| 计划索引表 | `docs/plan/README.md:22-48` |
| 日期计划索引 | `docs/plan/plan-long.md:871-872` |
| D 组 workflow | `.github/workflows/docker.yml:3-12` |

**Acceptance criteria:**

- [x] `docs/plan/README.md` 文件列表含本计划一行，状态与横幅一致。
- [x] `docs/plan/plan-long.md` 日期计划索引含本计划一行（PT 列 `N/A`）。
- [x] 本计划横幅、各卡 `Lifecycle / Acceptance`、完成判据三处一致。
- [x] Review log 记录每张卡的评审轮次与 `PASS`。
- [x] 聚合守卫：最终树上本计划引入的全部 `(new)` 具名用例在全量测试中通过（按「本机基线环境失败」口径比对）。
- [x] 最终树 C 组全绿（bump 后三门、`cargo build`、`cargo build --tests`）。
- [x] 手写 release note 汇总 FU-01..FU-22 的用户可见变更、兼容/配置/迁移说明（`root_dirs` 校验、`import_repo_cleanups` 迁移、FU-15 存量别名路径规范化——冲突行保留并告警、改写不可逆且 TP-08 兼容路径保留、推送拒绝文案变化）与已知限制（`DEFER-FU-*`、本机环境失败）。
- [x] D 组 `docker` job 对该 tag 与提交 SHA 为 `success`。
- [x] 本卡改动的文档中相对链接全部可解析。

**Verification:**

- [x] `rg -n "plan-20260923" docs/plan/README.md docs/plan/plan-long.md`
- [x] `cargo +nightly fmt --all --check`
- [x] `cargo clippy --all-targets --all-features -- -D warnings`
- [x] `source .env.test && cargo test --all --no-fail-fast`（全部 target 已运行；失败集 ⊆ 基线环境失败集且原因同类）
- [x] `cargo build && cargo build --tests`（0 错误 0 警告）
- [x] 卡范围暂存守卫：
  ```bash
  pre=$(libra diff --staged --name-only) || { echo "ERROR: libra diff failed"; exit 2; }
  if [ -n "$pre" ]; then echo "STOP: pre-staged paths not owned by this card (recorded as handoff, no commit):"; printf '%s\n' "$pre"; exit 3; fi
  libra add docs/plan/README.md docs/plan/plan-long.md docs/plan/plan-20260923.md Cargo.toml Cargo.lock
  staged=$(libra diff --staged --name-only) || { echo "ERROR: libra diff failed"; exit 2; }
  allowed=" docs/plan/README.md docs/plan/plan-long.md docs/plan/plan-20260923.md Cargo.toml Cargo.lock "
  printf '%s\n' "$staged" | while read -r f; do
    [ -z "$f" ] && continue
    case "$allowed" in *" $f "*) ;; *) echo "FAIL: undeclared staged file $f"; exit 1;; esac
  done || exit 1
  echo "OK: staged set ⊆ Deliverables + 版本面"
  ```
- [x] 相对链接可解析：
  ```bash
  for f in docs/plan/README.md docs/plan/plan-long.md docs/plan/plan-20260923.md; do
    d=$(dirname "$f")
    rg -o --no-filename '\]\(([^)#\s]+)' -r '$1' "$f" | rg -v '^[a-z]+:' | while read -r t; do
      test -e "$d/$t" || { echo "BROKEN: $f -> $t"; exit 1; }
    done || exit 1
  done
  echo "OK: links resolve"
  ```
- [x] D 组命令（「执行检查必备需求」D 组块，`v<version>` 为本卡版本）
- [x] 人工核对三处状态一致与 release note 内容

**Dependencies:** FU-22。

**Deliverables:** `docs/plan/README.md`；`docs/plan/plan-long.md`；`docs/plan/plan-20260923.md`；GitHub Release note

**Implementation write set:** `docs/plan/README.md`；`docs/plan/plan-long.md`；`docs/plan/plan-20260923.md`。

**Release write set:** Inherited

**Files likely touched:** 同 Implementation write set 与版本面

**Docs and compatibility impact:** 仅索引与发布说明。

**Rollback mode:** `immutable-release`

**Migration and rollback:** N/A

**Security and privacy:** release note 不含 token、路径外的部署信息。

**Performance budget:** N/A

**Estimated scope:** `S`

**Version increment:** `patch`

**Release boundary:** `independent`

**C/D coverage from:** `self`

**Granularity:** `type=release; axis=计划收口与发布证据; recovery=前滚版本（索引可 revert）; complete=yes; self-contained=yes; AC=9/12; VER=10/12; landing=0; prod-files=0; scope=S; deps=FU-22; writeset=本计划+README 索引+plan-long+版本面; release=independent; split-from=FU-10（R1）; exception=N/A`

## 测试矩阵

| 类别 | 必须覆盖 | Target / command |
|---|---|---|
| 单元 | 消息文法、成帧、blame 摘要、`PathPolicyError`/`ImportRepoError` 码与映射、分类、孤儿黏性、配置形状 | `source .env.test && cargo test -p mega2 --lib 'common::utils::test'`、`'common::errors::tests'`、`'ceres::pack::path_policy::tests'`、`'ceres::pack::push_chain::tests'`、`'ceres::pack::trunk_provenance::tests'`、`'ceres::api_service::blame_ops::tests'`、`'config::validate::tests'` |
| 集成（DB） | 物化剥离、落点回落、attach 幂等 + CAS（分支批量原子、tag 逐 ref）、detach 原子性与事务内子仓再检查、事务内审计、清扫与续做、行锁栅栏（receive-pack 与 API） | `'ceres::pack::monorepo::tests::fu'`、`'jupiter::service::push_queue_service::tests::fu'`、`'jupiter::storage::git_db_storage::tests::fu17_'`、`'jupiter::storage::audit_storage::tests'`、`'ceres::pack::import_repo::tests'`、`'ceres::api_service::import_api_service::tests::fu19_'` |
| 集成（进程） | 签名推送两对照、ImportRepo blame 摘要、孤儿重试、路径策略情形 + 自定义根 + 原始非零 old_id、开通 CLI 旅程、ImportRepo 增量与 CAS、detach 后 404、清理 API、严格 fsck、全新栈产品写 | `source .env.test && cargo test -p mega2 --test integration_git_cli -- --test-threads=1 <filter>`；`source .env.test && cargo test -p mega2 --test integration_api_write_trunk -- --test-threads=1 <filter>` |
| CLI | `path provision` 与 `import-repo remove` 解析、三处注册、LoadMode、退出码（含 3 / 130）、token 仅 env、`--yes`、`--cleanup-id`、stdout 末行规则、按台账排空（重新导入存活时、`--max-rounds` 停于排空）、未类型化失败退出码 1、vault 密钥文件不变、不生成配置、不迁移不播种 | `'cli::tests'`、`'commands::'` + `path_provision_cli_*`、`import_repo_remove_cli_*` |
| HTTP API | 两个新端点的状态码、JSON、鉴权、OpenAPI；产品写根外码 | `'api::'` + `path_provision_*`、`import_repo_remove_*`、`api_write_*` |
| 迁移 | `import_repo_cleanups` 建表与索引；存量 ImportRepo 别名行规范化（冲突保留、幂等）；`migrations()` 注册 | `source .env.test && cargo test -p mega2 --lib 'jupiter::migration::'`、`'jupiter::storage::git_db_storage::tests::cleanup_ledger_'` |
| 配置 | `root_dirs`/`import_dir` 形状校验；三份自带配置通过 | `config::validate::tests::monorepo_` + `config validate` ×3 |
| Git 协议 | 真实 `git push` / `clone` / `ls-remote` / `fsck --strict` | 上列进程 IT |
| 安全 | 401/403、最高新建组件授权、错误脱敏、import 根/越界拒绝、精确查找、LIKE 转义、行锁栅栏、清理端点无存在性泄漏 | `path_provision_token_scope`、`path_policy_message_redaction`、`import_repo_remove_*`（含 `import_repo_remove_authorizes_before_any_query`、`import_repo_remove_requires_token`、`import_repo_remove_exact_match_only`）、`fu17_`、`fu18_` |
| 性能 | 清扫每批 ≤ 1000 行、每请求预算有界；detach 锁内无按对象删除 | `fu17_sweep_bounded_and_complete`、`fu17_resume_budget_paginates`、`fu16_` |
| live/gated | Libra 手工证据（CI 无 Libra；FU-01 / FU-08 用 0.23.46，FU-10 起用本机 0.23.58） | FU-01、FU-08、FU-10、FU-12 |

## 追溯表

| 任务 | 来源/证据 | mega2 落点 | 文档/兼容动作 | 指定测试 |
|---|---|---|---|---|
| FU-01 | #28 AC1–5；E9/E10 | `src/common/utils.rs`、`trunk_provenance.rs` | `trunk-push.md` | `split_commit_message_grammar`、`signed_push_*_control` |
| FU-02 | #28 AC2/AC4；E11 | `materialize.rs`、`push_queue_service.rs` | `trunk-push.md` | `fu02_*` |
| FU-03 | E12；#28 AC2 | `mono_api_service.rs`、`mono_storage.rs`、`import_api_service.rs` | `deploy-trunk.md` | `*_strict_fsck`、`api_history_strict_clone`、`api_commit_subject_visible`、`fu03_review_and_legacy_sites_framed` |
| FU-04 | #29 AC5 | `src/config/validate.rs`、`src/jupiter/utils/converter.rs`（`INIT_ROOT_RESERVED_NAMES`） | `configuration(.zh).md`、`manual/monorepo-init(.zh).md` | `config::validate::tests::monorepo_`、`shipped_configs_pass_monorepo_shape` |
| FU-04A | #28 展示面（FU-03 R1 Claude P2）；用户决定 2026-09-24 | `src/ceres/api_service/blame_ops.rs` | —（字段语义修正，无 schema 变化） | `blame_commit_text_*`、`import_repo_blame_summary_framed` |
| FU-05 | #29 AC1/2/4 | `src/common/errors/`、`src/ceres/pack/path_policy.rs` | `errors.md` | `path_policy::tests`、`common::errors::tests::path_policy` |
| FU-06 | #25 AC1/2；#29 AC4/AC5 API 面（第三类见 `DEFER-FU-08`）；E5 | `mono_api_service.rs`、`path_policy.rs`（`check_write_operands`） | `deploy-trunk.md`、`refactoring/directory-entry-api.md`、`errors.md` | `create_entry_fresh_stack_without_clone`、`fresh_stack_*`、`api_write_*`、`import_attach_after_import_dir_api_write`、`path_policy::tests::write_operand_guard` |
| FU-07 | #25 AC1/5；E6 | `mono_api_service.rs`、`src/api/router/`、`src/ceres/model/` | 契约页 | `path_provision_*` |
| FU-08 | #25 AC2/6 | `src/commands/` | —（FU-11） | `path_provision_cli_*` |
| FU-09 | #25 AC3/4；E3/E4 | `push_chain.rs`、`src/common/errors/mod.rs`（`MegaError::OrphanChain`） | `trunk-push.md`、`errors.md` | `orphan_retry_same_rejection`、`orphan_rejection_is_sticky_for_known_tip`、`from_known_tip_zero_old_id_orphan` |
| FU-10 | #29 AC1–5；#25 AC3/4；E1/E2 | `monorepo.rs`、`push_queue_service.rs` | `trunk-push.md`、`errors.md` | `path_policy_*`、`fu10_*` |
| FU-11 | #25 AC7；#29 AC6 | 文档 | README、quick-start、user-guide、初始化手册、`errors.md` | 文档门 |
| FU-12 | #26 AC2/AC5（Git 语义）；Codex R9 P0（CAS 先于更新） | `push_queue_service.rs`、`import_repo.rs`、`git_db_storage.rs`、`src/common/errors/` | `errors.md` | `fu12_*`、`import_repo_error_domain` |
| FU-13 | #26 AC1–5、AC6（存量兼容）；E7 | `push_queue_service.rs`、`import_repo.rs`、`tree_ops.rs`、`audit_storage.rs`、`git_db_storage.rs` | —（FU-22） | `import_repo_*`、`fu13_*` |
| FU-14 | #27 AC3（可续做的稳定结局）；Codex R10 P1 | `src/callisto/`、`src/jupiter/migration/`、`git_db_storage.rs` | —（FU-22） | `cleanup_ledger_*`、`import_repo_cleanups_migration_applies` |
| FU-15 | #26 AC6 / #27 兼容（存量别名）；Codex R18 P1 | `src/jupiter/migration/` | `deploy-trunk.md` | `import_repo_alias_*` |
| FU-16 | #27 AC1/4/5 | `import_repo.rs`、`push_queue_service.rs`、`tree_ops.rs`、`lib.rs`、`audit_storage.rs` | `trunk-push.md` | `fu16_*`、`import_repo_detach_then_clone_404` |
| FU-17 | #27 AC3/5/6 | `import_repo.rs`、`git_db_storage.rs`、`push_queue_service.rs` | —（FU-22） | `fu17_*` |
| FU-18 | #27 AC3/AC4（无残留写回、清扫终态）；Codex R2/R5 P0、R7 P1 | `import_repo.rs`、`push_queue_service.rs`、`import_service.rs`、`git_db_storage.rs`、`protocol/mod.rs`、`path_policy.rs`、`pack/mod.rs`、`import_api_service.rs`（调用点） | `trunk-push.md`、`errors.md` | `fu18_*`、`import_repo_leaf_*`、`import_root_push_rejected` |
| FU-19 | #27 AC4（无残留写回）；Codex R3 P0；`DEFER-FU-33` | `import_api_service.rs`、`git_db_storage.rs`、`common/errors/api.rs` | `directory-entry-api.md`、`errors.md`、`trunk-push.md` | `fu19_*` 六例 |
| FU-20 | #27 AC1–4/6；E8 | `src/api/router/import_repo_router.rs`、`src/api/router/mod.rs`、`src/api/api_router.rs`、`src/api/api_write_auth.rs`、`src/common/errors/api.rs`、`src/ceres/model/git.rs`（另：`import_repo.rs`、`lib.rs` 仅注释） | 契约页、`docs/errors.md` | `import_repo_remove_*` IT 六例 + lib 九例 |
| FU-21 | #27 AC1（`push_auth=none` 部署的授权清理） | `src/commands/`、`src/cli.rs`（SIGINT 记录）、`src/context/mod.rs` 与 `src/jupiter/storage/init.rs`（可见性） | —（FU-22） | `import_repo_remove_cli_*` + `import_repo_command_registered` |
| FU-22 | #26 AC1/6；#27 AC7 | 文档 | README、quick-start、user-guide | 文档门 |
| FU-23 | README 规则 7；完成门 | 索引 | `plan/README.md`、`plan-long.md` | 计划完成门 |

## 里程碑验收与回滚

| 里程碑 | 完成条件 | 发布/证据 | 回滚或前滚 |
|---|---|---|---|
| M0 | 计划 Codex 评审 PASS | Review log | N/A |
| M1 | FU-01..FU-03 complete | `v0.38.22`..`v0.38.24` + `docker` job 绿 | 前滚补丁版本 |
| M2 | FU-04..FU-11（含 FU-04A）complete | `v0.39.0`..`v0.40.0` + `docker` job 绿；FU-11 文档提交 | 前滚补丁/次版本；文档 revert |
| M3 | FU-12..FU-22 complete | `v0.40.1`..`v0.40.9`、`v0.40.11` + `docker` job 绿；FU-22 文档提交 | 前滚补丁版本；已清理的 ImportRepo 不可恢复（功能语义） |
| M4 | FU-23 complete；完成判据全勾（「计划完成门」于 2026-09-26 在 v0.40.13 最终树补跑通过，`ld` 链接提示按用户决定视为平台噪音） | `v0.40.12` + `docker` job 绿；索引与最终树完成门 | 前滚版本；索引 revert |

### 故障恢复矩阵

| 故障点 | 可接受残留 | 恢复动作 | 禁止结果 |
|---|---|---|---|
| 开通：prepare 与他人并发创建同一路径 | 无 | 重读；已为目录则 `created:false` | 重复目录项、500 |
| 开通：B3 CAS 失败 | 队列行 `Conflict`/重排 | 重 prepare + 重授权 | 部分写入的树、越权写 |
| 惰性物化：并发两次物化 | 无（`WHERE NOT EXISTS`） | 无需 | 两个 `main@/<root>` 行 |
| attach 分支 CAS 失败 | 新对象行已入库（可被下次推送复用） | 回滚到 savepoint（本批全部分支不更新），行终态 `Failed`，客户端 `IMPORT_REPO_STALE_REF` | 行残留 `Running`、部分分支前进 |
| tag CAS 失败 | 无 | 该 ref `ng`，其它 ref 独立 | tag 被静默覆盖 |
| detach：提交前任一步失败 | 无 | 整体回滚（含审计行），行终态 `Failed` | 叶子已删而 `git_repo` 仍在（或反之）、孤立审计行 |
| detach 已提交、清扫前崩溃 | 该 `repo_id` 的元数据行 | 同路径下次清理请求按台账 `(path, state='detached', id)` 游标续做，`audit_logs` 只作证据 | 该 `repo_id` 的元数据行存在而台账无对应 `detached` 行（或无审计行） |
| 陈旧会话或 API 请求在 detach 之后写 | 无（detach 之前写入的行已被清扫；之后的每批写取锁失败不落行） | 行锁栅栏拒绝（`IMPORT_REPO_REMOVED`），客户端重推即重新导入 | 叶子被重新挂载、任何行写入已删除仓库 |
| ref 写事务持锁时 detach 到达 | 无 | detach 等待该事务提交后再删除（其 ref 一并删除） | 清理后仍有 ref 行 |
| 清扫中途崩溃 | 部分元数据行 | 续做，按批幂等 | 删除其它 `repo_id` 的行 |
| 运维 CLI 在 detach 提交后被中断或失败 | `detached` 台账行与对象行 | stdout `interrupted` / `pending` 带 `cleanup_id`，`--cleanup-id` 续做；台账不可读时无句柄（`interrupted` 不带 id，或退出码 1 无结局行），按 `import_repo_cleanups (path, state='detached')` 取 id 后 `--cleanup-id` | 续做 detach 了存活仓库 |
| 运维 CLI 在 detach 提交前被中断 | 一条 Running / Queued 队列行 | 服务 reaper 终态化（Running 取锁后 2 s，Queued 15 s 心跳），重跑同一命令 | 仓库仍存活却输出 `removed` |
| 运维 CLI 被 SIGKILL / SIGTERM | 同崩溃点 | 按台账 `(path, state='detached')` 取 id 后 `--cleanup-id` | 续做 detach 了存活仓库 |
| 清理请求在 detach 之后、响应之前中断（客户端超时 / 断连） | 台账 `detached` 行与对象行 | 队列行由既有收养 / reaper 终态化；无存活仓库时只带 `path` 的新请求续做：预算内清扫完答 `absent`，否则以 `pending` 返回最小待续 `cleanup_id` | 续做请求 detach 了存活仓库 |

## 风险登记

| 风险 | 影响 | 缓解 | 任务 |
|---|---|---|---|
| 关闭 fork 型创建新顶层影响依赖该未文档化行为的用户 | 中 | ADR-FU-04 + `minor` + 错误列出允许根与开通动作 | FU-10 |
| 非法 `root_dirs` / `import_dir` 配置由「坏根树」或「推送新建顶层」变为启动失败 | 低：只影响已损坏或不一致的配置（`import_dir` 首组件不在 `root_dirs`） | 错误点名字段；三份自带配置回归（默认 `third-party` 同时在 `root_dirs` 中） | FU-04 |
| 合成 commit 字节变化导致跨版本物化 id 不一致 | 低 | 物化 `WHERE NOT EXISTS` 首写者胜；不改写存量 | FU-01..FU-03 |
| 惰性物化误触 `import_dir` 或 Monorepo 产品写落入 import 命名空间 | 高 | 无条件 import 命名空间守卫 + 分类 + GC-FU-04 + `api_write_import_namespace_guard`（含已物化 `/third-party` 与清理后状态） | FU-06 |
| 窄 token 经开通创建全局可见祖先 | 中 | 最高新建组件授权 + 重 prepare 重授权 | FU-07 |
| 原始客户端以非零 `old_id` 绕过创建白名单 | 高 | B3 既有「无行且非零 `old_id`」拒绝 + 真创建分支锁内再分类 + 原始推送测试 | FU-10 |
| 清理经前缀匹配误删兄弟仓库 | 高 | 绑定参数精确查找、转义子仓查询、零命中守卫；`import_repo_remove_exact_match_only` + 加宽零命中守卫（FU-20） | FU-17、FU-20 |
| 清理与子仓注册/attach 并发导致父删子留 | 高 | detach 先锁自身行再查子仓（FU-16）；子仓注册对祖先行取共享锁（FU-18），两锁互斥只有两种串行结局 | FU-16、FU-18 |
| 无鉴权部署出现匿名破坏性端点 | 高 | HTTP 清理只接受覆盖路径的 token、`push_auth=none` 一律 403；无鉴权部署走服务器侧 CLI（ADR-FU-10/11） | FU-20、FU-21 |
| 运维 CLI 改写运行中部署的 vault 密钥 / 生成默认配置 / 迁移共享库 / 运行第二套后台任务 | 高 | 轻量装配（不经 `AppContext::new`、不开 vault、只读确认 schema、写连接不迁移不播种）；`import_repo_remove_cli_requires_yes` 断言零表、无 base_dir、删去的 `queue_control` 行不被补回；每次 IT 运行断言密钥文件不变 | FU-21 |
| CLI 续轮、排空或中断续做 detach 了重新导入 | 高 | 第 1 轮之后只续做、按台账排空；`import_repo_remove_cli_absent`（重新导入存活时排空）、`import_repo_remove_cli_pending`、`import_repo_remove_cli_interrupted`（提交前 / 后中断）；屏障后读台账给出句柄，屏障与连接池关闭无确定性测试（`DEFER-FU-47`） | FU-21 |
| 未授权调用方经清理端点探测仓库存在性/拓扑 | 中 | 语法校验后、任何查询前鉴权；三类路径响应逐字节相同；体只由状态码决定、日志只含固定文本、断开的库证明鉴权前零查询 | FU-20 |
| 续做或重试 detach 了同路径的重新导入 | 高 | 续做只处理台账行（FU-17）；请求拒绝未知字段；契约页写明只带 path 的请求会 detach 当时存活的仓库 | FU-17、FU-20 |
| 陈旧 attach / tag / 删除 / 对象行 / API 写在清理后写回 | 高 | 行锁存活栅栏覆盖全部元数据写入（对象行与 receive-pack 写 FU-18、`ImportApiService` FU-19）；端点晚于栅栏发布 | FU-18、FU-19、FU-20 |
| 清理删除共享 blob | 高 | 不删对象字节；共享 blob 可读断言 | FU-17 |
| attach 挂载幂等误把普通目录当叶子 | 高 | 持久挂载来源记录为唯一依据，存量只按 `.gitkeep`-only + 已有分支 ref 规则回填；清理只移除有来源记录的叶子 | FU-13、FU-16 |
| 错误消息泄漏部署信息 | 中 | 只列根名称；脱敏单测 | FU-05 |
| Libra 与 Git 行为不一致 | 中 | 用户可见卡附 Libra 手工证据 | FU-01、FU-08、FU-10、FU-12 |
| 更新路径先于 CAS 上线 | 高 | FU-12（CAS）先于 FU-13（开放更新）发布 | FU-12、FU-13 |
| 发布期间远端 `main` 前进 | 中 | ER-09：integrate 后重跑 C 组；禁止 `--force` | 全部 |

## 性能与容量摘要

| 操作 | 单次成本 | 累积成本 | 预算/上限 | 验证 |
|---|---|---|---|---|
| 消息分解 / 成帧 | O(消息长度) | 与合成 commit 数成正比 | 无新增 I/O | 单测 |
| 首推路径分类 | O(depth) 根树解析 | 仅 `old_id=ZERO` 推送 | 无额外扫描 | `fu10_` |
| 开通 | O(depth) 树读 + ≤1 次落地 | 按请求 | 已存在时零写 | `path_provision_*` |
| 产品写分类与物化回落 | O(depth) + 一次锁内短事务 | 每个一级根至多一次物化 | — | `fresh_stack_*` |
| attach 更新 / CAS | 每个 ref 一次条件写 | 按推送 | 无树重写 | `fu12_`、`fu13_` |
| 存活栅栏 | 每个元数据写事务一次主键 `FOR SHARE` | 按推送 / API 写 | — | `fu18_`、`fu19_` |
| detach | O(1) 行删除 + O(depth) 树重写 | 按请求 | 锁内无按对象删除 | `fu16_` |
| 清扫与续做 | 每批 ≤ 1000 行；每请求 ≤ 100 批、≤ 16 条台账行 | 超出预算分多次请求（`pending`） | 锁外、每请求有界 | `fu17_sweep_bounded_and_complete`、`fu17_resume_budget_paginates`、`fu17_sweep_budget_pending` |

## 兼容与文档收口

- [x] `docs/errors.md`：`PathPolicyError`（FU-05、FU-11）；`MegaError::OrphanChain`（FU-09）；`ImportRepoError`（FU-12、FU-13、FU-18、FU-20，各在首次暴露时登记）。
- [x] `docs/refactoring/trunk-push.md`（FU-01、FU-02、FU-09、FU-10、FU-16、FU-18、FU-19）与 `docs/refactoring/directory-entry-api.md`（FU-07、FU-19、FU-20）已同步。
- [x] `config/config.toml` 与 storage-only 样例：不新增键；`root_dirs` / `import_dir` 注释写明形状约束（FU-04）。
- [x] 运行时 OpenAPI 证据：FU-07、FU-20。
- [x] `README.md` / `README.zh.md`：FU-11、FU-22；`AGENTS.md`：N/A。
- [x] `src/callisto/`、`src/jupiter/storage/`、`src/jupiter/migration/`：新增 `import_repo_cleanups` entity、迁移与 storage 原语（FU-14）；新增存量别名路径规范化数据迁移（FU-15，forward-only，冲突行保留并告警，`docs/deploy-trunk.md` 登记）；两者均在 `migrations()` 按序登记；其它 storage 新函数随 FU-12..FU-19。
- [x] 新引入的 `docs/*.md` 引用全部指向真实文件。
- [x] `plan-long.md` 日期计划索引已同步（FU-23）。

## Review log

Result 只允许 `PASS` 或 `FAIL`。`FAIL` 必须列出 P0/P1 条目并在下一轮复审关闭（ER-05）。

| Round | Scope | Result | P0/P1 | P2 处置 | Evidence |
|---|---|---|---|---|---|
| 计划 R1 | 初版全文（FU-01..FU-10） | FAIL | P0-1 清理 LIKE 查找越界；P0-2 detach 未对陈旧 attach 设栅栏；P0-3 detach 操作身份未域分离；P1-4 审计非事务、缺 actor 语义与关联 id；P1-5 tag 无 CAS / 逐 ref 语义未定义；P1-6 `root_dirs` 形状与 import 优先、祖先授权未定义；P1-7 消息文法缺字节级定义；P1-8 G-03 计数失真；P1-9 Verification 模块名/前缀/守卫不合规；P1-10 docs 卡 C/D 覆盖与 D 组 run 绑定缺失；P1-11 CLI 卡 scope 应为 M —— R1 修订关闭（R2 确认 P1-8、P1-9 仍未关闭，见 R2 行） | P2-12 测试 target 计数已改为 15 | `codex exec -s read-only`（codex-cli 0.155.1） |
| 计划 R2 | R1 修订全文（FU-01..FU-18） | FAIL | 未关闭：P1-8（AC 仍含复合谓词）、P1-9（「同上」式验证）；新增 P0-13 非零 `old_id` 绕过创建白名单；P0-14 tag 直写未对清理设栅栏；P1-15 #28 AC1 两对照无验证；P1-16 #29 产品写口径未覆盖；P1-17 文档卡 scope 应为 M —— R2 修订关闭（见修订历史） | P2-18 ADR 引用订正；P2-19 `root_dirs` 拒绝反斜杠 —— 已改 | `codex exec -s read-only` |
| 计划 R3 | R2 修订全文（FU-01..FU-19） | FAIL | 未关闭：R2-9（FU-01 根对照仍写「同上」）、R2-14（`ImportApiService` 直写未设栅栏，P0）；新增 P1：分支逐 ref 语义无实现路径 —— R3 修订关闭（见修订历史） | 无 | `codex exec -s read-only` |
| 计划 R4 | R3 修订全文 | FAIL | P0：子仓检查未与 detach 原子；P1：审查表「每个 ref 独立」措辞残留、清理端点先查后鉴权泄漏存在性、`save_file_edit` 未成帧、FU-16 事务范围不可执行需拆分、docs 卡守卫用全工作区状态 —— R4 修订关闭（见修订历史） | 无 | `codex exec -s read-only` |
| 计划 R5 | R4 修订全文（FU-01..FU-20） | FAIL | 未关闭：R4-2（子仓注册在 B3 之外，P0）、R4-3（403 回显路径）、R4-6（全局暂存集）；新增 P1：#29 AC5 API 面自定义根与第三类、`import_dir` 未拒 NUL —— R5 修订关闭（见修订历史） | 无 | `codex exec -s read-only` |
| 计划 R6 | R5 修订全文 | FAIL | P0：清理端点在 `push_auth=none` 下匿名可用；P1：FU-16 协议 smoke 非可执行命令 —— R6 修订关闭（见修订历史） | 无 | `codex exec -s read-only` |
| 计划 R7 | R6 修订全文（FU-01..FU-21） | FAIL | 未关闭：R6-P1 协议 smoke 仍不可通过；新增 P1：`swept` 之后陈旧对象行写入可永久残留 —— R7 修订关闭（见修订历史） | 无 | `codex exec -s read-only` |
| 计划 R8 | R7 修订全文 | FAIL | 未关闭：FU-16 smoke 缺 `service init --yes`；新增 P1：import 命名空间保护只在无非根 tip 时生效 —— R8 修订关闭（见修订历史） | 无 | `codex exec -s read-only` |
| 计划 R9 | R8 修订全文 | FAIL | P0：move 目的路径未受 import 守卫；目录存在不能证明挂载归属；更新路径先于 CAS 发布；P1：FU-04 应为 minor；D 组 run 查询无轮询 —— R9 修订关闭（见修订历史） | 无 | `codex exec -s read-only` |
| 计划 R10 | R9 修订全文 | FAIL | P1：续做依赖 `audit_logs` JSON 无界扫描；import 根本身可被推送注册且不可清理；FU-04 缺样例配置注释 —— R10 修订关闭（见修订历史） | 无 | `codex exec -s read-only` |
| 计划 R11 | R10 修订全文（FU-01..FU-22）+ 基线环境失败登记 | FAIL | P1：C 组 ③ 命令未与 `--no-fail-fast` 口径一致；FU-04 AC/VER 计数失真 —— R11 修订关闭 | 无 | `codex exec -s read-only` |
| 计划 R12 | R11 修订全文 | FAIL | P1：7 张卡 VER 计数偏低；路径别名拒绝缺原始输入不变量；叶子校验未拒 NUL；FU-17 compose 查找缺 `-p mega2-it`；C 组未覆盖迁移卡 —— R12 修订关闭 | 无 | `codex exec -s read-only` |
| 计划 R13 | R12 修订全文 | FAIL | P1：FU-07/FU-10 VER 计数；FU-04 storage-only 样例含 `${file:…}` 无法在宿主校验；评审先于发布的顺序未写明 —— 首次修订脚本失败未生效，R14 一并关闭 | 无 | `codex exec -s read-only` |
| 计划 R14 | R13 未生效的全文 | FAIL | R13 三项未关闭（修订脚本失败）；新增 P1：`traverses_tree_and_update_filepath` 未设栅栏；续做台账结果集无界 —— R14 修订关闭（见修订历史） | 无 | `codex exec -s read-only` |
| 计划 R15 | R14 修订全文 | FAIL | 未关闭：R14-5（台账索引缺 `id`，排序无界）；新增 P1：FU-17 写集缺 `path_policy.rs`；FU-15 依赖表述不一致；FU-22 `no-release` 自行 C 覆盖不合模板 —— R15 修订关闭 | 无 | `codex exec -s read-only` |
| 计划 R16 | R15 修订全文 | FAIL | P1：`ImportRepoError` 码的文档登记归属冲突且晚于暴露；FU-22 VER 计数 —— R16 修订关闭 | 无 | `codex exec -s read-only` |
| 计划 R17 | R16 修订全文 | FAIL | P1：FU-13 VER 应为 6/8（已改）；FU-19 VER 质疑——按计数口径逐项复核为 7：`api::`、`import_repo_remove_`、`delete_entry_reject_import_repo_409` 三条测试命令 + 零命中守卫 + 末项 `test -f` / `rg` / 人工核对三门 = 7，保持 7/8 | 无 | `codex exec -s read-only`；全卡 VER 以脚本按「环境前缀与命令合计一门、`&&` 分计、人工核对另计」复算，21 张卡与声明一致 |
| 计划 R18 | R17 修订全文 | FAIL | P0：只带 `path` 的续做可删除同路径重新导入的仓库；P1：严格前置别名拒绝会搁浅存量别名行 —— R18 修订关闭（见修订历史） | 无 | `codex exec -s read-only` |
| 计划 R19 | R18 修订全文（FU-01..FU-23） | FAIL | P1：FU-15 迁移无法读取 `import_dir` —— R19 修订关闭（迁移改为与配置无关、覆盖全部 `git_repo` 行，新增非默认 `import_dir` 回归） | 无 | `codex exec -s read-only` |
| 计划 R20 | R19 修订全文 | FAIL | P1：多处仍称「仅一个迁移」，release note 与兼容清单遗漏 FU-15 —— R20 修订关闭 | 无 | `codex exec -s read-only` |
| 计划 R21 | R20 修订全文 | FAIL | P1：`import_dir` 首组件可不在 `root_dirs`，ImportRepo 首推会新建顶层根 —— R21 修订关闭 | 无 | `codex exec -s read-only` |
| 计划 R22 | R21 修订全文（FU-01..FU-23） | **PASS** | 无 | 无 | `codex exec -s read-only`（codex-cli 0.155.1），2026-09-23；Phase 0 退出 |
| FU-01 R1 | FU-01 diff（utils.rs、trunk_provenance.rs、integration_git_cli.rs、trunk-push.md） | PASS | 无 | Claude 第二评审 4×P2：trunk-push.md §3.2 旧句、ADR-FU-01 类型文字、层头部不得含客户端 armor 的断言——均已修复并重跑 `signed_push_` 与 fmt；第 4 项（全量测试）由 C 组承担 | Codex `VERDICT: PASS`；Claude `VERDICT: PASS` |
| FU-02 R1 | FU-02 diff（materialize.rs、push_queue_service.rs、monorepo.rs 测试、trunk-push.md；含 FU-01 收尾） | FAIL | Codex 3×P1：attach 取主题与 ADR-FU-01 第 5 条字面不符；无用例覆盖生产 attach 调用；FU-01 收尾混入 | Claude PASS（6×P2：同上两项 + 未成帧根用例、测试模块 import 顺序、状态、diff 新鲜度） | 修订：ADR-FU-01 第 5 条澄清；新增 `fu02_attach_root_commit_uses_signed_tip_subject`（反向验证失败）；FU-01 收尾拆为 `b76d04d`；P2 全部落实 |
| FU-02 R2 | FU-02 全量 diff（R1 修订后） | PASS | 无 | 无 | Codex `VERDICT: PASS`；Claude R1 `VERDICT: PASS` |
| FU-03 R1 | FU-03 diff（mono_api_service.rs、mono_storage.rs、import_api_service.rs、utils.rs 测试、integration_api_write_trunk.rs、deploy-trunk.md） | PASS | 无 | Codex 1×P2：事实基线表仍列签名路径 `:964`（已改）；Claude 4×P2：`deploy-trunk.md` probe clone 需同时关 `fetch.fsckObjects`、`sed` 前加 `LC_ALL=C`、追溯表补 `import_api_service.rs`（均已改并实测）；blame 摘要对成帧消息取空行为既有缺陷（所有客户端推送的未签名 commit 同样），不在本卡轴内，另起任务（→ FU-04A） | Codex `VERDICT: PASS`；Claude `VERDICT: PASS` |
| FU-04 R1 | FU-04 diff（validate.rs、三份样例配置注释、configuration 双语、reload.rs / integration_vault.rs 测试数据） | FAIL | Codex P1：storage-only `import_dir` 注释缺 NUL / `\`；Claude P1：`root_dirs` 可与 `init_trees` 自带根条目重名（`.cedar` 等）仍生成坏根树；`monorepo-init.md` 与新行为相反 | Claude P2×7：`dotted_import` 用例因新校验空转（改断言）、NUL 规则无独立用例、正例改调 `validate_monorepo_config`、注释措辞（点号 / 段）、「增删根」措辞、首尾空白、兼容说明补 `import_dir` —— 全部落实 | 修订后进入 R2 |
| FU-04 R2 | FU-04 全量 diff（R1 修订后） | PASS | 无 | Claude 4×P2：初始化措辞、常量双向同步、粒度记账（均已修）；其余 Git 特殊名 → `DEFER-FU-11` | Codex `VERDICT: PASS`；Claude `VERDICT: PASS` |
| FU-05 R1 | FU-05 diff（errors/mod.rs、errors/api.rs、path_policy.rs、pack/mod.rs、errors.md） | FAIL | Codex P1：根名原样拼接可含换行，破坏单行 `ng` / 码契约 | Claude PASS（10×P2：分类接受 NUL、`[code:…]` 截断、裸类型 500、开通命令路径未转义、守卫原语未导出、嵌套 `import_dir` 祖先物化、文档类型表 / 措辞、字面码断言、嵌套边界断言）—— 全部落实 | 修订后进入 R2 |
| FU-05 R2 | FU-05 全量 diff（R1 修订后） | PASS | 无 | Codex 1×P2：证据中多过滤器命令的可复现性（已补完整命令：`--` 之后的多个过滤器由 libtest 取并集） | Codex `VERDICT: PASS`；Claude R1 `VERDICT: PASS` |
| FU-06 R1 | FU-06 diff（mono_api_service.rs、integration_api_write_trunk.rs、deploy-trunk.md、directory-entry-api.md） | FAIL | Codex P1：嵌套 `import_dir` 祖先不物化的行为未入文档 / 无用例；Claude P1：文档称存活 ImportRepo 内的写也被 400 拒绝（实为分派给 `ImportApiService`） | Claude P2×7：用例对守卫证明不足、错误点名 `/`、`\` 名误拒、文档残留与错误表、ADR-TP-10 描述、GC-FU-04 其它缺口、开通命令未上线 —— 全部落实（第 7 项登记 `DEFER-FU-13`） | 修订后进入 R2 |
| FU-06 R2 | FU-06 全量 diff（R1 修订后） | PASS | 无 | Codex 1×P2：存活挂载叶子经父级 delete / move 也返回 400 的文档区分与用例；Claude 4×P2：开通提示路径、非法顶层名、文档措辞与注释、记账 —— 全部落实，代码改动交 R3 复核 | Codex `VERDICT: PASS`；Claude `VERDICT: PASS` |
| FU-06 R3 | R2 之后的代码改动（开通提示路径、非法顶层名映射、存活叶子用例、文档措辞） | PASS | 无 | Codex 2×P2：`\` 顶层名回归用例、`errors.md` 注明守卫也产生 `NotAllowed` / `Invalid`（均已补） | Codex `VERDICT: PASS` |
| FU-07 R1 | FU-07 diff（开通服务、DTO、路由、测试、契约页） | FAIL | Codex P0：apply 独立重读树，计划后删除容器可越权创建祖先；Codex P1 / Claude P1：计划后出现的同名文件未判冲突、多级重名路径被子串推导破坏 | Codex P2：重试靠字符串 `[code:4`；Claude P2×8：丢失更新窗口、重试分类、同名 blob、新增根与嵌套祖先的限制、契约页缺项、记账、测试缺口、空行 —— 全部落实（新增根 → `DEFER-FU-14`） | 修订后进入 R2 |
| FU-07 R2 | FU-07 全量 diff（R1 修订后） | FAIL | Codex P1：重试仍按子串（路径可拼出 `non-fast-forward` 使 409 变 500）；「恰一个 `created:true`」无保证（同 commit 被队列重放） | Codex P2：严格入口放行控制字符；Claude PASS（5×P2：措辞、重试集合与误判、`None` 计划越界、tip 移动用例、新根互指）—— 全部落实 | 修订后进入 R3 |
| FU-07 R3 | FU-07 全量 diff（R2 修订后） | PASS | 无 | 无 | Codex `VERDICT: PASS`；Claude R2 `VERDICT: PASS` |
| FU-08 R1 | FU-08 diff（path.rs、mod.rs、cli.rs 测试、integration_git_cli.rs） | FAIL | Codex P1：错误路径可泄露 URL 凭据与服务端反射的 token；响应体无上限；代理绕过无真实回归 | Codex P2：成功响应未校验契约；Claude PASS（11×P2：传输错误原因、超时断言、URL query / 凭据、token 读取、非 JSON 体、重定向文案、测试缺口、不读配置反证、测试服务器读取、Ctrl-C 退出码、构建错误前缀）—— 全部落实（Ctrl-C → `DEFER-FU-15`） | 修订后进入 R2 |
| FU-08 R2 | FU-08 全量 diff（R1 修订后） | PASS | 无 | Codex 1×P2：测试 HTTP 服务线程分离、socket 留到进程结束 —— 改为带 `Drop` 的 `TestServer`（停止标志 + 自连唤醒 + `join`），超时用例的持有线程有界并 join | Codex `VERDICT: PASS`；Claude R1 `VERDICT: PASS` |
| FU-04A R1 | FU-04A diff（blame_ops.rs + 计划插卡） | FAIL | Codex P1：无真实 blame 路径回归；Lifecycle / Acceptance 字段错位；一条 AC 合并两个回归；Phase 2 退出条件漏 FU-04A；Claude P1：新依赖边与 FU-09 / FU-04A 卡字段不一致（G-06） | Claude P2×5：未成帧多行历史消息展示变化未记录并补用例、手工证据取到 PGP 签名层 commit 不能区分新旧（改为 ImportRepo 未签名推送）、Out of scope 理由错误（→ `DEFER-FU-16`）、AC 措辞与 PGP 反向验证原因、字段格式 —— 全部落实 | 修订后进入 R2 |
| FU-04A R2 | FU-04A 全量 diff（R1 修订后：blame_ops.rs、integration_api_write_trunk.rs、计划） | PASS | 无 | Claude 2×P2：`DEFER-FU-16` / Out of scope 的外露头措辞、多行历史用例注释 —— 均已落实（仅文字与注释） | Codex `VERDICT: PASS`（无发现）；Claude `VERDICT: PASS` |
| FU-09 R1 | FU-09 diff（push_chain.rs、monorepo.rs 测试、integration_git_cli.rs、trunk-push.md） | FAIL | Codex P1：孤儿错误以 `MegaError::Other` + 文本匹配识别，与 `monorepo.rs` 同文本错误不可区分，未真正类型化 | Claude PASS（审阅已含 `OrphanChain` 的工作树；7×P2：孤儿措辞按情形区分、额外 commit 绕过（→ `DEFER-FU-17`）、IT 断言交接 FU-10、review 用例改走准入门、证据刷新与 `errors.md` 登记、`from_known_tip` 注释、不可达同文本分支（不改））—— 落实 | 修订后进入 R2 |
| FU-09 R2 | FU-09 全量 diff（R1 修订后，基线已含 FU-04A 与用户文档整合） | PASS | 无 | Codex 1×P2：注释「每次重试」过宽；Claude 3×P2：FU-10 未指向 `DEFER-FU-17`、收口清单漏 `OrphanChain`、文档小节位置与措辞 —— 全部落实（仅注释与文档） | Codex `VERDICT: PASS`；Claude `VERDICT: PASS` |
| FU-10 R1 | FU-10 diff（monorepo.rs、push_queue_service.rs、mono_api_service.rs 测试数据、integration_git_cli.rs、trunk-push.md、errors.md） | FAIL | Codex P1：证据中的库回归含一次失败（`tp12` 修正后只单独重跑），fmt 无证据 | Codex P2：B3 用例未断言失败类别；Claude PASS（8×P2：竞态 `ng` 行码不在行首、非创建孤儿无用例、尾斜杠说明错误、原始推送断言过弱、`DEFER-FU-14` 说明、两个既有边界（→ `DEFER-FU-19`/`DEFER-FU-20`）、计划一致性、注释）—— 全部落实 | 修订后进入 R2 |
| FU-10 R2 | FU-10 全量 diff（R1 修订后）+ 按终态完整重跑的证据 | PASS | 无 | Claude 3×P2：`map_err` 接线无端到端用例（已改用 `finalize_trunk_push` 并反向验证）、`Rejected` 形式消息（不可达，不采纳）、clippy 退出码记录（C 组门覆盖） | Codex `VERDICT: PASS`（无发现）；Claude `VERDICT: PASS` |
| FU-11 R1 | FU-11 diff（README、quick-start、user-guide、初始化手册、errors.md） | FAIL | Codex P1：README 首推说法过宽；quick-start `PORT` 双赋值；使用指南复制错误契约表；`INVALID` 的 Git 面场景（经代码与实测不采纳，见修订历史） | Claude PASS（10×P2：端口选择、镜像版本、首推表与重试措辞、产品写 / 新根限定、`CONFLICT` 与 ImportRepo 标注、英文链中文、README、手册白名单、link-don't-copy、证据与越界文件）—— 全部落实 | 修订后进入 R2 |
| FU-11 R2 | FU-11 全量 diff（R1 修订后） | PASS | 无 | Claude 4×P2：`CONFLICT` 来源、中英 HTTP 条目漂移、长度上限覆盖面与重试措辞、证据陈旧 —— 全部落实（仅文字）；Claude 同意不采纳 Codex R1 的 `INVALID` 条目 | Codex `VERDICT: PASS`（无发现）；Claude `VERDICT: PASS` |
| FU-12 R1 | FU-12 diff（errors/mod.rs、api.rs、git_db_storage.rs、push_queue_service.rs、import_repo.rs、errors.md） | FAIL | Codex P1：只含删除的分支批删除默认分支后不补默认；`.gitkeep` 在分支 CAS 之前写入、陈旧批留下孤儿 blob | Claude PASS（9×P2：`edit/save` 无条件写（→ `DEFER-FU-22`）、`errors.md` 包装措辞、用例缺口、CAS 顺序、描述措辞、unpack 失败写 tag（→ `DEFER-FU-21`）、AGENTS.md 版本（不在写集）、`already exists` 文本、变量名）—— 落实 | 修订后进入 R2 |
| FU-12 R2 | FU-12 全量 diff（R1 修订后）+ 三组反向验证 | FAIL | Codex P1：评审证据缺全量 `cargo test --all`、`cargo build`、`cargo build --tests` | Claude PASS（4×P2：Verification / 兼容说明滞后、`DEFER-FU-22` 的 tag 删除、零 id 判断复用（保留）、StaleRef 含义措辞）—— 落实 | 补跑三门后进入 R3 |
| FU-12 R3 | FU-12 全量 diff + bump 前树上的 AGENTS.md 三门证据（18 target、1898 通过、失败集恰为 6 个基线环境用例；`cargo build` 0 警告） | PASS | 无 | 无 | Codex `VERDICT: PASS`（无发现）；Claude R2 `VERDICT: PASS` |
| FU-13 R1 | FU-13 diff（audit_storage.rs、tree_ops.rs、push_queue_service.rs、import_repo.rs、integration_git_cli.rs、errors.md） | FAIL | Claude P1：同一组分支命令在更新 / 强推 / 删除后再次出现时被 Done 重放静默吞掉（客户端 ok、ref 不动，已实测复现） | Codex PASS（无发现）；Claude P2×6：ADR 预检措辞、嵌套先子后父（→ `DEFER-FU-23`）、`errors.md` 场景、用例缺口、`requester` 恒空与重复记录、全量三门证据 —— 全部落实 | 修订后进入 R2 |
| FU-13 R2 | FU-13 全量 diff（R1 修订后）+ bump 前树上 AGENTS.md 三门 + 反向验证 D | FAIL | Codex P1：全量有 6 个失败与 1 条 `build --tests` 提示（经核对为 DEP-FU-05 登记的基线环境项，不采纳，见修订历史） | Codex P2：父仓库更新未断言 ref 前进；Claude PASS（3×P2：回落文本前缀、Verification 覆盖、证据标注）—— 全部落实 | 进入 R3 |
| FU-13 R3 | FU-13 全量 diff（R2 修订后）+ DEP-FU-05 口径说明 | FAIL | Codex P1：未归类的 B3 失败文本原样外露给客户端（可能泄露存储内部信息） | 无 | 修订后进入 R4（Claude R2 已 PASS；本轮改动只收窄客户端文本） |
| FU-13 R4 | FU-13 全量 diff（R3 修订后） | FAIL | Codex P1：只含删除的分支批绕过 B3（GC-FU-03）；来源记录查询无界（GC-10） | 无 | 修订后进入 R5（Codex + Claude） |
| FU-13 R5 | FU-13 全量 diff（R4 修订后）+ 反向验证 E | FAIL | Codex P1：来源记录查询的索引覆盖（不加迁移，给规模与 `EXPLAIN` 断言）；重放核对读全部 ref（已改为按名）；拒绝原因写日志（已去除，队列表原文 → `DEFER-FU-24`） | 无 | Claude R5 PASS（3×P2：删除批不应经归属门（回归，已改）、证据标注、Verification 覆盖）；修订后进入 R6 |
| FU-13 R6 | FU-13 全量 diff（R5 修订后） | FAIL | Codex P1：64 位零 id 的删除被 B3 误判为非删除（已改用 `is_protocol_zero_id` 并加用例） | Codex P2：证据残留旧用例名（已重跑）；Claude R6 PASS（3×P2：写集文件数、删除批经物化预检（回归，已改）、64 位零 id（同 Codex P1））—— 全部落实 | 修订后进入 R7 |
| FU-13 R7 | FU-13 全量 diff（R6 修订后，8 个文件逐文件对 HEAD 生成）+ 反向验证 F / G / H | PASS | 无 | Codex `VERDICT: PASS`（1×P2：来源记录字段断言，已落实）；Claude R6 `VERDICT: PASS`（3×P2，已落实）、R7 `VERDICT: PASS`（1×P2：tip 查找用例，已落实） | 进入 C 组 |
| FU-14 R1 | FU-14 diff（6 个文件，2 个新文件对 `/dev/null`） | FAIL | Codex P1：`down` 先查后删竞态、页大小断言由常量推导、证据缺 `source .env.test &&` 前缀 | Codex P2：未验证重复执行 `up`；Claude PASS（3×P2：同页大小断言、竞态用例固定等待不稳、同证据前缀）—— 全部落实 | 修订后进入 R2 |
| FU-14 R2 | FU-14 diff（R1 修订后）+ 无并发变异树上的证据与反向验证 A–E | PASS | 无 | Codex `VERDICT: PASS`（无发现）；Claude `VERDICT: PASS`（无发现，只读复核） | 进入 C 组 |
| FU-15 R1 | FU-15 diff（5 个文件，新迁移对 `/dev/null`） | FAIL | Codex P1：改写扫描未锁表（并发插入可被漏掉或撞唯一约束）、运维说明把冲突流程套用到 `invalid`；Claude P1：冲突别名行仍被 Web / API 最长前缀查找命中，文档「不再被服务」不准确 | Codex P2：`invalid` 无用例；Claude P2×6：别名 URL 未测、`invalid` 无用例、WARN 内容未断言、升级模拟保留了来源记录、并发写（同 Codex P1）、`invalid` 措辞 —— 全部落实 | 修订后进入 R2 |
| FU-15 R2 | FU-15 diff（R1 修订后）+ 反向验证 A–E | FAIL | Claude P1：WARN 捕获混入 sqlx 慢语句 WARN，负载下偶发失败 | Codex `VERDICT: PASS`（无发现）；Claude P2×3：子仓排除只写在 FU-16 卡、预置 SQL 未断言命中、`pg_locks` 未限定数据库 —— 全部落实 | 修订后进入 R3 |
| FU-15 R3 | FU-15 diff（R2 修订后）+ 冲突用例重复与负载复测 | PASS | 无 | Codex `VERDICT: PASS`（无发现）；Claude `VERDICT: PASS`（负载下冲突用例 30/30 通过；1×P2 措辞，已落实） | 进入 C 组 |
| FU-16 R1 | FU-16 diff（7 个文件，逐文件对 HEAD 生成）+ 反向验证 A–E | FAIL | Codex P1：存量规则读全部分支 ref（已改为有界 EXISTS）；`.gitkeep` 的 `mega_blob` 行逃过回滚（已改入事务）；单测不清理 schema（不采纳按卡守卫：全套件 helper 约定，→ `DEFER-FU-25` + 另起任务） | Codex P2：`lib.rs` 注释错位、操作 id 无固定向量 —— 已落实；Claude `VERDICT: PASS`（5×P2：detach 重放核对、`.gitkeep` 服务级用例、伪码条目顺序、失败日志的 `op`、常量位置 —— 全部落实） | 修订后进入 R2 |
| FU-16 R2 | FU-16 diff（8 个文件）+ 反向验证 A–I | FAIL | Codex P1：重放可交出无台账行的裸队列 id；`import_dir` 本身的存量行 detach 会删掉 import 根 | Codex P2：Lifecycle 命令计数措辞 —— 全部落实；Claude R2 见下一行 | 修订后进入 R3 |
| FU-16 R3 | FU-16 diff（8 个文件）+ 反向验证 A–K | FAIL | Codex P1×2：子仓检查与分支存在检查无专用索引（不采纳新增迁移：GC-10 规模 + `fu16_lookups_bounded_at_scale`，→ `DEFER-FU-27`） | Claude `VERDICT: PASS`（1×P2：FU-17 卡登记台账读侧收口义务 —— 已落实） | 修订后进入 R4 |
| FU-16 R4 | FU-16 diff（8 个文件）+ 反向验证 A–K + 规模用例 | FAIL | Codex P1：锁内 ref 删除以该仓库 ref 数为界而非 O(1)（保留事务内删除；订正预算、规模用例加 EXPLAIN 与 1000-tag detach、`DEFER-FU-28`） | Codex P2：根 commit 消息未断言（已加）；Claude R4 见下一行 | 修订后进入 R5 |
| FU-16 R5 | FU-16 diff（8 个文件）+ 反向验证 A–L | PASS | 无 | Codex `VERDICT: PASS`（2×P2：等锁判定的特异性、`DEFER-FU-25` 措辞 —— 已落实）；Claude R4（中间结果：生产代码自 R3 未变、四条 Verification 与 fmt / clippy 通过）+ R5 `VERDICT: PASS`（认可 ref 删除留在 detach 事务内；2×P2：EXPLAIN 断言去掉 `enable_seqscan = off`、改由放在诱饵仓库上的 1000 个 tag 让规划器自行选索引（用例只读修订，双方 PASS 后落实）；提交只含 8 个文件 —— 已落实） | 进入 C 组 |
| FU-17 R1 | FU-17 diff（4 个文件）+ 反向验证 A–F | FAIL | Codex P1：`pending` 可能指向已被并发清扫者完成的行（已改为重读台账） | Codex P2：共享 blob 用例未经读路径核实、`latest_cleanup_for` 的排序不受索引约束 —— 已落实；独立评审（工作流：5 维查找 + 3 反驳者核实）见下一行 | 修订后进入 R2 |
| FU-17 R1（独立） | 同一 diff + 反向验证 A–F（工作流：5 个维度查找、每条发现 3 名反驳者、裁决 agent 复跑卡片命令） | FAIL | Claude P1：`EXISTS` 探测无强制走索引的计划形态（generic 计划可为顺序扫描）—— 改为唯一索引 top-1，两种计划的 EXPLAIN 钉住 | Claude P2 ×11：覆盖缺口（16 条上限计本次 detach、并发/受阻批、落败分支、行间预算耗尽与预算 0、`git_tag` 字面量、B3 类型化拒绝）→ 新增 5 个具名用例与 3 处既有用例扩展；`rows_deleted` 证据语义与 `from_json` 注释；计划三处措辞 —— 全部落实 | 修订后进入 R2 |
| FU-17 R2 | FU-17 diff（4 个文件，R1 修订后）+ 反向验证 A–L + R1→R2 增量 | PASS | 无 | Codex 1×P2：`latest_cleanup_for` 的 `repo_id` 过滤不受索引约束 —— 与工作流「未闭环」同一条，R3 落实 | Codex `VERDICT: PASS`；独立评审见下一行 |
| FU-17 R2（独立） | 同一 diff（工作流：4 组 R1 闭环核查 + 5 维新查找 + 每条 3 反驳者 + 裁决 agent 复跑卡片命令） | FAIL | Claude P1：分批子查询无强制走 `repo_id` 前导索引的计划形态（高占比自定义计划为顺序扫描）；R1 一条未闭环（`latest_cleanup_for` 去掉排序未去掉扫描、EXPLAIN 未在规模上钉住） | Claude P2 ×5：续做范围、共用预算、探测钉住措辞与断言、回归计数、受阻批语句数 —— 全部落实（R3） | 修订后进入 R3 |
| FU-17 R3 | FU-17 diff（4 个文件，R2 修订后）+ 反向验证 M–O、H + R2→R3 增量 | PASS | 无 | Codex 1×P2：整页 64 条别名保守视为有子仓 —— 不采纳（理由见变更记录，`DEFER-FU-10` 补记） | Codex `VERDICT: PASS`；独立评审见下一行 |
| FU-17 R3（独立） | 同一 diff（工作流：4 组 R2 闭环核查 + 5 维新查找 + 每条 3 反驳者 + 裁决 agent 复跑卡片命令；首轮因用量上限中断后续跑） | FAIL | R2 一条未闭环（落空分支「需要测试钩子」的理由不成立） | Claude P2 ×8：计划形态只钉住 `git_blob`、`git_commit` / `git_tree` 的 generic 计划可排序（1 名反驳者判 P1）、generic 钉住未绑定 InitPlan、注释「任何统计量下」过度声称、台账回退的界与计划模式、反向验证 O 记录、诱饵行数、「≤ 1000/占比」上界、`latest_cleanup_for` 两次查询 —— 全部落实（其中台账回退的计划模式措辞与 `DEFER-FU-27` 的界在 R4 仍未闭环，R5 补齐）（R4：清扫步骤的计划器设置、外层主键防护、四表计划钉住与零顺序扫描断言、落空分支用例） | 修订后进入 R4 |
| FU-17 R4 | FU-17 diff（4 个文件，R3 修订后）+ 反向验证 P–U、H + R3→R4 增量 | PASS | 无 | Codex 2×P2：清扫接受调用方事务时 `SET LOCAL` 泄漏到外层事务、快照随其隔离级别；探测断言未要求 `repo_id` 索引条件 —— R5 落实 | Codex `VERDICT: PASS`；独立评审见下一行 |
| FU-17 R4（独立） | 同一 diff（工作流：4 组 R3 闭环核查 + 5 维新查找 + 每条 3 反驳者 + 裁决 agent 复跑卡片命令；首轮因会话用量上限中断后续跑） | FAIL | R3 两条未闭环（台账回退的计划模式措辞、`DEFER-FU-27` 的界与来源） | Claude P2 ×8：外层事务模式下零顺序扫描断言只抓全部绕过、泛型签名允许事务调用方、受阻批的另一清扫者不在设置下、反向验证 S 记录有误（未访问三仓库 ANALYZE 状态）、探测未要求 `Index Cond`、统计状态与占比措辞、R3 记账、入口注释 —— 全部落实（R5） | 修订后进入 R5 |
| FU-17 R5 | FU-17 diff（4 个文件，R4 修订后）+ 反向验证 P–W、U、H + R4→R5 增量 | PASS | 无 | 无 | Codex `VERDICT: PASS`（单连接计数方式经核实：另一后端只会造成误报、不能掩盖清扫的顺序扫描）；独立评审见下一行 |
| FU-17 R5（独立） | 同一 diff（工作流：4 组 R4 闭环核查 + 4 维新查找 + 每条 3 反驳者 + 裁决 agent 复跑卡片命令） | PASS | 无 | Claude P2 ×6：设置随步骤结束未钉住、单连接池手工构建、回退来源与最坏情形措辞、刷新注释、R4 变更行范围列 —— 全部落实（反向验证 X） | Claude `VERDICT: PASS` |
| FU-18 R1 | FU-18 diff（12 个文件）+ 反向验证 R1–R14 | FAIL | Codex P1：B3 首次挂载在持锁时借用第二个池连接（既有，不采纳，`DEFER-FU-36`） | Codex P2 ×3：提交时错误的重试、预检顺序、IT 四表断言 —— 落实；独立评审因周用量上限未运行 | 修订后进入 R2 |
| FU-18 R2 | FU-18 diff（R1 修订后）+ R1→R2 增量 | PASS | 无 | Codex 1×P2：Lifecycle 中 R4 的旧结论与重跑结论并存 —— 已改为最终结论 | Codex `VERDICT: PASS`（P1 的不采纳理由未被再提）；独立评审见后续行 |
| FU-18 R1（独立） | FU-18 diff（R1 修订后，工作流：5 维查找 + 每条 3 反驳者 + 裁决 agent 复跑卡片命令；首次因周用量上限未运行） | PASS | 无 | Claude P2 ×12：锁序注释、重试无用例、SSH 相对路径范围、`removed_or` 调用点、树 `unwrap`、锁模式、追溯表、SSH 文本、`reason` 措辞、过时锚点、A 组规则、性能预算 —— 全部落实（反向验证 R15–R19） | Claude `VERDICT: PASS` |
| FU-19 R1（独立） | FU-19 diff（7 个文件）+ 反向验证 R1–R19（工作流：5 维查找 + 每条 3 反驳者 + 裁决 agent 复跑卡片库测试命令；首轮输入 diff 曾在反向验证 R3 生效时生成，已按还原后的树重新生成） | FAIL | Claude P1：Verification 称四个写事务各自先持锁，`fu19_api_lock_serializes_with_detach` 只覆盖三个（缺 lightweight tag）—— Part A 增 `light` 缝 | Claude P2 ×13：errors.md `Removed` 行与两段式设计不符、兼容说明「tag 路由此前为 500」不实（→ `DEFER-FU-40`）、三处注释（写集加两个仅注释文件）、同名 tag 并发创建与删除竞态（既有，→ `DEFER-FU-41`）、写落在带锁事务无用例（Part A，反向验证 R20–R22）、生产 `save_file_edit` 的 ref 写调用点（Part C，R23）、根树 `NotFound`（R24）、tag 用例补同路径重新导入阶段、VER 订正为 8/8、ADR-FU-03 第 4 条的 409 归属、`DEFER-FU-22` 多一格、收口清单与设计定稿行修订范围、别名假 409 补注 `DEFER-FU-10` —— 全部落实（1 条有据延后） | 修订后进入 R2；Codex R1 因用量上限未运行（重置后补跑，见后续行）；证据按终态以 R1–R24 重跑 |
| FU-19 R2（独立） | FU-19 diff（9 个文件，R1 修订后）+ 反向验证 R1–R24 + R1 闭环核查 | PASS | 无 | Claude P2 ×11：`ImportRepoError::http_status` 注释与写集说明的归属（对象批 FU-18，预读 / ref / tag 写 FU-19）、live tag `TagInfo` 无断言、`delete_tag_in_txn` 仓库过滤与 lightweight 删除（R25）、edit/save 写顺序（R26）、`DEFER-FU-32` 补 API 共享锁持有者、AC8 收为单谓词、G-04 计数订正为 landing=3 / prod-files=3、ADR-FU-03 第 4 条、修订历史 R1 行修订范围 —— 9 条落实；`map_ceres_error` 409 分支再解析 `[code:`、edit/save 新 404 文本不含「not found」—— 不采纳（与既有 400 / 404 分支及 FU-18 已发布文本一致） | Claude `VERDICT: PASS`（R1 的 P1 与 13 条 P2 中的 12 条经复核已关闭或有据延后，第 3 条的修订重新引入日期错误、作为本轮第 1 条修正）；证据按终态以 R1–R26 重跑 |
| FU-19 R1 | FU-19 终态 diff（9 个文件，独立评审 R2 修订后） | PASS | 无 | 无 | Codex `VERDICT: PASS`（无发现；首次因用量上限未运行，22:28 重置后补跑）；进入 C 组 |
| FU-20 R1 | FU-20 diff（12 个文件）+ 反向验证 R1–R22（独立评审工作流：5 维查找 + 每条 3 反驳者 + 裁决 agent 复跑卡片库测试） | FAIL | Claude P1：`import_repo_remove_pending_continuation` 中「属于另一路径的 `cleanup_id` 不改台账」在该行已 `swept` 后才断言，无法失败 —— 改到首个 `pending` 之后、重新导入之前，并断言对象行不变（新反向验证：入口去掉路径归属条件即失败） | Codex 无发现；Claude P2 ×12：409「无写」措辞（队列锁内再检留一行 `Failed` 队列行）、丢失 `cleanup_id` 后只带 path 的结局、OpenAPI `repo_id` / `cleanup_id` 未 required、`populated_then_absent` 未先断言叶子存在、Verification「任何查询都会 panic」、路由挂载只经 OpenAPI 锁定（新增 `import_repo_remove_live_surface`）、结尾空白、errors.md 新行竖线未转义、「只带 `cleanup_id`」措辞、行号锚点、「鉴权前不写日志」范围（`DEFER-FU-43`）、「全部为绑定参数的精确查找」—— 全部落实 | Codex `VERDICT: PASS`（审修订前 diff；npm 版缺平台二进制，改用 `/Applications/ChatGPT.app` 自带的 codex-cli）；Claude FAIL；修订后进入 R2，证据按终态以 R1–R25 重跑 |
| FU-20 R2 | FU-20 diff（12 个文件，R1 修订后）+ 反向验证 R1–R25 | PASS | 无 | Codex 无发现；Claude P2 ×5：`populated_then_absent` 删除后的叶子断言在 GET /tree 非 200 时也通过（改用断言 200 的 `tree_names`）、无用例钉住交给鉴权的是目标路径（只覆盖叶子的 token，反向验证 R26）、修订历史 R1 行竖线未转义、追溯表「lib 九例」、修订历史 R1 行反向验证范围 —— 全部落实 | Codex `VERDICT: PASS`；Claude `VERDICT: PASS`；证据按终态以 R1–R26 重跑；进入 C 组 |
| FU-21 R1 | FU-21 diff（7 个文件）+ 反向验证 R1–R22 | FAIL | Codex P1：写连接用 `database_connection`，只读确认后仍会跑迁移并补 `queue_control` 种子行 —— 改用 `postgres_connection`（写集加 `init.rs` 仅可见性），零命中守卫加 `\bdatabase_connection` / `ensure_queue_control_seed`；Claude P1：排空轮没有能失败的测试 —— `absent` 增三行匿名 detach + 存活重新导入阶段，`--max-rounds 1` 停于排空、`--cleanup-id` 排空其余而重新导入不动 | Codex P2 ×2：case 目录清理 —— 落实（作用域守卫，含 panic）；配置路径回显 —— 不采纳（操作者自己点名的路径，GC-FU-05 补范围说明）；Claude P2 ×14：未类型化失败映射、`pending` 句柄 stderr 措辞、`resume_handle` 机制注释与超时 / `live_before` 窄窗、`assemble` 租约续期、卡片安全与性能预算、`cli.rs` 注释归位与位置参数用例、`latest_cleanup_for` 注释（写集加 `git_db_storage.rs` 仅注释）、「台账不可读」结局、屏障等登记 `DEFER-FU-47`、FU-23 交接改登记 `DEFER-FU-48` —— 全部落实 | 修订后进入 R2（反向验证增至 26 项） |
| FU-21 R2 | FU-21 diff（9 个文件，R1 修订后）+ 反向验证 R1–R26 | PASS | 无 | Codex 1×P2：`Fu21Child` 在 panic 时留下 CLI 子进程（与 Claude 同一条）；Claude P2 ×6：`Resume::Unknown` 的 stderr 文本未断言（抽为 `ledger_unreadable` 并断言）、连接池维护任务的描述、`Fu21Hold` / `Fu21Child` 加 `Drop`、故障恢复矩阵补台账不可读、排空对象为该路径「其余」`detached` 行、零命中守卫补 `Migrator` 的 up / down / fresh / refresh / reset —— 全部落实 | Codex `VERDICT: PASS`；Claude `VERDICT: PASS`；进入 C 组（发布前 rebase 到 origin/main，远端改动与本卡文件无交集，ER-05 结论不变） |
| FU-22 R1 | FU-22 diff（8 个文件：README、quick-start、user-guide 各双语，errors.md，本计划） | FAIL | Codex P1 ×4 + Claude P1 ×3：兼容性与嵌套缺存量例外（两方）—— 补只含 `.gitkeep` 的存量挂载补齐来源、嵌套与无分支存量挂载以 `IMPORT_REPO_PATH_OCCUPIED` 拒绝；清理期间的推送（Claude）—— 只有摘除时进行中的推送得 `IMPORT_REPO_REMOVED`；`exec -T` 下 Ctrl-C 只结束 compose 客户端（Claude，alpine 复现）—— 130 限于前台直接运行；HTTP 与 CLI 的 `removed` 语义（Codex）；再次推送示例（Codex）—— 改为具体新提交与 annotated tag、`--mirror` 同步（实测）；quick-start 的 `interrupted` 指引（Codex）—— 只对 `pending` 给 `--cleanup-id` | Codex P2 ×3 + Claude P2 ×13：STALE_REF 与 `fetch first` 先后、CAS 限于推送、退出码 1 前缀与结局行有无、台账查询为空的含义、compose 占位符补 `-p`、裸机沿用 `--profile` 与 `MEGA_*`、前提补「服务正在运行」、版本门补 0.40.2、「一律 403」限于合法请求、errors.md PathInvalid 时点等 —— 全部落实 | 修订后进入 R2 |
| FU-22 R2 | FU-22 全量 diff（R1 修订后） | FAIL | Claude P1：存量兼容的补救不成立（detach 只移除属于该仓库的挂载，无分支存量挂载清理后占位目录保留、重推仍被拒）—— 改为「改用其它路径」并登记 `DEFER-FU-49`，嵌套父仓库只需清理子仓库；Codex P1 ×3：被拒后的恢复（`git fetch`、合并或变基、`--force`）、`.git` 后缀（`--path` 精确匹配存储路径，Git URL 去掉 `.git`）、写入队列范围（AC-9：限定 Monorepo 路径，存活 ImportRepo 内 `edit/save` 不经队列，`DEFER-FU-22`） | Codex P2 ×3 + Claude P2 ×4：排空只在主清理完成之后、2.3「一律 403」补合法请求、台账查询改 Compose `psql` 与 `docker compose top`（测试栈原样执行通过）、`--mirror` 覆盖 mega2 独有 ref 的提醒与 LFS `git lfs fetch --all origin` —— 全部落实 | 修订后进入 R3 |
| FU-22 R3 | FU-22 全量 diff（R2 修订后） | FAIL | Claude P1：嵌套存量父仓库的补救须为有序步骤（清理子仓库 → 向父仓库推一次新建或更新分支补齐来源 → 再推回子仓库）；Codex P1：`absent` 行不再列举会答 `absent` 的输入，改为 `--path` 原样精确匹配、执行前核对 | Codex P2 ×4 + Claude P2 ×3：摘除时进行中推送的 Tag 逐个写入、台账无 `detached` 行而仍能 clone 时先核对、4.1 补「新建不受支持（当前回 500）」、存量挂载补齐来源前勿删光分支（`DEFER-FU-49`）、`interrupted` 带 / 不带 id、LFS 同步补 `git lfs push --all mega2`（实测）、英文多余前导空格 —— 全部落实 | 修订后进入 R4 |
| FU-22 R4 | FU-22 全量 diff（R3 修订后） | FAIL | Codex P1 / Claude P1（同一条）：`absent` 行「先 clone 核对」查不出 `.git` 情形 —— 改为以 `psql` 精确查询 `git_repo.repo_path`（测试栈原样执行通过） | Claude P2 ×2：第 1 节只保留编辑保存并指向 4.1、LFS 同步写成有序命令链（实测）—— 全部落实 | 修订后进入 R5 |
| FU-22 R5 | FU-22 全量 diff（R4 修订后） | FAIL | Claude P1：R4 的 `&&` 链 LFS 同步在上游缺对象时停在 `git lfs fetch`（退出码 2），两次推送都不执行 —— 改为逐条四步，说明非零退出属预期、按 brewfs 示例设 `lfs.allowincompletepush` 后继续（实测） | 无 | Codex `VERDICT: PASS`（无发现）；Claude FAIL；修订后进入 R6 |
| FU-22 R6 | FU-22 全量 diff（R5 修订后） | PASS | 无 | 无 | Codex `VERDICT: PASS`；Claude `VERDICT: PASS`（均无发现）；本卡 `locally-accepted`，C / D 组由 FU-23 覆盖 |
| FU-23 R1 | FU-23 diff（README、plan-long、本计划、版本面）+ 手写 release note + 评审前门禁与聚合守卫证据 | FAIL | Codex P1 / Claude P1：FU-22 / FU-23 在评审 PASS 与推送前被记为 `remote-pending`，横幅与卡片对 FU-22 不一致——两卡回到 `locally-accepted`，版本 bump 与门禁改记为评审前证据、PASS 后正式重跑 C 组；Claude P1：release note 称完成判据「已填」——改写；Codex P1「全量须零失败零警告」——以 `DEP-FU-05` 不采纳（C 组 ③ 口径，自 FU-13 R3 起认可） | Codex 1×P2、Claude 11×P2：聚合守卫计数改为项（精确名 + 前缀组）并补 `import_repo_remove_contract`、索引行措辞、Review log 的 FU-19 R2 / FU-21 R1 更正、release note 七处措辞——均落实 | Codex `VERDICT: FAIL`；Claude `VERDICT: FAIL`（`wf23-r1/verdict.md`） |
| FU-23 R2 | FU-23 diff（R1 修订后）+ release note + 证据 | FAIL | Codex P1 / Claude P1：「计划完成门」无 `DEP-FU-05` 例外——用户决定：按 `DEP-FU-05` 发布、完成门保持未勾、计划记「已发布，完成门待 `DEP-FU-05`」；Claude P1：Review log 缺 FU-23 R1 行——已补 | Codex 2×P2、Claude 5×P2：聚合守卫来源、执行行计数、修订范围列、release note 两处、`DEFER-FU-50` 改道、失败摘录——均落实 | Codex `VERDICT: FAIL`；Claude `VERDICT: FAIL`（`wf23-r2/verdict.md`） |
| FU-23 R3 | FU-23 diff（R2 修订与用户决定后）+ release note + 证据 | PASS | 无 | Codex 1×P2、Claude 5×P2：收口措辞（执行行 ①、M4）、S3 原因更正为 macOS 系统代理、`ld` 提示归入 `DEP-FU-05`、修订范围列、release note 实测范围——均落实 | Codex `VERDICT: PASS`；Claude `VERDICT: PASS`（`wf23-r3/verdict.md`）；进入正式 C 组 |

## 非目标与延后项

| ID | 延后内容 | 原因 | 重启条件 | 承接位置 |
|---|---|---|---|---|
| DEFER-FU-01 | Git 命名空间对象存储 GC（被清理 ImportRepo 的 blob 字节） | 内容寻址、与 Monorepo 共享、无引用计数；#27 允许延迟 GC | 引入可达性 GC 计划 | 新计划 |
| DEFER-FU-02 | review 形态挂载开通 / 清理端点 | 唯一交付形态为 storage-only；FU-21 起运维 CLI 同样只在 storage-only 形态执行（拒绝，退出码 1） | review 重新成为交付形态 | 新计划 |
| DEFER-FU-03 | Libra 原生开通 / 清理命令 | 跨仓 | Libra 接手 `DEP-FU-03` | Libra 计划 |
| DEFER-FU-04 | create-entry 重名 500 改为 4xx | Libra pin 契约；首次使用由开通 API 覆盖 | 下一次 directory-entry 契约修订 | `directory-entry-api.md` |
| DEFER-FU-05 | `atomic` 推送能力与分支逐 ref 独立成败 | 分支已批量原子、tag 逐 ref 独立（ADR-FU-08 第 4 条）；逐分支独立需改协议层 `smart.rs` | 用户需要跨分支/tag 的全有或全无，或逐分支独立 | 新计划 |
| DEFER-FU-06 | 清扫的后台/启动续做 | 同路径请求续做已满足 #27 AC3 | 出现未被再次请求的残留 | 新计划 |
| DEFER-FU-07 | 改写历史错帧或签名泄漏 commit | commit 身份承载（永久非目标） | 永不 | N/A |
| DEFER-FU-10 | 合并存量别名迁移中检出的分裂身份（同一规范路径两行）；在此之前，以 `/` 或 `/.` 结尾的冲突别名行仍被 Web / API 的最长前缀查找（`find_git_repo_like_path`）命中（ADR-FU-10 第 3 条的子仓检查排除它们，FU-16 / FU-17 用例覆盖；检查读至多 64 行，整页都是目标自身的别名时保守视为有子仓、拒绝清理而不删除，FU-17 R3；FU-18 的祖先生命周期栅栏按规范祖先路径取 `FOR SHARE`，不锁别名祖先行；FU-19 的 API 写按 API 分派所得行判定存活：规范行清理后别名行可成为唯一行，请求期间 Git 面的改标签可致可重试的假 409，零行落地；FU-20：清理只删规范行，别名行保留、不算子仓、严格入口无法点名，清理后别名拼写的 Git 请求经改标签使规范路径重新存活——契约页的 `absent` / clone 404 以无别名行为前提，`import_repo_remove_exact_match_only` 断言别名行保留） | 自动合并需判定对象与 ref 归属，风险高 | 出现分裂身份的用户报告 | 新计划 |
| DEFER-FU-09 | 清除升级前已存在的 `import_dir` 本身的 `git_repo` 行 | FU-18 起该行不再被服务（惰性），清除需额外的运维入口 | 出现需要回收该行的报告 | 新计划 |
| DEFER-FU-08 | #29 AC5 第三类（真实 NFF）的 API 面对应 | 产品写 API 不携带客户端基线 commit，冲突由 MonoWriteQueue CAS 重排内部解决，不存在可分类的 NFF 结局；Git 面已由 FU-10 覆盖 | 某个产品写 API 增加「期望基线」参数 | 新计划 |
| DEFER-FU-11 | `root_dirs` 拒绝更多 Git 特殊名（`.gitmodules` / `.gitattributes` 作为目录、NTFS 别名如 `git~1`、`.git.`） | FU-04 已拒绝 `init_trees` 保留名与 `.git`（不区分大小写）；其余名字属 Git 客户端侧的 fsck / `core.protectNTFS` 约束，默认配置不触发（FU-04 R2 Claude P2） | 出现使用这类根名的部署或客户端报错 | 新计划 |
| DEFER-FU-12 | 同一路径并发 API 写的可重试语义 | 第二个写入在第一个仍 Queued/Running 时被 ADR-TP-10 拒绝（`ActivePushPathConflict` → `MegaError::Other` → 500），属既有队列约束，与全新栈回落无关（FU-06 执行时实测） | 出现并发写同一路径的客户端需求 | 新计划（映射为可重试 409 或排队等待） |
| DEFER-FU-13 | advertise / review 形态惰性物化嵌套 `import_dir` 的严格祖先（GC-FU-04 在 FU-06 之外的缺口） | clone / ls-remote（`monorepo.rs` 的 `refs_with_head_hash`）与 review 形态的 `create_repo_commit` 仍可物化 `/third-party`（`import_dir="/third-party/vendor"` 时），之后该目录下的 ImportRepo 挂载被祖先预检拒绝；FU-06 前即存在，默认平铺 `import_dir` 不触发（FU-06 R1 Claude P2）；同一原因使开通 API 在该祖先根之下返回 `MONO_PATH_UNINITIALIZED`，其提示的开通动作即自身（循环，FU-07 R1 Claude P2），目前只能经 `git push` 创建更深的路径 | 部署使用嵌套 `import_dir` | 新计划（在物化原语内统一拒绝 import 祖先） |
| DEFER-FU-14 | 经开通 API 创建初始化后新增到 `root_dirs` 的一级根 | 唯一可能的落点是 `/`，产品写从不在 `/` 落地（ADR-FU-06），返回 `MONO_PATH_NOT_ALLOWED`（点名 `/`）；需要「在不存在的路径上真创建」的 API 落地（B3 创建分支，FU-10 管 Git 面）；ADR-FU-04 的运维流程改为 `git push` 创建新根（FU-07 R1 Claude P2）；FU-10 之后无父首推到不存在的路径返回 `MONO_PATH_UNINITIALIZED` 并提示开通 API，二者对新根互相指引，只有沿用既有路径历史的推送可建根——FU-10 已写入 `trunk-push.md`「创建的路径策略」，用户旅程由 FU-11 说明（FU-07 R2 Claude P2） | 运维需要不经 Git 客户端新增根 | 新计划 |
| DEFER-FU-15 | 一次性子命令被 Ctrl-C 中断时的退出码 | `src/cli.rs` 为一次性命令安装的 Ctrl-C 处理以退出码 0 结束，被中断的 `mega2 path provision` 返回 0 且无输出，`provision && clone` 会继续；属既有 CLI 行为，不在 FU-08 写集（FU-08 R1 Claude P2）；FU-21：`import-repo remove` 改用记录式处理，SIGINT 以 130 退出并打印续做句柄；其它一次性命令仍退出 0，SIGTERM / SIGHUP 仍未处理 | 脚本依赖一次性命令的中断语义 | 新计划（一次性命令中断退出 130） |
| DEFER-FU-16 | 其它提交展示面（tree / 最新 commit 信息 `src/ceres/model/git.rs:85,123`、CL commit 行 `src/jupiter/storage/cl_storage.rs:544`、CL 标题 `src/ceres/code_edit/model.rs:322`）改用 FU-01 helper 取源正文 | 这些面用 git-internal `format_message()`，只按 PGP 装甲的结束行剥离，SSH 签名、`encoding` 头以及与 `gpgsig` 同时出现的 `mergetag` 会外露；不在 FU-04A 的 blame 轴内，CL commit 行已落库需回填（FU-04A 评审发现） | 出现 SSH 签名等提交在这些面展示异常的报告 | 新计划 |
| DEFER-FU-17 | 孤儿拒绝后「再加一个 commit」的绕过：被拒的无父 C1 在 unpack 后已入库，基于它推 C2 时 pack 内 C1 为已知 commit、被取作 fork 而接受（review 得到以 C1 起始的 CL；trunk 得到以孤儿 C1 为根的新路径历史）。修正需把 `old_id=ZERO` 推送的 fork 判定从「已入库」改为「可从存活 ref 或根树到达」 | 既有行为（FU-09 之前即存在），修正改变 fork 判定语义并增加可达性读取，超出「孤儿拒绝在重试间一致」轴（FU-09 R1 Claude P2） | 出现以此绕过的报告，或引入 commit 可达性索引（FU-10 已评估：不合入，见其 Out of scope） | 新计划 |
| DEFER-FU-18 | Monorepo 协议分派的服务端路径规范化 | ADR-FU-04 第 2 条假定 TP-08「先规范化再使用」覆盖 Git 协议 URL，实际只覆盖 ImportRepo 分派（`protocol/mod.rs:239-246`），Monorepo 分派使用原始路径（`:292`）；客户端构造 receive-pack URL 时去掉尾斜杠，常见形态不受影响，非规范原始路径（如 `/project//new`）在 FU-10 的创建分类中 fail-closed 为 `MONO_PATH_INVALID`（此前 B3 可能写入非规范行）（FU-10 R1 Claude P2） | 出现合法客户端发送非规范 Monorepo 路径的报告 | 新计划 |
| DEFER-FU-19 | 在「文件」路径上的创建（如 `/project/x.txt`） | 既有行为：该路径在根树中不是目录，被视为创建；孤儿推送得到「开通」提示而开通返回 `MONO_PATH_CONFLICT`，fork 型推送由 B3 以目录替换该文件（`insert_or_replace_tree_hash`）；可改为按 `MONO_PATH_CONFLICT` 分类（FU-10 R1 Claude P2） | 出现文件被目录替换或提示不一致的报告 | 新计划 |
| DEFER-FU-20 | Git 面 fork 型创建落在嵌套 `import_dir` 的严格祖先（`import_dir` 三级及以上，如 `/third-party/a/vendor` 的 `/third-party/a`） | 既有行为：创建分类不检查 `is_import_dir_ancestor`（FU-06 只在产品写上检查），在祖先插入 `main` 行后 attach 预检拒绝其下所有导入，违背 GC-FU-04；默认 `import_dir` 为一级根，不受影响（FU-10 R1 Claude P2） | 使用三级及以上 `import_dir` 的部署或相应报告 | 新计划 |
| DEFER-FU-21 | receive-pack 在 unpack 失败时仍写 tag ref | 既有行为：`smart.rs` 的 tag 分支只看命令状态、不看 unpack 结果即调用 `update_refs`（FU-12 只为其加 CAS），可能留下指向未入库对象的 tag（FU-12 R1 Claude P2）；FU-18 起 tag 写在自己的事务内取存活锁，仓库被清理后同样被拒 | 出现悬空 tag 的报告 | 新计划 |
| DEFER-FU-22 | `ImportApiService` 的 `edit/save` 与并发 ref 写之间的更新丢失：`save_file_edit` 先经 `get_root_tree` 读默认分支建树、随后再读默认分支作父并以无条件 ref 更新写回；两次读取之间的写（另一 `edit/save`，FU-13 起还包括后续推送）会被覆盖。修复需让建树与写回基于同一快照并以 `update_ref_if_unchanged` CAS（陈旧时 409 `IMPORT_REPO_STALE_REF`），涉及 `search_tree_for_update` 的快照接口；tag 删除按名称无条件删除，可能删掉被并发推送移动过的 tag（FU-12 R1 / R2 Claude P2）。FU-19 重写该写路径时已评估：ref 更新移入带锁事务但保持无条件、tag 删除保持按名删除——CAS 与快照一致的建树是第二个行为轴（FU-19 设计定稿） | 修复属另一行为轴 | FU-13 发布后出现 ImportRepo 编辑与推送互相覆盖的报告 | 新计划 |
| DEFER-FU-23 | 嵌套 ImportRepo 先子后父的导入，以及叶子下已有子仓的存量父挂载 | 父路径此时是「可选 `.gitkeep` + 通向子仓的子树」的目录，无来源记录则得到 `IMPORT_REPO_PATH_OCCUPIED`；可改为接受仅由已登记子仓路径构成的目录（FU-13 R1 Claude P2）。均非回归（FU-13 前一律 `cannot attach leaf`） | 出现需要先子后父导入的报告 | 新计划 |
| DEFER-FU-24 | 写入队列原样持久化失败文本 | B3 各类失败把 `e.to_string()` 写入 `push_queue.error_message`（所有队列类型的既有行为），可能含存储内部信息；客户端与日志均不再外露（FU-13 R3 / R5），但队列表内仍为原文。改为分类存储需要跨全部队列类型调整；`enqueue_and_wait` / `execute_b3` 自身的错误（队列控制、存储错误）经 `?` 直达客户端，同属既有行为（FU-13 R5 Codex P1 / Claude P2） | 队列表对非运维人员可见，或出现敏感信息落库的报告 | 新计划 |
| DEFER-FU-25 | 库用例的 per-test schema 在 HEAD 的 `crate::jupiter::tests::test_db_connection` 中不释放：每个用例建一个 `mega2_test_<pid>_<n>` schema 且不 drop，全套件约 1700 例每跑一次累积一次（2026-09-24 已达约 2.6 万个 schema、统计文件 370 MB、两次撑满 `/dev/shm`） | 根因在共用 helper，按卡加守卫会分裂约定；改 helper 影响全部库用例的时序与连接池（`max_connections = 2`） | 已另起独立任务并在另一会话实现（`TestSchemaGuard` 在 Drop 时释放 schema、一次性清理脚本 `scripts/drop_test_schemas.sh`），截至 FU-16 R5 尚未提交；该任务提交后本条关闭 | 独立任务（进行中） |
| DEFER-FU-26 | B3 attach 首次挂载写 `.gitkeep` 时 `save_blobs` 在 SAVEPOINT 之外写 `mega_blob` 行，其后（根 CAS 等）失败会留下孤儿行（FU-16 已把 detach 的同一写入改入事务） | attach 不在 FU-16 轴内；FU-12 R1 已把分支 CAS 前移使陈旧批不触发它，剩余窗口只有根 CAS / 提交失败 | 与 FU-16 detach 相同的改法（字节写对象库、行入事务） | 后续补丁卡 |
| DEFER-FU-27 | detach 两项锁内查询的专用索引：`git_repo (repo_path text_pattern_ops)`（子仓 `LIKE 'P/%'` 在 `en_US.utf8` 排序规则下不走现有 B-tree，目前为仓库数量级的顺序扫描 + `LIMIT 64`）与 `import_refs (repo_id, ref_type)`（分支存在检查目前经 `repo_id` 索引后过滤，触及该仓库全部 ref）；`import_repo_cleanups` 台账的 `repo_id` 定位索引（`resolve_cleanup_id` 的回退——仅对未 detach 任何东西的轮次，首次或重放皆然——按 `repo_id` 过滤 `(path, state)` 两段，采用索引时成本为该路径两段台账行数之和，该段占台账约 30% 起可为两次全台账扫描，FU-17 R2 / R4 / R5） | 改 schema 属迁移卡；`git_repo` 每个 ImportRepo 一行、detach 低频，现有规模下无需索引（`fu16_lookups_bounded_at_scale`） | ImportRepo 数量或单仓 tag 数增长到锁内扫描可测（例如 `git_repo` 超过 10 万行或单仓 tag 超过 10 万），或单一路径的清理历史超过 1 万行 | 迁移卡 |
| DEFER-FU-28 | detach 事务内的 `import_refs` 删除以该仓库的 ref 数为界（一条经 `repo_id` 索引的语句）；单仓 ref 数极大（数十万 tag）时锁内删除耗时可测 | ADR-FU-09 第 2 条要求提交后不存在可 advertise 的 ref；改为「删 `git_repo` 行即不可达、ref 由清扫分批删」需同步修订 ADR-FU-09 第 2 / 4 条与 FU-16 验收 | 单仓 ref 数超过 10 万且 detach 锁内耗时可测 | 后续卡 |
| DEFER-FU-29 | review 策略下 `POST /api/v1/repo/clone` 的 ImportRepo 错误面：`sync_third_party_repo`（`mono_api_service.rs:4974-5049`，`repo_router.rs:32-43`）走同一栅栏化 receive-pack，但丢弃 report-status 并把 `ProtocolError` 包成 `MegaError::Other`（500）——`IMPORT_REPO_REMOVED` 不达客户端，`IMPORT_REPO_PATH_INVALID` 表现为 500 | 该路由只在 review 路由集合中、不在 storage-only 部署暴露，错误面整理超出「receive-pack 写路径互斥」轴（FU-18 设计定稿） | review 模式对外开放 ImportRepo 同步 | 新计划 |
| DEFER-FU-30 | `traverses_tree_and_update_filepath` 的头选择：首个分支命令不看 `status=="ok"`（`import_repo.rs` 的 `filepath_pairs`；`attach_to_monorepo_parent` 看），无默认 ref 的仅删除推送头为零 id；FU-18 后二者由 panic 变为 `Not Found` 错误，语义不改 | 修语义属另一行为轴（FU-18 设计定稿） | 出现被拒分支导致 `file_path` 失败的报告 | 新计划 |
| DEFER-FU-31 | 死代码中未栅栏的 ImportRepo 写入者：`GitDbStorage::create_repo_and_save_ref` 与 `update_pack_id`（调用在 `pack/mod.rs` 中已注释）无调用者、未栅栏；FU-19 之后 `GitDbStorage::update_ref`（`unwrap` 未改）、`save_ref`、`remove_ref`、`insert_tag`、`delete_tag` 也只剩测试与该死函数调用；任何复活必须经 `lock_live_import_repo` / `register_import_repo` | 无调用者，删除属清理卡（FU-18 设计定稿）；FU-23 为只改索引与版本的收口卡，不删代码，移交新计划（FU-23 执行） | 复活，或清理卡删除 | 新计划 |
| DEFER-FU-32 | detach 在 `MONO_WRITE_LOCK` 下被共享锁持有者饿死：PostgreSQL 允许新的 `FOR SHARE` 越过排队中的 `FOR UPDATE`，`save_entry_concurrency > 1`（或 0 不限）时同一仓库连续的批事务可让 detach 等到一次推送的 unpack 结束，期间写队列停滞；FU-19 起 `ImportApiService` 的默认分支 ref、annotated / lightweight tag 与 tag 删除事务（以及 edit/save 经 `save_entry` 的对象批）也是共享锁持有者，同一仓库上连续的 API 写同样可让 detach 持续等待，单个 API 写事务的时长以锁后至多两条语句为界，但连续写流无上界 | 候选修正为 B3 detach `SET LOCAL lock_timeout` + 有界重试，属 FU-16 代码、超出本卡轴（FU-18 设计定稿） | 观测到 detach 等待超过预算 | 新计划 |
| DEFER-FU-33 | 已关闭——并入 FU-19（设计定稿 2026-09-25）：①`create_lightweight_tag` 的 `import_refs` 写改为带锁事务并补列入 ADR-FU-09 第 5 条（`fu19_tag_create_after_detach_rejected`）；②实测 detach 后首个预读（`get_root_tree`）直接 panic，只在 detach 落在两次预读之间时才是 500——`unwrap` 改 `NotFound` 并在预读失败时再检存活（`fu19_edit_save_after_detach_rejected`）；③默认分支 ref 改为锁后以 `update_ref_in_txn` 写（`fu19_edit_save_after_detach_writes_no_rows` W3）；原锚点 `git_db_storage.rs:144-149` 应为 `update_ref` 的 147-148 与 152 | — | — | FU-19 |
| DEFER-FU-34 | FU-18 之前遗留的损伤不回填：detach 后写入的孤儿 `import_refs` 行（清扫不触及 `import_refs`）与陈旧 attach 重新挂载的叶子不做清理；混版本窗口内（v0.40.6 及以前的实例执行 detach 之后的排队 attach）仍可能产生 | 回填需按仓库判定归属，超出本卡轴；发布说明声明（FU-18 设计定稿） | 发现存量孤儿行 | 新计划 |
| DEFER-FU-35 | `receiver_handler` 吞掉 panic / 被取消的批任务：`JoinError` 只记日志（`pack/mod.rs` 的 `receiver_handler`，`Err(join_err)` 分支），推送按 unpack 成功继续 | 既有行为；FU-18 不在该路径上新增 panic（FU-18 设计定稿） | 开 FIX 卡 | 新计划 |
| DEFER-FU-36 | B3 attach 首次挂载在持有 `MONO_WRITE_LOCK`（advisory 事务锁）时经连接池读写挂载树（`tree_ops::search_and_create_tree`，`push_queue_service.rs` 首次挂载分支）：连接池已满、且另一占着池连接的请求正在等 `MONO_WRITE_LOCK` 时，形成 PostgreSQL 看不见的等待环，直到连接获取超时 | FU-18 之前既有（HEAD 同一调用），与存活栅栏无关——B3 自己的共享锁只与 detach 冲突，而二者在同一 `MONO_WRITE_LOCK` 下串行；改为事务内树读写属 B3 挂载实现，超出本卡轴（FU-18 R1 Codex P1） | 观测到 B3 连接获取超时，或部署把连接池缩到极小 | 新计划 |
| DEFER-FU-37 | 协议分派按原始路径的组件前缀选择 ImportRepo 分支（`protocol/mod.rs` 的 `self.repo_path.starts_with(import_dir)`），规范化与叶子校验只在该分支内执行；SSH 的相对写法（`normalize_ssh_repo_path` 保留相对路径，如 `third-party`）照旧走 Monorepo 分支，不经叶子校验 | 分支选择早于 FU-18（既有），把规范化前移到分支选择之前会改变 Monorepo 面的路径处理，超出本卡轴（FU-18 R1 独立评审 P2） | 出现相对 SSH 路径绕过 ImportRepo 规则的报告 | 新计划 |
| DEFER-FU-38 | detach 在分派之前已提交时，发往被清理路径的 `POST /api/v1/tags` 与 `DELETE /api/v1/tags/{name}` 经 `api_handler` 落到 `MonoApiService`：其 `create_tag` 没有 `import_dir` 命名空间守卫，目标解析回落到 Monorepo 根 commit，可在 `import_dir` 路径下写出 `mega_tag` / `mega_refs` 行（200），删除为 Monorepo 的 404；从未导入的 `import_dir` 路径同样如此 | 属产品写的路径策略（ADR-FU-06 一族），不是存活互斥；被清理的 `repo_id` 不落行，栅栏不变量成立（FU-19 设计定稿）。FU-20 ER-03 复核（2026-09-26）：继续延后——①修正是 tag 写的路径策略守卫（`MonoApiService::create_tag` / `delete_tag`、`tag_router`），属另一 G-01 轴（ADR-FU-06 一族），改动 Libra 钉住的 tag 契约，删除守卫还会使既有的误放 tag 无法经 API 删除；②不新增能力：从未导入的 `import_dir` 路径今日已如此，FU-20 只增加曾导入过的路径，且仍需覆盖 token；③残留只在 Monorepo `mega_refs` / `mega_tag`，attach 的 I3 预检只看 `refs/heads/main`，不阻止重新导入；被清理的 `repo_id` 不落行。契约页写明该行为 | 在 `import_dir` 下发现 Monorepo tag（`mega_refs` 中 `import_dir` 之下的 `refs/tags/*`）的报告，或下一张改 tag 写路径策略的卡开工 | 新计划 |
| DEFER-FU-39 | 嵌套子 ImportRepo 被清理而父仓库存活时，`find_git_repo_like_path`（最长字面前缀）把子路径派给父仓库的 `ImportApiService`，以子路径为 `path_context` 的 tag 创建 / 删除作用于父仓库并答 200 | 分派早于 FU-19，超出栅栏轴（FU-19 设计定稿）。重启条件「FU-20 暴露子仓清理」已触发（无子仓的嵌套子仓可在父仓库存活时清理，`import_repo_remove_exact_match_only` Phase C）；复核后继续延后：任何存活 ImportRepo 的非仓库子路径今日已如此（覆盖 `/third-party/p/x` 的 token 可写 `p` 的 tag），修正属 API 分派轴（`api_handler` 改精确查找 + 显式父仓库解析）；`HAS_CHILDREN` 要求先清子仓，故不能禁止先清子仓。契约页写明：子仓被清理后，该路径的 tag 与编辑路由作用于存活的父仓库，而 Git clone 该路径为 404 | 出现此类报告，或 API 分派改为精确查找的计划 | 新计划 |
| DEFER-FU-40 | 写路径预读之外剩余的 panic：`ImportApiService::get_root_commit`、`get_commit_by_hash`、`get_commits_by_hashes`（blame / history 读）、`GitDbStorage::get_commits_by_hashes` 等读路径的 `unwrap`，以及 `api_handler` 在分派时对 `to_str` / 查找错误的 `unwrap` | 不写任何行，超出本卡轴与写集（FU-19 设计定稿） | 清理期间读路径出现 panic / 连接断开的报告，或开 FIX 卡 | 新计划 |
| DEFER-FU-41 | 存活 ImportRepo 上对同名 tag 的并发创建与删除：tag 删除在同一事务内以两条语句先删 ref、再删 `git_tag` 行（READ COMMITTED 下各取快照），删除一个尚不存在的名字时，若同名创建恰在两条语句之间提交，结果留下没有 `git_tag` 行的 ref（两个请求都 200）；FU-19 之前两条删除分别自动提交，同类竞态已存在 | 与清理互斥无关（FU-19 R1 评审 TX-1）；单语句删除（数据修改 CTE）或按名串行化需另立行为轴，且无确定性的反向验证手段 | 出现 tag ref 与 `git_tag` 行不一致的报告 | 新计划 |
| DEFER-FU-42 | 可重试的清理失败统一为 500 `Internal server error`（写入队列暂停 / 硬停 / 容量、detach 等待放弃或未完成、重放后仍存活、B3 其它拒绝、存储错误），无可区分的可重试码（如 503 + `Retry-After`） | `MegaError::Other` 不带可重试类型，`ApiError` 对 5xx 一律脱敏（同 `DEFER-FU-12` 一类）；FU-20 在 OpenAPI 与契约页声明 500 可重试（FU-20 设计定稿）；CLI 面（FU-21）：同类失败沿用 `MegaError` 文本，未记录清理前退出码 1，已记录后退出码 3 并给出句柄；台账不可读时退出码 1、无句柄，stderr 要求先查 `import_repo_cleanups` | 客户端需要区分可重试失败，或统一 API 队列错误映射的计划 | 新计划 |
| DEFER-FU-43 | 未鉴权的 400 `IMPORT_REPO_PATH_INVALID`（与开通端点的 `MONO_PATH_INVALID` 相同）把调用方原始输入（转义后）写进响应体与 error 级日志，长度只受 axum 默认 2 MiB 请求体上限约束 | 两个严格入口共用的既有行为；截断需改 `path_policy.rs` 与错误文本契约，超出本卡轴与写集（FU-20 设计定稿） | 日志量 / 放大报告，或统一严格入口的卡 | 新计划 |
| DEFER-FU-44 | `strict_import_repo_leaf_input` 只拒绝 NUL 与 `\`，不拒绝其它控制字符（`\n`、`\t`、DEL）与 Unicode 格式字符，与 `strict_creation_path_input` 不一致；这类路径过校验、鉴权后答 `absent`（绑定参数，无注入；Git HTTP 面不解码 URL，无法注册这类仓库） | ADR-FU-10 第 1 条只要求 NUL 与 `\`；在 FU-20 改会新增 `src/ceres/pack` 落点（landing 5 > M 上限 4）（FU-20 设计定稿）。FU-21 ER-03 复核（2026-09-26）继续延后：严格入口已随 FU-20（v0.40.9）发布、对这类路径答 200 `absent` 并写入契约页，收紧会把已发布的 200 改为鉴权前 400，需改 `path_policy.rs`、契约页、errors.md 与 FU-20 IT（HTTP 契约轴，超出 FU-21 写集）；CLI 另行拒绝会破坏 ADR-FU-11「校验与 HTTP 相同」；storage-only 无法注册这类仓库；CLI 的 stdout 回显已转义 | 统一两个严格入口的卡（与 `DEFER-FU-43` 一并），或出现含控制字符的 ImportRepo 路径 | 新计划 |
| DEFER-FU-45 | push token 名不保留：名为 `operator-cli` 或 `anonymous` 的 token 在审计日志中与运维 CLI 或匿名调用方无法区分 | push token 校验不在本计划轴内（FU-21 设计定稿） | 审计消费方需要区分，或修订 push token 校验的卡 | 新计划 |
| DEFER-FU-46 | 运维 CLI 拒绝 `redis.url` 与 `object_storage.s3.*` 中的 `vault://` SecretRef：现有 vault 打开路径都会动密钥文件（`VaultCore::config` 重写、`open_readonly` → `read_core_key` chmod 为 0600） | 用户约束禁止运维命令触碰 vault 密钥文件；无不做文件操作的 vault 打开路径（FU-21 设计定稿） | 部署需要以 vault 凭据运行该 CLI，或出现不对 `core_key.json` 做文件操作的 vault 打开路径 | 新计划（vault / 只读装配） |
| DEFER-FU-47 | 运维 CLI 中断 / 失败后句柄查询的剩余测试缺口与已知窄窗：①`MONO_WRITE_LOCK` 屏障与连接池关闭没有确定性 IT（去掉屏障 `interrupted` Phase A 仍通过）；②未经 IT 的 SIGINT 分支：装配期间、`--cleanup-id` 预读、排空轮、`live_before` 为空、`Resume::Unknown`（结局行、退出码与 stderr 文本由 `import_repo_remove_contract` 单测覆盖）；③detach 之后的未类型化失败（`Resume::Known`）与失败后台账不可读（`Resume::Unknown`，退出码 1，文本经 `ledger_unreadable` 由同一单测覆盖）无 IT；④`live_before` 在第 1 轮之前单独读取，其间仓库被替换时中断 / 失败给出被替换仓库的清理句柄 | 确定性注入需在进程内轮次的 detach 提交与答复之间停住或伪造连接故障，超出本卡测试手段；任何句柄续做都安全（续做永不 detach），句柄错指只影响提示（FU-21 R1） | 出现错误句柄或 `Unknown` 结局的报告，或引入进程内故障注入钩子 | 新计划 |
| DEFER-FU-48 | `AGENTS.md` 的子命令执行器签名（实际为 `fn(CommandContext, &ArgMatches)`）与 `#![allow(dead_code)]` 所在文件、`tests/common/mod.rs` 的说明与代码漂移（FU-21 设计定稿时记录，原拟交 FU-23） | 不属 FU-23「计划收口与发布证据」轴；`AGENTS.md` 另有其它会话的未提交改动（FU-21 R1） | 文档维护卡，或 `AGENTS.md` 的并行改动落地后 | 新计划 |
| DEFER-FU-49 | 没有任何分支、也没有挂载来源记录的存量 ImportRepo 挂载（只含 `.gitkeep`）：新建或更新分支的推送以 `IMPORT_REPO_PATH_OCCUPIED` 拒绝；清理时 B3 detach 只在挂载属于该仓库（有来源记录，或只含 `.gitkeep` 且有分支）时移除叶子，此形态只删行、根树中的占位目录保留，之后重新推送得到新 `repo_id`（无分支、无来源记录）仍被拒——该路径无法再导入；补齐来源记录之前用只删除分支的推送删光存量挂载的全部分支，也会落入此形态（只删除的批次不补来源记录） | 移除不属于该仓库的叶子会破坏 ADR-FU-09 第 2 条「否则不改根树」的归属保护，需另立行为轴；用户文档（FU-22）已写明改用其它路径（FU-22 R2） | 出现需要恢复这类路径的报告，或引入运维级的占位目录移除 | 新计划 |
| DEFER-FU-50 | `docs/errors.md` 开头的结构块与错误类型表未列 `ImportRepoError`；`docs/refactoring/integration.md` 的 IT 清单未列本计划新增的集成用例（FU-20 设计定稿时记录，原拟交 FU-23） | FU-23 写集只含计划索引、本计划与版本面，不改 `docs/errors.md` 与 `docs/refactoring/*`（FU-23 R2 改道） | 文档维护卡，或下一次改动 `docs/errors.md` / `integration.md` 的卡 | 新计划 |

## 完成判据

计划只有在以下条件全部满足后才能标记完成：

- [x] 所有任务卡满足粒度规则 `G-*`；「任务卡粒度审计表」已填齐。
- [x] 所有非延后任务 `Lifecycle=done` **且** `Acceptance=complete`（ER-04）；无卡停在 `remote-pending` 或 `blocked`。
- [x] 所有任务的 Verification 命令已运行并记录结果。
- [x] **计划完成门**（FU-23 作为最终 `release` 卡在最终树执行；2026-09-26 在 v0.40.13 最终树 `5e1cbd0` 上补跑通过；用户决定 macOS `ld` 的 `__eh_frame` 链接提示为平台噪音、不计入门禁，见修订历史 FU-23 R2 行与「计划完成门补跑」行）：`cargo +nightly fmt --all --check`、`cargo clippy --all-targets --all-features -- -D warnings`、`source .env.test && cargo test --all` 全绿，`cargo build`、`cargo build --tests` 均 0 错误 0 警告；未新增 crate 级 `#[allow(...)]`。
- [x] 必要的 docs / 错误契约 / 测试矩阵更新已完成。
- [x] 每张卡的 `Rollback mode` 已被验证或记录为不可验证的原因。（各卡 `Rollback mode` 字段均已记录：实现 / 迁移 / 发布卡为 `immutable-release`（前滚补丁），文档卡为 `revert`；未做实际回滚演练）
- [x] 代码 review 最终结论为 `PASS`，P0/P1 全部关闭。
- [x] 每次实际版本 bump 已提交、推送，并已创建和推送同名 `v<version>` tag 与手写 GitHub Release，且 D 组 `docker` job 绿。
- [x] 「修订历史」已记录成稿后的全部规范性变更（G-09）。
- [x] `plan-long.md` 日期计划索引已同步（FU-23）。