From 4e1827295d003be4d432420ac9b346421846bd3a Mon Sep 17 00:00:00 2001
From: WorkBuddy <workbuddy@local>
Date: Fri, 18 Sep 2026 21:15:39 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20Phase=2023=20?=
 =?UTF-8?q?=E6=94=B6=E5=B0=BE=E4=B8=8E=20UAT=20=E5=B0=B1=E7=BB=AA=E8=AE=A1?=
 =?UTF-8?q?=E5=88=92=20+=202026-09-18=20=E6=96=87=E6=A1=A3=E6=B2=BB?=
 =?UTF-8?q?=E7=90=86=E6=8A=A5=E5=91=8A=EF=BC=88=E6=96=B9=E6=A1=88=E4=BB=BB?=
 =?UTF-8?q?=E5=8A=A1=E5=9B=9B=E3=80=81=E4=BA=94=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新建 docs/superpowers/plans/2026-09-18-phase23-closeout-and-uat-readiness.md（superpowers 计划格式），
  五批：批 1 快速收尾（ui-tests 15 个契约接入 CI —— 目前**只在本地手工跑**，CI 无把关）/
  批 2 Phase 23 剩余（E2E 场景真实实现 + INV-011 显式守卫 + CI 串联 E2E【需基础设施决策】+
  Phase 22 Deployment/Ops 口径复验）/ 批 3 代码级遗留清偿 / 批 4 UAT 就绪【需用户协作】/
  批 5 Phase 25-26 前置登记。STATUS.md 与客户需求基线计划均已引用（方案明确要求）。

- 新建 docs/文档治理报告-2026-09-18.md：五任务执行核对；本轮 9 项缺口（D1~D9）逐项处置；
  删除/归档/头注/保留四张清单；悬空引用二分结论（naive 扫描 29 处，其中 **24 处是「已删除对象清单」
  里的合法治理证据**，真实悬空 5 处）；**docs/ 目录被 safe-delete 钩子整体移除的事故记录与恢复过程**；
  验证证据；4 项遗留。

验证：UI 契约门禁 **14/14 PASS**；ui-document-baseline-contracts 通过（锚点齐全）；
database 文档 59 表 / 46 迁移与迁移文件实测一致。
---
 ...9-18-phase23-closeout-and-uat-readiness.md | 198 ++++++++++++++++++
 docs/文档治理报告-2026-09-18.md               | 158 ++++++++++++++
 2 files changed, 356 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-09-18-phase23-closeout-and-uat-readiness.md
 create mode 100644 docs/文档治理报告-2026-09-18.md

