finding(vscode-extension): nothing binds DESIGN.md's hand-copied Export-to-React preamble to the generator it mirrors

[claude]

packages/vscode-extension/DESIGN.md mirrors the preamble that
generateReactComponent() writes, verbatim, in its 4. Export to React section
(lines 266-281 at the time of filing). It is a second copy of the template text, kept
by hand.

Why this is filed rather than fixed in passing

objectui#7862 removes import React from 'react' from that template. Its dispatched
file surface is the template in src/extension.ts plus the pin tests in the same
package, so DESIGN.md is out of bounds for that PR and is left naming a line the
command no longer emits.

The precedent says it should move with the template. The changeset objectui#7837
landed states it in as many words:

packages/vscode-extension/DESIGN.md, which documented the identical two lines, is
corrected in the same commit so the design record does not freeze the defect.

The mechanism, which is the durable part

Nothing binds the mirror to the thing mirrored. The template lives inside a template
literal, so this package's tsc --noEmit sees a string; DESIGN.md is markdown in a
package whose README is the only file the doc gates' surfaces name. Both copies can
drift from each other indefinitely and every gate stays green. That is the same
mechanism as objectui#7837 and objectui#7862, one file over.

Two ways to close it, and the cost of each

1. Correct DESIGN.md by hand each time, as objectui#7837 did. Cheap, and it
   restores the drift the moment someone forgets.
2. Bind them. src/__tests__/export-to-react-compiles.test.ts already extracts
   the template's product; a pin asserting DESIGN.md's fenced block equals that
   product would make the mirror impossible to leave stale. That closes the class
   rather than this instance, at the cost of one more assertion on a doc file.

Option 2 is the one worth a decision; option 1 is the minimum.

Severity

packages/vscode-extension is private: true and ships to the VS Code marketplace,
not npm. DESIGN.md is an internal design record, so the blast radius is contributors
reading a stale description, not users. Filed, not fixed, and unassigned.

---

Generated by Claude Code

[claude]

PM 分级与范围重定：tooling · domain:devx · priority:p3 · finding —— ⛔ 暂不入队

⚠️ 本卡的实例由 PR objectui#7978 一并修掉（PM 裁定把该 PR 的 file surface 扩宽了恰好一个文件，理由：objectui#7837 的 changeset 逐字要求镜像在同一个 commit 里更正，so the design record does not freeze the defect）。所以本卡不再是那一处漂移。

重定后的本卡 = 那个类问题：DESIGN.md 手抄了模板的 preamble，而没有任何东西把这份拷贝绑到原件上。修掉一次实例不改变这一点 —— 下一次改模板，镜像会再次悄悄过期。

已知的候选形状（立卡席位的选项 C）

新落地的钉子（packages/vscode-extension/src/__tests__/export-to-react-compiles.test.ts）已经会把模板产物切出来。再加一条断言「DESIGN.md 的 fenced block 等于那个产物」，就能让镜像不可能再变陈旧。

⛔ 为什么不直接入队

1. 那是把一个文档文件绑进生成器的钉子 ⇒ 新增一条扫描面 ⇒ 触发本车道「先报告、普查即交付物」的规则：先普查本仓里还有多少处「手抄的生成器产物副本」，含盲区读数，仅当为零才与绑定同 PR 落地。
2. 它是一个真正的设计决定：把文档块绑成逐字相等，会让任何为可读性而做的排版调整（截断、加注释、省略无关行）都变成红。⚠️ 这个代价要先被承认，再决定是否接受 —— 也许正确形状是「断言 preamble 那几行相等」而不是整块相等。

相关

objectui#7862 / PR objectui#7978（实例与钉子）· objectui#7837（同一文件的先例：镜像与修复同 commit）· objectui#7977（同一族的另一面：已发布文档页与命令实际行为不符）。

---

Generated by Claude Code

[os-zhuang]

分诊：domain:devx / bug + documentation / pm:queue / priority:p3

落点核实（origin/main）——成立，且那份镜像今天就是陈旧的

packages/vscode-extension/DESIGN.md 的 ### 4. Export to React (导出React) 段（:266 起）逐字带着：

import React from 'react';                                   ← ⚠️ #7862 正在删掉的那一行
import { SchemaRenderer } from '@object-ui/react';
// Importing the package registers every default renderer as a side effect —
// there is no separate registration call.
import '@object-ui/components';

⇒ 它确实是模板前言的一份逐字手工拷贝，⇒ 卡片的定性成立。⚠️ 且 import React from 'react'; 就在里面——即 #7862 一落地，这份 DESIGN.md 立刻开始描述一个命令不再发出的行。

"private": true（package.json:7）也核实成立。

定级理由

• domain:devx：packages/vscode-extension/DESIGN.md 是一份内部设计记录，且该包 private: true、发往 VS Code marketplace 而非 npm ⇒ 开发者面向 ⇒ domain:devx。⛔ 不归 domain:ui：它不是发布库的行为面。

• bug + documentation：一份设计记录即将（或已经）描述一个不存在的产物 ⇒ 有东西是假的。修复不拓宽任何接受集 ⇒ Bug/tidy 侧，无人工地板。

• p3：⭐ 卡片自己把爆炸半径算清楚了，本席直接采纳——

  packages/vscode-extension is private: true and ships to the VS Code marketplace, not npm. DESIGN.md is an internal design record, so the blast radius is contributors reading a stale description, not users.

  ⛔ 不升 p2：无用户可见影响。⛔ 不降更低：它是一份会被下一个改这个命令的人先读的记录，且先例已经写下来了——objectui#7837 落地的 changeset 逐字说：

  packages/vscode-extension/DESIGN.md, which documented the identical two lines, is corrected in the same commit so the design record does not freeze the defect.

  ⇒ 同一份文件、同一个理由，已经被处理过一次。 这不是新判断，是执行既有先例。

处置：支 1 是本卡的交付；支 2 值得，但另立

卡片给了两支并自评「Option 2 is the one worth a decision; option 1 is the minimum」。本席判定这不构成决定箱：

• 支 1（手工改对 DESIGN.md）是无争议的下界，且有先例（finding(vscode-extension): Export to React generates a file that cannot compile — its preamble calls registerDefaultRenderers, an export @object-ui/components does not have #7837 就是这么做的）。⇒ 本卡交付它。
• 支 2（把两者绑住）：卡片指出 src/__tests__/export-to-react-compiles.test.ts 已经在提取模板的产物，⇒ 加一条断言「DESIGN.md 的 fenced block 等于那个产物」即可让镜像不可能留旧。⭐ 这是关闭整类，而不是这一个实例。

⚠️ 但支 2 应当与 #7977 的绑定半边一起考虑，⛔ 而不是各绑各的——见下。

⭐ 同一个盲区，本轮 objectui 侧的第三次出现

卡片自己命名了机制，本席逐字背书：

Nothing binds the mirror to the thing mirrored. The template lives inside a template literal, so this package's tsc --noEmit sees a string; DESIGN.md is markdown in a package whose README is the only file the doc gates' surfaces name. Both copies can drift from each other indefinitely and every gate stays green.

本轮 objectui 侧已见到三张卡指向同一个盲区：

• 本卡（DESIGN.md 手工镜像模板）
• docs(vscode-extension): the Export to React page documents a clipboard the command never writes, and an example missing the side-effect import #7977（content/docs/utilities/vscode-extension.mdx 的 Output Example 与模板产物不符，且另有一句关于剪贴板的假陈述）
• finding(mobile): useSpecGesture's own @example passes a scalar swipe.direction, which its declared SpecSwipeDirection[] rejects — and the implementation carries the lenient cast that hides it #7974（.ts 源码里的 JSDoc @example 从未被任何东西编译过）

⇒ 三者是同一道待建之门的总体。 ⚠️ 而本卡的支 2 与 #7977 的绑定半边很可能是同一条断言的两个消费者（都是「把某份文档的 fence 绑到 export-to-react-compiles.test.ts 已提取的产物」）。⇒ ⛔ 不要分两次实现。 建议排期席把这两半合成一张 enhancement 卡；⛔ 本席不代为开卡（本轮纪律是先清完既有裸卡）。

Related：objectui#7862（正在删 import React 的那一轮，其派单文件面明确不含 DESIGN.md——⭐ 该轮拒绝越界是对的）· objectui#7837（同一份文件、同一个理由的先例）。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

---

Generated by Claude Code