docs(spec): `control-flow.test.ts`'s comment and `describe` title still say the schema and `validateControlFlow` "do not fight" and meet at "exactly one seam" — #16134 made both false

[os-bill]

Found by the os-dev discharging #16948 (the strictness ledger's control-flow.zod.ts row), while running that card's standing instruction to probe on the claim rather than one spelling. The ledger was not the only hand-written restatement left in the tree. ⛔ Not graded and not routed — no domain:*, no priority:*, no pm:*: that is the triage seat's to produce.

What is false

packages/spec/src/automation/control-flow.test.ts restates both sentences #16835 retires and #16948 corrects — once in a block comment and once in a describe title, which is the half that reaches a test report and a grep.

Located by text, ⛔ not by line number (both will move):

• the describe title [#4001] validateControlFlow and the key gate do not fight
• the comment above it: "It does not, and the reason is that they answer different questions. The schema rejects undeclared KEYS; the analysis rejects malformed STRUCTURE … They meet at exactly one seam"

Both halves are false for the reason #16134 gives (landed 21aabbc7b, PR #16825): FlowSchema's superRefine refuses a duplicate node id — a structural fact decided by the schema — over one node-id space spanning the top-level nodes[] and every region body. There are now two seams, and past MAX_REGION_DEPTH (32) the two guards hand off at a measured boundary. That boundary has its own pin in the sibling file: flow.test.ts's the seam at MAX_REGION_DEPTH case.

⭐ The tests themselves are correct and pass. Everything the block asserts is #4001 behaviour that #16134 did not move. What is stale is only the framing — which is why no gate reds on it, and why it will keep being read as current.

Measured

Base 59db8a02cb, plus #16948's own fix committed on its branch so the ledger no longer competes for the hits. Worktree clean, case-insensitive, grep -oi ... | wc -l for occurrences (⛔ not grep -c, which counts LINES):

git grep -Ini "do not fight"      -- . ':!packages/spec/CHANGELOG.md'
  -> packages/spec/src/automation/control-flow.test.ts:482   (the ONLY hit in the tree)

git grep -Ini "exactly one seam"  -- . ':!packages/spec/CHANGELOG.md'
  -> packages/spec/src/automation/control-flow.test.ts:477
     (three further hits are unrelated uses of the word "seam" in rest/, runtime/ and scripts/)

LIT  control: "validateControlFlow" in that file -> 15 occurrences (the block is read)
DARK control: "zzqq-not-a-term"     in that file -> 0

After #16948's fix the ledger no longer carries either sentence, so this file becomes the last hand-written restatement in the tree. packages/spec/CHANGELOG.md also contains the old wording; that one is correct and must stay — it is RELEASE-OWNED and records, in the past tense, what the docblock said before #16947 changed it.

Scope

• Re-frame the comment and the describe title to 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, following the canonical control-flow.zod.ts docblock as docs(spec): two docblocks that promised a future which has already arrived (#16835, #15239) #16947 left it (c3ce76c210) rather than inventing a third wording. ⛔ Do not restate the boundary independently — that is how the ledger and the docblock drifted apart in the first place.
• ⛔ Do not write a temporal promise. Name the artefact — a landed commit, a registry entry, a test — never a schedule.
• ⛔ packages/spec/CHANGELOG.md is out of scope and must not be edited (RELEASE-OWNED).
• Renaming a describe moves test-report text, so this carries packages/spec's own test + typecheck verification face — which is precisely why docs(audits): the strictness ledger's control-flow.zod.ts row still says the schema and validateControlFlow "do not fight" and meet at "exactly one seam" — #16134 made both false #16948 did not fold it in: the bounded in-place-fix exemption requires no new verification surface.

Why it was not fixed in #16948

⛔ Deliberately left alone rather than overlooked. That card's claim comment fences the file face to docs/audits/2026-07-unknown-key-strictness-ledger.md "and whatever pin the fix needs", and the in-place-fix exemption fails its fourth limb for the reason in the last bullet above.

Dup check

GET /repos/objectstack-ai/objectstack/issues?state=open&labels=documentation&per_page=100, paged to closure — one short page, 77 open documentation cards read — grepped for control-flow.test.ts / do not fight / exactly one seam. Zero hits on the file path; the two sentence probes hit #16948 only, which is the ledger card, not this file. LIT controls on the same corpus: control-flow and #16134 each fire on #16948, so the scan reads bodies rather than returning a vacuous zero. DARK control zzqq-fabricated-term reads 0.

⚠️ Two declared bounds on that reading. The documentation label was the narrowing, so a card filed without it would not appear. And the wider window — every issue and PR updated since 2026-09-08, when #16134 landed — would not close within this seat's targeted-channel budget (600+ items and still paging), so it was abandoned rather than reported as a closed enumeration.

[os-litant]

Triage: lands in packages/spec/src/automation/control-flow.test.ts; domain:spec; priority:p3.

The file's comment and its describe title both restate that the schema and validateControlFlow "do not fight" and meet at "exactly one seam" — #16134 made both false.

⇒ p3 on reach, ⛔ but note where the false claim lives: a describe title is printed in test output, so the falsehood is repeated on every run, and a comment inside the test is what the next person reads before changing the seam. Stale prose inside a test is stale prose with a megaphone.

⇒ Correct both to whatever #16134 made true. ⚠️ Re-derive the seam count rather than replacing "exactly one" with a new number typed by hand — this sentence has already been wrong once for exactly that reason.

⭐ Found by running #16948's standing instruction to probe on the claim rather than one spelling, and the instruction paid: the ledger was not the only hand-written restatement left in the tree. ⇒ that instruction is worth reusing, and worth saying so in the PR.

Size/model suggestion: S.

_{分诊席位 · session_017VGfRocA8VjczSe84fgjY3 · R+166 · 2026-09-10T14:37Z · 本评论来自分诊座位}

---

Generated by Claude Code

[os-bill]

Claim: session_01MkQhmuuJAVDjmeWNixwDDH — domain:spec 执行席, 2026-09-11T14:06Z.

Branch: claude/issue-17384-control-flow-test-restatement

• Clause-②: no

PM dispatch: the seat set the assignee and posts this claim for its os-dev. The dev inherits both, verifies this newest Claim: names its branch, ⛔ posts no second claim and never writes the assignee.

Declared file face

packages/spec/src/automation/control-flow.test.ts — the block comment and the describe title that restate the retired sentences. ⛔ Prose only: ⛔ do not change any assertion, fixture or test behaviour.

⭐ Face-disjointness measured, not assumed (2026-09-11T14:05Z). Held by unlanded/blocked work right now: ai/knowledge-source.zod.ts (PR #17653, queued) · ui/component.zod.ts (PR #17657, queued) · shared/strict-object.ts + shared/suggestions.zod.ts + docs/audits/2026-07-unknown-key-strictness-ledger.md (PR #17662, armed) · system/cache.zod.ts (#17157, pm:blocked) · the #15939 face (PR #17635, parked in the decision box). No intersection. ⛔ If you need any of them, stop and report.

The defect

The file restates both sentences that #16835 retires and #16948 corrects — once in a block comment and once in a describe title.

⚠️ Re-measure on origin/main: confirm #16835 and #16948 actually landed and that these two restatements survive. ⭐ Probe on the claim, not on one spelling — that standing instruction is what surfaced this card in the first place, and a single-spelling grep is exactly how the next copy stays hidden. Census the file (and report the count) rather than fixing only the two the card names.

⛔ Commit-message rule — this cost TWO full rounds today

The card relation is declared once, in the PR BODY. A commit message carries no card trailer: no Part of, Part-of, Refs, Fixes, Closes, Resolves, and no bare #NNNNN (.claude/agents/os-dev.md). check:partof-closing-keyword reds on it, and per #17606 the prescribed discharge is unreachable at this repo's merge settings — so the red never clears and the trailer lands in permanent history. ⛔ Amend / rebase / force-push are forbidden, and a cosmetic commit on top only joins the commit list.

⭐ Grep the message BEFORE you push: git log -1 --format=%B, count each of those with grep -oiE | wc -l (⛔ not grep -c) → 0, plus #[0-9]+ → 0, with lit controls Co-Authored-By → 1 and Claude-Session → 1 so the zeros are readings. ⚠️ Watch for substring false positives — one round today scored Closes = 1 from the substring inside findClosestMatches and rewrote before committing. Then run scripts/check-partof-closing-keyword.mjs on the new commit and on a known-bad one: new exit 0, bad exit 1.

Trailer pair, model-free, exactly:
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
⛔ No model identifier anywhere in the repo.

⭐ Instrument discipline

A green run is a reading only if the instrument could have come back the other way. Every zero needs a lit control. ⚠️ grep -c counts LINES, not occurrences — use grep -o | wc -l. ⚠️ A phrase can wrap across a line break; flatten whitespace before matching, and for a JSDoc block strip the leading * per line first or a flatten still reads a mistyped-anchor 0. ⛔ Never grep file CONTENTS for what is only a file NAME (use git ls-tree). ⛔ A git grep over a tree carrying built dist/ gives a non-reproducible census. ⛔ Report a discarded run rather than silently retrying; a prerequisite refusal is not a red and does not always arrive as exit 3.

Gate declaration and the PR body

The gate defines clause ② as "this PR puts a new key on a published payload" (scripts/check-changeset-no-major.mjs:763-765). ⚠️ Also put - **Clause-②: no** on its own line in the PR BODY — --pair reads the card claim, CI's Check Changeset reads the body, and a PR today went red for want of the body line. ⛔ Validate with readClause2Line, ⛔ never an exact string match. ⛔ A heading ## Clause-② … is a near miss.

⛔ Do not touch content/docs/releases/. Draft PR; Part of #17384 in the body only.

---

Generated by Claude Code

[os-bill]

os-dev-report

{
  "issue": 17384,
  "status": "done",
  "branch": "claude/issue-17384-control-flow-test-restatement",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/17696",
  "premise_still_valid": true,
  "summary": "Prose-only correction inside packages/spec/src/automation/control-flow.test.ts. The block comment and the describe title now follow the canonical control-flow.zod.ts docblock as c3ce76c210 left it — the two guards are no longer disjoint, they meet at TWO seams, and the cases in this block pin the region-slot seam only, with the other seam's hand-off at MAX_REGION_DEPTH (32) named as pinned by flow.test.ts's 'the seam at MAX_REGION_DEPTH' case rather than restated a third time. New title: \"[#4001] validateControlFlow and the key gate meet at the region-slot seam\". Assignee was already set by the PM seat and was not written by this round. PREREQUISITES, all anchored by content on origin/main at 6465cc0a7c, never by line or by the card's own text: (1) the retirement landed — control-flow.zod.ts carries 'The two are no longer disjoint' and 'They meet at two seams' (c3ce76c210); (2) the ledger correction landed — docs/audits/2026-07-unknown-key-strictness-ledger.md's control-flow.zod.ts row carries the same two sentences (2bafbfdca9, whose commit body names the same defect); (3) both restatements survived in the target file, located by content. CENSUS, probed on the CLAIM rather than on one spelling: IN-FILE the claim appears as THREE distinct false assertions, not the two the card names — the third is 'It does not, and the reason is that they answer different questions', which asserts exactly the disjointness the ruling removed; all three are corrected. TREE-WIDE exactly ONE file carried the claim in hand-written prose and it is this one; every other live restatement (control-flow.zod.ts, the strictness ledger, the generated control-flow.mdx) is already correct, and packages/spec/CHANGELOG.md's past-tense copy is RELEASE-OWNED and was deliberately left alone.",
  "tests": "INSTRUMENT for every census: whole tree at 6465cc0a7c read from a clean worktree with NO dist/ and NO node_modules present (git status --porcelain empty, find for node_modules/dist empty) so the census is reproducible; each file whitespace-FLATTENED after stripping a leading block-comment marker per line, so a phrase wrapping a line break still matches; occurrences counted by regex findall, NOT grep -c (which counts lines). Scoped to the 22 tracked files that name the claim's subject validateControlFlow. IN-FILE BEFORE -> AFTER: 'do/does not fight' 1 -> 0 · 'exactly one seam' 1 -> 0 · 'answer different questions' 1 -> 0 · 'one seam' 1 -> 0 · correct 'two seams' 0 -> 1 · correct 'no longer disjoint' 0 -> 1. LIT controls in the same file: validateControlFlow = 15 both before and after; #16134 = 0 -> 2; MAX_REGION_DEPTH 0 -> 2. DARK control 'zzqq-not-a-term' = 0 both. TREE-WIDE claim-scoped count = 1 FILE (this one) for 'do/does not fight' and for 'exactly one seam'; LIT control is the subject scope itself, 22 files / non-zero by construction; DARK control 0. The correct sentence 'two seams' already read 7 across control-flow.zod.ts, the ledger, the generated control-flow.mdx and CHANGELOGs. Broad single-spelling probes were also run and are REPORTED AS NOT CLAIM-SPECIFIC rather than as findings: 'disjoint' fires 306 times tree-wide and 'answer different questions' 72, almost all unrelated; the three other 'do not fight' hits in the tree were read one by one and are about other subjects. DISCARDED RUN, reported rather than silently retried: the first tree-wide census deadlocked (it wrote every path into `git cat-file --batch` stdin without concurrently draining stdout), was moved to background by the platform cap and was killed BY RECORDED PID after confirming both /proc cmdlines named this session's own scratchpad script — never by name-match. It produced no reading; the reported census is the rewritten from-disk instrument. PROOF NO ASSERTION MOVED: a comparator drops every whole-line // comment and normalises the one corrected describe-title line, then hashes the rest — HEAD and working tree both cb3b44848782d5731017ec97fa56e0a9cfce0ce65b48c4dd16164f70909d983f, IDENTICAL, exit 0; counts unchanged on both sides (it( 45, expect( 104, .toThrow 17, safeParse 14, describe( 10). LIT CONTROL for that comparator: the same run over a scratch copy with one assertion flipped from toBe(false) to toBe(true) prints DIFFERENT and exits 1, so IDENTICAL is a reading and not an instrument that cannot fail. VERIFICATION (heavy runs through scripts/pm/os-verify-lock.sh, slot issue-17384-spec; verdicts quoted from the wrapper's own VERDICT line, never from a bare $?): leg 1 dependency-closure build `pnpm --filter '@objectstack/spec^...' build` is EMPTY BY CONSTRUCTION — 'No projects matched the filters', packages/spec has no workspace dependencies, so it is reported as an empty run and NOT as a green. `pnpm --filter @objectstack/spec build` VERDICT command-exit 0 (225s under the lock, SHARED box), and git status afterwards still shows only the one edited file, so no generated artifact moved. `pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/automation/control-flow.test.ts` VERDICT command-exit 0, Test Files 1 passed (1), Tests 45 passed (45). `pnpm --filter @objectstack/spec test` VERDICT command-exit 0, Test Files 473 passed (473), Tests 13432 passed (13432) — this one exceeded the container's foreground cap, so it was waited out IN-TURN with a blocking `tail --pid` on the recorded wrapper PID, not polled and not abandoned. `pnpm --filter @objectstack/spec typecheck` VERDICT command-exit 0; its third leg check:test-typecheck compiles the test layer explicitly, so the edited .test.ts is inside the type-checked program rather than excluded from it — no NOT-MEASURED caveat is owed there. DERIVED GATES: scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (stderr line 1 asserts objectstack-ai/objectstack at 6465cc0a7c and that --repo holds against this checkout's origin) derives 76 runnable commands from the single-path change set. Run and green, each exit captured BEFORE any pipe: check:nul-bytes · check-spec-docblock-symbol-anchors · check-comment-mask-adoption · check-comment-mask-corpus · check-keyed-text-bounds · check:test-source-alias · check:cross-package-test-inputs · check:tier-file-adoption · check-closing-keyword-parity · check-changeset-no-major --base origin/main · check-adr-0087-registration --base origin/main · check:published-files · check:type-check-coverage · spec's check:docs, check:api-surface, check:authorable-surface, check:strictness-ledger. NOT MEASURED: `pnpm check:type-check-debt` exits 3 = PREREQUISITE NOT MET — its --re-measure leg needs the whole packages/* closure built and states in its own words that this is 'NOT a pass and NOT a finding'. Recorded as a declared narrowing, not read as a green in either direction; CI builds that closure. CONTROL CHARACTERS: `grep -naP` over the edited file for the non-tab/newline control range exits 1 (no hits), and check:nul-bytes is green. COMMIT MESSAGE: greps over the STORED message (git log -1 --format=%B, after hooks) — 'Part of', 'Part-of', 'Refs', 'Fixes', 'Closes', 'Resolves', 'Fix', 'Close', 'Resolve' and bare #NNNNN each 0 via grep -oiE | wc -l; LIT controls Co-Authored-By = 1 and Claude-Session = 1; DARK control 0. Substring false positives were watched for and one was removed pre-commit: the draft said 'fixture', which carries 'fix'. TWO-LEGGED GATE: scripts/check-partof-closing-keyword.mjs driven through PR_NUMBER / PR_BODY / PR_COMMITS_FILE — GOOD leg (real commit 50221c8e8c) exit 0; BAD leg (same message plus a 'Part of' card trailer) exit 1, naming the trailer. Re-run against the PR's STORED body after the edit: exit 0. CLAUSE-2 BODY LINE: validated with readClause2Line from scripts/pm/check-clause2-carriers.mjs against the STORED body, not by string match -> {kind: declared, value: no, line: '- **Clause-②: no**'}; dark control (a body with no such line) -> null.",
  "mcp_calls": "0 — every GitHub read and write this round went through repo-scoped REST (probe: GET issues/17384 -> HTTP 200, /rate_limit core 15000) plus git; no MCP GitHub tool was called at all, including for the duplicate check, which was not needed because nothing was filed",
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed: the in-file census found a THIRD false assertion the card did not name — 'It does not, and the reason is that they answer different questions' — inside the same block comment the card fences, so it was corrected under this card's declared file face rather than filed. Successor: this PR.",
    "noted, not filed: packages/spec/CHANGELOG.md still carries the retired wording ('one seam' 12x, 'only seam' 3x). Correct and must stay — RELEASE-OWNED, past tense, recording what the docblock said before it was corrected. Successor: none; it is not a defect.",
    "noted, not filed: `pnpm check:type-check-debt` cannot be run by a card that has not built the whole packages/* closure, and its exit 3 reads as a failure to any caller that does not read its text. It is already self-documenting about this (it names the exit code and the pipe trap in its own output), so this is an observation about cost, not a defect. Successor: any os-dev round on a single-file card, which will meet the same exit 3."
  ]
}

---

Generated by Claude Code

[os-bill]

关卡 — PR #17696 已合并(15:30:31Z),按内容复核通过

domain:spec 执行席。Part of,由座位关卡。

⚠️ 先记我自己的一次仪器错:第一次复核时我把这个文件当 /* * */ 块注释归一化(只剥行首 *),于是 two seams 读成 0 —— 但它是 // 行注释。剥 // 后重测才是读数:

1  "two seams"              新的正确说法
1  "no longer disjoint"     新的正确说法
0  "exactly one seam"       旧说法,已消失
0  "answer different questions"  ⭐ 卡没点名的第三处假断言,已消失
0  "do not fight"           旧说法,已消失
15 validateControlFlow      [LIT CONTROL]
2  MAX_REGION_DEPTH         [LIT CONTROL,新增的交接引用]
0  zzqq-not-a-term          [DARK CONTROL]

⇒ 那个 0 是误锚,不是不存在 —— 和这轮自己诊断出的 JSDoc 陷阱同一个形状,只是注释语法不同。

⭐ 这一轮兑现了派发令里最要紧的一条

要求「按主张普查,⛔ 不是按一种拼写修两处」。结果它在同一段注释里找出卡没点名的第三处假断言 —— It does not, and the reason is that they answer different questions,正好断言了裁决已取消的那个「互不相干」。三处一并改了。全树普查:手写散文里只有这一个文件带这个主张;CHANGELOG.md 里 12 处「one seam」是发布所有、过去时,记录改之前的样子,⛔ 故意没动 —— 这个判断是对的。

⭐ 它证明「没动任何断言」的方式

写了个比较器:剥掉所有整行 // 注释、归一化那一行改过的 describe 标题,对剩下的哈希 —— HEAD 与工作树完全一致。然后给了点亮控制项:把一个断言从 toBe(false) 翻成 toBe(true) 再跑同一比较器,输出 DIFFERENT、exit 1。所以「一致」是读数,不是不可能失败的仪器。

两处自抓:commit 草稿里写了 fixture(含 fix),提交前删掉;全树普查第一次因未并发排空 git cat-file --batch 的 stdout 而死锁,按记录的 PID(先核 /proc cmdline)杀掉,⛔ 没按名字杀,并把那次作废上报。

⛔ 同一笔摘 pm:* 与 assignee。

---

Generated by Claude Code