# Repo 瘦身执行简报（交 Codex 执行 · Claude 复核）

- **日期**：2026-07-23
- **分工**：Claude 分类 + 复核；**Codex 执行本简报**；Owner 拍板 PENDING 策略。
- **执行者须知**：你（Codex）对本仓库零上下文，本简报自包含。只做「执行范围 A / B」里 APPROVED 的事；PENDING 的事在 Owner 定策略前**不要碰**；「明确 KEEP」的东西**绝对不动**。

---

## 1. Owner 目的（为什么做这件事）

1. **瘦身仓库**，并**根治「查文件反复查错地方」**——陈旧/重复/误导性文件还留在仓库里，下次还会被误读。只加索引不够，要把确认无用的文件真正清掉。
2. **顺序**：先整理瘦身当前项目 → 再同步到 claude.ai/design 的两个设计系统。合并任务的正式计划见 `docs/superpowers/plans/2026-07-23-ds-merge-two-systems.md`（已写好、**泊住**，待瘦身完成后执行）。

## 2. 当前状态（事实基线）

- 仓库 **3621 个 committed 文件**。顶层分布：`figma-data/ 2141` · `docs/ 318` · `playground-dist/ 292` · `react-pilot/ 188` · `src/ 184` · `tests/ 163` · `scripts/ 77` · `playground/ 65` · `figma-sync/ 45` · `.design-sync/ 39` · `templates/ 34` + 根文件 28。
- 关键基础设施（**改动前三思、本简报不许动它们**）：导出管道 `scripts/export-claude-design-bundle.mjs`（→ 远端 Sync A）；gitignored 系统 driver `.ds-sync/`；committed 配置 `.design-sync/`；upstream gate；双 remote（Gitea `origin` + `github`）。
- 已完成的前置：全仓只读盘点（keep/discard/uncertain，带证据）；`figma-data/raw/`（689）已**核实为 load-bearing**（`figma-sync/extract.mjs` 写它、15+ 脚本读它），**KEEP，非瘦身对象**。

---

## 3. 执行范围 A —— 高信心废弃（✅ APPROVED，请删除）

以下 6 项无入站引用、不触及导出管道/gate/driver/remote、git 历史仍可找回。**逐项执行前先自行 `rg` 复核一次该文件 basename 全仓无引用**（下方已给证据，你再确认一遍），确认后 `git rm`。

| # | 路径 | 证据（删前请复核） |
|---|---|---|
| 1 | `docs/superpowers/plans/2026-07-23-ds-merge-two-systems-HANDOFF.md` | 首行自述「正式 plan 未写」；已被同日 `2026-07-23-ds-merge-two-systems.md`（正式 plan，**保留**）取代。删前确认 `rg -F "ds-merge-two-systems-HANDOFF"` 仅命中自身/复盘。 |
| 2 | `docs/internal/_backups/mockup-conventions.HEAD-543bc257a3a3.bak.md`<br>`docs/internal/_backups/mockup-conventions-xref-manifest.md` | 真源 `docs/internal/mockup-conventions.md` 仍在（bundle 03 源，保留）；`rg -F "_backups"` / `"mockup-conventions.HEAD"` 在 `.mjs/.js/.json` 零命中。可删整个空掉的 `docs/internal/_backups/`（若删后为空）。 |
| 3 | `docs/superpowers/verification/2026-07-23-L5-base-layer-smoke.html`<br>`docs/superpowers/verification/2026-07-23-L5-composite-smoke.html` | L5（已 ship）一次性冒烟 HTML；`rg -F` 文件名在代码零命中。 |
| 4 | `figma-sync/auto-tokenize-exact-match.mjs` | 一次性 tokenize 迁移脚本，迁移早完成；不在 `package.json`，代码引用 0（仅历史 `_reports/f25-*` 提及）。 |
| 5 | `docs/internal/_reports/figma-vs-code-fidelity-audit-2026-05-29.raw.json` | 2026-05-29 审计的原始 dump，配对 `.md` 报告仍在；无代码引用。 |
| 6 | `_draft/code-api.json`<br>`_draft/figma-api.json` | 2026-04-28 审计的原始输入。**仅** `docs/internal/retrospection/2026-04-28-design-system-audit.md:418-419` 与 `docs/PROJECT_MAP.md:163` 引用。删后请把 retrospection 那 2 行改注「（原始 dump 已于 2026-07-23 瘦身删除）」，并删掉 `PROJECT_MAP.md:163` 的 `_draft/` 待确认行。 |

