Protocol caveats: a step condition sits in a note beneath the step

[m2ux]

Summary

When a protocol step carries a caveat — an error path, a memory-limit fallback, a stale-index retry —
that caveat was written either as an indented bullet under the step or as an extra clause in the
step's own sentence. Neither is what the reader or the parser needs.

An indented bullet is read as a separate step to perform, because the parser that splits a protocol
into steps discards leading whitespace before it looks at the line. So a line meaning "if this went
wrong, do that instead" arrives as another thing to do. An extra clause buries the branch mid-sentence,
so a reader has to evaluate every clause in the step to work out which parts apply to their run.

This puts each caveat in a blockquote note beneath the step it qualifies, which folds into that step
rather than reading as another one, and leaves the step stating its outcome alone. It also extends
the catalogue entry that governs this so it names both spellings, not just the indented one.

What happens today

The catalogue entry for this defect describes only one spelling: a caveat written as an indented
sub-bullet. It says nothing about the clause-inside-the-sentence form, even though the design
principle it points at names that form explicitly. So the inline spelling was governed by a stance
with no operative test anywhere, and passed audits by falling between the two.

27 caveats across 22 technique files carry the indented form, spread over six families —
atlassian-operations, cargo-operations, gitnexus-operations, knowledge-base-search, dco-provenance
and validate-build. Most are error paths and retry instructions: run the analyzer again when the
index is stale, halve the job budget when a compile runs out of memory, fetch the available
transitions when the one requested is not offered.

Two more carry the inline form. The clippy step composes its status value and then, in the same
sentence, says what to do when the run failed — twice, in two different wordings of one condition
("when the check did not pass" beside "if the linter emitted denied warnings"), which read as two
branches over a single predicate. The formatting-check step does the same thing with its own failure
path.

The fix

Name both spellings in the catalogue entry. The detection criteria now cover the indented
sub-bullet and the clause inside the step's own sentence, including the case of two clauses restating
one condition in different words. The carve-outs are stated more precisely too: a complete selection
ladder — an "if / else if / otherwise" chain over one choice — is a branch table and stands whichever
way it is indented, alongside the ordered sub-actions and precedence ladders already exempt.

Move each caveat into a note. A lone caveat becomes the note's prose; where a step has two, each
takes a bullet inside one note. The steps themselves are unchanged.

State the clippy and formatting-check outcomes alone. Each compose step now states its status
value, with the failure path in the note beneath. Clippy's note names its condition once.

Stop counting the schema table's rows. A sentence describing what the aggregate schema address
covers said "the five schemas" directly beneath a five-row table listing them. It now names the
table, so it survives the table gaining a schema.

Why now is cheap

The paired server change widens the guard that measures this class, and that guard can only be shown
to work while the defects are still present. Measured against this corpus before these commits, it
names 28 sites — 27 real, plus one selection ladder that the carve-out then excludes. The same guard
reported a clean run on every one of them beforehand, because it could only parse protocols written
with heading-separated phases and 221 of the corpus's 569 technique files use a flat numbered list.
That measurement is the evidence the guard detects anything at all, and it is unavailable once these
files are converted.

Scope

24 files: the anti-pattern catalogue, the schema construct inventory, and 22 technique definitions.

Acceptance criteria

• No technique protocol carries a caveat as an indented sub-bullet
• The clippy and formatting-check compose steps state their status value with the failure path in a note
• The catalogue entry's detection criteria name both spellings, and its carve-outs name the selection ladder
• The full guard suite is no worse than before these commits

Non-goals

Mutually exclusive branches written as top-level peer bullets are the same underlying defect and are
left alone: separating them from a step that legitimately handles several cases in sequence needs
judgement a line pattern cannot supply.

The guard suite has one pre-existing failure unrelated to this change — three stale entries in the
binding-fidelity triage list, naming GitNexus operation techniques, with no live bugs behind them.
Verified identical before and after these commits by re-running against this branch with the changes
set aside. Whether each is a real closure is someone's decision, not this change's.

Paired change

The guard that detects this class is widened in a server-side pull request. Its clean-corpus
assertion turns over when this merges and the submodule pointer moves, so that one is expected red
until then. This corpus change runs green against either version of the guard, since the version on
the main line cannot see these files.

Investigation detail

The reviewer's original observation, the guard's blind-spot measurement, and the full site list:
.engineering/artifacts/planning/2026-09-03-manual-technique-review/

[m2ux]

Paired with #592, which widens the guard that measures this class. Merge order: this first, then the submodule pointer bump on #592 turns its clean-corpus assertion over.