Review-run defects: values a worker can trust, findings a reader can act on, and a status that says where the run stands

[m2ux]

Summary

A full work-package run in review mode surfaced a register of defects and conventions (#446, plus the ten follow-up comments on it). This change addresses every one of them that lands in the workflow definitions. Two rows from the register are out of scope here because their fix is not a definition change: the missing batch block, which is server behaviour, and the backfill of existing artifacts, which is host-repository work.

The work falls into three groups.

Values a worker can trust

Several values reached a worker with no producer, or named a thing other than the one they were used for.

A repository the request names now reaches every run. The step that extracts it only ran when the request stated resume intent, so on a fresh run nothing held the component under work. It runs on every path.

A GitHub call that names a working tree now addresses that tree's repository. The coordinate resolver preferred the session's repository binding whenever it was set — and it is always set. On a monorepo that binding names the superproject, so a component's issues, pull requests and reviews all addressed the host. A caller that names a checkout has said which repository the call is about, and that checkout's origin is now what the call resolves. The run that produced this register avoided the fault only because two workers noticed independently and passed the component repository literally to every call.

The component's working tree is a declared value. Three worktree operations each re-derived it from a different guess, and the operations that address the component's repository had no path to name. One value, produced once.

The component-selection gate records which component was chosen. Its only option carried "stop asking" and named no submodule, so the worker landed the path from its own ranking and a user who picked differently was silently overridden. The enumerated submodules are now offered one at a time and the accepted one lands in component_path. A monorepo that leaves the gate with nothing chosen fails there rather than proceeding against the host root.

The work carries one name. The slug that names the planning folder is the session's durable key, and the operation composing it declared an input no step supplied — so each worker invented the name, and a resume looked for a folder the first run never wrote. A new operation takes the name from the request's own words.

Comprehension artifacts land in the corpus. The directory variable defaulted to the empty string, so the artifact went to the session's planning folder, was read once and lost. All three writes in that activity now target the cumulative corpus.

A resource reference a client activity receives resolves. Meta techniques cited their own resources by a path carrying no workflow segment, so a client activity received refs like planning-readme#template that resolve nowhere. The citations carry the segment, and the emitted ref resolves for every consumer.

Gates that ask what the run can answer

On the review path nobody in the session fixes anything: no component file may be modified, and every finding travels to the pull-request author. The strategic-review gate nonetheless offered "Fix findings before proceeding", "Fix selected findings" and "Defer findings" — a choice between actions none of which that run can take.

The create path and the review path now carry their own findings gate. The create-path gate is unchanged. The review-path gate asks which findings the posted review carries to the author: raise all, raise selected, raise none, or hold.

Behind it, the review-fix cycle in post-implementation review had no mode gate at all, so an actionable finding would have edited and committed to the author's branch. It is gated out, which makes the definitions' own claim — no component file is modified — structural rather than stated. The routing flags are renamed to say what they mean on both paths: a finding reached a severity that warrants action, rather than an order to repair it.

The validation gate's message was a question implying the session owned the branch; it now states the choice, and its options name what each does.

Findings a reader can act on

Across three reports, fifteen findings deviated from the declared field list in all fifteen cases, one invented a field, one report used a designator prefix that appears nowhere in the definitions, nine findings carried no severity at all, eight carried values outside the declared scale, one finding was classified into no delivery class, and restructuring silently broke 23 links. The conformance pass ran over these artifacts and reported that they conformed — it verifies artifact-level properties and had no rule that could see any of it.

One shared layout, declared once. A new findings-report guide owns the shape every findings report follows: a finding is a heading, then one labelled paragraph per declared field, in the order that report declares. The code review, test-suite review and strategic review each declare only their own designator prefix and field list against it. Before this, one of them stated its findings as rows of four differently-shaped wide tables, some cells running to a paragraph against a two-word cell beside them.

A finding is a heading, because the summary's designator column links to it and a bold title is unlinkable. The label set is closed, so a field nobody declared is a visible breach rather than a judgement call. The site is carried by the inline link in the prose rather than by a separate location field, which would state it twice in one artifact.

Severity is checkable. The declared scale and the map from the classification scale onto it already existed; nothing checked that a rendered value came from the scale, or that it was the value the map produces from that finding's own classification. Both are now stated as constraints, along with the two rules the run needed: a qualifier is not part of a severity value, and a report that produces findings produces their severities.

Findings order by ID, and every finding the run produces appears in exactly one delivery class — compared as sets, since hand-written ranges are where a finding falls through.

Every code reference is an inline link whose visible text is the named entity, reading as part of the sentence that holds it. Four shapes fail it and each is repaired by moving the link onto the name. Applied by hand to one run's comprehension artifact this took 34 links to 179; without the generator change the next run undoes it.

Every anchor inside the planning folder resolves. A markdown anchor that does not resolve renders as a working link that goes nowhere.

The conformance pass enforces all of it, over the report and its method record alike.

Each review emits two artifacts. Measured over the run's three reports, between 48% and 65% of each was methodology — real work, but it answers how the review was conducted rather than what the author should do, and the part with an addressee was a minority of the document holding it. The findings and the outcome are the report; the baseline, the enumerations, the sweeps that came back clean and the coverage tables are a method record beside it. A finding's own evidence stays with the finding — the split is between method and conclusions, never between a conclusion and its support.

The posted summary's tables lose the columns that fought for width. The header field naming workflow activities is called Activities, not Reviewers, which in a pull request means the people whose approval the change waits on. The prior-feedback table drops its Reasoning column and constrains Disposition to its three values. The per-section report links are gone; the header lists them once.

The status a run emits

Between dispatches the run emitted multi-paragraph summaries restating what the artifact already recorded, and a paraphrase drifts from its artifact with no way for the reader to tell which is authoritative.

A status emission now carries three things: a link to the artifact the completed activity produced, a one-line summary, and the complete activity checklist as a task list whose item text is the Progress row's number and name, and is itself the link. Workflow mechanics stay out — dispatch, worker identities, batch room, usage recording, commit bookkeeping. What the user needs in order to decide stays in, at whatever length it takes.

It is emitted as the last phase of commit-and-persist, after that operation confirms the remote holds the commit, which makes publishing a link before its artifact structurally impossible. A gate is reached mid-activity, before that commit, so there the checklist is resolved against the remote first: present renders as a link, absent renders as plain text.

The shared shape sits on the workflow-engine contract rather than on either operation that spends it, since a rule naming what a sibling operation emits binds beyond the operation it sits on.

Blast radius that says what it measured

Two changed symbols returned no callers and a LOW rating against a freshly re-analysed index. The graph holds no edge because the callers' bodies are macro-generated, and type-level references are not edges at all — so re-analysing changes nothing. In a Substrate codebase that removes most of the interesting edges, and the standing guidance read as though staleness were the only failure mode. The blind spot is recorded where the GitNexus guidance lives, and a blast radius now says whether it rests on graph edges or on a hand-derived caller set.

The bootstrap text

Carried in alongside the register, because it is the same fault on the surface that can least afford it. This text is read by an agent holding a git checkout and a tool surface and nothing else — that is what a bootstrap is for. It nonetheless explained itself in the vocabulary of the framework it had not yet delivered: activities and gates, the meta session and the client session it dispatches, planning folders, the operations bundle, drift detection, delivery topology, and a character budget the server measures over everything arriving before the first decision.

None of it is executable from that position, and some of it manufactured the very impulse it existed to check — a line forbidding a schema fetch was the only mention of a schema in the file, so a reader with no reason to want one came away holding a rule about it.

The file is now the three steps and the two rules that bind before the bundle is read. It went from 67 lines to 42, and every sentence left is one the reader can act on with what it has.

Conduct rules

Swept for the same fault once the bootstrap text was clean. Its reader does hold the workflow model, so the test is not what it knows but whether reading a sentence changes what it does. Four families each stated one invariant several times, and 23 rules become 13.

Family	Was	Now
file-sensitivity-*	3 entries: one threshold in three verbs over three file classes	1
communication-*	4 entries: register and its negation, merit and its negation	1
attribution-prohibition-*	3 entries: one invariant over decisions, comments, docs	1
checkpoint-discipline-*	4 entries, so every agent read two prohibitions aimed at another actor	1

The checkpoint collapse is the one that changes what an agent reads: resolution is the meta-orchestrator's, a worker pauses at the gate, an orchestrator passes the yield up — each role now finds its own clause instead of three vantage points on one fact. The fourth entry only cited present-before-any-resolution, which states it, and no-option-hallucination covers the fabricated-option_id half; it is deleted. The list of sibling delivery rules trailing operational-discipline-resources-via-tool goes too — the reader holds them, and the list goes stale as soon as a fourth is added.

workflow-canonical stated its read-once instruction in both its description and its opening line; the body copy is gone. It is otherwise sound — an ontology whose job is to define the model may teach vocabulary.

One distinction was deliberately lost. The three file-sensitivity entries read without explicit user direction (core configuration), unless specifically requested (build scripts) and request approval before (CI/CD and container files). Read as one threshold in three phrasings, collapsed to the strongest. If build scripts were meant to sit lower than the other two, that entry splits back out.

One finding left open. workflow-canonical carries an authoring standard — no absolute intra-protocol step-number references — which the anti-pattern catalog owns as phase-cited-by-ordinal. The audiences differ (runtime resource versus design-time canon), so it is not straightforwardly dual-homed, but an agent authoring a technique reads both. Which surface owns it is a decision rather than a cleanup.

What the audit of this change found

The canon was walked over the branch itself, twice. Nine defects in what this change ships, all fixed here.

Entry	Where	What
apply-omits-declared-input	prepare-workflow-branch	Composed create-worktree with two inputs it no longer declares and passed nothing for the one it now requires. The compose is Protocol prose rather than an activity bind, so the binding guard cannot see it — and the file sits in a workflow this change never opened.
checkpoint-requires-decision	findings-delivery	An option to hold, where the review-mode transition routes to submit-for-review whatever is chosen and its effect matched another option's. Holding is already the user's at review-summary-approval.
no-technique-resource-dual-home	findings guide ∥ conformance pass	Both carried the same detect criteria. The guide owns them; the pass names which rule a breach records against.
no-contradictory-rules	findings guide ∥ review mode	The guide required every report severity to be a render-scale member, while the map keeps Informational out of the summary tables and in the report, where it still needs a value.
canonical-fact-home	report guides ∥ review mode	Each designator prefix was declared twice — which is the disagreement the prefix rule exists to prevent. Declared once now, by the summary category that indexes the report.
canonical-fact-home	conformance pass ∥ link pass	Anchor resolution sat apart from the other three unresolved-link classes. One pass answers whether a link resolves.
duplicate-shared-capability	authoring ∥ design	Two copies of the workflows-library path derivation, which this change had widened in both. Hoisted to meta; the union keeps what each copy held alone.
no-rationale-in-description	initiative-name rule	Carried its own justification.
avoidance-voice-in-definitions	strategic-review field list	Explained itself by comparison with its sibling reports.

A sentence-level duplication scan across every touched file went from 16 cross-file repeats to 13. The remainder are legitimate on the catalog's own carve-outs: a worker-directed rule repeated across techniques is correct for reach, citations of one home are pointers rather than second homes, and per-workflow variable declarations are how the variable model works.

The README seed's Progress inventory runs 1 to 33 contiguously — new rows take their place in the sequence rather than a letter suffix — and the code review's method record takes the prefix of the activity that actually writes it.

Inherited inputs, across the corpus

The catalog gained inherited-input-re-declared for a defect this change introduced in three places, and the sweep that followed found 139 more: leaf operations declaring an input a container contract already merges into them.

The loader composes a workflow-root TECHNIQUE.md and any group TECHNIQUE.md into every descendant, so an operation reaches those inputs without declaring them. A leaf that declares one again adds no bind point — it adds a second description of one slot, and the two get edited apart. Most had narrowed the wording to the operation they sat on, so a caller binding the op read the ancestor's contract while a reader of the file took the leaf's, with nothing marking which governed.

139 entries deleted from 88 operations in 15 groups. Protocols are untouched; they reference the same designators and the merge supplies them. The heaviest single group is work-package/techniques/manage-git, where target_path was declared on 7 operations and branch_name on 6, all already on the workflow root.

20 entries stay, each changing the bind contract rather than restating it — a differing #### default, or an optionality the operation genuinely needs. That is what a leaf declaration is for, and it is the carve-out the entry names.

On the count. A script resolves each operation's ancestors, drops the redundant entries, skips the overrides, and re-parses every written file to confirm the entry is gone before counting it; its file count is cross-checked against git status, and both report 88. That cross-check exists because the first version lacked it — a regex consumed a newline, every replacement silently missed, and the run reported 139 deletions it had not made. The number here comes from what changed on disk.

Not changed

The designator-wrap fix proposed in one comment was withdrawn in a later one: a non-breaking hyphen, dropping the hyphen, and freeing width were each tried against the rendered page and none worked, because the break is forced by column width rather than taken at a break opportunity. Nothing in the definitions ever prescribed it, so nothing needed reverting. The remaining candidate — dropping the # column and carrying the designator as the opening token of the Finding cell — trades one readability property for another and is left for a deliberate decision.

Companion change in the host repository

The binding-fidelity guard now reports one stale triage entry: the orphan-input finding for version-control::initialize-folder no longer occurs, because this change gives that input a producer. Deleting the entry from scripts/binding-fidelity-triage.json is a host-repository edit and lands separately. Every other corpus guard passes.

Closes #446

[m2ux]

Companion host-repo change: #449 (draft) deletes the now-stale binding-fidelity triage entry for version-control::initialize-folder, whose initiative_name input gains a producer here.

It must land with the submodule pointer bump that carries this PR onto main, not before. Verified both ways in a provisioned worktree: with the pointer where main has it today the deletion leaves the finding untriaged and check:all fails; with the pointer at this branch head all 24 guards pass.