**执行方式**：`git rm <paths>`，**一个干净 commit**，message：`chore(repo-slim): remove superseded handoff, dead backups, one-time artifacts`。**不要 push**（留给 Owner / Claude 复核后再推）。

---

## 4. 执行范围 B —— 增补 `docs/PROJECT_MAP.md`（✅ APPROVED，请编辑，勿新建文件）

目的：根治「查错地方」。在**现有** `docs/PROJECT_MAP.md` 里加一节「真源导航 / 易混点澄清」，含以下 4 块（内容已备好，直接落）：

### 4.1 源名 ↔ 导出后 bundle 名（01–14）映射——「查规则改真源，别去 bundle 找 01–14」
真源在 `docs/` 与 `docs/internal/`，由 `scripts/export-claude-design-bundle.mjs` 的 `REFERENCE_DOCS` 重命名成 bundle 里的 01–14：

| bundle 名 | repo 真源 |
|---|---|
| `01-figma-component-catalog.md` | `docs/internal/figma-component-catalog.md` |
| `02-component-affordances.md` | `docs/internal/component-affordances.md` |
| `03-mockup-conventions.md` | `docs/internal/mockup-conventions.md` |
| `04-design-process.md` | `docs/internal/design-process.md` |
| `05-domain-tvu.md` | `docs/internal/domain-tvu.md` |
| `06-*`（图标目录） | 生成自 `docs/internal/affordance-categories/*.json` |
| `07-working-principles.md` | `docs/working-principles.md` |
| `08-getting-started-code.md` | `docs/GETTING_STARTED.md` |
| `09-project-goal.md` | `docs/PROJECT_GOAL.md` |
| `10-code-conventions.md` | `docs/internal/code-conventions.md` |
| `11-component-review-rules.md` | `docs/component-review-rules.md` |
| `12-component-generation-pitfalls.md` | `docs/component-generation-pitfalls.md` |
| `13-icon-naming-convention.md` | `docs/internal/icon-naming-convention.md` |
| `14-upstream-gate.md` | `docs/internal/upstream-gate-l1-instructions.md` |

（注：repo 内**没有**顶层 `reference/` 目录；`reference/` 只存在于导出后的 bundle。）

### 4.2 `.ds-sync/` vs `.design-sync/`（头号脚滑点）
- `.design-sync/`＝**committed** 的 DesignSync 配置 + `previews/*.tsx` + `conventions.md` + `reapply-driver-patches.mjs`（本仓拥有，可改）。
- `.ds-sync/`＝**gitignored、运行时生成**的系统 driver（`/design-sync` harness 出的），**勿手改**、重建会覆盖。

### 4.3 `designAssetData.ts` vs `atomicAssets.ts`（`playground/docs/pages/`）
- `designAssetData.ts`＝**颜色 + 图标**数据（ColorPage / IconPage 消费）。
- `atomicAssets.ts`＝**排版 + 边框/圆角 + 效果/投影**数据（Typography / Border / Effect 页消费）。
- 建议：各在文件头加一行注释注明服务哪些页面。

### 4.4 `src/canonical/` vs `src/components/`（双真值）
- `src/canonical/`＝**对外 API / bridge 层**（改对外 props/API 进这里；`src/index.ts` 多从此导出）。
- `src/components/`＝**运行时实现层**（改运行时逻辑进这里；canonical 会 import 它）。

