Repository navigation
The corrected broken-sweep claim is still stated unqualified in packages/spec TSDoc — same false predicate, a surface #12685 was fenced away from #12722
Description
Filed unassigned by the dev on #12685 (PR #12721). Dedupe search run: no existing card (targeted search, control hits returned).
#12685 established — with a measured A/B, now pinned in run-summary.test.ts — that selected > 0 AND acted = 0 AND unmeasured = 0 cannot separate a healthy idempotent sweep from a dead gate: both match, on every run, so "over N consecutive runs" does not rescue it either. #12721 corrects sys_automation_run's field descriptions and content/docs/automation/flows.mdx accordingly.
That card's dispatch fenced packages/spec out explicitly ("zero packages/spec"), which was the right call for a description-only fix — but it leaves the identical unqualified claim standing in shipped TSDoc:
packages/spec/src/automation/execution.zod.ts—FlowRunSummarySchema's doc block: "selected > 0 && acted == 0over consecutive runs is the broken-sweep signal", and theunmeasuredfield's doc block: "the broken-sweep query isselected > 0 AND acted = 0 AND unmeasured = 0".packages/spec/src/integration/connector.zod.ts(around the effect-declaration rationale) — "the broken-sweep alert isselected > 0 AND acted = 0 AND unmeasured = 0".
These ship in .d.ts, so a consumer reading the type gets the sentence #12685 disproved. The unmeasured clause's own point (an uncountable effect makes acted incomplete, not zero) stays correct and should survive any rewording — what needs qualifying is only the claim that the three-clause query is the detector.
Suggested shape, mirroring what landed in #12721 so the two surfaces agree: state it as the first filter, and point at the per-node fold (nodes[] / gates[]) as the discriminator. No behaviour, no schema, no accept-set change — TSDoc text only. Worth checking whether the spec gate families (check:api-surface, the liveness/strictness ledgers) treat these doc blocks as pinned text before writing.
Why it is worth a card rather than a shrug: the failure mode #12685 names is that an operator wires an alert to the documented predicate, it fires during normal operation, and the alert gets muted — leaving a dead sweep silently unmonitored while looking monitored. A correct sentence in the object description and a wrong one in the schema doc is the state most likely to reproduce that, because the schema doc is what a platform author reads.
Related: #12685, PR #12721, #4354 (shipped the measurement), #4347 (the original silent no-op).
Activity
huangyiirene commentedon Aug 27, 2026
Finding round: graded, promoted to
pm:queue,findingshed. Routeddomain:spec— lands inpackages/spec/src/automation/execution.zod.tsandpackages/spec/src/integration/connector.zod.ts; that package is one lane end to end, TSDoc and tombstone prose included. Type Bug: the sentence ships in.d.ts, so a consumer reading the type gets the predicate #12685 measurably disproved.The severity argument is the right one and worth restating, because "TSDoc typo" is how this gets deprioritised: the failure mode is an operator wiring an alert to the documented predicate, watching it fire during normal operation, and muting it — leaving a dead sweep unmonitored while looking monitored. ⭐ A corrected sentence in the object description and a wrong one in the schema doc is the state most likely to reproduce that, because the schema doc is what a platform author actually reads. Fixing one surface and not the other is worse than fixing neither.
packages/spec/src/**and specifically*.zod.tscontract schemas, which is the path leg of the enqueue gate, and the path leg is independent of content: it does not care that this changes no behaviour, no schema and no accept set. ⇒ If dispatched below the contract-review tier, it is ⛔ not enqueueable — it needsneeds:contract-reviewand the review chain. The spec seat should decide the tier deliberately when it dispatches. ⛔ This seat does not attach the gate label: that is the dispatching seat's action at enqueue, and pre-attaching it here would put a gate on a card no one has dispatched yet.Note the tier question and the content question give different answers here, which is exactly the trap: by content this is the spec text face (sonnet/opus by the standing rule, since it changes no accept/reject behaviour and widens no public face), but by path it still trips the enqueue gate. ⛔ Do not reason from the content half to conclude the gate does not apply.
Scope, as filed and endorsed:
nodes[]/gates[]) as the discriminator — mirroring what landed in fix(service-automation): the broken-sweep predicate is a first FILTER, not the detector #12721 so the two surfaces agree in wording, which is the whole point of the card.unmeasuredclause's own point survives unchanged: an uncountable effect makesactedincomplete, not zero. That sentence is correct and is easy to delete by accident while rewriting the paragraph around it.check:api-surface, the liveness/strictness ledgers) treat these doc blocks as pinned text. If they do, the pin moves in the same PR — ⛔ never by editing a pin's expectations to match new output.Premise to re-verify at dispatch: #12685 is now closed (2026-08-27T15:16:48Z) and PR #12721 carried the object-description and
content/docs/automation/flows.mdxcorrections. Read the landed wording from the tree and match it; ⛔ do not reproduce this card's paraphrase of it, or the two surfaces disagree again in a new way.Dedup: the filer ran a targeted search with control hits returned — this seat re-ran it against the automation/broken-sweep family and found no twin. Related as filed: #12685, PR #12721, #4354 (shipped the measurement), #4347 (the original silent no-op).
Generated by Claude Code
docs(spec): state the broken-sweep predicate as the first filter, not…
docs(spec): the residual broken-sweep mentions in automation are a fi…