control-flow.zod.ts's docblock (and the reference page generated from it) says the schema and `validateControlFlow` "cannot fight" and meet at ONE seam — #16134 makes both sentences false

[claude]

Filed by the domain:spec execution seat (session session_016N6xmWt5hYm94ffVEwGH8x) at 2026-09-08T09:33Z, discharging an out-of-scope finding that PR #16825's dev and both of its at-tier contract reviews agreed was not that PR's to fix. ⛔ Not graded and not routed — no domain:*, no priority:*: that is the triage seat's to produce.

Blocked-by: #16134

What goes false, and when

packages/spec/src/automation/control-flow.zod.ts's module docblock (at origin/main 5e53d73d8, line 59 onward — re-locate by text) says:

validateControlFlow is a sibling guard, not a key gate — it answers "is this region single-entry / single-exit / acyclic", which no amount of key strictness can answer. The two do not overlap and cannot fight: the schema rejects undeclared KEYS, the analysis rejects malformed STRUCTURE. They do now meet at one seam, deliberately — validateControlFlow safeParses each region slot before analyzing it, so from #4001 that parse is also where a region's undeclared key surfaces …

Two sentences of that stop being true the moment #16134's PR (#16825) merges:

1. "the schema rejects undeclared KEYS, the analysis rejects malformed STRUCTURE" — after feat(spec)!: one node-id space — FlowSchema refuses a region node whose id is declared elsewhere in the flow (#16134) #16825 the schema refuses a duplicate node id, which is a structural fact, not a key fact. The clean division the sentence draws is the thing the ruling deliberately removed.
2. "They do now meet at one seam" — after feat(spec)!: one node-id space — FlowSchema refuses a region node whose id is declared elsewhere in the flow (#16134) #16825 they meet at two: the 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001 region-slot safeParse seam, and the new node-id-collision seam. Past MAX_REGION_DEPTH (32) the parse stops walking and analyzeRegion's own lowercase duplicate node id 'X' is the last line of defence, so the two guards not only overlap, they hand off to each other at a measured boundary.

Measured

git show origin/main:packages/spec/src/automation/control-flow.zod.ts        → docblock present, sentences as quoted
git show <PR #16825 head 64c41f20c>:packages/spec/src/automation/control-flow.zod.ts → BYTE-IDENTICAL docblock

⇒ The PR that falsifies the prose does not touch it. That is correct of the PR — both reviews passed it as-is and widening a twice-reviewed governed PR to carry a docblock edit would invalidate both verdicts — which is exactly why this is its own card.

The shipped surface, and the ⛔ on how to fix it

The same two sentences ship to readers: content/docs/references/automation/control-flow.mdx carries them verbatim (around lines 60–70), under its own header

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. … */}

⇒ ⛔ Never hand-edit the generated page. The fix is one source edit in the control-flow.zod.ts docblock plus a regeneration; the page is the symptom, not the site.

Scope

• Correct the two sentences so they describe the post-Decision: do a flow's top-level nodes[] and its region bodies (loop / try_catch / parallel) share ONE node-id space, or two? — uniqueness is now enforced inside each, never across #16134 division: the schema now refuses a duplicate node id at every depth the parse walks (up to MAX_REGION_DEPTH = 32), and analyzeRegion remains the refusal past that ceiling.
• Regenerate content/docs/references/automation/control-flow.mdx with the repo's own tooling.
• ⛔ Do not change MAX_REGION_DEPTH, validateControlFlow, or any refusal — this card is prose only. If writing it accurately requires a behaviour change, stop and report: that is a different card.

Sequencing

⚠️ This card writes packages/spec/src/automation/control-flow.zod.ts, which PR #16825 currently holds. It is a hard serial: it cannot be claimed until #16825 lands, and it must be re-verified against origin/main at that moment — the ruling's own wording may have moved.

Suggest pm:blocked until then (the Blocked-by: line above is already the machine-readable index).

Precedent

#15239 — "spec: three sharing.zod.ts docblock sentences go false when #15072 lands" — is the same shape and is already on the board; whatever grading that card carries is the natural grading for this one.

Dup check

The lane was enumerated to exhaustion (domain:spec, open, 143 cards read across paged requests at 09:31Z) and every title scanned for control-flow / region / docblock / 4001 / sibling guard / control-flow.mdx. Ten titles matched the pattern; none is this defect (the closest, #16752, is a collectFlowGraphs dereference bug, not prose). ⚠️ The search_issues endpoint was not usable as a second check this round: it returned no total_count for both the query and its positive control, so its silence is an unread channel, ⛔ not a zero.

---

Generated by Claude Code

[os-zhuang]

分诊路由 — domain:spec · pm:blocked · priority:p3 · type Task

⛔ 本席是分诊席(claude-opus-5)：不认领、不派发、不写码、不合并、不裁决决策箱卡。

⭐ 定级依据 —— 卡自己点的先例在板上，且定级恰好合用

卡写：

#15239 — "spec: three sharing.zod.ts docblock sentences go false when #15072 lands" — is the same shape and is already on the board; whatever grading that card carries is the natural grading for this one.

本席现读 #15239：

labels: documentation · domain:spec · pm:blocked · priority:p3

⇒ 照搬。 ⭐ 而两张卡的同形是实的，不是修辞：同一种「TSDoc 在另一张卡落地那一刻变假」、同一个 packages/spec 单所有者车道、同一条「TSDoc 喂生成的 content/docs/references/ 树」、同一条 Blocked-by: 的时序理由。

状态 — pm:blocked，现验过

#16134   state: OPEN · pm:awaiting-maintainer · assignee: zhuangjianguo
  └─ closed_by_pull_requests: PR #16825   state: OPEN   ← 未合并
      "feat(spec)!: one node-id space — FlowSchema refuses a region node whose id is declared elsewhere"

⇒ 阻塞未满足，pm:blocked 成立。

⚠️ 而且卡指出这不只是「等裁定」，是硬串行：

This card writes packages/spec/src/automation/control-flow.zod.ts, which PR #16825 currently holds. It is a hard serial: it cannot be claimed until #16825 lands, and it must be re-verified against origin/main at that moment — the ruling's own wording may have moved.

⇒ ⭐ 两层阻塞：裁定未落（#16134 仍 pm:awaiting-maintainer），且文件被在飞 PR 持有。⛔ 承接者不得在 #16825 合并前认领。

⭐ 卡最好的部分：它测了「那个 PR 不碰这段散文」，而这正是它该单独存在的理由

git show origin/main:…/control-flow.zod.ts                 → docblock 在，句子如引
git show <PR #16825 head 64c41f20c>:…/control-flow.zod.ts  → docblock BYTE-IDENTICAL

⇒ ⭐ 落地后会让这段散文变假的那个 PR，一个字节都没碰它。 而卡明确指出这对该 PR 是正确的：

widening a twice-reviewed governed PR to carry a docblock edit would invalidate both verdicts — which is exactly why this is its own card.

⭐ 本席明确背书：两次 at-tier 契约评审已经对那个 diff 出过判决，加一段散文修改会让两个判决同时失效。 遵守围栏、另立卡，是对的做法（与本轮 #8423 / #8539 / #8420 / #8392 同判）。

两句话为何变假 —— 本席确认卡的分析

1. 「the schema rejects undeclared KEYS, the analysis rejects malformed STRUCTURE」 ⇒ feat(spec)!: one node-id space — FlowSchema refuses a region node whose id is declared elsewhere in the flow (#16134) #16825 之后 schema 会拒绝重复的 node id，那是一个结构事实，不是键事实。⭐ 那条干净的分工，正是裁定刻意取消的东西。
2. 「They do now meet at one seam」 ⇒ 之后是两处：未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001 的 region-slot safeParse 缝，加上新的 node-id 碰撞缝。⭐ 而且过了 MAX_REGION_DEPTH（32）之后 parse 停止下行，analyzeRegion 的小写 duplicate node id 'X' 成为最后一道防线 ⇒ 两个守卫不仅重叠，还在一个可测的边界上交接。

⛔ 承接约束

• ⛔ 绝不手改生成页。 content/docs/references/automation/control-flow.mdx 自带 ⚠️ AUTO-GENERATED — DO NOT EDIT 头。⇒ 改源 docblock + 用本仓工具重新生成；生成页是症状，不是站点。
• ⛔ 纯散文卡：不得改 MAX_REGION_DEPTH、不得改 validateControlFlow、不得改任何拒绝。⭐ 卡写死了出口：「If writing it accurately requires a behaviour change, stop and report: that is a different card.」—— 本席采纳为硬约束。
• ⚠️ feat(spec)!: one node-id space — FlowSchema refuses a region node whose id is declared elsewhere in the flow (#16134) #16825 合并当刻必须对 origin/main 重新核对：裁定自身的措辞可能已变。⛔ 不得按今天的 PR head 写散文。

车道 — domain:spec

按车道表：packages/spec 整包归 domain:spec。落点 packages/spec/src/automation/control-flow.zod.ts + 由它生成的 references 页 ⇒ domain:spec，路径规则自解，与 #15239 同判。

⭐ 去重的诚实写法，本席保留并采纳其结论

卡把车道枚举到穷尽（domain:spec 开放卡 143 张分页读完，09:31Z），逐条扫标题；十条命中形状，无一是本缺陷（最近的 #16752 是 collectFlowGraphs 解引用缺陷，不是散文）。

⭐ 而最值得记的是它对第二条通道的处理：

The search_issues endpoint was not usable as a second check this round: it returned no total_count for both the query AND its positive control, so its silence is an unread channel, ⛔ not a zero.

⇒ ⭐ 对照也没响 ⇒ 那不是一个零，是一次没读成。 这与本轮 #16801 / #16810 / #16807 各自独立测到的同一仪器缺陷一致 —— 四张卡从四个方向测到同一件事，已是本席的常规纪律。

type = Task

⛔ 不是 Bug：实现（schema 与 validateControlFlow）在 #16825 之后是正确的，⛔ 无任何实现违背声明；变假的是描述它们分工的两句散文。⇒ Task（附 documentation），与 #15239 同判。

---

Generated by Claude Code

[zhuangjianguo]

Release: pm:blocked → pm:queue — both blocking layers discharged at 2026-09-08T14:55Z, both limbs of 放行双查 recorded

domain:spec execution seat, session session_016N6xmWt5hYm94ffVEwGH8x, at 2026-09-08T14:56Z. One replace, assignee left empty, read back.

The condition, taken from the MOST RECENT conversion comment only

The triage comment of 2026-09-08T09:34:22Z set pm:blocked on a two-layer condition, and both layers are now measured discharged:

layer	condition	now
the ruling	#16134 was pm:awaiting-maintainer, PR #16825 open	#16134 closed completed 14:55Z; PR #16825 merged 14:55:26Z (21aabbc7b)
the hard serial	"This card writes packages/spec/src/automation/control-flow.zod.ts, which PR #16825 currently holds"	the PR merged ⇒ the file is released

⛔ Released against that comment's condition and no earlier one, per 「只放最近一次转换评论的条件」.

Limb ② — refuse the release if a merged PR newer than that conversion comment sits on the card. Measured: comments: 1, closed_by_pull_requests: null, and the card's only timeline cross-reference is 09:33:33Z, which is earlier than the 09:34:22Z conversion comment. ⇒ nothing newer exists; limb ② passes.

⚠️ The re-verification this card's own conversion comment demands is the claimant's FIRST act, ⛔ not done here

That comment is explicit:

it must be re-verified against origin/main at that moment — the ruling's own wording may have moved.

⇒ This release moves the state only. What this seat did measure, so the next reader starts from a fact rather than an assumption: both sentences are still present, unchanged, on origin/main after the merge —

control-flow.zod.ts:61   * key strictness can answer. The two do not overlap and cannot fight: the
control-flow.zod.ts:63   * They do now meet at one seam, deliberately — `validateControlFlow`

positive control on the same file: validateControlFlow → 9 hits, so the grep fires.

⇒ ⭐ That is exactly the shape this card predicted: the merge falsifies the prose without touching it, which is why the card exists separately from #16825 and why triage rated the card's own measurement ("that PR does not touch this prose") as the reason it deserves to stand alone.

⛔ This seat does not assert the two sentences are now false. Whether #16134's landing actually breaks "cannot fight" and "one seam" is a reading against the merged tree, and the conversion comment reserves it for the claimant at claim time. ⚠️ Take it before writing — the ruling's wording may have moved, and rewriting a docblock to match a ruling you did not re-read is how this card's own family of defects is produced.

Sibling, for whoever picks this up

#15239 is the same shape ("three sharing.zod.ts docblock sentences go false when #15072 lands") and triage graded this card by copying it. Worth checking whether #15072 has landed too — if it has, the two are candidates for a fold under gate ① (same defect shape, same fix method, same packages/spec region), and if it has not, they are not.

---

Generated by Claude Code