**执行方式**：编辑 `docs/PROJECT_MAP.md`，与范围 A **同一或相邻 commit**（message：`docs(repo-slim): add source↔bundle map & twin-dir clarifications to PROJECT_MAP`）。

---

## 5. PENDING —— 历史存档（⏸ Owner 未定策略，勿擅动）

`docs/internal/_reports`（~25）、`docs/internal/retrospection`（~55）、`docs/internal/_plans` + `_plans/_archive`（8）、translation 归档，以及**已 ship** 的 ds-rule-consumption `plans/` + `specs/`。这些无代码引用，但属项目史 / 描述 gate·driver·双 sync 的设计契约。

**三个候选策略（Owner 拍板前不要执行）**：
- **(推荐) 归拢 + 瘦身**：把已完成任务的复盘/报告集中进单一 `docs/_archive/`，删明显冗余（raw dump 等），保留设计契约类文档。
- **全部保留**：只靠 PROJECT_MAP 指路，不删历史。
- **删所有已完成的**：最激进；风险是设计契约知识若未迁入正式文档会丢失。

Codex：执行完范围 A/B 后，**在此停下等 Owner 选定 5 的策略**再继续。

---

## 6. 明确 KEEP（绝对别碰）

- `figma-data/raw/`（689，上游 Figma extract 源）、`figma-data/normalized/`。
- `playground-dist/`、`react-pilot/dist/`（`.gitignore` 注明「有意 track 的构建产物」，非误提交）。
- `src/canonical/` + `src/components/`（双层皆 load-bearing）。
- playground 两入口 `playground/canonical.html`、`playground/legacy.html`（均仍接线）。
- `scripts/` 与 `figma-sync/` 中所有被其它脚本 import 的 helper（`api.mjs`、`variable-map.mjs`、`icon-artifacts.mjs`、`affordance-sot.mjs` 等）——逐一验证过无死脚本（唯一例外见范围 A #4）。
- 4 个手动工具脚本（`scripts/a11y-survey.mjs`、`scripts/scaffold-git-remote.mjs`、`scripts/smoke-consumer-treeshake.mjs`、`figma-sync/generate-docs-figma-members.mjs`）——本轮**保留**（Owner 未要求删；`generate-docs-figma-members` 产物被 NotificationPage 消费）。
- 导出管道/driver/gate 的一切真源：`scripts/export-claude-design-bundle.mjs`、`.design-sync/config.json` 及其引用链、`scripts/upstream-gate.schema.json`、`src/tokens/variables.css`、`figma-data/normalized/variables.json` 等。

## 7. 硬约束

- 只 `git rm` 范围 A 的文件；每个删前自行 `rg -F "<basename>"` 复核无入站引用。
- **不改**任何 `src/`、`figma-data/`、`figma-sync/`、`scripts/export-*`、`.design-sync/config.json`、`.ds-sync/`、gate、`package.json`。
- 不 `push`（复核后由 Owner/Claude 决定推送；push 以 `git ls-remote` 为准，GitHub 常 phantom reject）。
- commit message 用英文；干净、原子。

## 8. Claude 复核清单（Codex 执行后由 Claude 亲验）

- [ ] `git status` + `git diff --stat`：只动了范围 A 的删除 + `docs/PROJECT_MAP.md` 的增补，无越界。
- [ ] 跑构建/导出冒烟确认没删坏：`pnpm build`（或 `pnpm vitest run` 关键子集）+ `node scripts/export-claude-design-bundle.mjs --no-zip` 干跑成功。
- [ ] `docs/PROJECT_MAP.md` 新增映射表逐条 `test -f` 亲验真源路径存在。
- [ ] 确认 PENDING（第 5 节历史存档）**未被动过**。
- [ ] 确认「明确 KEEP」清单里的文件一个没少。