Skip to content

decision(docs/adr): is a code block inside an ADR or a dated audit a SPECIMEN of what was decided, or an EXAMPLE a reader may copy? — the answer decides the four ledgered records at once (objectui#7856 card 2) #8363

Description

@os-musk

Filed by the domain:skills execution seat (session session_018dxq7YqsLDMeZDZ5AzsgJX, os-musk, 2026-09-07T14:4xZ) at the ACCEPT of objectui#7856 card 2 (PR #8357), from the dev's second open question. ⛔ Not dispatchable as filed: it is a convention decision on a governed face (docs/adr/**), and the four measured rows depend on it as one question.

The measurement that raised it (PR #8357, on fedfa3e4, with the gate's own analyzer)

Four records under docs/adr/** and docs/audits/** carry five ts blocks and 29 diagnostics: ADR-0001 (2 blocks, 15 syntax-phase), ADR-0036 (1 block, 3 syntax-phase), ADR-0057 (1 block, 8 semantic — the only one that parses; it names three helpers it never defines), the 2026-07 objectview audit (1 block, 3 syntax-phase). Three of the four are schema SKETCHES written in prose TypeScript (?: on values, [...] elisions, a 'create' | 'edit' union standing where a value goes). Triage ruled (5570217599) that repairing a block inside a dated record falsifies the record, so PR #8357 brought both subtrees into the doc-snippet walk LEDGER-FIRST: each record is named on UNGATED_DOCS with its measured count, no byte inside them moved. That ledger is now a permanent, measured debt nobody is authorised to pay down — unless the question below is answered.

四棱分析(skills 席出具,供裁决)

  • ① 项目长远合理性(≥50%,领起推荐)—— 指向 A(样本)。 ADR 记录的是某日决定了什么,审计记录的是某日测到了什么;可抄的教学示例住 skills/objectui/**content/docs/**,由门禁编译并有各自的修复路径。把 ADR 里的代码块定义为「样本」把两个面分开:记录不再是需要随 API 演进维护的代码面,教学面也不会被记录里的过期草图污染。B(示例)把每份 ADR 变成一份要持续编译的 API 文档——与「记录不可改」直接矛盾,而且以后每次契约变动都要回改历史记录。
  • ② 实际业务拉动 —— 弱且方向明确。 没有实测的读者从 ADR 抄代码;抄的来源是 skills 与 docs。拉动来自内部:四条记录 29 条诊断已被量出,ledger 是唯一的账;若不裁,它永远是「已量而无人可付」的债。
  • ③ 防 AI 犯错 —— 指向 A。 一个约定的、不编译的 fence 语言(如 ```txt 或一个约定名)让 AI 一眼知道那是草图不是可运行代码;B 让 AI 把 ADR 当 API 文档去抄,恰是 objectui#7838 / finding(docs): docs/ARCHITECTURE.md and docs/CONSOLE-STREAMLINING-SUMMARY.md attribute three more renderer names to @object-ui/app-shell, and all three are wrong in different ways #7854 那类幻影教学点的来源。
  • ④ 创业阶段不扩散 —— A = 一行约定(写进 ADR 模板/贡献指南)+ 存量四条留在 ledger 不动;B = 编辑四份受管记录 + 新维护义务;C(维持现状)= 债务永久但无人认领。

推荐 A:约定「记录内的代码块是样本,使用一个不编译的 fence 语言」,新 ADR 从此照办;存量四条记录不动,ledger 四行即终态(或在同一约定下把它们的 fence 语言改成样本语言——那仍是对记录的编辑,需你点头)。B 仅在你认为 ADR 里的代码必须可运行时选。C 不推荐:它把一个可以一句话关掉的问题留成永久的四行账。

维护者速读

事情:四份 ADR/审计记录里的代码块是写给人看的草图,按字面编译会报 29 处错误。门禁现在把它们记在账上而不修(修了就改了历史记录)。要不要给「记录里的代码块」一个明确定义?

选项:A(推荐) 定义为样本:约定一个不编译的 fence 语言,新记录照办,存量四条不动、账即终态。B 定义为可抄示例:把四条记录修成可编译,以后 ADR 里的代码必须编译。C 不定义,账永久挂着。

你要做的:回一个字母,A / B / C。

Refs: objectui#7856 (card 2, PR #8357), objectui#5174 (the ledger distinction), objectui#8162 (the fence-languages header), objectui#7838 · #7854 (phantom teaching sites).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions