Skip to content

feat(gates): gate-111 — a flow node declares what kind of step it is - #698

Merged
rubenvdlinde merged 1 commit into
mainfrom
feat/gate-111-flow-node-taxonomy
Sep 7, 2026
Merged

rubenvdlinde merged 1 commit into
mainfrom
feat/gate-111-flow-node-taxonomy

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

What it refuses

A class under a repository's own flow-node directory that implements IFlowNode and does not implement IFlowNodeTaxonomy. Such a node is served to the palette as serviceTask / other — visible, but only to whoever opens the palette, and wrong in a BPMN export in a way that looks answered.

Scoped by path, never by interface

This is the whole design, and the reason the gate is safe to add fleet-wide.

On a measured instance 38 of 65 step types are contributed by apps in other repositories, on their own release cycles. A gate that flagged any IFlowNode implementation missing the methods would fire on every one of them — which is exactly the behaviour the optional declaration exists to prevent, moved from run time into CI, and unfixable from the pull request it fired on.

So it only ever looks inside lib/Service/Flow/Nodes/. A repository without that directory reports NOT APPLICABLE, not a pass: nothing was inspected, and saying so is not the same as saying it was clean.

Acceptance, in both places

Where Arms Why there
the matrix planted/, clean/ the planted arm keeps a declared node beside the undeclared one, so the gate is proven to refuse a node rather than a directory — a checker that failed the whole tree would pass a single-file fixture for free
test_gate111_flow_node_taxonomy.sh + no-nodes/ NOT APPLICABLE is neither FAIL nor PASS, so the matrix's pair cannot express it — and it is the arm a gate scoped by interface gets wrong

Every arm also asserts the terminal checked N flow node file(s) summary, so a crashed checker cannot read as clean.

Measured against the real thing

  • Green on openregister's development: 29 files, all declaring.
  • Red on the same tree before the declarations landed.
  • NOT APPLICABLE on nextcloud-vue.

Suite

109 helper suites passed, this one among them. The 2 failures are pre-existing and unchanged: test_gate_45_to_55_acceptance.sh exits 2 for a missing ajv on a clean clone of main too, and test_gate_acceptance_matrix.sh now passes at 244 (it briefly failed on a fixture bundle with no expect.conf, which this adds).

A step type can now say what KIND of thing it is, in BPMN's vocabulary, and
where in the palette an author finds it. Both are optional by design: on a
measured instance 38 of 65 step types are contributed by apps in other
repositories on their own release cycles, so a node that declares neither is
served as `serviceTask` / `other` rather than fataling or being hidden.

That fallback is honest about somebody ELSE's node. For a node the repository
owns, it is just an undeclared node nobody noticed — and it reaches a BPMN
export as a wrong element type that looks answered.

🔴 SCOPED BY PATH, NEVER BY INTERFACE, AND THAT IS THE WHOLE DESIGN. A gate
that flagged any `IFlowNode` implementation missing the methods would fire on
all 38 contributed nodes — exactly the behaviour the defaults exist to prevent,
moved from run time into CI, and unfixable from the pull request it fired on.
So it only ever looks inside `lib/Service/Flow/Nodes/`, and a repository
without that directory is NOT APPLICABLE rather than a pass.

Acceptance in both places, deliberately:

- The matrix drives `planted/` and `clean/`. The planted arm keeps a DECLARED
  node beside the undeclared one, so the gate is proven to refuse a node rather
  than a directory — a checker that failed the whole tree would pass a
  single-file fixture for free.
- `test_gate111_flow_node_taxonomy.sh` adds the third arm, which the matrix's
  FAIL/PASS pair cannot express: a repository with no flow-node directory must
  report NOT APPLICABLE. That is the arm that matters most, and it is the one
  a gate scoped by interface would get wrong.

Every arm also asserts the terminal `checked N flow node file(s)` summary, so a
crashed checker cannot read as clean.

Measured against the real thing: green on openregister's `development` (29
files, all declaring), red on the same tree before the declarations landed, and
NOT APPLICABLE on nextcloud-vue.

Helper suite: 109 passed, my suite among them, and the 2 pre-existing failures
are unchanged — `test_gate_45_to_55_acceptance.sh` exits 2 for a missing `ajv`
on a clean clone of `main` too.
@rubenvdlinde
rubenvdlinde merged commit f808893 into main Sep 7, 2026
39 of 40 checks passed
WilcoLouwerse added a commit that referenced this pull request Sep 8, 2026
#698 shipped check_flow_node_taxonomy.py, its three-arm fixture tree, its
unit suite and an expect.conf declaring gate 111 — but never added a call
site to run-hydra-gates.sh. The acceptance matrix ran the runner over the
planted and clean arms, found no `[gate-111]` verdict line, and reported
"emitted NO verdict line at all" for both. `main` has been red on the
"Package invariants" check since f808893; this PR only inherited it,
because the hydra-gates workflow deliberately carries no `paths:` filter
and so runs on every PR to main.

The unit suite passed throughout, because it invokes the checker directly
rather than through the runner — a gate can be fully implemented and fully
unit-tested and still not exist for any repository the runner is pointed at.

Wiring follows gate-83's exit-code shape (0 pass / 4 not applicable /
crash-without-terminal-summary as `wiring`), with one deliberate difference:
no `[ -d ... ]` guard around the call. The checker reports NOT APPLICABLE
itself, so repos without lib/Service/Flow/Nodes/ get a verdict line instead
of the silence that hid this gate in the first place.

Verified locally:
- test_gate_acceptance_matrix.sh    244 passed / 0 failed (was 241 / 2)
- test_gate111_flow_node_taxonomy.sh  all three arms behaved
- check_gate_numbers_unique.sh      91 gates, every number claimed once
- errexit-discipline, exit-code-semantics, empty-scope suites all pass

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
rubenvdlinde added a commit that referenced this pull request Sep 8, 2026
…g called (#706)

#698 landed gate-111 (flow-node-taxonomy) with its checker, its acceptance
fixtures, its expect.conf row and its own test suite. Nothing ever called it.

So it emitted no verdict in any repository, and the acceptance matrix failed
with the only sentence that fits:

    FAIL — [flow-node-taxonomy/planted] gate-111 emitted NO verdict line at
           all — a gate that says nothing is not a pass

That failure fails `test_gate_acceptance_matrix.sh`, which fails the `Package
invariants` job, which is a REQUIRED status check on main. An unregistered
gate has therefore been blocking every pull request to this repository since
#698 merged.

The checker itself was never broken. Run against its own fixtures it already
answered correctly, and still does:

    planted   rc=1, 1 finding, names PlantedNode
    clean     rc=0
    no-nodes  rc=4, NOT APPLICABLE

This adds the runner block those return codes were written for.

TWO THINGS THE BLOCK DOES DELIBERATELY.

Scoped by PATH (`[ -d lib/Service/Flow/Nodes ]`), never by interface. That is
#698's own design note: on a measured instance 38 of 65 step types come from
apps in other repositories on their own release cycles, and an
interface-scoped gate would fire on all 38 inside pull requests that cannot
fix them.

The terminal summary is asserted BEFORE the exit code is believed. The checker
says in its own source that `checked N flow node file(s)` is how the runner
tells a clean run from a crashed one, so a missing summary reports a wiring
skip rather than a pass.

Verified: `test_gate_acceptance_matrix.sh` goes from 2 failures to
244 passed / 0 failed, and gate-111 now reports FAIL on planted/ naming
PlantedNode, PASS on clean/, and NOT APPLICABLE on no-nodes/.

Co-authored-by: Conduction Release Bot <release-bot@conduction.nl>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant