{ "generator": "ai-ds-lab/metrics/retrospection-s2-prep.mjs", "subject": "tvu-ds", "dir": "docs/_archive/retrospection", "criterionSource": "lab 自写；path 口径来自 ds-doc-graph.mjs（下界），basename 口径本脚本（上界）", "scanned": { "textFiles": 1499, "note": "与 ds-doc-graph.mjs 同一套 walk，已内建总数对账" }, "calibers": { "path 口径（下界）": "markdown link / refdef / 仓库相对裸路径；⛔ 不含只提文件名。用途：>0 ⇒ 确定不能删", "basename 口径（上界）": "全仓非归档文件里出现完整文件名（含 .md）；含叙述性提及。用途：=0 ⇒ 确定可交由 S2 放行判定" }, "boundaries": [ "B1 上界只认完整文件名 + .md；「见 05-14 那份复盘」这类采不到 ⇒ 仍不是真上界", "B2 扫描面与 doc-graph 同形，已内建文件总数对账", "B3 shape 是形态计数不是归因（AGENTS §3.5）", "B4 decisionCandidates 是召回优先粗筛，不是判定结果" ], "total": { "count": 35, "lines": 4665 }, "byShape": { "other": { "count": 20, "lines": 2620 }, "phase-debug": { "count": 2, "lines": 490 }, "bridge-mockup-log": { "count": 3, "lines": 451 }, "release-log": { "count": 5, "lines": 888 }, "evolution-step": { "count": 5, "lines": 216 } }, "promotedOutOfS2": { "count": 0, "lines": 0, "files": [] }, "rows": [ { "file": "docs/_archive/retrospection/2026-04-29-meta-rules-and-bridge-goal-establishment.md", "lines": 233, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 27, "tldr": { "line": 6, "heading": "TL;DR", "endLine": 14 }, "decisionCandidateCount": 22, "decisionCandidates": [ { "line": 1, "text": "# 元规则建立 + 项目目标升级 + T1a audit 上线（2026-04-29）" }, { "line": 9, "text": "- **结构升级**：建立元规则真源、把项目目标从\"npm 包\"升级到\"双向 Figma↔Code 桥\"、协作规则角色化（不绑工具）" }, { "line": 51, "text": "**第三轮触发**：用户问\"目前应该只有 DateTime 这么干，能不能抽象成规则\"——逼出\"拓扑映射真源机制\"，避免 hardcode 组件名。" }, { "line": 55, "text": "## 阶段 3：建立元规则真源（最重要的结构性升级）" }, { "line": 62, "text": "- 用户：\"我希望你后续能一直记住，而不是让我来反复提醒\"——逼 Claude 把规则机制化" }, { "line": 63, "text": "- 用户：\"规则不区分哪个模型，只是当前我用 Claude 和 Codex\"——逼 Claude 把规则角色化" }, { "line": 65, "text": "### 产出：`docs/meta-rules.md`（项目元规则真源）" }, { "line": 72, "text": "5. Audit / 数据产出类 prompt 子规则（含 evidenceLevel schema）" }, { "line": 75, "text": "### 反模式清单（任何角色违反 → 停下重新设计）" }, { "line": 79, "text": "| 1 | 在脚本/工具里硬编码项目级规则 | 在 .md 真源，工具读真源 |" }, { "line": 126, "text": "→ 写进 `docs/PROJECT_GOAL.md` \"前置约束\"段，T3/T4 prompt 设计时强制读。" }, { "line": 130, "text": "## 阶段 5：协作规则角色化（不绑工具）" }, { "line": 133, "text": "用户：\"请把规则不区分哪个模型，只是当前我用 Claude 和 Codex 来做了——把这个写进去\"" }, { "line": 162, "text": "- 推荐\"M1 后再加 CLAUDE.md 规则\"（用\"避免越界\"做防御借口）" }, { "line": 165, "text": "**根因**：写完后没强制过反模式清单，用\"详尽 prompt\"思维而非\"产出契约\"思维。" }, { "line": 171, "text": "本对话用户至少 4 次发出元提醒（\"怎么老修改 / 我记不住那么多规则 / 这个问题为什么需要我主动来提 / 我希望你后续能记住\"）——这些**比技术问题更重要**，每次都揭示协作模式的根因。" }, { "line": 177, "text": "承诺\"我会记住\"无效（/insights 数据印证）。规则必须落到仓库 `.md` 文件，下次 session 读到才生效。" }, { "line": 194, "text": "**executor 后续机械规则**：" }, { "line": 196, "text": "1. 修 audit/report bug 时，先做三层核对：`normalized JSON` → `audit JSON` → `markdown report`。不要只看报告 grep 结果。" }, { "line": 197, "text": "2. 如果“报告为空/轴消失”，先确认 JSON 中该 component 的 `axes / variants / findings` 是否存在；存在则优先修报告渲染或验证命令，不要改数据算法。" }, { "line": 199, "text": "4. dimension finding 默认仍是 heuristic 视觉/尺寸检查；除非真源明确登记了 dimension token 链，否则不要给 topology/token-match 类 direct verdict。" }, { "line": 232, "text": "4 modified + 9 untracked，no commit，符合 v2 plan no-commit until milestone 纪律。" } ], "gatesMentioned": [ "audit-component-token-fidelity.mjs" ], "gatesDead": [ "audit-component-token-fidelity.mjs" ], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-06-t2-sample-extension-and-phase-a-bootstrap.md", "lines": 436, "s1Class": "superseded-weak", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 55, "tldr": { "line": 3, "heading": "TL;DR", "endLine": 13 }, "decisionCandidateCount": 46, "decisionCandidates": [ { "line": 8, "text": "- **2 milestone commits**：T2 sample 范式 lock (Badge + Tooltip) → Phase A bootstrap (auto-discovery)" }, { "line": 18, "text": "T2 plan + 3 份 Round 1 draft（generator schema 表达层 / grid contract 表达层 / audit 算法）→ plan owner 17 条裁定 → Round 2 实施：" }, { "line": 65, "text": "每个 placement direction 用一致的几何镜像（visible \"L\" 朝向远离锚点 → arrow tip 视觉指向锚点）—— 一致镜像逻辑无特例（反模式 #2 合规）。" }, { "line": 82, "text": "- propByAxis 含空格 axis 名（'dark theme' → 'darkTheme'）" }, { "line": 131, "text": "> \"还有多少步？一次只能做一个组件吗？不能按照已经做的那几个组件，把规则复用下来，做成脚本或者其他定性的规则，应用到剩下的组件上吗？\"" }, { "line": 138, "text": "- 50 COMPONENT_SET → 19 Tier 1 / 8 Tier 2（多 set 单 canonical）/ 21 Tier 3 (Button mega)" }, { "line": 152, "text": "- Tooltips → Tooltip 复数→单数 alias 补登" }, { "line": 157, "text": "- Tier 3 Button (21 sets / 8400 variants) 强行 auto-discovery 套 Badge 范式会出灾难性 bug → 必须独立 mega aggregation 模型（BRIDGE-Tier3 backlog）" }, { "line": 167, "text": "- COMPONENTS = { Badge, Tooltip } 硬编码 → discover Tier 1/2/3 自动派生" }, { "line": 168, "text": "- Tier 分类规则用具体前缀白名单（`Button/` / `Dark/` / `Light/` 是 Tier 3，`Drop down List/` / `input box/` / `select box/` 是 Tier 2）" }, { "line": 169, "text": "- Component name 派生 = prop-aliases 表 → fallback PascalCase" }, { "line": 174, "text": "Follow-up：单值 axis 跳过通用规则（PromptMessage `interact=Yes` 实证——figma 用独立 boolean property `Show close icon` 控制关闭图标，与 variant axis 解耦）。规则 1 加到 prop-aliases.md \"Figma axis 处理规则\" 段作为通用机制。" }, { "line": 188, "text": "CANONICAL-002 PromptMessage auto-dismiss 入 backlog（`closable=false` → `setTimeout(autoDismissMs ?? 3000)` 自动消失）。" }, { "line": 198, "text": "- 扫 playground/docs/pages/*Page.vue → SFC import 解析 → Tier 1 .ts 过滤 → tiebreaker" }, { "line": 199, "text": "- tiebreaker 3 项：BreadcrumbPage → BreadcrumbItem / StepsPage → StepItem / TabsPage → TabItem（wrapper canonical 无 figma 真源，item 才是真实 figma source）" }, { "line": 213, "text": "→ Phase A4 page 批量改造工作清单 ready，分 4 sub-prompts。" }, { "line": 237, "text": "A4.0 prompt 已写 [`docs/internal/_prompts/archived/phase-a4-0-generator-theme-identity-fix.prompt.md`](../_prompts/archived/phase-a4-0-generator-theme-identity-fix.prompt.md)，未 fire。fix 后 NotificationPage α 从 N/A → fail（correctness improvemen" }, { "line": 243, "text": "| 决策 | 落地位置 |" }, { "line": 245, "text": "| T2 sample 范式：generator → grid → 4+1 audit | commit f6e9a77 / 8870419 |" }, { "line": 253, "text": "| Page → Component tiebreaker 3 项（wrapper canonical 让 Item primary） | A2 audit (commit f9ca71c) |" }, { "line": 264, "text": "- 用户 \"这个为什么不修？后续可能忘记了？\" → plan owner 立刻停 A4 推进，转 backlog.md 真源建立 + CANONICAL-001 fix" }, { "line": 265, "text": "- 用户 \"一次只能做一个组件吗？\" → plan owner 立刻承认线性路径优化失误，pivot 到 Phase A 自动化切分" }, { "line": 270, "text": "- Phase A1：plan owner 锁 Tier 分类规则 + 派生算法；executor 实施 SFC 解析 + markdown table parser" }, { "line": 271, "text": "- 用户 challenge \"generator 输出 schema 这个任务为什么是你适合？\" → plan owner 修正分工边界，把表达层让 executor 提议（健康承认错误）" }, { "line": 275, "text": "- Black variants 视觉问题 → plan owner 实读 figma JSON Black variants 的 fill token + 读 docs `--bg-layer*` 实际值，发现是 docs cell bg 选层问题不是 Badge 漂移（避免误改 canonical）" }, { "line": 276, "text": "- variant.theme 缺失 → plan owner 实证 grep 5 个 Tier 1 .ts 验 figma axis 名 vs variant.theme 字段，定位 Notification gap（避免凭印象 patch 错位置）" }, { "line": 293, "text": "- A1 plan owner 锁 propByAxis 派生规则时只考虑 alias path（dark theme → theme）—— 漏了 figma 已是 canonical theme 的 identity case" }, { "line": 295, "text": "- 教训：plan owner 在锁规则时应**枚举所有 axis 名形态**（不只 alias 触发情况），不靠后续 sample 暴露" }, { "line": 299, "text": "- #1 硬编码项目级规则：generator/audit 是真源消费者，规则全在 prop-aliases.md / backlog.md / types.ts" }, { "line": 301, "text": "- #3 to-do list 思维：plan owner 都先产出契约（17 裁定 / verdict schema / Tier 分类规则）再 fire" }, { "line": 302, "text": "- #4 没问下游消费：generator → grid + audit 各自需求清楚标注" }, { "line": 303, "text": "- #5 没问扩展时改哪里：Tier 2/3 分别留 backlog 入口；GLOBAL alias / 处理规则段独立扩展" }, { "line": 327, "text": "- 当前 dirty 工作区，等用户决定单独 commit 还是合并到其它 ticket" }, { "line": 330, "text": "- 待 backlog.md 演进稳定后再决定迁移策略" }, { "line": 337, "text": "- 7 commits 累积本 session（f9ca71c → 130fc13 → 616e719 → 20445f3 → 54ca6ad → 8870419 → f6e9a77）" }, { "line": 338, "text": "- 本 session 改 5 真源 .md：prop-aliases.md / backlog.md（新增）/ AGENTS.md / Tooltip canonical / 28 audit reports" }, { "line": 358, "text": "1. 复盘 commit 99be418 落地后，plan owner 看 git status 仍有 M files（generate-docs-figma-members.mjs / 19 .ts / 18 audit reports）" }, { "line": 363, "text": "- notification.ts 实质 diff：新增 14 个 `variant.theme` 字段" }, { "line": 367, "text": "**根因诊断**：" }, { "line": 370, "text": "- generator 文件 diff 显示 `componentPropAliases` 等明显非 timestamp 改动，但 plan owner 在前一次审查时已经标记为\"A2 scope creep\"（见反思项），后续看到同样 diff 直接套用旧诊断 → **anchoring bias**" } ], "gatesMentioned": [ "audit-page-t2-sample.mjs" ], "gatesDead": [ "audit-page-t2-sample.mjs" ], "ruleIdsMentioned": [], "ruleIdsAlive": [ "触发器D", "触发器G", "触发器I", "触发器A", "触发器E" ], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-07-phase-a4-deep-debug.md", "lines": 303, "s1Class": "superseded-weak", "shape": "phase-debug", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 31, "tldr": { "line": 9, "heading": "TL;DR", "endLine": 27 }, "decisionCandidateCount": 45, "decisionCandidates": [ { "line": 11, "text": "- **范围**：A4.0 generator theme fix + A4.1 NotificationPage sample (含 grid contract 扩展 / dark-only 规则建立 / Interactive Scenario / Icon stack 多层 root fix) + A4.0 follow-up identity fallback" }, { "line": 12, "text": "- **6 commits**：c623544 → 8679c3a → e966d41（其中 8679c3a 大 commit 30 文件 +1306/-354）" }, { "line": 34, "text": "- NotificationPage α verdict: N/A → fail (correctness improvement)" }, { "line": 38, "text": "- Codex 实施时**只**走 globalAxisAliases + componentPropAliases 双路径，**未**加 identity 三 fallback —— 这是阶段 9 fix 不完整的根因（阶段 11 follow-up 补完）" }, { "line": 50, "text": "| Round 3 follow-up-2 | restore 2 selector + cellMinWidth='100%' | 视觉 reverify 仍 error/info 白色 → 暴露 Icon.vue inline override 设计 bug |" }, { "line": 51, "text": "| Round 4 follow-up-3 | Icon.vue conditional inline color emission | + Codex 顺手改 raw.ts (status-error 三角 → X 圆) |" }, { "line": 52, "text": "| user-Codex 直接 channel | 用户授权 Codex 走 raw.ts 真源对齐 | plan owner 误判 silent scope creep → 用户截图澄清 |" }, { "line": 58, "text": "**Fix**：加 `cellMinWidth?: string` prop（默认 `'176px'`）→ NotificationPage 传 `'100%'` 强制 1 column。" }, { "line": 60, "text": "### 关键发现 2：Docs site dark-only 规则" }, { "line": 66, "text": "- AGENTS.md \"项目约束\" 段加 \"Docs site 默认 dark-only 显示\" 规则（扩展 `dark-theme-only-monitoring` memory rule）" }, { "line": 71, "text": "[`src/components/Icon/Icon.vue`](../../src/components/Icon/Icon.vue) default `color = 'currentColor'` → render ``。" }, { "line": 76, "text": "- **inline 永远赢** → 任何 Consumer 用外部 CSS 改 icon color 失效" }, { "line": 95, "text": "**用户授权 Codex 走根因修法**：raw.ts `IconStatusError` SVG path 三角 → X 圆（保 `fill=\"currentColor\"`）+ 保 BaseNotification iconMap.error 用 'status-error' 别名。Runtime 真源对齐。" }, { "line": 103, "text": "- 根因：A4.0 fix 派生只走 globalAxisAliases + componentPropAliases 双路径，遗漏 figma axis 名直接是 canonical 'theme' 但没在 Known Entries 段登记的 identity case" }, { "line": 114, "text": "## 触发器 / 反模式 实证（新增 5 条，超 commit 9dc00ac）" }, { "line": 123, "text": "- 任何\"scope creep\"surface 措辞应**先 ask 用户是否授权**（\"以下改动不在 prompt 范围，是你单独授权 Codex 还是 silent creep？\"）—— 不下结论性判断" }, { "line": 131, "text": "- **error / info**：not dead（icons 用 `fill=\"currentColor\"`）❌ 误删 → 视觉 white" }, { "line": 141, "text": "Icon.vue default `color = 'currentColor'` + inline emit → `style=\"color: currentColor\"` —— 看似 no-op（语义等于 inherit）但**有 specificity (1,0,0,0)** 屏蔽外部 class color rules。" }, { "line": 151, "text": "根因：plan owner spec 没**枚举**所有 axis 名进入 'theme' 的形态：" }, { "line": 152, "text": "- alias 'dark theme' → 'theme'（Codex 实施 ✓）" }, { "line": 162, "text": "User 选 (c) \"sample-first\" 切分 A4.2 时 plan owner 推荐 ProgressPage 作 2nd sample。准备时实证 A4.0 fix 不完整 → 在批量 fire 前 catch。" }, { "line": 164, "text": "**机制 / 教训**：" }, { "line": 168, "text": "- 推论：未来类似复杂 phase **必须** sample-first，不要\"线性单 prompt 复用\"" }, { "line": 177, "text": "- 跑完 plan owner 复审 + 视觉验收 → commit → 进 A4.2 batch (8 page) 或 A4.3" }, { "line": 229, "text": "1. [`AGENTS.md`](../../AGENTS.md) — 跨工具入口 + 硬规则 6 条 + 项目约束（Pro plan + **Docs site 默认 dark-only 显示**——本 session 新加）" }, { "line": 230, "text": "2. [`docs/meta-rules.md`](../meta-rules.md) — 元规则 + 反模式清单 + 触发器（特别 G + I + 9dc00ac 加的 ABCD/E/H/I 触发器）" }, { "line": 242, "text": "1. **destructive 操作（git checkout / reset / clean）前必须先报告 + 等用户授权**——commit 9dc00ac 教训" }, { "line": 244, "text": "3. **Plan owner 看不到 user-Codex 直接通道**——任何\"silent scope creep\"surface 应先 ask 用户而不是下结论" }, { "line": 249, "text": "8. **Sample-first 是发现机制完整性的工具**——任何复杂 phase 必须 sample-first，不要\"线性批量\"" }, { "line": 250, "text": "9. **改造 figma-data-missing 8 组件之一的 page 前，plan owner 必须先视觉对比 Figma 真源截图 vs canonical 渲染**（FormItem / Rating / Switch / Notification / TopBar / StepItem / Slider / Checkbox+Input + Progress）—— 发现 token mismatch → 先修 canonical 或入 backlog → 再 " }, { "line": 251, "text": "- **Why**：T1c PAUSED → 这 8 组件的 canonical token 选择是历史/猜测，未真源 verify。Page transform 不暴露 canonical 视觉问题；A4.2 ProgressPage sample 是因为用户主动对比才发现 track invisible" }, { "line": 252, "text": "- **How to apply**：进入 A4.2 batch / A4.3 / A4.4 任何 figma-data-missing 组件 page 改造前，plan owner 用 figma 真源截图（用户提供 / Figma MCP `get_screenshot`）+ canonical dev 截图对比；mismatch → 入 backlog (类似 CANONICAL-004) → 修 canonical token 或决定延后 → 再 fire page " }, { "line": 255, "text": "10. **Page transform prompt §0 必须 explicit 约束 \"template restructure 禁止替代动态 prop binding\"**——不能假设 executor 理解\"只改数据来源\"语义边界" }, { "line": 259, "text": "- \"禁止拆分多个 conditional renders (v-if/v-else-if/v-else) 替代动态 prop binding\"" }, { "line": 260, "text": "- \"如 type widening 担忧 → STOP 报 blocker，不要自由发挥加 type cast 或拆条件渲染\"" }, { "line": 269, "text": "- **Why**：A4.2-safe PaginationPage sample 用户报 grid 折行——Pagination Classic figma w=652px，默认 cellMinWidth 176px 把 component 强行 squeeze 到 ~233px → 折行不优雅" }, { "line": 270, "text": "- **How to apply**：page transform prompt §0 必须 explicit 列每 page 的 cellMinWidth 决策；plan owner 用 figma MCP get_design_context 拿 component w，决定 100% (≥400px) 还是 176px (<200px) 还是中间值" }, { "line": 271, "text": "- **实证 case**：Pagination Classic w 652 / Small w 628 / Simple w 460 → 100%（commit 待 sample 一并落）；Notification 480px hardcoded → 100%（A4.1 已 commit）" }, { "line": 273, "text": "13. **Sample commit 后 plan owner 不发掘 canonical 层 finding 阻塞 commit**——所有非 page-transform-范畴的 finding（spacing / composition / boolean / token 选择）→ 入 backlog 不阻塞 → 后续独立 ticket 排期" }, { "line": 274, "text": "- **Why**：A4.2-safe PaginationPage sample 完成后 plan owner 连续发掘 6 个 canonical 层 finding（v-if 反模式 / cellMinWidth / boolean properties / button composition / spacing mismatch / sub-frame 真源缺失）让用户拍板 → 决策疲劳 + 项目失去线性流程" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [ "触发器D", "触发器K", "触发器G" ], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-08-phase-x4-2-and-badge-rename.md", "lines": 187, "s1Class": "superseded-weak", "shape": "phase-debug", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 26, "tldr": { "line": 9, "heading": "TL;DR", "endLine": 18 }, "decisionCandidateCount": 41, "decisionCandidates": [ { "line": 4, "text": "> 本复盘覆盖 commit e966d41 → Phase X.4.2 落地 → Badge 三轮 figma roundtrip → audit/alias 工具修整。" }, { "line": 11, "text": "- **Phase X.4.2 mass refactor**（19 components canonical 对齐 figma 真源 + TopBar slot rename + 24 page alias 统一）落地：fix specs + Codex 实施 + 6 agent 并行复审 + 12 处 §0 plan owner-defined token 值 drift 修" }, { "line": 12, "text": "- **Badge 三轮 figma roundtrip**（用户驱动 + MCP 验证 + canonical sync）：Black→Neutral 重命名 + Filled text 由 white 改 theme-aware → Filled bg `--bg-layer4` 改 `--bg-layer3`" }, { "line": 13, "text": "- **Audit 工具修整**：`audit:docs-site` regex 老 bug（不认 `@/src/` alias）→ 1 line fix；2 page 残余相对路径统一 alias；FormItem 用 components/Select → 改 canonical/SelectBoxFilled" }, { "line": 14, "text": "- **新行为约束**：(#16) plan owner 不下\"by-design\"判断，(#17) 视觉差异先验证 figma 真源 vs canonical token 一致再下结论，(#18) 阶段收口期 transient script 不入主 commit，(#19) 新阶段任务必须有 backlog/prompt repo 锚点" }, { "line": 19, "text": "## 阶段 A — Phase X.4.2 mass refactor 落地" }, { "line": 22, "text": "1. **Plan owner 写 19 fix specs** [`docs/internal/_prompts/x4-2-batch/-fix.md`](../_prompts/x4-2-batch/) — 4 parallel agents 起草 → plan owner 整合" }, { "line": 25, "text": "4. **Plan owner 复审**：5 个我自验 + 6 个 parallel agent 各审 3 components → **23 PASS / 1 PARTIAL**（Checkbox theme prop CSS 待 plan owner approval）" }, { "line": 26, "text": "5. **静态 token 值审计**：cross-check §0 已落 30+ tokens vs 19 fix specs 的 figma 真源数值 → **发现 12 处 drift**（`--input-number-*-width` / `--notification-width-side-pop` / `--radio-circle-border-width` / `--radio-selected-dot-size` / `--slider-track-h-m" }, { "line": 33, "text": "- 行为约束 #4 实证：prompt §4 完成报告含\"§4.X 完整改动清单\"段 → 配合 6 agent 并行复审让 silent scope creep 几乎不可能" }, { "line": 43, "text": "- User 改 figma：`Tag=Line` 变体的 text fill 由 `--color-type/text/primary-button` (white) 改为 palette color（Red/Line 文字 = `--ux/red/default`，etc.）" }, { "line": 44, "text": "- User publish → plan owner MCP `get_design_context` 验证 → canonical Badge.vue 加 `lineText` 字段" }, { "line": 45, "text": "- light-theme audit Badge: 11 → 4 finding" }, { "line": 47, "text": "### Round 2：Black → Neutral 重命名 + 全 Black 文字 theme-aware" }, { "line": 49, "text": "- User publish → plan owner MCP 验证 → canonical type/palette/content/figma.ts 等 5 文件改 `Black` → `Neutral`" }, { "line": 52, "text": "- light-theme audit Badge: 4 → 2 finding" }, { "line": 54, "text": "### Round 3：Neutral/Filled bg `layer_4` → `layer_3`" }, { "line": 56, "text": "- User publish → MCP 验证 → canonical Neutral.fillBg 改 `--bg-layer3`" }, { "line": 57, "text": "- 用户视觉验收\"目前 badge 看起来可以了\" → Round 3 收口" }, { "line": 61, "text": "- **figma-data raw 删除 stale variant** 是 destructive op，需用户授权——本次 Black→Neutral rename 用户隐式授权了\"包括但不限于之前的导出的组件的 JSON 文件\"" }, { "line": 70, "text": "- 根因：[`figma-sync/audit-docs-site-readiness.mjs:12`](../../figma-sync/audit-docs-site-readiness.mjs#L12) `extractImports()` regex `/from\\s+['\"]\\.\\.\\/\\.\\.\\/\\.\\.\\/src\\/(canonical|components)\\/([^'\"]+)['\"]/g` 只认相对路径，**不认 22/24 docs page 用的 `@/" }, { "line": 73, "text": "- 2 page (FormItemPage / IconPage) 用相对路径不合 alias 项目惯例 → 统一 alias" }, { "line": 74, "text": "- FormItem 用 `Select` (from components/) 不合 canonical-only 期望 → 改 canonical `SelectBoxFilled`" }, { "line": 75, "text": "- audit:docs-site error: 25+ → **0**（剩 6 warn 是 pixel review in-review 非 blocker）" }, { "line": 89, "text": "- **机制修复**（行为约束 #16）：plan owner **不**下\"by-design / 设计意图\"判断；只报告 figma binding + 实际渲染值，让 user 决定 figma 是否需修" }, { "line": 94, "text": "- **plan owner 实证**：grep `figma-data/normalized/variables.json` → `Color Type/Line/Deep Divider` 的 `Light: \"#dbdbdb\"` 与 canonical `--line-deep` light value 完全一致 → **canonical 严格镜射 figma**，\"不一致\"是错觉" }, { "line": 95, "text": "- **机制修复**（行为约束 #17）：plan owner 报\"视觉差异\"前必先 grep figma 真源 token value（dark+light 两 mode）vs canonical token 定义 → 一致则 figma 自身就这个值，不一致才是 canonical 漂" }, { "line": 100, "text": "- **plan owner 误操作**：把\"不提交\"误解为\"删除\" → 跑 `rm .light-theme-audit.mjs` + `pnpm remove playwright` → 未授权 destructive op" }, { "line": 106, "text": "- 不要混淆\"不入本次 commit\" vs \"从工作区删除\"——前者是 commit scope 控制，后者是文件生命周期管理。两者分立" }, { "line": 111, "text": "- **用户实证**：新 session 跑 grep `F20|f20` 搜遍 docs/ AGENTS.md backlog.md _prompts/ memory 全无命中→ 完全找不到任务上下文" }, { "line": 124, "text": "- **`src/components/Badge/Badge.figma.ts`**：Code Connect mapping Black→Neutral" }, { "line": 126, "text": "- **`playground/docs/pages/FormItemPage.vue`**：Select → SelectBoxFilled + alias" }, { "line": 136, "text": "- audit:published-vs-code 新增 needs-review 条目（per AGENTS.md 唤醒词约束，\"禁止自动 approved\"），需 user 单独审" }, { "line": 158, "text": "## 必记入册的 plan owner 行为约束（新增 4 条，编号续 2026-05-07 复盘）" }, { "line": 160, "text": "16. **Plan owner 不下\"by-design\"/ 设计意图判断**——视觉低对比、subtle outlined、低强度等措辞绕过 figma 端审视；只报告 figma binding + 实际渲染值，让用户决定 figma 是否需修" }, { "line": 161, "text": "- **Why**：行为约束 #1 硬规则衍生——canonical 永远只镜射 figma，\"by-design\" 是 plan owner 替 figma 编理由的反模式" }, { "line": 167, "text": "- **How to apply**：grep `figma-data/normalized/variables.json` 找 Dark/Light mode 值 → 对比 `src/tokens/variables.css` 同 token 同 mode → 一致 = canonical 严格镜射，\"不一致视觉\"是 figma 端就那个 design choice" }, { "line": 168, "text": "- **实证 case**：2026-05-08 plan owner 暗示 Badge light theme \"与 figma 不一致\"，user 拷问 → grep 实证两边 #dbdbdb 完全一致 → plan owner 撤回错误判断" }, { "line": 173, "text": "- **实证 case**：2026-05-08 plan owner 写 `.light-theme-audit.mjs` 驱动 Badge fix，commit prep 想留作\"待定项\" → user 判 \"F20 一起提交版本更干净\" → cleanup" }, { "line": 176, "text": "- **Why**：repo 是真源，对话是流；新 session onboarding 读 AGENTS.md → backlog → 必须能找到任务 scope" } ], "gatesMentioned": [ "audit-docs-site-readiness.mjs" ], "gatesDead": [ "audit-docs-site-readiness.mjs" ], "ruleIdsMentioned": [], "ruleIdsAlive": [ "触发器D" ], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-09-f23-formitem-page-rewrite.md", "lines": 127, "s1Class": "superseded-weak", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 15, "tldr": { "line": 3, "heading": "TL;DR", "endLine": 9 }, "decisionCandidateCount": 7, "decisionCandidates": [ { "line": 51, "text": "教训: prompt 设计阶段 (F23 prompt v1) 误以为 FigmaMembersGrid 通用; 实际 FormItem 的 slot-required 性质让 FigmaMembersGrid 不适配。**架构兼容性需要在 prompt 设计阶段 verify, 不能让 executor 跑完才发现**。" }, { "line": 53, "text": "### D2: align-items: center → flex-start (Issue 3)" }, { "line": 59, "text": "**Plan owner 元教训**: 历史 CSS override (尤其是 `:deep` 选择器) 经常基于\"Normal 假设\" 写, error / loading / disabled 等扩展状态会暴露 layout 假设。下次定 :deep override 时**先列出所有可能 child layout state 再决定 align-items**。" }, { "line": 72, "text": "| `.member-card :deep(.form-item__main) align-items: center` 历史 override 基于 Normal 状态假设, error 状态下 label 垂直居中错位 | 反模式 #5 (没问扩展时改哪里) | 写 :deep CSS override 时先列出 child 所有 layout state (Normal / Error / Loading / Disabled), 再决定 align-items / j" }, { "line": 79, "text": "| `b6b5cc38` fix(SelectBoxBase) | `src/canonical/SelectBoxBase.vue` | filled trigger bg `var(--bg-layer4)` → `var(--input-filled-bg)`, 1 line |" }, { "line": 96, "text": "> **⚠️ Next session 起手第一件事 (2026-05-10 更新决策)**：先做 **META-F27 系统性 review**, 再起 F20。**不要直接跑 F20**。" }, { "line": 105, "text": "2. (review 完后) Plan owner 决定哪些 cleanup 现在做; 落 cleanup commits" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [ "触发器G" ], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-09-microapps-mockup-retrospect.md", "lines": 167, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 20, "tldr": null, "decisionCandidateCount": 23, "decisionCandidates": [ { "line": 7, "text": "> **复盘焦点**：plan owner 在本次 session 暴露的 8 类反复出现的方法论错误 + 3 个 root cause + 10 条硬规则（已落 [`mockup-conventions.md`](../mockup-conventions.md) M11–M20）+ 库债 backlog（已落 [`backlog.md`](../backlog.md) BRIDGE-MOCKUP-001/002/003）。" }, { "line": 62, "text": "| 7 | **M9 / 规则僵化解读** | 2 | 把\"icon 配文字\"理解成必须永远显示文字 → 错过 icon-only + tooltip |" }, { "line": 63, "text": "| 8 | **写完规则立刻违反规则** | 2 | M10.1 写完下一条验证就 gestalt 通过 / M10.5 把 ObjID 错分类成\"定长\" |" }, { "line": 71, "text": "完成度阈值设低了。\"看起来对\"就停，不去逐元素 diff、不去 probe 数值确认。**质量阈值由我自己默认设定，而不是由\"产物能否直接交付\"决定**。" }, { "line": 89, "text": "写规则时大脑能识别错误模式，执行时大脑回到 reflexive 默认路径（快/省/简）。**M10.1 写完下一秒违反**就是最尖锐的证据——刚写\"自查必须 element-by-element\"立刻又给 gestalt 结论。" }, { "line": 92, "text": "- 规则放进 conventions 文档不等于会被执行" }, { "line": 98, "text": "## 四、对应的 10 条硬规则（已落 [`mockup-conventions.md`](../mockup-conventions.md) M11–M20）" }, { "line": 104, "text": "- **M11.1 — Probe-based 自查**（原 M11 — 禁止 gestalt 自查）：必须 4 步走 — probe reference + probe my impl + 字段级 diff + mismatch 解释" }, { "line": 105, "text": "- **M11.2 — 截图 literacy**（原 M12）：2× scale 截图 / probe 数值二次确认 / 1024 px 缩图禁止做 spec 判断" }, { "line": 106, "text": "- **M11.3 — Inverse-question 视觉元素**（原 M13）：删掉它会有 visible 损失吗？答\"看不出\"→重新审视" }, { "line": 113, "text": "- **M17 — 1px tall/wide 节点必须 probe `.fills`**：禁止凭几何尺寸猜视觉性质" }, { "line": 119, "text": "- **M20 — Column 宽度策略：FIXED vs FILL 按内容类型分类**：禁止\"全 FIXED / 全 FILL\"一刀切；定长 / 真变长 / responsive-display 三类分别处理" }, { "line": 137, "text": "不进 conventions 文档（因为不是项目级规则），但是 plan owner 自己的 reflex training：" }, { "line": 139, "text": "1. **每次 user 说\"自查 / 复盘 / 找还能优化\"** → 触发 M11.1–M11.3 流程，**不是输出 forward TODO list**" }, { "line": 140, "text": "2. **每次需要库组件** → 先 enumerate library 全部相关 component（多关键字 + 列出来），再决定用哪个；**不要现搜现用**" }, { "line": 141, "text": "3. **每次截图给 user 看** → 附 probe 关键字段值（不只截图）" }, { "line": 142, "text": "4. **遇到 user 问\"为什么 X 是这样\"** → 先讲推理路径，再讲修法 — \"为什么\"比\"修了\"更有价值" }, { "line": 143, "text": "5. **任何 \"we're done\" 类断言前** → 必须先输出 probe 数值，**禁止直接给视觉结论**" }, { "line": 147, "text": "## 七、最大的元教训" }, { "line": 149, "text": "> **写下一条规则的下一秒，我违反了它**。" }, { "line": 151, "text": "> 这暴露的不是认知问题，是 **execution discipline 问题**。规则不会自动 enforce 自己。" }, { "line": 153, "text": "> 下次起 session，**让 self-check 变成必经流程而不是可选 enhancement**——任何 \"we're done\" 类断言前必须先输出 probe 数值，禁止直接给视觉结论。" }, { "line": 155, "text": "这条不能写进文档，因为它需要的不是规则文字，而是反射性习惯。文档只能 capture rule，没法 capture discipline。所以这份复盘文件的真正价值不是被读，而是**作为下次 session 起手时的 onboarding artifact**——让起手的 plan owner 看到自己上次踩坑的具体记录，激发 vigilance。" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-11-bridge-mockup-004-baseline-assumption-invalid.md", "lines": 139, "s1Class": "residual", "shape": "bridge-mockup-log", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 16, "tldr": { "line": 3, "heading": "TL;DR", "endLine": 13 }, "decisionCandidateCount": 8, "decisionCandidates": [ { "line": 8, "text": "- BRIDGE-MOCKUP-004 entry 重定义为 **tracker entry**（不是单一任务），跨 v0.1.x → v0.2 sprint" }, { "line": 66, "text": "**根因**：backlog entry 写时**没跑 baseline**，凭\"figma-only 一般是漂移\"的范式 prior 假设；pickup 写时未质疑 backlog 假设。" }, { "line": 71, "text": "- 真相 vs 假设差 >2x 时 **STOP + 重新 propose 路线**，不要 fight 走完原路径" }, { "line": 72, "text": "- \"tracker entry\" 是 backlog 自然组合范式：当单一 task entry 工作量爆炸 → 拆 tracker + child entries" }, { "line": 78, "text": "- backlog 层：单一 task entry vs tracker + child entries（按工作量爆炸性决定）" }, { "line": 79, "text": "- executor 层：分阶段 prompt vs 一步到位 prompt（按假分阶段触发条件决定）" }, { "line": 115, "text": "- **重写覆盖**（旧版归 archived/）—— 适合**整个 sprint 路径前提变**（如 v0.1 → v0.2 大方向变）" }, { "line": 129, "text": "| 0.1.1 release cycle 演练 | 待 user 操作 | `changeset:version → tag → push → CI auto-publish` |" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-11-m21-r6-existing-pattern-reuse.md", "lines": 111, "s1Class": "superseded-weak", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 9, "tldr": null, "decisionCandidateCount": 26, "decisionCandidates": [ { "line": 1, "text": "# M21 + R6 — Existing pattern reuse 规则诞生复盘 (2026-05-11)" }, { "line": 5, "text": "US-3 任务：\"在 TVU SaaS Dashboard 产品文件（Usage Service 产品）新增 Cost per Token Trend dashboard 页\"。" }, { "line": 10, "text": "User 在任务进行中提示：\"像这个已有本地组件的，若无特殊说明，优先使用本地的组件，因为是新增功能，不是重新设计，已有模块需要直接挪用，否则出现不同页面同一时间的样式差异太大了。这条规则属于通用规则，应该可以更新 Mockup/code-conventions 的相关文件中。\"" }, { "line": 12, "text": "触发规则诞生流程。" }, { "line": 29, "text": "**关键洞察**：sibling page 的 \"dark cards on dark bg\" 是 authoring 偷懒（截图当 card 内容），不是 design-system-driven dark theme。盲目照抄 → 把懒惰原型传染。但用户看到的视觉合同就是 dark，应当对齐**视觉结果**，不对齐 authoring trick。" }, { "line": 33, "text": "- **1.a** — local 数据可 adapt（slot / variant） → 直接 instance" }, { "line": 34, "text": "- **1.b** — local 不可 adapt（bitmap / 硬编码） → mirror **视觉壳层**（用户看到的），rebuild internals 用 design system 真组件" }, { "line": 38, "text": "## 核心发现 2：M21 第一次实战 self-test pass — 配色 (a)→(b) 自纠" }, { "line": 46, "text": "- 路径 (a) → 与 sibling 视觉割裂（违反 M21）" }, { "line": 47, "text": "- 路径 (b) → 与 sibling 视觉对齐" }, { "line": 49, "text": "**自纠到 (b) dark 重建**。这次自纠不是 user 提示，是 AI 应用刚立的 M21 规则做的判断。规则的**实战有效性**得到第一次实证：规则不是说辞，规则在指导决策。" }, { "line": 51, "text": "教训：写规则当下立刻在当前任务上 *self-test*——如果规则在自己任务里都用不上，说明规则错或者用得不到位。" }, { "line": 67, "text": "- M14 要求每个元素重新判定适配性 → 标题放顶部（F-shape reading 通用 UX）" }, { "line": 70, "text": "写进 M21 \"与既有规则关系\" 段：M14 补充 M21——mirror 视觉合同**不**要求复刻 sibling 任一具体元素尺寸 / 间距。" }, { "line": 82, "text": "- 增 settings 页时不看 profile 页已有的 `` composable，重新从 canonical 拼 → ❌ 真实场景" }, { "line": 83, "text": "- 增 chart 页时绕过 dashboard 已用的 `` layout 包装器，独立用 raw chart lib → ❌ 真实场景" }, { "line": 85, "text": "\"import 机制存在 ≠ 自动复用\"。code 侧的 anti-pattern 不是技术机制缺失，是 *人/AI 没看 sibling 现状就开搞*——和 mockup 侧反模式根因相同。" }, { "line": 87, "text": "R6 镜像进 code-conventions 是对的。规则不能因为\"看似不会发生\"而省略——AI 没看 sibling 现状这件事在 mockup 和 code 两侧 *都会发生*。" }, { "line": 91, "text": "## 规则全文落地" }, { "line": 93, "text": "- **M21** → [`mockup-conventions.md`](../mockup-conventions.md) §M0 后、M1 前（作为 P1 hard rule）" }, { "line": 94, "text": "- **R6** → [`code-conventions.md`](../code-conventions.md) §R5 后、§关联文档 前（作为 P1 hard rule）" }, { "line": 102, "text": "这条 scope 区分是规则成立的关键——M21 / R6 不是要推翻 M2 / R0-R3，是**补全 incremental scope 的决策空白**。" }, { "line": 106, "text": "## 元规则启发" }, { "line": 108, "text": "1. **写规则当下 self-test**：新规则首要 acceptance criteria 是它能指导当前任务的决策（这次配色 (a)→(b) 自纠就是 self-test pass）" }, { "line": 109, "text": "2. **规则不能假设\"机制 = 行为\"**：import 机制存在不等于复用行为自动发生；规则要约束行为，不要假设机制保证" }, { "line": 110, "text": "3. **scope 显式标注**：M2 与 M21 不冲突的关键是 scope 时序差 (greenfield vs incremental) 写进规则正文，避免后续 AI 误判规则适用范围" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [ "§M0", "§R5" ], "ruleIdsAlive": [ "§M0", "§R5" ], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-11-mockup-conventions-trifecta-rule-update.md", "lines": 98, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 10, "tldr": null, "decisionCandidateCount": 20, "decisionCandidates": [ { "line": 3, "text": "> **Plan-owner 视角复盘**。SaaS Dashboard chart build 踩坑细节由 MicroApps session 自己 wrap-up 写；本文档聚焦三规则改动的设计决策与 cross-reference 互锁。" }, { "line": 11, "text": "MicroApps Console session 准备 Cost per Token Trend mockup 前，pre-step SaaS Dashboard chart 暴露三规则同时盲点：" }, { "line": 13, "text": "1. **AI 抄 user 发的数据参考截图主色（紫）** → 把数据样例截图当 spec 抄 → 违 M14" }, { "line": 14, "text": "2. **没 probe sibling page 视觉合同**（实际 sibling chart 用绿 + area chart） → 违 M21 字面执行" }, { "line": 15, "text": "3. **跳过 PRD \"feel more like business health indicator rather than technical monitoring graph\" design ask** → 把 user 显式视觉哲学需求降级成\"AI 觉得用户想要什么\" → M22 未存在，是 rule gap" }, { "line": 17, "text": "单一规则不够防 trifecta；需新增 + 扩展 + 互锁。" }, { "line": 21, "text": "## 三规则改动" }, { "line": 41, "text": "1. 标题 `复刻原 mockup 任一元素前必问适配性` → `复刻任何参考输入前必问适配性`——范围扩到 user 截图 / competitor 截图（user 发的截图打擦边球漏网是实战盲点）" }, { "line": 62, "text": "三规则不是孤立列表，要 **互相 link** 让未来 review 能从任一条找到完整案例：" }, { "line": 65, "text": "- **M22 § 与既有规则关系** 写 `M22 > M21 > M14`，cross-reference M14 踩坑段 + M21 probe 反例段" }, { "line": 67, "text": "- **M14 § 与既有规则关系** 写 `M22 > M14` + `M14 + M21 双层防线`（M14 防\"参考输入当 spec\"，M21 防\"sibling 合同没 probe\"）" }, { "line": 68, "text": "- **历史背景段** 加 2026-05-11 entry，写明 \"**M14 / M21 / M22 三规则同时违反**\"" }, { "line": 76, "text": "| 同一 build 错误可踩多条规则盲点，单一规则补强不够 | 三规则联动 cross-reference + Hierarchy 示例 |" }, { "line": 77, "text": "| User 显式 design ask 是最高优先级输入，必须有独立 acknowledge gate；不能默认靠 M14（\"截图不是 spec\"）兜底——M14 防的是误抄，不是 acknowledge 缺失 | M22 新规则诞生 |" }, { "line": 80, "text": "| 规则之间必须 cross-reference，否则未来 review 从任一条找不到完整案例 | Hierarchy 示例 + 三规则的\"与既有规则关系\"段都写 link |" }, { "line": 86, "text": "- **MicroApps session 实战检验**：Cost per Token Trend mockup 是 M22 / M21 probe / M14 ext 三规则上线后第一次 US-3 build，看是否能：" }, { "line": 90, "text": "- **MicroApps session wrap-up retrospect** 应**只写 build 第一手细节**（具体抄了什么紫色 / sibling 实际什么绿 / 哪步漏 probe），不重复本文档已记录的规则设计决策。" }, { "line": 91, "text": "- 若 Cost per Token Trend build 暴露**新**盲点（M22 / M21 probe / M14 ext 没 cover 的），触发第 4 条规则或第 4 块扩展。" }, { "line": 95, "text": "## 元规则补强（可选 future improvement）" }, { "line": 97, "text": "- **Plan-owner review 模式协议**: 三规则联动改动，executor 草案分块 propose + plan-owner 逐块改/留/调反馈，最终 plan-owner 直接 commit 的范式跑通——这次 plan-owner 直接 edit + commit 没回退给 executor 改，因为 executor session 已在跑别的 task（任务 2 build / 任务 1 verify）。考虑在 meta-rules.md 加一条：" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-11-package-rename-scope-alignment.md", "lines": 183, "s1Class": "superseded-weak", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 22, "tldr": { "line": 3, "heading": "TL;DR", "endLine": 12 }, "decisionCandidateCount": 17, "decisionCandidates": [ { "line": 6, "text": "- 修复：rename package scope `@tvu/design-system` → `@nancyzeng0210/tvu-design-system`，重发 **v0.1.2** patch — **first actual successful publish**。v0.1.0/v0.1.1 tags 保留为 historical artifacts（no consumer impact — no install ever succeeded）。" }, { "line": 19, "text": "| 1 | `git tag v0.1.0 && git push --tags` | \"tag pushed → CI 触发\" | ✅ 这一步正常 |" }, { "line": 21, "text": "| 3 | 8 strict audit 全过 + `pnpm publish` step exit 0 | \"audit + publish 都过 → published\" | ❌ **关键误判** |" }, { "line": 46, "text": "### 盲点根因" }, { "line": 58, "text": "- `docs/STATUS.md` \"已 publish\" 行 — 写\"2026-05-11 → GitHub Packages\"" }, { "line": 63, "text": "每一份都基于\"上游 retrospect / pickup 这么写所以是真的\"的链式信任，没人主动去 verify。" }, { "line": 69, "text": "中间信号 vs 最终 artifact 不区分 → 任何 distributed system 都会被坑。" }, { "line": 73, "text": "## §3 修复（落地清单）" }, { "line": 77, "text": "`@tvu/design-system` → `@nancyzeng0210/tvu-design-system`：" }, { "line": 90, "text": "- 改历史段 = 重写历史叙事 → 违反 \"history is history\" 原则" }, { "line": 95, "text": "**STATUS.md `Release wrap-up 必改项` 段（新增）**：" }, { "line": 127, "text": "**核心规则**：Release wrap-up 必须 verify package registry 实物状态；tag pushed + CI triggered 不等于 publish 成功。" }, { "line": 141, "text": "- **不要 retrofit 历史**叙事掩盖错判（CHANGELOG [0.1.0]/[0.1.1] 不改，错判留作 baseline）" }, { "line": 146, "text": "任何\"中间步骤成功 → 假设整链成功\"的 reasoning 都是 distributed system 经典坑：" }, { "line": 178, "text": "- 关联 retrospect: [v0-1-publish-flow.md](2026-05-11-v0-1-publish-flow.md)（保留 v0.1 publish 错判叙事作 baseline 实证，本复盘修正其结论）" }, { "line": 180, "text": "- [STATUS.md](../../STATUS.md) §Wrap-up 协议 §Release wrap-up 必改项（新增段）" }, { "line": 181, "text": "- [code-conventions.md](../code-conventions.md) §R5 §7（新增 release evidence 条目）" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [ "§R5" ], "ruleIdsAlive": [ "§R5" ], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-11-v0-1-publish-flow.md", "lines": 260, "s1Class": "residual", "shape": "release-log", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 27, "tldr": { "line": 3, "heading": "TL;DR", "endLine": 11 }, "decisionCandidateCount": 35, "decisionCandidates": [ { "line": 5, "text": "- **v0.1 publish 4/4 阻塞物全部解锁** → `@tvu/design-system@0.1.0` 已发到 GitHub Packages" }, { "line": 6, "text": "- 落 commit chain（跨 2-3 个 plan owner session）：`5125e625` (INFRA-F27) → `7e54d50d` (NPM-001) → `babee0fd` (NPM-002) → `520bb15a` (NPM-003) → `26122ad3` (收尾) → `v0.1.0` tag → `45ef1aa2` (pickup 归档) → `1c23bf28` (collision 修复)" }, { "line": 54, "text": "- CI 流程：checkout → setup pnpm/Node → `pnpm install` (触发 prepare = typecheck + build) → 2 warn-only audit → `pnpm publish --no-git-checks` (prepublishOnly 跑 7 strict audit)" }, { "line": 82, "text": "- **0.1.0 publish 之后**：每个 PR → `pnpm changeset` → 累积 → 发版时 `pnpm changeset:version` 聚合 + 自动 bump。从此版本号粒度变细。" }, { "line": 84, "text": "→ 接受 0.1.0 = \"foundation release\"；0.1.1+ 起严格 changeset 管控。" }, { "line": 88, "text": "NPM-003 Phase 1 baseline 发现 `v0.1.0` 已存在但指向 stale commit `49fb8f1e`（2026-04-22 早期 placeholder，103 commits 前）。**仅 local，未 push origin** → 可放心删除：" }, { "line": 104, "text": "**User 反馈**：\"没有推荐吗？不要弹窗确认\"" }, { "line": 107, "text": "- pickup/backlog/review 已预分析过的决策点 → 直接在文本里给推荐 + 理由，等 user 文本 go/no-go" }, { "line": 108, "text": "- 真正分叉决策（pickup 没预分析、user 没明确倾向）→ 才用 AskUserQuestion" }, { "line": 122, "text": "### Anti-pattern 3 — Baseline → 拍板 → Phase 2 假分阶段" }, { "line": 124, "text": "**现场**：写 NPM-003 prompt 时，我设计成两阶段——Phase 1 baseline audit 数据收集 + STOP → user 拍板 gate 配置 → Phase 2 写 publish workflow。Phase 1 跑完，executor 报告 7 PASS / 2 FAIL，我开始 propose gate 分层给 user 拍板。" }, { "line": 126, "text": "**User 反馈**：\"我需要的是一步到位，不要分那么多阶段了，除非是我后续又增加了新的 Figma 组件\"" }, { "line": 129, "text": "- baseline 不确定 → propose 时带 **风险 + recommendation + fallback** 一步到位写完整 prompt" }, { "line": 130, "text": "- 真正可分阶段：**外部 trigger 导致 scope 变化**（如 user 后续加 figma 组件 → 触发新 audit cycle）" }, { "line": 131, "text": "- 不是 plan owner 自己制造的 \"baseline 收集 → 拍板\"" }, { "line": 136, "text": "### Anti-pattern 4 — Backlog ID 凭印象选号 → collision" }, { "line": 142, "text": "- 挑**最大数字 +1**（不要补缺号 — 已弃用的 ID 可能在历史 retrospection / commit msg 里还有引用）" }, { "line": 143, "text": "- 写完 entry 后 grep 新 ID 在仓库其它处出现的命中数：应只有 1（backlog.md 内）；如 >1 → 又撞了" }, { "line": 164, "text": "1. 硬编码项目级规则到工具（应在 `.md` 真源，工具读真源）" }, { "line": 170, "text": "命中任一 → 重新设计，不 fire。本次 NPM-002/003 每个 prompt §6 都有自检表实证。" }, { "line": 191, "text": "### 6. changesets 工作流（累积 → 聚合 → bump → tag）" }, { "line": 194, "text": "- 发版时 `pnpm changeset:version` 聚合 → 自动 bump `package.json` version + 写入 CHANGELOG 新段" }, { "line": 195, "text": "- `git tag vX.Y.Z && git push --tags` → CI 自动 publish" }, { "line": 216, "text": "> **AI 协作工程化 ≠ AI 自由发挥。让多 AI 工具（Claude/Codex/Cursor/Cline/Copilot）在同一项目协作不互相破坏，关键是把规则\"硬\"在仓库里——而不是\"软\"在某个 AI 的 prompt 历史里。**" }, { "line": 221, "text": "- 项目级规则真源在 `.md` 文件（AGENTS.md / meta-rules.md / mockup-conventions.md）" }, { "line": 222, "text": "- 工具读真源 → 任何 AI 工具新接手该项目 24h 内就能上手" }, { "line": 231, "text": "- \"Baseline → 拍板 → Phase 2\" 这种 plan owner 自己造的分阶段 = 浪费 cycle + 用户决策疲劳" }, { "line": 237, "text": "1. **AI 凭\"行业惯例\"自由发挥**（违反 AGENTS.md 硬规则 #2）→ 必须读 `translation/` 已登记决策；新决策必须 user 拍板" }, { "line": 238, "text": "2. **AI 自创未登记的 prop / variant / 状态** → 例如 Notification 历史上自创的 `success` status（已识别为 bug，等待删除）" }, { "line": 239, "text": "3. **AI 把项目级规则硬编码到脚本里**（违反 meta-rules §3 #1）→ 应在 `.md` 真源；工具读真源；规则修改 = 改一处" }, { "line": 247, "text": "| CANONICAL-009 | Tab.vue 硬编码 + Icon/Logo raw SVG → 升 audit:design-system strict | Medium | ~2-3h |" }, { "line": 248, "text": "| BRIDGE-MOCKUP-004 | 2 figma-only 组件漂移 → 升 audit:published-vs-code strict | Medium | ~1-2h baseline + 后续 fix |" }, { "line": 250, "text": "| 0.1.1 演练 | 走一次完整 changeset → version → tag → publish 流程，验证工具链 | Medium | 视后续 patch 发版触发 |" }, { "line": 257, "text": "- 本复盘文件落仓库前漏写了 ~30min（plan owner 疏漏 — v0.1 publish 流程完整闭环后没主动写复盘）。User 提醒 → 补写。" }, { "line": 258, "text": "- AGENTS.md §共同规则要求 \"阶段完成后追加复盘到 `docs/internal/retrospection/{date}.md`\" 应作为 plan owner closing checklist 强制项（next-session pickup §8 元说明同步加 reminder）" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-12-evolution-step-1.md", "lines": 37, "s1Class": "residual", "shape": "evolution-step", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 5, "tldr": null, "decisionCandidateCount": 8, "decisionCandidates": [ { "line": 1, "text": "# Retrospect — Design Process Evolution Step 1（C 系列规则修订）" }, { "line": 4, "text": "**TL;DR**: C1/C2/C3/C4 四项规则修订全部落地。M16 从\"必须改\"改成\"必须评估\"；M14 加 IA level / persona / state / device / locale 五维度 context 检查表；新建 design-discovery skill；meta-rules 加\"枚举特例\"元规则。" }, { "line": 12, "text": "| C1 | `docs/internal/mockup-conventions.md` | M16 全文替换：标题从\"Library 组件不可裸用\" → \"默认值必须评估，不可直接用 placeholder 当真实内容\"；规则体从\"必须改\"→\"必须评估（符合则可保留）\" |" }, { "line": 14, "text": "| C3 | `~/.claude/skills/design-discovery/SKILL.md` | 新建文件（1.4 KB）：5 项 deliverable（Personas / Use scenarios / Pain points / User stories / Market analysis）+ Pain→Feature mapping + MVP scope 声明 + gate + 跳过记录 |" }, { "line": 15, "text": "| C4 | `docs/meta-rules.md` | §3 反模式清单加 sub-section \"反模式 — 规则正文枚举特例\"（现象 / Why 错 / 修正表 / 自查）|" }, { "line": 21, "text": "- **M16 修正精神**：规则原来隐含\"AI 需为每个 default 做 override\"——实际违反\"举一反三\"，instance 过度 override 失去 library 同步价值。改成\"评估\"更准确。" }, { "line": 22, "text": "- **M14 C2 vs M21 sub-rule**：原方案 M21 加 IA probe 行 → 最终选 M14 加 generic context 维度表，因为 IA level 是 \"reference input adaptation\" 问题，不是 \"sibling visual contract\" 问题。任何未来出现的 context mismatch 都被表格覆盖，不需逐个加规则。" }, { "line": 29, "text": "- 无（Step 1 按 prompt 字面落地，无偏差）" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-12-evolution-step-2.md", "lines": 38, "s1Class": "residual", "shape": "evolution-step", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 5, "tldr": null, "decisionCandidateCount": 6, "decisionCandidates": [ { "line": 12, "text": "| D1 | `docs/internal/mockup-conventions.md` | M11/M12/M13 → 合并为 M11 Self-audit Discipline（M11.1 Probe-based 自查 / M11.2 截图 literacy / M11.3 Inverse-question）；删除原 M12/M13 独立段落 |" }, { "line": 13, "text": "| D1 cross-ref | `docs/internal/retrospection/2026-05-09-microapps-mockup-retrospect.md` | M11/M12/M13 → M11.1/M11.2/M11.3；M11–M13 流程 → M11.1–M11.3 流程 |" }, { "line": 15, "text": "| D2 edit | `docs/internal/mockup-conventions.md` | 删 M17-M20 内容；原 `### 反 C — Silent API + Rule execution` 段替换为单句指针 → `figma-technical-reference.md` |" }, { "line": 16, "text": "| D3 | `docs/internal/mockup-conventions.md` | 顶部加 Rule Category Guide 表（3 类：Process Rules / TVU Domain / Figma Quirks）；原 \"Plan-owner 方法论硬规则 M11-M20\" → \"Process Discipline Rules（M11/M14/M15/M16）\" |" }, { "line": 24, "text": "- **D3 \"不动顺序\"的实践**：当前规则跨 section 交叉（Process rules 和 Domain rules 在 Hard Rules 里混排），无法用 section header 完全分离而不动内容。最终选择在顶部加 Category Guide 表 + 重命名 Plan-owner 段，是在 \"不动顺序不动内容\" 约束下能做到的最清晰分类。Step 3 E5 再做真正的分离。" }, { "line": 30, "text": "- `2026-05-11-saas-dashboard-2-option-pm-review.md:129` \"M11 元教训\"保留为 M11（父级规则名），未拆成 M11.x，属有意保留（M11 整体作为 self-audit 概念仍成立）。" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-12-evolution-step-3.md", "lines": 47, "s1Class": "residual", "shape": "evolution-step", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 6, "tldr": null, "decisionCandidateCount": 7, "decisionCandidates": [ { "line": 4, "text": "**TL;DR**: 三条 path 从单一 mockup-conventions.md 提取出来：design-process.md（通用 process 原则）+ domain-tvu.md（TVU 业务规则）+ tools/figma-quirks.md（Figma quirks 快查表）。两条 path conventions 加必读链路入口。" }, { "line": 13, "text": "| `docs/internal/domain-tvu.md` | ~80 行 | TVU 业务规则 6 条：M3 状态色 / M4 dark theme / M5 no session creation / M7 control surface / M8 dashboard cards / M9 action labels |" }, { "line": 22, "text": "| `docs/internal/retrospection/2026-05-09-microapps-mockup-retrospect.md` | E6 cross-ref 更新（M11/M12/M13 → M11.1/M11.2/M11.3）|" }, { "line": 28, "text": "- **\"Thin\" 的实现方式**：conventions 文件没有删除规则内容，而是在顶部加 **必读链路** 表。理由：删除会破坏历史 AI 依赖这些文件的 session onboard 路径；加入口指针 + 保留内容在 E5 阶段是最稳妥的做法，实质上新 session onboard 从链路入口出发。" }, { "line": 29, "text": "- **design-process.md voice-neutral**：所有规则措辞改为\"生成 deliverable\" / \"采用 source 组件\"，不说\"画 mockup\"或\"写代码\"。M21 probe 表也做了 path-neutral 化（不引用 Figma 特定 API）。" }, { "line": 30, "text": "- **domain-tvu.md scope**：M1（TVU Top bar，Figma-only）和 M10（icon Color Variable，Figma-only）没有放入 domain-tvu.md，它们是 Path A 专属规则，留在 mockup-conventions.md 更合适。domain-tvu.md 只放 Path A + Path B 都适用的业务规则（M3/M4/M5/M7/M8/M9）。" }, { "line": 37, "text": "新 session 上手**只读 design-process.md + domain-tvu.md**（共 ~16 条规则）可以覆盖 80% 决策路径：" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-12-evolution-step-4.md", "lines": 42, "s1Class": "residual", "shape": "evolution-step", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 5, "tldr": null, "decisionCandidateCount": 0, "decisionCandidates": [], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-12-evolution-step-5.md", "lines": 52, "s1Class": "residual", "shape": "evolution-step", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 5, "tldr": null, "decisionCandidateCount": 3, "decisionCandidates": [ { "line": 18, "text": "- **Persona 来源**：优先从 design-discovery skill 输出取，无 discovery → 按 PRD 推断 + 用户确认。设计走查（F1）先行，persona 模拟（F2）聚焦用户视角反应，两者互补。" }, { "line": 30, "text": "- 🔴 \"this month\" 时间锚点与 6M date picker 不同步 → 已修复为 \"this period\"（Figma node `1780:402`）" }, { "line": 31, "text": "- 🟡 X 轴 Jan→Jul（7 labels）与 6M tab 不一致 → 已修复为 Nov→May（nodes `1780:181–187`）" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-13-canonical-011-prompt-gap.md", "lines": 61, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 6, "tldr": null, "decisionCandidateCount": 5, "decisionCandidates": [ { "line": 20, "text": "## 2 — 一般化教训" }, { "line": 45, "text": "**结论**：先 inline 进每个 canonical prompt 的 §0 export wiring 段。等 3 个以上 canonical impl 都 inline 后再考虑抽 template（OK 抽象，遵循 CLAUDE.md \"三似 better than premature 抽象\"）。" }, { "line": 56, "text": "1. 起手必读 STATUS.md → 第 3 项 `_plans/next-session-pickup-*.md`（如有指向）" }, { "line": 58, "text": "3. **应 grep `docs/internal/retrospection/*canonical-impl*` + `*prompt-gap*` 看历史教训**（不在协议里，建议加进 META checklist）" }, { "line": 60, "text": "如要更机械触发：把 §2 表格直接写进 [`docs/meta-rules.md`](../meta-rules.md) 的「Audit/数据产出类 prompt 子规则」段或 AGENTS.md 必读链路第 6 项后面。但那是更大动作，本次先存档此 retrospect。" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-13-layout-a-line-by-line.md", "lines": 36, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 6, "tldr": null, "decisionCandidateCount": 5, "decisionCandidates": [ { "line": 7, "text": "## 翻车 → 升级路径" }, { "line": 17, "text": "**形态**：同一 text node 内，按 EN 自然分行（`\\n` 或 `•`）拆段，每段后内联 ZH，再 `\\n` 进下一段。继承 Layout A-右 的所有规则（同节点 / 2-space 分隔 / Noto Sans SC / 小 2px / opacity 0.45），区别在于\"拆 line\"。" }, { "line": 21, "text": "**反例**：未拆 line 就整块内联（EN 全段 + 2-space + ZH 全段）→ ZH 在 EN 末尾继续 wrap，工程师看不到一一对应。" }, { "line": 27, "text": "1. **设计规范的\"内联式\"不是单一形态**。Layout A-右 是单行 case 的语法糖，多行 case 需要 A-逐行 sub-form——首版翻车根因是\"用单行 case 的规则强套多行 case\"。" }, { "line": 35, "text": "- 改动：表格新增 1 行（A-逐行）+ 决策树 3 分支 → 4 分支 + 技术实现段补代码骨架 + 视觉优先级段下加 \"逐行内联 > 上下分节\" 原则 + 反例改写 + 验收清单 + 1 条" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-13-onboarding-gate-enforcement.md", "lines": 93, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 7, "tldr": null, "decisionCandidateCount": 8, "decisionCandidates": [ { "line": 23, "text": "1. AGENTS 硬规则 #6 — Figma URL → code 必须用 `src/canonical/*`" }, { "line": 28, "text": "User 反问：\"上面这个路径是我对你的预期，你是按照这个顺序来读取的吗？\" → AI 诚实承认偏离 → 补齐 → 进入修复设计。" }, { "line": 32, "text": "## 2. 根因 — L1 文本规则不够" }, { "line": 43, "text": "这是 [`meta-rules.md`](../meta-rules.md) trigger K \"客观可测规则必须 L3+\" 的直接违反 — onboarding 链路是**客观可测**（Read 5 个文件 / 没 Read = 不合格），不应停在 L1。" }, { "line": 52, "text": "| **L1b** | `AGENTS.md` 顶部新增 `⛔ Onboarding Gate` 段（5-step checklist + 机械执行说明 + 违反信号）| ✅ 所有工具 | 文本 + mandatory 措辞 |" }, { "line": 74, "text": "## 5. 通用工程教训" }, { "line": 76, "text": "1. **L1 文本规则 = 提示，L3 hook = 触发** — 关键流程必须升 L3，文本规则不可替代机械触发" }, { "line": 90, "text": "- **触发器**：`docs/meta-rules.md` trigger K（客观可测规则 → L3+）" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-13-v020-release-and-infra-f30.md", "lines": 130, "s1Class": "residual", "shape": "release-log", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 15, "tldr": null, "decisionCandidateCount": 21, "decisionCandidates": [ { "line": 3, "text": "> **TL;DR**：v0.2.0 ✅ shipped & verified；CI 第一次 fail（CANONICAL-011 prompt gap — ChartPage 未登记 site-review-manifest）借机修了 + 顺手补 INFRA-F30（3 个 timestamp churn source 全 idempotent）+ 完整 v0.2 → v1.0 排期 SoT 落仓库 + meta-rule trigger M 防排期反模式复发。三件套打包 " }, { "line": 17, "text": "| **回滚 cost** | 0（v0.2.0 第一次 publish 失败时 Packages 页无实物 → 删 remote tag 重打无 consumer 影响）|" }, { "line": 35, "text": "| **计划层 SoT** | `tracker.md` | \"排期原则\" 自检清单 5 条 + Release 排期 v0.2 → v1.0（每版本对齐 PROJECT_GOAL 5 能力栏）+ 轨道 C 自动化 Tier 1/2/3 |" }, { "line": 38, "text": "| **元规则层** | `meta-rules.md` | 新增 **trigger M（排期决策反模式）** — 信号词机械触发 + 违反检测 + 实证案例 + 附录沉淀 |" }, { "line": 59, "text": "## 3 — 关键决策 / 反模式 / 教训" }, { "line": 65, "text": "→ **后续**：CANONICAL prompt 模板必须含 site-review-manifest entry deliverable（同级 docs/canonical/.vue/page/spec）。" }, { "line": 69, "text": "`audit:docs-site` exit 1 → publish.yml exit 1 → Packages 页完全无实物。如果按 v0.1.0/v0.1.1 silent fail 时代的协议（只看 CI green），我会以为 publish 成功；按 STATUS release wrap-up 协议必 verify Packages 实物 → 真实状态可见 → fix → re-publish。" }, { "line": 71, "text": "→ **协议价值实证**：v0.1.0/v0.1.1 silent fail 后加的 \"Packages 页 actual 显示\" 步骤是真有用的，不是 ceremony。" }, { "line": 79, "text": "| **consumer 影响** | 0（v0.2.0 publish fail → Packages 无实物 → 无 consumer 装过）|" }, { "line": 84, "text": "→ **教训**：destructive 不等于不能做；按\"实物影响 + 可逆性 + 替代成本\"框架决策，本次 A 路径明确优。" }, { "line": 90, "text": "→ **后续**：trigger K (规则提案声明 enforcement) 配套加 sub-rule \"新 sync/audit 脚本必须用 F26/F29 idempotent helper 写文件\"？暂不加 — 等真有第 4 个 dirty source 再 promote 成机制。" }, { "line": 94, "text": "User 纠正 \"v1.0 major\" 措辞后，我意识到排期决策反模式很容易复发（按耗时/复杂度排）。把这写成 meta-rules trigger M + 4 层防失忆机制（tracker + STATUS + PROJECT_GOAL + trigger M）是 trigger K \"规则文档无法保证执行\" 的具体落地。" }, { "line": 96, "text": "→ **新机制实证**：下次 session 提排期前必须读 tracker §排期原则；trigger M 信号词机械触发；违反时回 5 条自检。" }, { "line": 105, "text": "→ **判断 ok 的边界**：同一 commit 内、同一 pattern、同一 user pain → 扩 ok；不同 pattern 或新 deliverable → 不扩。本次未越界。" }, { "line": 114, "text": "| STATUS.md \"当前版本\" → v0.2.0 + Packages URL evidence | ✅ done |" }, { "line": 118, "text": "| 下个 session 启动 v0.3.0 主线（Tier 1-A translation schema 化）| → 起手 onboarding |" }, { "line": 119, "text": "| CANONICAL prompt 模板补 manifest deliverable checklist（防 P1 复发）| → backlog |" }, { "line": 125, "text": "- **0.x semver 哲学落地**：minor 含破坏性、patch 只 non-breaking、1.0 = 稳定承诺；写进 trigger M 违反检测。" }, { "line": 126, "text": "- **排期 SoT 4 层防失忆**：tracker（计划）+ STATUS（状态）+ PROJECT_GOAL（目标）+ meta-rules（元规则）；每层各自独立可读，单点失忆不影响整体。" }, { "line": 127, "text": "- **协议价值需实证**：v0.1.0/v0.1.1 silent fail 后加的 Packages 页 verify 步骤本次第一次\"如果没它，我会以为 CI green = publish 成功\" → 协议 value 直接看到。" }, { "line": 129, "text": "- **INFRA-F30 模式可复用**：未来任何\"每次跑都 dirty 的 generate/audit 输出\" → 同 F26/F29/F30 pattern，inline helper + timestamp strip + skip。当前 8 个 candidate 待 user feedback 触发再做。" } ], "gatesMentioned": [ "audit-page-t2-sample.mjs", "audit-figma-published-vs-code.mjs" ], "gatesDead": [ "audit-page-t2-sample.mjs", "audit-figma-published-vs-code.mjs" ], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-13-vitest-fixture-drift.md", "lines": 73, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 10, "tldr": null, "decisionCandidateCount": 12, "decisionCandidates": [ { "line": 4, "text": "> **结论**：3 个本 session commit（CANONICAL-002/006/008）在 page/component 重构时漂走了 test fixture，commit 时未跑 vitest gate → 直接进 master。" }, { "line": 13, "text": "| `596acb05` feat: Rating figma → token-driven (L3) | Rating.vue 删 `theme` prop | tests/Canonical.test.ts Rating: 仍传 `theme: 'light'` + 断言 `data-figma-theme=\"light\"` |" }, { "line": 17, "text": "| 多 page 迁移到 `figma-data/normalized/docs-figma-members/*` 数据模块 | variant count 从双 theme 合并 → 单 theme 真实计数（如 Notification 14 → 7） | tests/RemainingCanonicalPages.test.ts: 5 处 variant count / source 名漂移 |" }, { "line": 22, "text": "## 2 — 根因" }, { "line": 34, "text": "## 3 — 教训 / pattern" }, { "line": 38, "text": "测试断言 `wrapper.text()).toContain('variant count=14')` 这种**写死 runtime-rendered 文本**的测试，对应数据漂移时不会编译错也不会运行错，**只在跑测时报错**。Commit 时不跑 → 直接进 master。" }, { "line": 40, "text": "→ **缓解**：F21 pre-commit hook 加 `pnpm test` 🔴 block（本次 backlog 已升级）" }, { "line": 46, "text": "→ **决策**：删 `requiredSourceMarkers` 检查（rendered-text 检查应该走 mount-based `RemainingCanonicalPages.test.ts`，而不是 source grep）" }, { "line": 52, "text": "→ **存档为 debugging 标准动作**：怀疑某改动引入回归 → stash + 跑测 + pop 比对" }, { "line": 58, "text": "最终决定保留 dead field、commit 仅 3 个 test 文件（+15/-28），把 dead field 清理留给后续 lint hygiene 顺手。**最小 diff = 最低回归风险**。" }, { "line": 71, "text": "- **commit chain 走得越快越要警惕**：F19 close / F20 prompt / CANONICAL-002/008 close 一连串 commit 在同一天连发，相互掩护视觉成本（\"前一个 commit 都没跑 test，这个也别管了\"）。F21 落地前临时纪律：**每个 commit 前 `pnpm test`**，session-end wrap-up 再确认一遍。" }, { "line": 72, "text": "- **release health 优先 > dirty 噪音**：vitest 不绿是 release 路径直接 break（changesets → CI → publish），F26 dirty 噪音只是开发体验。推荐路径排序 vitest 修 → F26，事后回看正确。" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-14-tier1a-translation-schema.md", "lines": 42, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 5, "tldr": null, "decisionCandidateCount": 0, "decisionCandidates": [], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-14-v030-release.md", "lines": 228, "s1Class": "residual", "shape": "release-log", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 20, "tldr": null, "decisionCandidateCount": 17, "decisionCandidates": [ { "line": 13, "text": "| 1 | `40e8c777` | axis-implementation-map.md → JSON + Schema (16 instances) | ~1h vs 1d |" }, { "line": 14, "text": "| 2 | `76e99070` | prop-aliases.md split → JSON (102 entries 13 scope) + 瘦身 md (225→125 行) | ~1h vs 2-3d |" }, { "line": 15, "text": "| 3 | `859c2ba5` | divergences.md split → decisions JSON (26 decisions 8 category) + 保留 narrative | ~1h vs 2-3d |" }, { "line": 20, "text": "- audit `shell: '/bin/sh'` → `/bin/bash`（rg/grep PATH 解析需要）" }, { "line": 21, "text": "- 5 处 divergences verifyHint `rg -n` → `grep -rnE`（本机无 rg binary; spec/prompt 既推荐 grep）" }, { "line": 33, "text": "**Audit dim 6 机械防复发**：扫 STATUS.md / tracker.md 所有 `### ... v0.X.Y` section（archived ~~v0.X.0~~ 段除外），cross-check `divergences-decisions.json` `category: resolved` 的 `resolutionRef`，inline ack 检测窗口 30 chars。实证抓到 8 个 stale finding 后修正 + 维度 6 落" }, { "line": 48, "text": "**Plan owner fix**：generator 排除已在 axes 字段的 prop name（figma-mcp-cache TSX lossy 把 enum axis 如 Radio.Status=\"on\"|\"off\" 推断成 boolean，会造成假阳性）。修后 17 → 8 boolean props（5 components）。" }, { "line": 63, "text": "- `pnpm changeset:version` → package.json 0.2.0 → 0.3.0 + CHANGELOG 聚合" }, { "line": 66, "text": "- **Packages API verified**：`0.3.0` created 2026-05-14T08:25:59Z（v0.1.0/v0.1.1 silent fail 教训 mandatory verify）" }, { "line": 91, "text": "## 3 — 关键决策 / 反模式 / 教训" }, { "line": 96, "text": "- Tier 1-A spec §0：plan owner read 6 个 translation 文件后发现 \"5 SoT 统一\" 描述不准确（实际 6 文件 + 1 draft），\"split\" 路径比 \"整 md → JSON\" 更适合" }, { "line": 97, "text": "- BRIDGE-005 baseline 发现 scope 实际更小（mcp-cache 已含数据），估时 6-10h → 实跑 1.5h" }, { "line": 122, "text": "**问题**：plan owner 自己写完 prompt 后留 untracked + session-start hook 自动 bump STATUS.md → 3 项 dirty 打破 §0 假设 → executor 严格 STOP。" }, { "line": 132, "text": "### D. SoT drift 根因 + 机械防御（Phase 6.3）" }, { "line": 134, "text": "**链路 stale 传染**：每一步看起来合理，没人做 cross-check → drift 持续放任 13 天 → plan owner baseline 时被 misled。" }, { "line": 137, "text": "- 文本规则 \"active 段不能含 resolved 项\" 弱（人易忘）" }, { "line": 154, "text": "### F. v0.1.0/v0.1.1 silent fail 教训持续生效" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-14-v040-release.md", "lines": 155, "s1Class": "residual", "shape": "release-log", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 15, "tldr": null, "decisionCandidateCount": 12, "decisionCandidates": [ { "line": 6, "text": "> - Tag: `v0.4.0` → release commit `77f338fd`" }, { "line": 15, "text": "| Audit fix | `cca1a043` | audit-translation-completeness.mjs h2 boundary fix（防 `### v1.0.0` section 吞掉后续 `## 轨道 A` timeline 表 → 2 个 Phase 6.3 false-positive active-stale 清除） | 30min / TBD |" }, { "line": 57, "text": "## 反模式 + 学到的教训" }, { "line": 61, "text": "**症状**：H2 audit fix prompt + Phase 6.6a prompt v1 都含 `## 5. Commit message` section 给完整 commit message 模板 → Codex 跟着 verify-then-commit。" }, { "line": 65, "text": "**教训**：写 prompt 前 grep 最近 3-5 个 prompt 的结尾段（`## 严格不做` + `## 完成后 STOP`），机械复用模板；不要脑补。落实到 [`feedback_executor-no-self-commit`](../../../-Users-nancy-claude-projects-tvu-design-system/memory/feedback_executor-no-self-commit.md) memory。" }, { "line": 69, "text": "**症状**：6.6a 时 Codex 报告 \"docs contract 禁止 component page import src/components/*\"，我 grep `docs/` + `AGENTS.md` + `playground/` 没找到 → 错误结论 \"Codex 编造\"，并指示 6.6b prompt 让 Codex 用 `from '@/src/components/Icon/Icon.vue'` 修 demo。" }, { "line": 73, "text": "**Root cause**：plan owner grep 范围太窄（漏 `tests/`），下结论\"不存在\"前没覆盖全仓库。" }, { "line": 75, "text": "**教训**：rationale 实证必须 grep 全仓库（`tests/` + `scripts/` + `.husky/` + config 文件，不仅 markdown）。落实到 [`feedback_review-result-vs-rationale`](../../../-Users-nancy-claude-projects-tvu-design-system/memory/feedback_review-result-vs-rationale.md) mem" }, { "line": 81, "text": "**Root cause**：pickup 是手写文档，跟 canonical 代码 / divergences-decisions.json 不自动同步；写时基于过时认知 → desync。" }, { "line": 83, "text": "**教训**：开始 sprint 实施前 **plan owner baseline 实跑**：读 canonical 现状代码 + grep decisions JSON 现状，再对照 pickup spec。如发现 desync → propose path B（修 pickup/spec）或 path A（实施补齐），不擅自按 pickup 跑。" }, { "line": 121, "text": "| 15. CI run → green wait | 自动 | 自动监控 |" }, { "line": 154, "text": "**Next**：tag v0.4.0 push → CI green → Packages 页 verify → STATUS.md 回填 evidence → 进 v0.5.0 主线。" } ], "gatesMentioned": [ "audit-translation-completeness.mjs" ], "gatesDead": [ "audit-translation-completeness.mjs" ], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-18-v050-release.md", "lines": 115, "s1Class": "residual", "shape": "release-log", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 12, "tldr": null, "decisionCandidateCount": 12, "decisionCandidates": [ { "line": 6, "text": "> - Tag: `v0.5.0` → release commit `2b54a73b` (+ hotfix `4f18a065` `4b7de2ed`)" }, { "line": 21, "text": "| CANONICAL-007 | `63a9cdaf` | Pagination native button → DS Button (`canonicalStyle/Color/Size/Radius` + `:deep(.btn)` compact) | ~30min / ~2h |" }, { "line": 24, "text": "| CI hotfix #1 | `4f18a065` | token-aliases.ts `Mask blur8` single→double-space match figma 真源 | ~10min |" }, { "line": 33, "text": "### v0.5.0 scope 反复 (X → Z)" }, { "line": 39, "text": "**User 拍板 → Z 路线**: 把 INFRA-F32 也做完一起发，unblock Tier 1-B 数据源（audit 实现仍 v0.6.0）。" }, { "line": 41, "text": "**结论**: F32 实跑 ~30min（远低于估 2-3h），ROI 极好——一个 session 解锁未来 Tier 1-B audit；Z 路线判断对，X 过度保守。" }, { "line": 63, "text": "- 本地 Node 22+ 有 `node:fs.globSync`，CI runner Node 20 没有 → `SyntaxError: globSync not exported` at module load (try/catch 来不及 fallback)" }, { "line": 75, "text": "- 不做 normalized-key match → 旧 entry 的 canonicalToken/usage 丢失" }, { "line": 76, "text": "- 不修 token-aliases.ts → audit:translation-completeness `token-figma-reference` 抓 missing alias → CI fail" }, { "line": 79, "text": "**漏了**：token-aliases.ts 反向（code → figma）也用单空格 → audit fail；release CI 抓出来" }, { "line": 85, "text": "**模式**: 上 session 写 pickup 决定版本 scope；下 session 起手照办；用户 push back 时及时调整。" }, { "line": 89, "text": "**实证本 session**: Z 路线把 F32 加入 → Tier 1-B 解锁 → 下 session 直接做 audit 而不再等\"前置 sync 机制\"。" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-27-bridge-mockup-007-roi-validation.md", "lines": 154, "s1Class": "residual", "shape": "bridge-mockup-log", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 22, "tldr": null, "decisionCandidateCount": 7, "decisionCandidates": [ { "line": 54, "text": "- **T3 救场（0.0）**：TVU 库 `search_design_system` 对 sun/moon/theme/dark/light 全无命中 → A fallback Setting/Switch（语义偏离）。SoT 把 picture-light 的 synonyms 含\"theme toggle / brightness\"，B 一击命中。这是 **SoT 不可替代** 的 case" }, { "line": 64, "text": "→ BRIDGE-MOCKUP-007 目标从 ~~\"icon 语义数据库\"~~ → **\"mockup 一致性收敛器\"**" }, { "line": 68, "text": "## Scope hole 根因" }, { "line": 89, "text": "| **D** | Sync 机制：扩 `pnpm sync:figma-library` 加一步对比 Figma 库新增/移除 icon vs `affordance-categories.json`，差异 → 候选 entry / 弃用警告 | 1-2h |" }, { "line": 134, "text": "v3 T1/T7 A 选得更好，第一反应是\"schema 不够好\"——但根因是 35-pilot scope 漏。**schema 没坏，要扩 scope**。" }, { "line": 136, "text": "### 4. user judgment 反转结论方向" }, { "line": 137, "text": "我最初推 demand-driven，user 立刻指出\"不集中、要批量、且 SoT 应镜像 Figma 库\"。这个反推完全正确，把方案从 trickle 改成 batch + 全库镜像。**plan owner 要保持对 user 战略输入的开放，不要锚定第一推荐**。" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-05-28-bridge-mockup-008-closure.md", "lines": 158, "s1Class": "residual", "shape": "bridge-mockup-log", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 19, "tldr": null, "decisionCandidateCount": 24, "decisionCandidates": [ { "line": 4, "text": "> Total span: 2026-05-27 (BRIDGE-MOCKUP-007 ROI PASS → BRIDGE-MOCKUP-008 open) → 2026-05-28 (4 phase shipped)" }, { "line": 5, "text": "> Final commits: `6afd6a2c` (Phase B-v2) → `652bed79` (Phase C) → `71aff271` (Phase D) → `e173d4bc` (doc-lag follow-up)" }, { "line": 19, "text": "| 轮次 | 假设 | Δ accuracy | 结论 |" }, { "line": 23, "text": "| **v3 mockup-AI Figma** | mockup AI 真画 Figma 时 SoT 增益 | **+44pp PASS** (A=4.5/8 / B=8/8) | 3 个 value case 实证：T3 rescue (search 不到 sun/moon → SoT picture-light 救场) / T2/T4/T6 variant precision / T1/T7 user-confirmed A 找到的 mark/favorite + Me" }, { "line": 25, "text": "**关键 finding**：T1/T7 user-pick 比 pilot 35 entries 好 → 暴露 **scope hole**。" }, { "line": 28, "text": "- SoT 目标：~~icon 语义数据库~~ → **mockup 一致性收敛器**" }, { "line": 29, "text": "- Scope：manifest(642) → **Figma 库全镜像 ~650+ published icon components**" }, { "line": 30, "text": "- 方法：demand-driven trickle → **batch 集中处理**（一次 author 完所有 icon，未来 incremental 只补 figma 新增）" }, { "line": 38, "text": "`scripts/extract-figma-icon-worklist.mjs` — 从 `figma-data/normalized/components.manifest.json` 拉所有 `figmaName.startsWith(\"icon/\")` published entries，标识 35 已有 SoT entries → 输出 `docs/internal/bridge-mockup-008-icon-worklist.{json,md}`（605 tod" }, { "line": 44, "text": "1. **命名 spec 升级 15 → 18-enum**：input/output 从 network/* 拆出独立 category；最终 18 个 `affordance_category` enum 在 `icon-naming-convention.md`" }, { "line": 56, "text": "608 drafts user batch-review accept → merge 进 `affordance-categories.json` SoT（35 → **643 entries**）+ 11 new category files；icon manifest aggregate 643 ✅。" }, { "line": 76, "text": "Plan owner independent verify（component_key + nodeId 全对，仅 `figma_name` 字段漂移）→ in-place patch SoT → 复跑 A=B=C=D=0 ✅。" }, { "line": 80, "text": "Sprint Self-Audit 7-类 (INFRA-F37 Phase 5 expanded A/B/C → A-G mandatory) 跑后 C-class doc-lag findings 一并 closure：" }, { "line": 82, "text": "- `divergences.md §time/calendar` — divergence ✅ resolved（Figma 端 typo 已落地）" }, { "line": 84, "text": "- `AGENTS.md §\"同步 Figma 库\"` 11-step → **14-step**（F35 +12/13 + Phase D +14）" }, { "line": 97, "text": "Phase D 让 SoT 一次 author 完后**不再依赖人工对照 Figma**。任何 designer 改名 / 加 / 删 → sync pipeline Step 14 自动报警。这是 [[trigger-O-product-truth-over-onboarding]] 元规则的具体落地：**onboarding 知识有 staleness 风险，需要 audit 持续验证产品真值**。" }, { "line": 99, "text": "### 3. memory 实证完成 → divergence closure" }, { "line": 101, "text": "`[[feedback_name-search-absent-fallacy]]` 2026-05-26 case（grep `Calendar` 全 miss 因为 Figma 是 `Calender` typo）→ user 当时建议 Figma 端正名 → 今天 Phase D drift 报警证实**已落地**。memory 实证完成 = divergence closure 触发器；不应永远保留 \"modification direction: figma 端重命名" }, { "line": 107, "text": "### 5. Sprint Self-Audit 7-类落地实证" }, { "line": 117, "text": "| SoT entries (affordance-categories.json) | 35 → **643** |" }, { "line": 120, "text": "| sync pipeline steps | 11 → **14**（F35 +12/13 + Phase D +14） |" }, { "line": 121, "text": "| Self-Audit 类别 | 3 → **7**（D/E/F/G via INFRA-F37 Phase 2） |" }, { "line": 141, "text": "- 排期 SoT: [`design-spec-canonical-alignment-tracker.md`](./design-spec-canonical-alignment-tracker.md) 新增 BRIDGE-MOCKUP-008 Phase D entry" }, { "line": 153, "text": "- ✅ Tracker §轨道 A 已完成 entry 新增 Phase D row (commit `e173d4bc`)" } ], "gatesMentioned": [ "audit-figma-vs-sot.mjs" ], "gatesDead": [ "audit-figma-vs-sot.mjs" ], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-06-01-affordance-sot-shard-and-parallel-session.md", "lines": 69, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 9, "tldr": null, "decisionCandidateCount": 13, "decisionCandidates": [ { "line": 16, "text": "把单文件 SoT 拆成目录时，**不要让分片变成\"第二份真源\"**。做法：" }, { "line": 20, "text": "- `loadAffordanceSot()` 把目录**重组回旧的合并形状** `{ _meta, affordance_categories, icons }` → 所有读 `sot.icons` / `sot._meta` 的消费方**零语义改动**。" }, { "line": 22, "text": "3. **拆分键选 `path` 顶层而非 `registry_name`**：`path` 644/644 全有值，`registry_name` 有 null → 后者会产生孤儿桶；且 `path` 1:1 镜像 Figma 文件夹，符合项目 Figma↔Code 镜像命题。" }, { "line": 24, "text": "**先验消费方再动手**：grep 出 3 个硬消费方（audit-figma-vs-sot 阻塞门 / extract-icon-worklist / phase-c-merge），确认 affordance-search agent **不读**此文件（它扫 Figma 库 / svg dir）。两个 read 消费方按 component_key 建 map → **顺序无关**，所以分片顺序不影响行为；phase-c 是已耗尽的一次性脚本（断言 35 条，现 644 " }, { "line": 30, "text": "## 经验 2 — 并行 session 共享同一工作树的纠缠（核心教训）" }, { "line": 38, "text": "| 行数 | 317 → 409 |" }, { "line": 42, "text": "→ 命中 [[user_parallel-sessions]]「dirty/untracked 文件先假设别 session 在动」。按纪律**先停下报告 + 等用户拍板**，没有基于陈旧 Read 直接改。" }, { "line": 46, "text": "一度误以为「留给那个 session」有意义 —— 错。同机同目录的并行 Claude session **共享同一个工作树 / 同一个 git repo**，只有一份工作树。所以\"提交对那个 session 无害\"才是对的：F/G 是 INFRA-F38 同批活，提交后对所有 session 都是已落地。" }, { "line": 50, "text": "`audit-figma-vs-sot.mjs` 同时含：(a) 我的 loader 迁移（**必须**进拆分 commit，否则删了单文件 audit 还读单文件 → 坏树）；(b) 另一 session 未提交的 F/G 逻辑。二者在**同一文件**，文件粒度 `git add` 无法分离，hunk 级手术 + 报告重生成成本过高且 ROI 低。" }, { "line": 58, "text": "- **基于 session 起手的 Read 快照直接改 dirty 文件** → 可能 clobber 并行 session 的在途工作。复核 mtime/行数/git-status 是廉价保险。" }, { "line": 59, "text": "- **为了\"提交干净\"对同文件做 hunk 级手术剥离他人在途改动** → 当生成物（drift report）依赖该文件的完整逻辑时会引入不一致；ROI 低时不如整体提交 + provenance 注明。" }, { "line": 67, "text": "- tracker 轨道 C 已完成 +1 行；STATUS.md Last updated → 2026-06-01" }, { "line": 68, "text": "- 无新增 memory（教训已被既有 [[user_parallel-sessions]] 覆盖；loader-shard 模式记在此复盘 + affordance-layer.md）" } ], "gatesMentioned": [ "audit-figma-vs-sot.mjs" ], "gatesDead": [ "audit-figma-vs-sot.mjs" ], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-06-01-source-type-mockup-batch.md", "lines": 114, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 13, "tldr": { "line": 3, "heading": "TL;DR", "endLine": 11 }, "decisionCandidateCount": 13, "decisionCandidates": [ { "line": 17, "text": "| 最终落地 | 23 个完整弹窗（1 SRT Listener + 22 other source types） + 2 个修复 + 1 个 NDI 状态补画 |" }, { "line": 28, "text": "| 2 | 22 source type 批量弹窗 | TEXT node TypeError → page 切换错误 → 44 个重复 frame | 调试 4 轮 | +4 |" }, { "line": 40, "text": "**根因**：`figma.currentPage` 随 Figma 桌面端活跃页面变化，不等于 `template.parent`。" }, { "line": 42, "text": "**回流规则**：任何 `use_figma` 写操作前，先验证：" }, { "line": 53, "text": "**根因**：Figma Plugin API 中 TEXT node 的 `children` getter 直接抛错而非返回 undefined/null。" }, { "line": 55, "text": "**回流规则**：所有递归遍历子节点前必须做类型守卫：" }, { "line": 66, "text": "**根因**：部分组件实例有内部约束阻止外部覆盖 sizing 属性，需要在克隆后显式验证再决定用 resize() 兜底。" }, { "line": 68, "text": "**回流规则**：克隆 INSTANCE 后验证：" }, { "line": 85, "text": "3. **不要信任\"运行成功\"**：脚本返回无报错 ≠ 结果正确；批量创建后立即查 frame count" }, { "line": 94, "text": "## 已回流 / 待回流规则" }, { "line": 96, "text": "| 规则 | 回流落点 | 状态 |" }, { "line": 108, "text": "| 克隆 SRT Caller → SRT Listener | 581:36846 | ✅ |" }, { "line": 111, "text": "| 批量克隆 × 22 source types（第 2 次，正确页） | 428:53644 | ✅（44 → 22 去重） |" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-06-02-wave1a-verifier-confirm-and-color-mix-blindspot.md", "lines": 43, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 7, "tldr": null, "decisionCandidateCount": 8, "decisionCandidates": [ { "line": 7, "text": "起手确认 CANONICAL-017 verifier 覆盖已落地（30/34 covered，4 internal-base 走 canonical wrapper），fresh verifier run 实测 Wave 1a 各 CANONICAL 的 A field 真清数 → A **295→248 (-47)**。过程中发现并修了一个 verifier 假阳 bug。" }, { "line": 9, "text": "## 两个转移性教训" }, { "line": 13, "text": "CANONICAL-018 的 fix 用 `color-mix(in srgb, var(--brand) 54%, #fff 46%)`。Chromium 把它**计算成 `color(srgb 0.5595 0.8433 0.6252)`**，不是 `rgb()`。verifier 的 `colorToHex()` 正则只匹配 `^rgba?\\(…\\)$` → 落到 fallback `return value.toLowerCase()` → 返回字面串 `color" }, { "line": 17, "text": "- 修后：Drop down 5 假阳清，A 252→248，CANONICAL-018 正确性才显形。" }, { "line": 19, "text": "**归类**：同 EXTRACT-008（composite fills）、[[feedback_figma-fills-must-composite]]、[[feedback_verifier-css-transition-race]] —— \"verifier 读不懂正确渲染 = 假阳\" 是 FIGMA_AS_SOURCE_OF_TRUTH deterministic 验证的反复落点。任何用 `color-mix()` 的组件（本库还有 Button/Pill/Ratin" }, { "line": 23, "text": "旧 ledger A 走势 398→…→**92**（2026-05-29 EXTRACT-008）跑在 CANONICAL-017 verifier 覆盖 backfill **之前** 的 ~633-entry manifest。CANONICAL-017 Batch 1-5+6.1 把覆盖扩到 **900 entry**（FormItem/Table/Notification/Select 全家族首次纳入），surface 出大量此前根本没 check 的真 A dri" }, { "line": 25, "text": "- **教训**：A 余量是相对\"当前覆盖的 manifest\"的，不是绝对项目健康度。覆盖率一变，数字不可跨段比较。pickup 写的 \"92→90 预期\" 就是拿旧分母套，[[feedback_baseline-before-plan]] 实跑才看出根本是 295→248 的全新故事。" }, { "line": 35, "text": "| 018 | Drop down | 7→3 | dark+light leaf fix（需 colorToHex 修才可见）；剩 1 Parent/Leaf + 2 Multi 行 bg null |" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-06-03-infra-f39-verifier-accuracy.md", "lines": 74, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 11, "tldr": null, "decisionCandidateCount": 16, "decisionCandidates": [ { "line": 7, "text": "修 render-verifier 量错元素的拓扑问题，让 `pnpm drift:summary` 从 **247 A → 87 A** 可信化；FormItem 94 全幻影清零、Table 66 拆成 54 幻影清 + 12 真 drift 暴露（owner 当场确认后按 Figma 还原 code → Table 清零）；顺带交付欠着的 PillPage docs 页。" }, { "line": 17, "text": "**根因**：`extract.mjs firstTextNode` DFS 取第一个 TEXT 节点作为变体代表 text。FormItem 全 64 变体的第一个 text 节点是 required 星号 `* `，且 `visible:false`（Status=Normal/Error 都隐藏），fill `#ea4233`（--red）。verifier `textTargetSelector='.form-item__label'` 量的是灰 label，拿灰 l" }, { "line": 20, "text": "1. `extract.mjs firstTextNode`：跳过 `node.visible===false`（根因；下次 re-extract 会取可见 label 而非隐藏星号，恢复真覆盖）。" }, { "line": 21, "text": "2. `generate-render-verification-manifest.mjs expectedFromVariant`：当 `variant.text.visible===false` 视为无 text（textFillHex→null）。**为什么需要这条**：raw 已被 extract 扁平化（无 children tree），无法 re-derive 可见 label，只能在当前 baked data 上把隐藏 text 当无。" }, { "line": 22, "text": "3. `manifest-verifier.spec.ts`：`pushExact` 对 textFillHex 无 null-guard（不同于 `pushNumber`），置 null 后会变成 `灰 === null` FAIL 而非跳过 → 加 null-skip（一致于 pushNumber / rootBorderHex 的\"无 Figma 数据就不断言\"）。" }, { "line": 28, "text": "### Step 2 — Table 66：retarget `` → cell + 真 drift 按 Figma 还原" }, { "line": 30, "text": "Figma「Table」组件是**单元格**（6 变体 Type=Header/Tbody × Align，w120 h33，padding **L0/R8/T8/B8**，gap 4，无填充）。verifier 之前量整个 `
`（padding/gap/fill 全 0）→ 54 幻影。" }, { "line": 32, "text": "- retarget `rootTargetSelector` 为 per-variant 函数：Type → `.tbl-head/.tbl-body`，Align → `.tbl-cell--{align}`；`mapCodeProps` 给 column 设 align 让渲染 cell 命中。" }, { "line": 33, "text": "- gap 在内层 `.tbl-cell__content`（flex），不在 `
` → 用新 `gapTargetSelector`。" }, { "line": 34, "text": "- cell 的 120×33 是 component-frame，真 table 里 cell box 由 layout 驱动 → 新 `suppressRootSize` 跳 rootWidth/rootHeight（否则 cell≠120 会 +12 噪声）。" }, { "line": 40, "text": "**→ owner 当场确认按 Figma 还原**（FIGMA_AS_SOURCE_OF_TRUTH「Figma 真源、确认的真 drift 一律按 Figma 改 code」）：改 base `Table.vue` `.tbl-head/.tbl-body .tbl-cell` padding `var(--sp-xs)` → `var(--sp-xs) var(--sp-xs) var(--sp-xs) 0`（L0/R8/T8/B8）→ **Table 12→0**，T" }, { "line": 44, "text": "gap 在内层 `.form-item__main`（flex row，1-line gap 8 / 2-line gap 0），verifier 量外层 `.form-item`（block，gap 0）→ 48 幻影。加 `gapTargetSelector='.form-item__main'` → 全清（1-line 8==8✓ / 2-line 0==0✓）。" }, { "line": 66, "text": "vue-tsc ✓ · 193 vitest ✓ · H1 hard-rule ✓ · docs-site ✓（pill in-review warn）· component-affordances ✓。3 audit exit1 全 pre-existing（CANONICAL-013/015/017 + PillCounter code-first），零新增。" }, { "line": 68, "text": "## 教训 / pattern" }, { "line": 71, "text": "2. **修 fix 前 grep 下游消费方**：原计划 normalize 置 null 会破 `audit:tokenized-diff` 的 raw↔tokenized 恒等约束。动手前 grep tokenized `.text` 消费方发现该 strict gate → 改 verifier 层，避免返工。[[feedback_review-result-vs-rationale]] 同源（先实证约束再动手）。" }, { "line": 72, "text": "3. **没盲信 pickup**：pickup step 1 指向 extract/normalize；实测发现 normalize 路被 audit 挡 + raw 无 children 无法 re-derive label → fix 落 verifier 层。pickup step 2 假设 Table 是清幻影；实测发现是 54 幻影 + 12 真 drift（pickup 自己也警示了 L0 可能=0，实证证实）。[[feedback_baseline-befor" } ], "gatesMentioned": [ "audit-tokenized-diff.mjs" ], "gatesDead": [ "audit-tokenized-diff.mjs" ], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-06-11-contrast-closure-axe-artifact.md", "lines": 35, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 5, "tldr": null, "decisionCandidateCount": 6, "decisionCandidates": [ { "line": 1, "text": "# 2026-06-11 — Contrast 全线收口 + axe 测量伪影 pattern + backlog staleness 教训" }, { "line": 3, "text": "> 触发：发现新 pattern（WRAP-UP §Retrospection 触发表 \"学到通用工程经验 / 发现新 pattern → 必写\"）。" }, { "line": 12, "text": "**机理**：docs site 在 light 主题下 `body` 背景仍是 `#141414`（dark 默认），`.canonical-page` 白底盖在其上。axe-core 的背景检测一旦没识别到中间白层（层叠/滚动等原因），就回退到 body 色 → 报出 \"fg on `#141414`\" 的假失败。" }, { "line": 23, "text": "**纪律（复跑 inspector / 任何 axe 审计时生效）**：报告里 \"light 主题 + `#141414`（或其他 dark-layer 色）背景\" 的配对，**一律先疑伪影**——用 painted-ancestor 链实测真实绘制底，证实后才进设计师清单。决策视图 [`a11y-contrast-designer-review-2026-06-01.md`](../a11y-contrast-designer-review-2026-06-01.md) 顶" }, { "line": 29, "text": "**纪律**：把\"等设计师\"类 entry 报给 owner 之前，**先 live Figma 复核该 entry 是否 stale**（trigger-O：实际产品态 > 文档记载；owner 是并发编辑者 [[feedback_figma-library-concurrent-editing]]）。本次同型遗留：select placeholder 散绑 / input·select clear 图标 / multi-select padding / disabled " }, { "line": 33, "text": "- **accept 型收口的语义**：axe 原始数字不变 → CI a11y job 维持非阻塞不翻 blocking；v1 DoD 的 \"color-contrast clean\" 按 owner accept ack 判定（同能力 3 旁路 ack 范式）。" } ], "gatesMentioned": [], "gatesDead": [], "ruleIdsMentioned": [], "ruleIdsAlive": [], "ruleIdsDead": [] }, { "file": "docs/_archive/retrospection/2026-06-30-dual-framework-generator-and-low-risk-batch.md", "lines": 133, "s1Class": "residual", "shape": "other", "inboundPathCaliber": 0, "inboundBasenameCaliber": 0, "basenameOnlySources": [], "scriptDecidable": "no-inbound-either-caliber", "headingCount": 19, "tldr": { "line": 10, "heading": "TL;DR", "endLine": 18 }, "decisionCandidateCount": 32, "decisionCandidates": [ { "line": 6, "text": "> **执行**：subagent-driven-development，全程在 master 直 commit（Owner override），逐 task implementer→review-package→reviewer→fix→ledger。" }, { "line": 13, "text": "- 生成器（config 单源 → WC 注册 + React wrapper + 类型）证明 ROI——重生成 3 个 pilot 过同一 React gate **0 A_TRUE_DRIFT**，与手写逐项一致。" }, { "line": 14, "text": "- 15 组件中 **13 个 render-gate 验证 0 A_TRUE_DRIFT**（cross-gate 逐条等价 Vue），**2 个（PillCounter/Breadcrumb）无 manifest → 生成 + smoke 但 gate-unverified**（owner 已知共享覆盖缺口）。" }, { "line": 21, "text": "### Phase 0 — 生成器基础设施（6 task，commits 96f3c41e→98cd0f82，已推）" }, { "line": 22, "text": "1. config schema + `reserved-names.ts`（`style`→`variant` 单源重映射）。" }, { "line": 24, "text": "4. 重生成 3 pilot → React gate 180/0（生成器 ROI 坐实）。" }, { "line": 28, "text": "### Phase 1 — 低风险批 15（commits 88d8a17e→8f74f2f3）" }, { "line": 29, "text": "按 interop 形态分批：A 纯 props/slot 6 → B v-model:status 3 → C v-model:modelValue 4（含 number）→ D 无 manifest 2。" }, { "line": 36, "text": "2. **按 interop 形态分批**（非 findings §6 的笼统\"复合/slot\"）：纯 props/slot → v-model:status → v-model:modelValue → 无 manifest。每批暴露并修复一类生成器类型缺陷。" }, { "line": 43, "text": "生成器在 pilot（Button 无 v-model / Input string v-model / FormItem 无 v-model）上的 string-centric 假设，随组件多样性扩大逐一暴露，**全部修在模板根因层，后续批自动继承**：" }, { "line": 45, "text": "| # | 缺陷（哪批暴露） | 根因 | 修法 |" }, { "line": 47, "text": "| 1 | TopBar 5 具名 slot → wrapper prop-only（Batch A） | 模板只在 `hasDefaultSlot` 渲染 children | `hasDefaultSlot \\|\\| namedSlots.length>0` → 渲染 `{children}`（具名 slot 靠 light-DOM 投影，FormItem 已证） |" }, { "line": 51, "text": "**教训**：分批 + 每批过 gate/review 正是为了在低风险阶段把这些类型缺陷挤出来，而非到高风险组件才发现。pilot 的 3 组件覆盖面不足以暴露它们。" }, { "line": 57, "text": "每批 controller 不只看 React gate 的 `A_TRUE_DRIFT=0`，而是**逐组件对比 React gate vs Vue gate 的分类**（同一 manifest 条目、共享 comparator）。结论：**React 与 Vue 对每个组件逐条等价**——所有 B_RESIDUAL 两侧数字完全相同（Switch 90-B、Slider 10-B 等），证明这些是继承自 Vue 侧的预存 Figma schema gap，**不是 Rea" }, { "line": 63, "text": "- **subagent 越权改 SoT**：Batch B implementer 自作主张 commit 了一条 STATUS.md ㊱ 条目（未要求、过早、不全）。controller 核 git log 抓出（agent 摘要未提）。修正：后续 dispatch 显式禁止碰 docs/STATUS 等 SoT + 限定单 commit；STATUS 综合条目由 controller 在 wrap-up 统一重写。**\"核磁盘实物别信摘要\" 再次验证有效。**" }, { "line": 64, "text": "- **commit/push 纪律**：Phase 内本地 commit，phase 边界一次性 push（避免每 commit 触发 master CI）。" }, { "line": 71, "text": "单独 `chore` commit 处理：① 生成 smoke-test 描述 `'renders without throwing'` 名实不符（只 check toBeDefined，未 mount）→ 统一改名（注意 write-if-absent，15 个现存需手改）；② 模板 `vModelConst=''` inert dead code 删除；③ 测试 describe 标签错挂；④ vModel down-push 注释硬编码 \"value\" 即使 prop " }, { "line": 77, "text": "- **Plan 2 — overlay/teleport**：PopupBox、SelectBoxBase/Line/Filled、DropDownListSelect、Tooltip。关键未知：teleport 节点落 document.body（shadow root 外）仍继承 token（应可，token 在根）；comparator 定位 teleported 根。Button 已 teleport 且过闸 → 基础已证。" }, { "line": 94, "text": "# Batch E / F / G — 剩余 14 组件全落地（2026-06-30 续，29/29 完成）" }, { "line": 99, "text": "- **route-B 担忧未成立**：父子作为各自 custom element 注册，孤立渲染时 inject 落默认值，TabList/TabItem/StepItem 有 manifest 条目过闸 A=0；Tab/Steps 容器无 manifest → 生成 + smoke 但 gate-unverified（同 D 的 PillCounter/Breadcrumb，owner 已知共享缺口）。" }, { "line": 104, "text": "2. 仅 `shadowRoot:false`：PopupBox **仍 12 A**、DropDownList **反而 1→134 A**（更糟）。根因 = **Vue 3.5 在 light-DOM 模式明确拒绝注入 styles，只 `warn`**（runtime-dom `_applyStyles` 守卫：`if(this.shadowRoot) _applyStyles(styles); else if(styles) warn(...)`）。" }, { "line": 105, "text": "3. 正解 = **`shadowRoot:false` + 手动把组件编译后 `styles` 注入 `document.head`**（`injectLightDomStyles`，由生成器从 config 生成）。PopupBox 的模态/Teleport/样式全在 `BasePopupBox`（canonical 仅转发、无 `