Step-number rule: state it where a Protocol is defined, and cite it from the catalog - #464
Merged
Conversation
The ontology that defines what a Protocol is, and the anti-pattern catalog entry that detects citations by ordinal, each stated the same prohibition with its own reasoning beside it. The ontology now states the fact its own domain owns — the loader assigns step numbers, so a number is a position rather than an address — and the catalog entry cites it instead of deriving the same conclusion a second time. Detect, the carve-outs and the fix stay where they were.
Citing the ontology by anchor brought it into the section-framing guard's scope for the first time: a resource delivered one section at a time strands whatever sits above its first heading. The line above that heading says which files the ontology governs, which a reader who asked for one section already knows — it names the resource, its subject and its reader, and nothing in it binds the work that section describes. Recorded as orientation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A review-mode run raised a register of twenty-three defects and conventions (#446). #448 closed almost all of them, and left one open on purpose: two files each stated the rule against citing a Protocol phase by its number. This change settles which of them owns it.
What happens today
The ontology that defines what a
## Protocolis says the server assigns step numbers when it loads a technique, and then tells the author not to write "go to step 3" because composition and renumbering shift the numbers. The anti-pattern catalog carries the same prohibition as an entry, with its own account of why an ordinal drifts — that it survives insertion, deletion and reordering by addressing whichever phase now holds that index.Two files, one rule, two separate derivations of the same reasoning. Either can be edited without the other, which is the condition the one-authoritative-home principle exists to prevent, and an agent authoring a technique reads both.
The fix
The ontology keeps the fact, because the fact is what a Protocol is: the loader assigns the numbers, so a step number is a position rather than an address. That sentence is the whole rule, and the prohibition now follows from it rather than sitting beside it with a second justification.
The catalog entry keeps everything a catalog entry is for — how to detect a citation by ordinal, the four cases that must not be flagged, and the fix — and cites the ontology for the fact instead of re-deriving it. The entry's structural test is unchanged: insert one phase above the cited one, re-read the citing sentence, and flag it if it now names the wrong work.
Scope of change
Two files, four lines. No definition changes shape, no technique changes its contract, and no run behaves differently — this is which surface a reader finds the rule stated on.
A third file records a judgement the new link made necessary. A resource cited by anchor is delivered one section at a time, so whatever sits above its first heading reaches nobody who asks for a section, and the guard that checks this measures a resource only once something cites it that way. This is the first anchored citation of the ontology, so it enters that guard's scope here. The line above its first heading says which files the ontology governs — it names the resource, its subject and its reader, and binds none of the work the cited section describes — so it is classified as orientation in the corpus triage rather than moved.
What the rest of the register looks like now
Every other row was checked against the current definitions rather than taken from the merged pull request's description. All are closed: the values a worker receives (the initiative name, the chosen component, the component repository, the comprehension directory, the resource references), the batch bound the server now emits, the review-path gates, the findings report shape with its designator, severity, delivery-class and anchor contracts, the report-and-method split, the summary header and tables, the status a run emits between activities, and the blast-radius blind spot under macro expansion.
One row stays open and is deliberately not in this change. The designator column of a posted review still wraps mid-token. The fix originally proposed for it was tested against the rendered page, refuted three ways and reverted — the break is forced by column width, and nothing expressible in markdown reaches the layout. The remaining candidate is structural: delete the column and carry the designator as the opening token of the finding cell, which trades a scannable left edge for a cell wide enough not to break. That trade is a decision rather than a cleanup, and it stays on the issue until it is made.
Acceptance criteria
Non-goals
Closes nothing on its own; #446 can close once the designator-column decision is made.