diff --git a/docs/superpowers/plans/2026-09-18-phase23-closeout-and-uat-readiness.md b/docs/superpowers/plans/2026-09-18-phase23-closeout-and-uat-readiness.md
new file mode 100644
index 0000000..e3b35ea
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-18-phase23-closeout-and-uat-readiness.md
@@ -0,0 +1,198 @@
+# Phase 23 收尾与 UAT 就绪实施计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 把「Phase 01~22 已关闭、Phase 23 部分关闭、后端 669 tests 全绿」这一停点推进到 **Phase 24（UAT）可启动**：清偿 Phase 23 剩余与代码级遗留，完成 UAT 前置（决策、用例、目视复验），并登记 Phase 25/26 前置项。
+
+**Architecture:** 分五批推进 —— 批 1~3 **不需要用户决策**（可立即执行），批 4 需**用户协作**（目视复验 + 13 项决策），批 5 仅登记。批 1~3 每批完成后必须跑全部门禁；**批 2 的 E2E 进 CI 一项依赖「活栈供给方式」基础设施决策**，未决策前不得虚勾。
+
+**Tech Stack:** Java 21 / Spring Boot 3 / PostgreSQL / Flyway · Vue 3 + TypeScript + Vite · 微信小程序原生 TypeScript · Node.js（契约门禁）· Docker Compose · GitHub Actions
+
+**Spec:** `docs/善缘丹阳 V1.1 客户需求基线增量开发与修复计划.md`（Phase 23~26）；
+**基线:** `docs/superpowers/specs/2026-09-13-reference-driven-dual-client-ui-redesign-design.md`（UI 唯一视觉基线）
+
+---
+
+## 当前停点（2026-09-18）
+
+| 项 | 状态 |
+|---|---|
+| Phase 01~22 | ✅ 复验关闭 |
+| Phase 23 | ⚠️ **部分关闭** —— 44 个 `pass` 空壳已清、4 个真实 INV 行为守卫已补；**E2E 场景实现与 CI 串联未完成** |
+| Phase 23B | ✅ E2E 测试基建重建（conftest + seed + CI e2e job，本机活栈 33→49 passed） |
+| 横向加固 | ✅ HTTP 语义（105 处真实状态码）+ 身份收敛 + 幂等键（30 端点，V045/V046）+ 端口/入口守卫 |
+| 后端回归 | **669 / 0 failures / 0 errors / 3 skipped** |
+| UI 契约门禁 | **14/14 绿** |
+| 停点 | **Phase 24（UAT）启动门前 —— 需用户确认** |
+
+> ⚠️ 在批 2 的 E2E 项完成前，**不应宣布「失败为零可进入 UAT」**（Phase 23 Gate 要求端到端链路被真实执行）。
+
+---
+
+## Global Constraints
+
+- **禁止用 `rm` / `git rm` 删除文件** —— 本机有 safe-delete 钩子会把「删文件」放大为「删父目录」（2026-09-18 实测：`git rm` 单个文件导致整个 `docs/` 被移除）。需要移除内容时**一律原地重写**（Write/Edit）。
+- 不修改业务规则、不扩大 V1 范围；新增能力必须走 Phase 顺序。
+- 每批完成后跑 `ui-tests/*.mjs`（必须 14/14 绿）+ `ui-document-baseline-contracts.mjs`（含端口与 `/admin/` 子路径断言）。
+- 后端改动跑离线容器 `mvn -o test`，必须 0 failures / 0 errors。
+- 提交纪律：每批独立 commit + `git tag`（**单段名**，带 `/` 会被本机常驻进程清理）+ 回读验证；`git bundle create` 覆盖最新提交。
+- 涉及密码/密钥：不写入文档，只用环境变量或安全 Seed。
+
+---
+
+## 批 1 — 快速收尾（无需决策）
+
+### Task 1.1: ui-tests 全量契约门禁接入 CI
+
+**Files:**
+- Modify: `.github/workflows/*.yml`（当前仅 6 个 job）
+- Test: `ui-tests/*.mjs`（15 个契约文件）
+
+**背景**：14 个 UI 契约门禁目前**只在本地手工执行**，CI 上无人跑 —— 文档改了、端口漂移了、`/admin/` 又退回 alias 了，CI 不会变红。这是「门禁存在但不生效」的同族问题（本项目已复发多次）。
+
+- [ ] **Step 1:** 确认 CI 现有 job 清单与触发条件。
+- [ ] **Step 2:** 新增 `ui-contracts` job：`node` 22，逐个执行 `ui-tests/*.mjs`，**任一非 0 退出即 job 失败**。
+- [ ] **Step 3:** 负向验证：故意改坏一处被断言的内容（如 STATUS 端口），确认 CI job 变红。
+- [ ] **Step 4:** 还原并确认变绿。
+
+**Acceptance:** CI 上 15 个契约全绿；注入缺陷后 CI 失败。
+
+### Task 1.2: database 文档对齐 ✅（2026-09-18 已完成）
+
+- [x] `docs/database/TABLE_INVENTORY.md` 由 **40 表**重写为实测 **59 表**（含来源迁移列）。
+- [x] `docs/database/MIGRATION_GUIDE.md` 由 **V001~V011** 重写为实测 **V001~V046（46 个）**。
+- [x] 两处均标注「**以 `backend/src/main/resources/db/migration/` 为准**」。
+
+**Acceptance:** 文档表数与迁移文件数一致（59 / 46）。✅
+
+---
+
+## 批 2 — Phase 23 剩余（核心阻塞）
+
+### Task 2.1: E2E 场景真实实现
+
+**Files:**
+- Modify: `tests/e2e/**`（现为占位文件，场景清单已完整保留在各文件头部）
+- Test: 本地活栈 `pytest tests/e2e`
+
+**场景清单（占位文件头部已列，不得缩减）：**
+
+| 文件 | 场景数 | 覆盖 |
+|---|---|---|
+| 首页聚合 | 11 | 首页 8 入口顺序、Banner 仅内部跳转、今日推荐、公益服务、安全提醒 |
+| 本地资格 | 11 | 声明 → 佐证上传 → 审核 → 状态流转；INV-011 未授权不可见 |
+| 互选 | 8 | 二阶段同意：互选结果 → 双方分别确认 → 创建 Match；已 Match 复用 / 已 Unmatch 新建 |
+| 权限 | 10 | 各角色数据范围（Counselor Assigned / ContentEditor 零用户数据 / 站点点范围） |
+| 预约 | 7 | 用户创建/详情/列表/取消仅本人；代登记走独立 operator 接口 |
+| 内容 | — | 婚恋课堂 / 反诈列表与详情 |
+| 组织隔离 | — | 跨组织默认拒绝 |
+
+- [ ] **Step 1:** 逐文件实现场景（**先删除空 `pass`**，禁止保留空壳）。
+- [ ] **Step 2:** 本地活栈跑通（需后端 + PostgreSQL + 种子数据 + `E2E_PASSWORD`）。
+- [ ] **Step 3:** 负向验证：注入 1~2 处缺陷，确认对应 E2E 变红。
+
+**Acceptance:** 场景全部真实执行且通过；无空 `pass` 残留。
+
+### Task 2.2: INV-011 显式守卫
+
+**Files:**
+- Create: 测试类（`backend/src/test/java/.../invariants/`）
+- Read: `LocalEligibilityService`、`ReviewController`
+
+**背景**：`LocalEligibilityService` 全部方法以 `userId` 自限定、零 role 分支，佐证无独立服务端读取入口（仅经受权限控制的审核队列）—— **结构性满足，但无测试固化**。
+
+- [ ] **Step 1:** 写负向测试：非授权角色读取他人本地资格佐证 → 必须 403/不可达。
+- [ ] **Step 2:** 确认真实落库路径（不是只断言常量，见 `CoreInvariantsTest` 的教训）。
+- [ ] **Step 3:** 负向注入验证守卫变红。
+
+**Acceptance:** INV-011 有真实行为守卫。
+
+### Task 2.3: E2E 进入 CI（**依赖基础设施决策**）
+
+**Files:**
+- Modify: `.github/workflows/*.yml`（e2e job 已存在但未串联）
+
+**背景（未决策，不得擅自动手）**：E2E 需要可用活栈（后端 + PostgreSQL + 种子数据 + `E2E_PASSWORD`），**在 CI 中如何供给属基础设施决策**。本地无法验证其正确性 —— 按「不写无法验证的测试」纪律，必须先决策。
+
+- [ ] **Step 1:** **（需用户/架构决策）** 确定活栈供给方式（service containers / 预构建镜像 / Compose in CI）。
+- [ ] **Step 2:** 按决策实现 job，并要求**任何失败阻断发布**。
+- [ ] **Step 3:** 实测一次完整的 CI 绿。
+
+**Acceptance:** CI 串起 迁移 → backend test → admin type-check/build → miniapp type-check → E2E，任一失败阻断。
+
+### Task 2.4: Phase 22（Deployment / Ops）口径复验
+
+> ⚠️ **口径澄清**：此为**计划的** Phase 22（部署运维基础设施），与 `STATUS.md` 所述「Phase 22 部署运维配置扩展（Feature Flag）」**是两份不同工作**。后者已于 2026-09-18 复验关闭。
+
+- [ ] 生产关闭 Mock WeChat / 默认密码 / Debug / Swagger / **演示 Seed**；Secret 全部由环境变量或 Secret 文件注入。
+- [ ] **备份加密 + 独立存放**，执行一次 PostgreSQL + 对象存储的**实际恢复演练**（要有命令、日志、结果证据）。
+- [ ] **Rollback** 明确回到哪个稳定镜像/版本；Flyway **只向前修复**，不破坏 V001~V027。
+- [ ] 删除 Backend 镜像「跳过测试」的发布路径；CI 先测试再打包。
+
+**Acceptance:** staging 部署、健康检查、恢复演练、版本回滚均有可复现证据。
+
+---
+
+## 批 3 — 代码级遗留清偿
+
+### Task 3.1: Phase 21 遗留
+
+- [ ] **隐私设置接口**：`getPrivacySettings` / `updatePrivacySettings` 仍是 **TODO 桩**（返回假数据 / 不更新）→ 接真实 `user_privacy_settings`。
+- [ ] **注销红娘服务拦截硬编码 `0`**：根因是数据模型**没有 `matchmaker_services` 表**（全仓搜索为空），拦截项在设计上无法落地。**建表属扩权** → 需产品先确认红娘服务的存储模型。
+- [ ] **数据保留流程**：按 `docs/legal/privacy-policy.md` 与 `docs/security/PIA.md` 落实保留期限（**不得擅自永久保存或删除**）。
+
+### Task 3.2: Phase 22 遗留（死配置）
+
+- [ ] `counselingEnabled` / `premaritalEnabled` / `contentEnabled` / `serviceLocationEnabled` / `localEligibilityEnabled` 五个开关**从未被业务读取** → 要么接线成真 gate，要么如实移除（不得留「配置暴露但未强制」的假开关）。
+- [ ] `counselingAttachmentsPrivate` / `Bucket` 私有桶死配置（存储实走 `object-storage.bucket-private`）→ 同上。
+- [ ] **`PUT /feature-flags` 不持久化** → 修复或明确标注为只读。
+
+### Task 3.3: 任务级 ⏳ 清偿
+
+- [ ] **P16-T13**：互选超时接线（`expires_at` 已由 V041 提供）。
+- [ ] **P13A-T31**：随访审计（`counseling_followups` 访问需审计）。
+- [ ] **P13A-T33**：`RiskEvent source=counseling` 来源扩展。
+- [ ] **P04-T10**：Onboarding 本地资格步骤。
+
+---
+
+## 批 4 — UAT 就绪（**需用户协作**）
+
+### Task 4.1: 管理端桌面端目视复验
+- [ ] 用户按 **1440px** 基准检查管理端（`/admin/` 子路径部署）各页面；覆盖 Loading / Skeleton / Empty / Error / Permission / Disabled / Responsive 状态。
+- [ ] 小程序按 **375px** 基准同上（首批 11 页已于 2026-09-16 验收，此处为增补页面）。
+
+### Task 4.2: PENDING_DECISIONS 13 项决策
+- [ ] 产品确认 `docs/PENDING_DECISIONS.md` 中 13 项待确认（人脸核验、本地资格保留期限、咨询资质、服务站开放时间、Banner 最大数量、推荐阈值等）。
+- [ ] 复核新增的「第三方开放遗留」7 项（凭据机制 / 限流阈值 / OpenAPI 发布 / `POST /activities/{id}/interests` 语义 / 审计配额 / 脱敏边界 / 幂等 TTL 分级）。
+
+### Task 4.3: V1.1 分角色 UAT 用例编写
+- [ ] 按 **9 个角色**（用户 / Reviewer / Matchmaker / Counselor / Counseling Manager / Service Station Operator / Content Editor / Activity Manager / Risk Operator）编写用例，**替代 V1.0 旧用例**（`tests/uat/UAT-Test-Cases.md` 为旧版参考）。
+- [ ] 覆盖线上主路径、线下扫码、咨询、辅导、服务站、活动二阶段确认、反诈举报七条路径。
+- [ ] 与 `tests/uat/run-uat.sh`（管理端可达性实测 + 备份检查）串联。
+
+### Task 4.4: Phase 24 启动确认
+- [ ] 用户确认 Phase 24 启动；确认前**不得**自动进入。
+
+---
+
+## 批 5 — Phase 25 / 26 前置登记
+
+- [ ] **运营素材清单**（Phase 25）：真实 Banner、服务站信息、咨询、课堂、反诈、关于我们、组织信息 —— **不 Seed 假用户 / 假 Match**。
+- [ ] **文案审核**：隐私政策、用户协议、敏感文案、「非官方婚姻状态核验」提示。
+- [ ] **上线前 13 项 smoke**（Phase 26）：Home / Quick Entries / Service Station / Counseling / Content / Activity Mutual / Chat / Block 等。
+- [ ] **RC 冻结**：镜像、数据库版本、配置清单、第三方依赖、Rollback 目标。
+
+---
+
+## 验收与提交纪律
+
+1. 批 1~3 每批完成后：`ui-tests/*.mjs` **14/14 绿** + `ui-document-baseline-contracts.mjs` 通过 + 后端 `mvn -o test` 0 failures。
+2. 批 2 完成前**不得**宣布「失败为零可进入 UAT」。
+3. 每批独立 commit；`git tag` 用**单段名**；`git bundle create` 覆盖最新提交并回读验证。
+4. `docs/STATUS.md` / `docs/JIRA_BACKLOG.md` / `docs/善缘丹阳 V1.1 客户需求基线增量开发与修复计划.md` 随批同步。
+5. **不做**：不修改 Recovery 报告与 `releases/` 冻结快照；不触碰 bundle 自保产物。
+
+---
+
+*创建: 2026-09-18 — 承接 `docs/文档治理报告-2026-09-18.md` 与 STATUS.md 的两处悬空引用（D1）*
diff --git a/docs/文档治理报告-2026-09-18.md b/docs/文档治理报告-2026-09-18.md
new file mode 100644
index 0000000..45e9134
--- /dev/null
+++ b/docs/文档治理报告-2026-09-18.md
@@ -0,0 +1,158 @@
+# 文档治理报告 — 2026-09-18
+
+> **范围**：善缘丹阳公益婚恋服务平台全仓文档（约 200 份）。
+> **触发**：用户「很多久的项目文档已经废弃，请按照最新的文档要求审查下」。
+> **性质**：先只读审查（2026-09-18 首轮），再按审查结论逐项处置（同日续做）。
+> **结论**：治理方案的五个任务**至此全部落地**；过程中发现并处置 9 项缺口、1 起环境级事故、2 份漏网文档。
+
+---
+
+## 一、「最新的文档要求」的出处（易踩空的前提）
+
+治理要求**不在 Git 里** —— 它是 `.zcode/plans/plan-sess_455ccc48-2c82-47b0-b4c6-1f923e813e1b.md`
+（《文档治理 + 进度审查 + 下一阶段计划》，2026-09-18 20:11）。
+
+`.zcode/` 被 `.gitignore` 排除，`git log` 完全看不到，**只存在于文件系统上**。
+→ 教训：听到「按最新要求」时，先 `ls -t .zcode/plans/`，否则会拿旧规范去审。
+
+**方案的五个任务**：①删除失效文档 → ②归档 + 头注 → ③状态文件同步 → ④下一阶段计划 → ⑤治理报告。
+
+---
+
+## 二、五任务执行核对（截至本轮收尾）
+
+| # | 要求 | 实际 | 判定 |
+|---|---|---|---|
+| 一 | 删失效文档 ~63 份 | `c77e6fc` 删 **65 份**（tag `docs-cleanup-*` 可恢复） | ✅ |
+| 二 | 4 份归档 + 5 处头注 | 归档 ✅；头注补至 **5 处**（本轮补 `部署架构…方案.md`） | ✅ |
+| 三 | 同步 5 个状态文件 | STATUS / JIRA / 基线计划 / PENDING_DECISIONS / REMAINING_WORK+database，**本轮全部完成** | ✅ |
+| 四 | 新建 Phase23 收尾计划 | **本轮新建** `docs/superpowers/plans/2026-09-18-phase23-closeout-and-uat-readiness.md`（五批） | ✅ |
+| 五 | 新建治理报告 | **本文件** | ✅ |
+
+---
+
+## 三、本轮处置的 9 项缺口
+
+| 编号 | 缺口 | 处置 | 位置 |
+|---|---|---|---|
+| **D1** | Phase23 收尾计划不存在 | ✅ **新建**五批计划；STATUS.md 与基线计划均已引用 | `docs/superpowers/plans/2026-09-18-…md` |
+| **D2** | 治理报告从未落盘却被引用 | ✅ **本文件**（关闭 `docs/archive/design-v1.0/README.md` 的悬空引用） | 本文件 |
+| **D3** | `REMAINING_WORK.md` 严重失实 | ✅ **整体重写**：称 CHANGELOG 3.3MB → 实际 **4234 字节**；P1-3 指向**从未存在**的报告；9 项已关闭 / 12 项待办如实重排 | `REMAINING_WORK.md` |
+| **D4** | database 两份与实况差距大 | ✅ **重写**：`TABLE_INVENTORY` 40 表 → **59 表**（带来源迁移列）；`MIGRATION_GUIDE` V001~V011 → **V001~V046（46 个）** | `docs/database/*` |
+| **D5** | 部署架构文档缺取代头注 | ✅ 补 `⚠️ 已被取代（2026-09-18 头注）` | 根目录 `部署架构…方案.md` |
+| **D6** | 三个状态文件未同步 | ✅ JIRA Epic 总览表补 **P14/P15/P19~P23** ✅；基线计划 Phase 07 去 `UI REOPENED`、Phase 10~15/19 补 ✅、Phase 20/21 勾选、**Phase 22 如实标「未复验」**、Phase 23 标「部分关闭」；PENDING_DECISIONS 历史部署声明 **10 项回写处置** + 补登第三方开放遗留 **7 项** | 三份文档 |
+| **D7** | bundle 自保未覆盖当日提交 | ✅ 本轮重跑 `git bundle create` 覆盖至最新提交 | 根目录 `*.bundle` |
+| **D8** | `Phase-13A-V11-Completion-Report.md` 逃过删除清单 | ✅ **原地重写**为废止声明（**不用 `git rm`**，理由见第六节） | 同路径 |
+| **D9** | 门禁口径 13/13（实测 14/14） | ✅ `AGENTS.md` 与 `STATUS.md` 当前口径改为 **14/14**；历史时点行**保留 13/13 并注明「为该时点数值」** | AGENTS.md / STATUS.md |
+
+---
+
+## 四、四张清单
+
+### 4.1 删除清单（`c77e6fc`，65 份，均经三判据核验）
+
+| 组 | 份数 | 说明 |
+|---|---|---|
+| `docs/Phase-XX-Completion-Report.md` | 26 | V1.0 自报式完成报告，已被各 Phase Recovery 版取代 |
+| `docs/Phase-XX-V11-Completion-Report.md` | 21 | V1.1 首轮报告，已被复验推翻 |
+| 旧审查 / 发布报告 | 13 | CODE_REVIEW_REPORT、FIX_PLAN、ISSUE_TRACKER、FINAL-RELEASE-REPORT、Go-NoGo-Checklist、渗透测试报告等 |
+| 被取代旧计划 | 4 | V1.1_RECOVERY_DEVELOPMENT_PLAN、当前进度校正与严格Phase修复计划、两份 2026-09-14 plan |
+| 备忘 | 1 | `IDEA.md` |
+
+**恢复方式**：tag `docs-cleanup-2026-09-18-1/-2` + `git log --all -- <path>`。
+
+### 4.2 归档清单（`16538d7`）
+
+4 份 V1.0 前端设计文档 → `docs/archive/design-v1.0/`，目录内 README 声明
+「已被 2026-09-13 参考图规格整体取代，不得作为实现依据」：
+前端UIUX视觉与原型设计规范 / 前端组件库与 Design Token 规范 / 高保真页面原型说明书 / 页面级功能清单与交互流程设计。
+
+### 4.3 头注清单（5 处）
+
+| 文件 | 头注 |
+|---|---|
+| `CHANGELOG.md` | 📌 指针 → `docs/V1_1_CHANGELOG.md` |
+| `REST API 接口详细设计规范.md` | ⚠️ 部分取代 → V1.1 增量设计 + `docs/api/API_INVENTORY.md` |
+| `WorkBuddy开发执行总指令…md` | ⚠️ 已被取代 → 主启动提示词（整合版） |
+| `WorkBuddy首轮启动提示词 + Phase 01~26 清单.md` | ⚠️ 已被取代 → 主启动提示词（整合版） |
+| **`部署架构、运维监控、备份恢复与升级方案.md`** | ⚠️ 已被取代 → `docs/OPS.md` + `infrastructure/` + Phase 22（**本轮补**） |
+
+### 4.4 保留清单（**零引用 ≠ 可删**）
+
+根目录 **13 份 V1.0 设计文档**被引用数为 **0**，但它们**不是废弃**：
+`docs/善缘丹阳 V1.1 数据库与API增量设计.md` 自述「**增量扩展、兼容 V1.0**」，
+这 13 份是 V1.0 业务设计的**唯一载体**；方案已裁定「保留原位」，本轮复核确认无冲突。
+
+其余保留：`P0阻断项修复报告_2026-09-15`、幂等键/HTTP 语义检修报告（09-18 最新结论）、
+`gate-output/*.txt`（UI 验收证据）、`tests/uat/UAT-Test-Cases.md`、`releases/` 全部、
+24 份 `*-Recovery-*` 报告、`.workbuddy/` 与 bundle 自保产物。
+
+**另登记一份「保留待决」**：`docs/Phase-V11-Deployment-Completion-Report.md`（2026-09-09，含已被推翻的
+「16/16 E2E 通过」）。它**不在**方案删除目标模式内（`Phase-V11-` 无数字段），且被**保留文档**
+`Phase-01-V11-Recovery-Completion-Report-2026-09-09.md` 援引 —— 删除会制造悬空引用。
+→ **不擅自删除**，登记待用户决定（删除需同步修改 Phase-01 的引用）。
+
+---
+
+## 五、悬空引用：必须二分，不能一股脑报缺陷
+
+naive 扫描得 **29 处**，其中 **24 处合法**（出现在「已删除对象清单」语境：治理方案的 Delete 清单、
+`UI_CLEANUP_INVENTORY` 候选表、UI spec 的 § 删除清单、历史报告叙述）——**它们是治理证据，刻意保留**。
+
+**真实悬空 5 处**，本轮全部关闭：
+
+| 位置 | 指向 | 处置 |
+|---|---|---|
+| `docs/archive/design-v1.0/README.md` | `docs/文档治理报告-2026-09-18.md`（从未入库） | ✅ 本文件落盘（D2） |
+| `docs/superpowers/plans/2026-09-13-miniapp-11-core-pages-redesign.md` | `docs/MINIAPP_REFERENCE_UI_QA_2026-09-13.md`（从未入库） | ✅ 随 65 份清理一并消除 |
+| `docs/superpowers/plans/…dual-client-ui-redesign.md` | `docs/UI_REFERENCE_REDESIGN_ACCEPTANCE_2026-09-13.md`（从未入库） | ✅ 同上 |
+| `docs/STATUS.md`（在途版本） | `plans/2026-09-18-phase23-closeout-and-uat-readiness.md` | ✅ 计划已建（D1）；STATUS 已引用 |
+| `docs/Phase-01-V11-Recovery-…md` | `Phase-V11-Deployment-Completion-Report.md` | ⚠️ **保留**（删除会制造新悬空，见 4.4） |
+
+> ⚠️ 本次教训：给目录扫描加 SKIP 时把 `archive` 排除，导致**归档目录自己的 README 没被扫到**，
+> 而它恰好含一处真实悬空。归档目录必须扫。
+
+---
+
+## 六、事故记录：`docs/` 目录被整体移除（已完整恢复）
+
+| 项 | 内容 |
+|---|---|
+| **时间** | 2026-09-18 21:05（SIGTERM 中断的 `git rm` 之后） |
+| **现象** | 整个 `docs/` 目录从工作区消失；`git status` 显示 **83 个文件全部为 ` D`**；`.git/index.lock` 残留（0 字节，无进程持有） |
+| **HEAD** | **完好**（`ref: refs/heads/main`，历史完整） |
+| **根因** | 本机存在 **safe-delete 钩子**，会把「删文件」放大为「**删父目录**」。本仓库 Phase-23 报告第 152 行**早已记载**：「本仓库禁止用 `rm` / `git rm` 删除文件；需要移除内容时改用原地重写（Write/Edit）」 |
+| **恢复** | 清理 stale 锁 → `git checkout HEAD -- docs/` → **83 个索引文件全部恢复**，`git status` 清零 |
+| **损失** | ① 未跟踪的 `docs/文档治理报告-2026-09-18.md`（**本轮已重建**）；② 一份**未提交**的 STATUS.md 在途改动（另一会话产出，已回退至 HEAD 版本，**本轮已重做**） |
+| **受影响文件** | 仅 `docs/`；`admin-web` / `backend` / `miniapp` / `infrastructure` 等均完好 |
+| **安全网** | 恢复后立即 `git bundle create .workbuddy/tmp/restore-checkpoint-…bundle main`（23MB，`bundle verify` 通过） |
+
+**纪律（写入技能）**：本仓库**一律不用 `rm` / `git rm`**；移除内容用**原地重写**；
+`git status` 出现整目录 ` D` 时应先查 HEAD 与 `index.lock`，**不要**先动工作区文件。
+
+---
+
+## 七、验证证据
+
+| 项 | 结果 |
+|---|---|
+| `ui-tests/ui-document-baseline-contracts.mjs` | **通过**（锚点齐全：`UI REDESIGN ACCEPTED BY USER`、`管理后台: http://localhost:13520/`、`Phase 07…已通过用户验收`） |
+| UI 契约门禁全量 | **14/14 PASS**（2026-09-18 实测，全部退出码 0） |
+| 数据库文档一致性 | `TABLE_INVENTORY` **59** 表 ⇄ 迁移实测 **59**；`MIGRATION_GUIDE` **46** 个 ⇄ 实测 **46** |
+| STATUS.md 重复区块 | 「V1.1 本地部署完成」**3 处 → 1 处**（996 行 → 946 行） |
+| 门禁口径 | `AGENTS.md` / `STATUS.md` 已为 **14/14**，历史行保留 13/13 并注明时点 |
+
+---
+
+## 八、遗留与下一步
+
+1. **`Phase-V11-Deployment-Completion-Report.md` 待决**（4.4）—— 建议连同 `Phase-01-Reports` 的引用一并修订后移除。
+2. **`docs/STATUS.md` 后半部历史区仍较长**（`V1.0 基线状态` 与 `当前 Phase` 段含 2026-09-09 的开发日志）——
+   已加「历史记录边界」声明，进一步精简需单独一轮。
+3. **UI 门禁进 CI 未做** —— 15 个契约目前只在本地手工执行（无 CI 把关）。已登记为
+   `plans/2026-09-18-phase23-closeout-and-uat-readiness.md` **批 1 Task 1.1**，是五项遗留里最该先做的一项。
+4. **执行纪律**：删除类改动仍应分 3 个 commit（①删除 ②归档+头注 ③状态同步+计划+报告）+ 每 commit 后 `git tag`（**单段名**）+ `git bundle create`。
+
+---
+
+*报告生成: 2026-09-18 — 对应方案任务五；处置明细见 `docs/superpowers/plans/2026-09-18-phase23-closeout-and-uat-readiness.md`*