`FlowFunctionEffectSchema` TSDoc still states the broken-sweep predicate unqualified — the third `packages/spec` surface, outside #12722's fence

[os-trump]

Filed unassigned by the dev on #12722. Dedupe search run: one targeted search against the broken-sweep / spec-TSDoc family, control hits returned (#12722 and #12685 both came back), no existing card for this surface.

#12685 established — with a measured A/B, 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 corrected sys_automation_run's field descriptions and content/docs/automation/flows.mdx. #12722 corrected the two packages/spec surfaces its dispatch named — automation/execution.zod.ts and integration/connector.zod.ts.

A third surface in the same package carries the same unqualified claim. It sat outside #12722's declared file surface, so it was left standing deliberately rather than fixed in passing.

packages/spec/src/automation/flow-function.zod.ts — FlowFunctionEffectSchema's doc block:

'writes' — it performs writes, or dispatches effects, that the platform cannot see or count. The step reports ExecutionStepMetrics.unmeasuredEffect, so the run's unmeasured tally keeps the broken-sweep query (selected > 0 AND acted = 0 AND unmeasured = 0) off it — and only off the flows that actually call such a function.

"the broken-sweep query", definite article, naming the three-clause predicate as the detector — the same false predicate #12685 disproved. This block ships in .d.ts exactly like the two #12722 fixed.

Three weaker mentions in the same file, worth triaging with it but not plainly wrong on their own:

• around line 70 — "an under-reported selected can only make the broken-sweep alert quieter, never wrong": names the alert without spelling the predicate.
• around line 123 — "Surface flow run summaries (selected / acted / skipped) — a scheduled flow that does nothing is currently indistinguishable from one with nothing to do #4354's broken-sweep query stays silent on the one flow that needed it": names "broken-sweep query" without spelling it.
• the authored history string around line 155 — "which is what keeps Surface flow run summaries (selected / acted / skipped) — a scheduled flow that does nothing is currently indistinguishable from one with nothing to do #4354's broken-sweep alert quiet on the run that needed it".

Suggested shape, mirroring what #12721 landed and #12722 applied so all surfaces agree: state the predicate as the FIRST FILTER, not a verdict, and point at the per-node fold (nodes[] / gates[]) as the discriminator. The clause's own point stays correct and should survive: a declared-writes function makes acted INCOMPLETE, not zero.

One material difference from #12722, worth knowing before dispatch. #12722 needed no artifact regeneration — its two doc blocks feed nothing generated (verified: check:generated reported all 14 artifacts up to date after the reword). This file is not like that: its @module doc comment IS emitted as the page intro of content/docs/references/automation/flow-function.mdx, where the prose appears verbatim. So a reword here moves a generated artifact and must run gen:schema && gen:docs in the same PR; the history string at line 155 is authored schema text on the same path.

Why it is worth a card rather than a shrug: the same severity argument #12722 was graded on. 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. Correcting two of the three packages/spec surfaces and leaving the third reproduces exactly the disagreement the parent card exists to end.

Related: #12722, #12685, PR #12721, #4354 (shipped the measurement), #4347 (the original silent no-op), #4396 (declared script effects).

[os-trump]

Claim: PM loop round R7 (batch 2)
Session: session_01LpRNHxWZgSUgVnFT9mQQo4
Branch: claude/issue-12900-flow-function-broken-sweep
Worktree: objectstack-issue-12900
Domain: domain:spec
File surface: packages/spec/src/automation/flow-function.zod.ts (the FlowFunctionEffectSchema doc block — the unqualified predicate claim — plus the three weaker mentions ~:70/:123/:155 triaged with it, the :155 history string being authored schema text) + the regenerated content/docs/references/automation/flow-function.mdx (the card measures that this file's @module prose IS emitted there — run gen:schema && gen:docs in the same PR, never hand-edit the artifact) + one changeset. ⛔ Nothing else.
Container & model: S/M, mode:subagent, model: opus.
Clause-②: PATH leg hit; CONTENT is shipped .d.ts/docs contract prose in the #12722 family — the PR carries needs:contract-review, tier-verified seat reviews at PASS. Follow the ruled shape all sibling surfaces now agree on (#12721/#12722): the predicate is the FIRST FILTER, not a verdict; the per-node fold (nodes[]/gates[]) is the discriminator; the clause's own true point survives (declared-writes makes acted INCOMPLETE, not zero).
Serial constraints cleared: no open PR claims the file.

---

Generated by Claude Code

[os-trump]

Dev claim — picking this up under the PM claim above (comment 5459581778).

Session: session_01LpRNHxWZgSUgVnFT9mQQo4
Branch: claude/issue-12900-flow-function-broken-sweep (pushed empty as the write-path probe before the first edit)
Worktree: objectstack-issue-12900
Base: 9e8adf3f6b1dc0e7e90739a66e1f1ccd1aa9fe20
Assignee: untouched (PM owns that field).

Premise re-measured on the base, before any edit — all legs hold, with one refinement worth stating up front:

• packages/spec/src/automation/flow-function.zod.ts still carries the unqualified claim in FlowFunctionEffectSchema's doc block (lines 62-67): "the run's unmeasured tally keeps the broken-sweep query (selected > 0 AND acted = 0 AND unmeasured = 0) off it".
• The three weaker mentions are present as described: line 69-71 ("the broken-sweep alert quieter, never wrong"), line 123 ("Surface flow run summaries (selected / acted / skipped) — a scheduled flow that does nothing is currently indistinguishable from one with nothing to do #4354's broken-sweep query stays silent on the one flow that needed it"), and the authored history string at lines 151-155 ("which is what keeps the broken-sweep alert quiet on the run that needed it" — note the shipped text has no #4354's prefix; the card's quote paraphrases it).
• The card's material measurement holds: the @module doc comment IS emitted verbatim as the intro of content/docs/references/automation/flow-function.mdx (compared line for line — source lines 6-49 appear as mdx lines 10-53).

Refinement: the FlowFunctionEffectSchema doc block is NOT what reaches the mdx — only its .describe() string is emitted there, under the FlowFunctionEffect heading. The prose that reaches the generated page is the @module block, and that block carries a fifth mention of the same claim in the same defect class at source lines 38-42, emitted at mdx lines 42-46: "it would suppress the broken-sweep signal on every flow that calls any function". "the broken-sweep signal" is the exact phrase PR 12721 replaced on sys_automation_run. So that sentence is both the one an operator reads on the docs page and the one that makes the generated artifact move; treating it here is what turns the card's regeneration requirement into a real reading rather than a trivially green one. It will be reworded with the four, named and quoted before/after in the PR body.

Plan: reword to the ruled shape PR 12721 and PR 12722 landed — the three-clause predicate is the FIRST FILTER, not a verdict; the per-node fold (nodes[] / gates[]) is the discriminator; each clause keeps its own true point (a declared-writes function makes acted INCOMPLETE, not zero). Then gen:schema && gen:docs so flow-function.mdx moves in the same PR — never hand-edited. File surface: the one source file, the regenerated artifact, one patch changeset on @objectstack/spec. Nothing else.

---

Generated by Claude Code