flows: lint a `loop` body with a fallible node and no containment, and a `try_catch` without `catch`; document `loop { try_catch }` as the per-iteration containment spelling (B-branch items 1–2 of #13681)

[claude]

Part of #13681 — the B-branch's lint and docs limbs, filed into the domain:devx queue by the domain:spec seat (session session_01GDA48PuRFrHyRfdkBz8m21) under the cross-seat path the retriage comment on that card prescribes (comment 5479171811: the lint limb is handed to its lane by a proper card, never privately). The visibility half (item 3, the run-summary contract) stays on #13681 and is in flight in the spec lane; this card does not depend on it — the lint rules and the docs spelling are authoring-time facts measured on origin/main today.

Reader: the domain:devx execution seat, at its next selection pass (this card is a plain pm:queue candidate; triage adds domain:* and type).

Ruling of record (do not re-decide)

Maintainer 2026-08-31, director decision batch #18, verbatim 「其他同意」 on the conditional ruling (issue comment 5478768627); branch selected by measurement (comment 5478879587): B — no new key (⛔ no loop.config.onIterationError), because loop { body: [ try_catch { try, catch } ] } measured as real per-iteration containment on the real AutomationEngine (5 elements, third fails, 5/5 iterations, elements 4–5 processed, run completes; measurement comment 5478851960).

Deliverables (from comment 5478879587 §B, items 1–2, and the retriage's three standing prohibitions in comment 5479171811)

1. Lint rule A — loop without containment: a loop whose body region contains a fallible node (any node that can return success: false or throw — at minimum every builtin action node, notify, connector_action, record writes) and no try_catch enclosing it ⇒ an authoring-time warning that names the loop node, the fallible node, and the prescribed spelling. Lands in packages/lint under the flow lint family.
2. Lint rule B — the near-miss shape, first target not an extra: a try_catch node whose catch region is absent gives zero containment and dies exactly like an unwrapped node (measured). Name it at authoring time; the fix text is the minimal catch spelling below.
3. Docs: write loop { try_catch { … } } into the flow docs as the orthography for per-iteration containment, carrying the measured minimal catch spelling verbatim (do not re-derive): catch cannot be empty — the region's nodes is .min(1), so catch: {} and catch: { nodes: [] } are both refused; the shortest usable catch is one bare assignment node with no config; edges may be omitted; errorVariable may be omitted.
4. Both lint rules ship with the positive control (a fixture that trips each rule) and the negative control (the documented spelling passes clean), and the docs example must type-check under check:skill-examples / check:yaml-examples where applicable.

Acceptance (executable)

• pnpm --filter @objectstack/lint exec vitest run <the flow-lint test file> shows: the unwrapped-loop fixture → warning naming the loop and the node; the try_catch-without-catch fixture → warning; the documented loop { try_catch { try, catch: [assignment] } } fixture → no finding.
• content/docs/automation/flows.mdx (or the page the devx seat judges canonical) documents the spelling with the minimal catch form above, and the example parses under FlowSchema.

Out of scope here

• The run-level visibility of a contained failure (FlowRunSummarySchema has no failure count; nested try/catch steps do not inherit the loop iteration; $error binds no row identity) — that is A loop node aborts the entire flow run when one iteration's node fails — a single bad row kills a whole scheduled sweep, and there is no per-iteration containment to opt into #13681's spec half, followed by a services card for the engine.
• [finding] A dying loop discards its body's completed steps wholesale — the run summary reports acted: 0 while 5 writes actually happened (childSteps splice only after a SUCCESSFUL node result) #13803 (summary reports acted: 0 after a mid-loop death) — independent, domain:services, ⛔ do not merge.

---

Generated by Claude Code

[claude]

Claim: session session_01WLJQhde67SeTccsmnBVarV (domain:devx execution seat, seat post #6023) — R1 wave 8.

• Branch: claude/issue-14394-loop-containment-lint
• Worktree: ../objectstack-14394 (dedicated per-task worktree, off origin/main)
• Domain: domain:devx per the cross-seat filing (lint in packages/lint + docs in content/docs/**; the visibility half stays on A loop node aborts the entire flow run when one iteration's node fails — a single bad row kills a whole scheduled sweep, and there is no per-iteration containment to opt into #13681 in the spec lane). ⛔ No packages/spec change — the region schema (FlowRegionSchema.nodes .min(1), catch optional) is read, not moved.
• File surface: packages/lint/src/lint-flow-patterns.ts (the two new rules + their FLOW_* rule-id constants, in the flow anti-pattern family), packages/lint/src/lint-flow-patterns.test.ts (positive + negative controls for both rules), packages/lint/src/index.ts (the two new rule-id constants on the barrel's existing FLOW_* export block only), content/docs/automation/flows.mdx (§"Structured control flow (ADR-0031)" — the loop { try_catch { … } } per-iteration containment spelling with the measured minimal catch verbatim), .changeset/*.md (@objectstack/lint patch). ⛔ No engine change (packages/services/service-automation), no loop.config.onIterationError, no new spec key.
• Premise re-verified on origin/main f60ab90ae: control-flow.zod.ts:142 region nodes .min(1), :144 edges default [], :216 loop.config.body optional (legacy flat-graph loops have no body), :314-317 try required / catch optional / errorVariable default $error; collectFlowGraphs :683 (scope string loop 'sweep' body → try_catch 'guard' catch) is the traversal lint-flow-patterns.ts:333/:1168 already uses; rule-id convention FLOW_* = 'flow-…' (lint-flow-patterns.ts:193-232), all warnings by default (FlowLintFinding.severity :150-167), mapped into authoring-rules.ts:1097 (CLI + runtime surfaces); docs anchor flows.mdx:379-470 (### Loop container :397, ### Try / catch / retry :446). No existing rule mentions containment (git grep -n "try_catch" lint-flow-patterns.ts → region-walk comments and the BRANCH_LABEL_NODE_TYPES set only). Premise holds.
• Container & model: subagent lane (M), opus.
• Clause ②: not reached — two new advisory warnings; no accept set moves, no contract change (the B-branch ruling is "zero contract change" by construction).
• Serial constraints: no open PR (27 open at 13:0xZ) touches lint-flow-patterns.ts, flow-walk.ts, flows.mdx, or packages/lint/src/index.ts. PR fix(lint): consolidate did-you-mean suggestion helpers into object-graph's shared nearestName #14575 / fix(lint): extend the flattened-scope shadowing warning to the descriptor-declared predicate slots #14576 (this seat, landing) touch other packages/lint/src files only — disjoint. Changeset: @objectstack/lint publishes ⇒ one patch changeset.

---

Generated by Claude Code