Skip to content

[Decision] Should a json fence under content/docs that fails JSON.parse block the PR that adds it? #10943

Description

@objectstack-fleet

Ruled: 5869344478 · letter A · 2026-09-28T11:57Z

This card carries the gate-strength half of objectui#10088's acceptance; objectui#10088 keeps the fence repairs and the named json/jsonc convention (PR objectui#10942). Filing-gate category: ② — a decision only the maintainer can make (objectui#10088's acceptance: 「Gate strength is not this lane's to grant itself」). Reader: the maintainer (decision box); after the ruling, the domain:devx execution seat. Filed by domain:devx seat 2 (session_01EBx9rvB7dufCz4at53x35U, seat post objectui#10917).

维护者速读

改了什么(待裁):问的是一件事——文档站 content/docs 里标成 json 的代码块,如果不是合法 JSON,要不要在 PR 上直接拦下。
为什么要问:这类错误在 main 上悄悄攒到了 21 处(PR objectui#10942 正在一次修完),因为唯一读这些代码块的检查(carriage 普查)为另一个目的放宽了解析,把这几种坏形状都当成了「能解析」。技能包 skills/** 那边早已对 json 严格要求,文档站这边没有。
风险与代价:选 A,把现有普查对 json 改为严格解析,它现有的那个 pin 会在新增坏代码块的 PR 上变红;不新增脚本或 workflow,落地时文档站已是 0 处,所以直接是绿的。代价是那个普查多回答一个问题,作者须知道「带注释的写 jsonc」。选 B 不花任何成本,但这类错误会再慢慢攒回来。回滚:revert 一个小 PR。
席位意见:荐 A。理由见下文四轴;它不新增门禁零件,只把一个已存在、已在每个文档 PR 上运行的检查从「宽容」改为「严格」。
你要做的:回一个字母(A / B / C)。

One-sentence problem

A reader who copies a json example from the published docs can get text their editor or JSON.parse rejects, and today no check on a PR can tell — 21 such fences reached main before PR objectui#10942 repaired them.

Governing text

  • objectui#10088 acceptance (card text, not a ruling): 「Whether a gate blocks is answered — and if the answer is 「it should」, that is raised as its own decision rather than landed inside this card. ⛔ Gate strength is not this lane's to grant itself.」
  • The four-axis frame's gate clause: 「新增门禁默认否:门禁是只减不增的零件,例外只有维护者点名」.
  • Precedent on the sister tree: scripts/check-skill-examples.mjs — 「json is parsed STRICTLY — JSON.parse and nothing else」, jsonc strips comments and trailing commas (objectui#7474).

Premises (each with its re-check)

  1. After PR objectui#10942, every json fence under content/docs passes strict JSON.parse (dev reading: 203 fences, 0 failing; the PM's own probe on the pre-fix tree found 24 failing across json+jsonc). Re-check: walk git ls-files content/docs for fences tagged exactly json, JSON.parse each body; control in the same command: a body with a trailing comma must be rejected.
  2. The one gate that reads these fences, scripts/check-doc-expression-carriage.mjs, is report-only and applies tolerances (comments, raw newlines, elisions, object-body retry, multi-document split) before parsing, to json and jsonc alike. Re-check: git grep -n -i "report-only" origin/main -- scripts/check-doc-expression-carriage.mjs (hits expected) and read its tolerance list; control: git grep -c "parseJsonFence" origin/main -- scripts/check-skill-examples.mjs must be non-zero.
  3. The census's existing pin (「has no blind spot on the corpus it ships against」) asserts census.unparsed is empty and runs on every content/docs PR. Re-check: grep its test file for unparsed and scripts/markdown-test-inputs.mjs --changed for a docs page.

Options

option what it does what a customer / reader feels
A Tighten the EXISTING carriage census: strict JSON.parse for json, tolerances kept for jsonc only (ideally importing parseJsonFence from check-skill-examples.mjs so both doc trees share one contract). Its existing pin then blocks the PR that adds a non-JSON json fence. No new script or workflow; lands green (0 today). Every json example they copy parses. An author who wants comments writes jsonc and is told so on the PR.
B No gate. The convention lives in PR objectui#10942 and in the skills checker only. Nothing today; drift returns silently — measured: 0 → 21 with nothing reading it.
C A new dedicated json-fence gate. Same as A, one more part to maintain; the default is no and no maintainer has named one.

Business meaning: A = the docs promise the same thing the skills already promise («json means JSON»); B = trust authors and fix in batches when someone notices; C = A with an extra moving part.

Four axes, from the reader's side

  • Long-term (① leads): two years out, both doc trees an AI reads should hold one json/jsonc contract, enforced where examples are added — mainstream docs toolchains lint example code in CI the same way. A reaches that with the parts that already exist; B leaves two trees with two contracts.
  • Real pull: measured, not assumed — 21 fences accumulated on main; the skills tree needed the same rule (objectui#7474).
  • Anti-AI-error: a json fence is what an AI copies into a metadata file. Under A a bad fence is refused loudly on the PR that adds it; under B it is accepted silently and the failure lands in the reader's editor.
  • Startup focus: A adds no gate, script or workflow; it raises the strength of one existing pin for one new class, which is exactly why it needs your yes.

os-decision-facets
① 项目长远合理性:A 收窄特例——两棵文档树共用一份 json/jsonc 契约,不再各说各话;B 保留两套约定,C 多一个零件。
② 实际业务拉动:有实测拉动——main 上累计 21 处坏 json 代码块,技能树已为同类问题立过规则(objectui#7474)。
③ 防 AI 犯错:A 在新增坏代码块的 PR 上响亮拒绝;B 静默放过,错误出现在读者的编辑器里。
④ 创业阶段不扩散:A 不新增门禁、脚本或 workflow,只提高一个既有 pin 的强度;C 新增零件,默认否。
Prior rulings read: json fence,jsonc,expression-carriage,gate strength,blocking → 7 hits; ADR-0069 D3, ADR-0087 D1, ADR-0087 D6 (all on the generic term blocking — MFA gating and protocol upgrades — none rules on doc-fence gates); thread: objectui#10088 read in full by this seat, no ruling on it
Recommendation: A, fallback B. 只看①选 A;②③④ 是否翻转:否(④ 把 A 计为「提高既有 pin 强度」而非新零件,这正是本卡请你裁的点)。
Confidence gap: not measured — how often a future author will legitimately want comments in a json-tagged fence (the jsonc retag is the answer, but authors must learn it), and whether one census answering two questions makes its red harder to read.

After the ruling

  • A ⇒ this card flips to pm:queue in the domain:devx lane: strict json in check-doc-expression-carriage.mjs (reusing parseJsonFence), fixture pins for both tags, a planted bad fence proven red; lands after PR objectui#10942.
  • B ⇒ this card closes not_planned with the ruling quoted; the convention stays documented in PR objectui#10942.
  • C ⇒ only with your named exception for a new gate; otherwise read as A.

Related: objectui#10088 · PR objectui#10942 · objectui#7474 (the skills precedent) · objectui#7418 (the census's origin).

Activity

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

Metadata

Metadata

Assignees

Labels

domain:devxobjectui devx stream: fix lands on .github/, scripts/ or release pipeline — devx lane cross-repopriority:p2

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions