fix(work-package): close the #346 review-mode defects; cite resources at section grain

[m2ux]

Closes the 27 definition defects issue #346 registers from the review-mode run of work-package v3.36.0. The verdict that run produced was sound; every defect is in the reporting and bookkeeping layer around it.

Two things grew out of that work and are carried here rather than deferred, because both were found by auditing this change and both touch the same files:

• Canon — two design principles and five anti-patterns for the smells the audit passes kept finding with no entry to cite, plus a resource rename and two rule consolidations they identify.
• Section-grain citations — principle 32 makes a citation's grain a delivery decision, which is measurable, so the corpus was measured. Twenty-two techniques now cite the sections they read, taking 209,422 characters of resource body out of the bundles that carry them. The tail is registered as Cite resources at section grain: the pre-principle-32 corpus tail #358.

Definition changes only — the paired pointer bump, guard-triage prune, walk re-baseline and DI-33's engine half are in the main-repo PR.

Required set

ID	Change
DI-35 / DI-32	artifact_publish_ref is the engineering branch, never a commit sha. complete re-publishes the planning folder on that branch, so close-out, retrospective, session trace and follow-ups reach the tree a posted review already links. The format now states the ref split explicitly: engineering artifacts by branch, reviewed code by sha.
DI-31	Change-block and manual-diff citations are permanent blob URLs at the reviewed commit, built from a new reviewed_code_base_url pinned by review-diff. The old checkout-relative form died with the review worktree remove-worktree deletes at close-out.
DI-33	Cost travels on its own call. dispatch-activity gains account-every-dispatch: every dispatch's harness-reported usage is recorded as it completes, via record_usage, covering the first worker, each continue, each fresh worker after a timeout, each resume after a checkpoint yield and any out-of-band dispatch. render-token-usage reconciles the ledger against the run's actual dispatch count and, with any dispatch unaccounted, labels the figure a floor and states the unaccounted count beside it.
DI-34	Cost lives only in token-usage.md; session-trace.md reports mechanical execution and links it. The ownership claim sits in the manage-artifacts canonical-home map, so one wrong ledger yields one wrong artifact instead of two that disagree.
DI-23	The rendered Progress table drops the @ column. # is untouched — still the monotonic display index, still not a selection key.

Review-mode gating

• DI-8 — unsigned-commits-prompt and resign-unsigned-commits are gated is_review_mode != true. Both are author-side; the checkpoint was asking whether to force-push a rewrite of another organisation's branch.
• DI-18 / DI-21 — render-token-usage and create-complete-doc run on both paths. A review run has a verdict to close out and a cost to report.
• DI-19 — the retrospective's one-item-at-a-time interview is unrunnable on a depth-1 worker, so it is replaced by an item budget reviewed whole. The confirm gate recorded setVariable: undefined on its only reachable option, so it becomes an action: message per checkpoint-requires-decision.
• DI-20 — assumption_decisions, issue_request and comprehension_dir are declared as workflow variables, closing the three gaps in work-package scope.

Posted-comment format

review-mode was specifying table structure and nothing else, which is the root cause behind most of this group.

• DI-9 — Strategic Review gets a findings table on the shared format (prefix SR), and a skeleton placeholder.
• DI-10 — Reference, Don't Restate gains a declared budget per slot, review-summary measures against it and emits summary_budget_overruns, and the bind site carries a validate action. The rule is now checkable rather than aspirational.
• DI-11 — a prose register: plain language, one claim per sentence, one hedge, one symbol and one location.
• DI-13 / DI-14 / DI-16 — tables are # | @ | Finding | Severity. @ is a hyperlinked ASCII >, so filename link text stops setting the column to the width of the longest path. Disposition survives only in Prior Feedback Triage, at the far right.
• DI-15 — caveats are one line: claim plus a link to the report section holding its basis.
• DI-17 — What This Change Gets Right, between Strategic Review and Action Items.

Planning README

• DI-22 — 🟡 replaces ◐, so the status meaning "being worked on now" is as visible as its full-colour siblings.
• DI-24 / DI-25 / DI-26 — the Item cell is the row's only link slot, linked whenever the row's activity wrote or amended a file, carrying the human name alone; Description is plain text.
• DI-28 — status tracks the deliverable, not the producer: content that lands elsewhere is complete with a repointed link, never cancelled-with-a-link.
• DI-29 — a cancel write unlinks the seeded target that was never created.

Artifact routing and link integrity

• DI-27 — close-out reads both registers and links them; it no longer restates open work in its own table.
• DI-30 — new manage-artifacts::verify-artifact-links, bound as a close-out gate, resolving every planning-folder link at the publish ref rather than in the working tree. Three classes: missing relative target, citation into the review worktree, resource id emitted as a relative link.

On DI-23's anchor

The issue notes that sync-progress-status selected on the @ column, so the matching rule needed a new anchor first. Neither remaining column can be it — # is documented display-only and renumbers whenever the inventory changes — so the anchor moved off the rendered table into a row-ownership map: the seed profile's inventory keeps @ as seed data, create-readme consumes it and drops it when rendering, and sync-progress-status resolves artifact_prefix through it to the activity's Item labels. One declaration, serving readers and writers, absent from the reader-facing table.

planning-readme reorganisation

Touching this resource for DI-22 through DI-29 put six new facts into it, and that exposed a layout problem worth fixing in the same change rather than leaving for the next one: seven facts had more than one home, and the status model was spread across five sibling sections plus bullets inside Progress table, so a reader assembled it from six places.

Deduplicated:

Repetition	Was	Now
Status column section	Verbatim restatement of one line in Status vocabulary	Deleted; its one citer points at the vocabulary
seed exclusion vs path skip → cancelled/N/A	4 statements	1 seeding bullet, plus the vocabulary row's parenthetical
"status tracks the deliverable, not the producer"	3 statements	1, in Status vocabulary
unlink-on-cancel	2 full statements	1, in the transition policy
# is display-only	3 statements	2 — the definition and the selection prohibition are different claims
"do not invent alternate glyphs"	2	1
call-sites Writer: paragraph	Restated its own table row and the section intro	Keeps only the {mark_progress_na} rationale, the one fact in it that was not duplicated

Restructured so the file reads Template → rules for the sections it lays out → the status model → how writers address rows:

• ## Rules now covers only the Template's own sections. Row-ownership map is demoted to #### under Progress table, where it belongs.
• The five status sections become one ## Status parent with four children.
• ## Matching is promoted to a peer of those two.

Anchors survive: GitHub derives them from heading text, not level, so all 43 external citations still resolve. The exception is #status-column, whose single citer (sync-progress-status step 6) is updated.

Collapsing the three scattered link-reconciliation statements into one table also closed a gap — the "complete, deliverable already at the seeded target" case was not stated anywhere before.

Fidelity was checked by probing 31 distinct facts from the pre-reorg file; none is lost. 190 → 184 lines. The first pass came out net-zero on length because the dedup savings went straight back into new prose, so there is a second tightening pass on top.

Canon additions

The audit passes over this change kept finding smells the catalogue had no entry for, so they are entered here rather than rediscovered next time.

Two design principles:

• 31. Isolate Conditional Branches as Notes — within a Protocol step the unconditional instruction is the bullet and each when / if / otherwise branch is its own > note. A reader scanning the step sees the shape of the work without evaluating every clause to learn which parts apply. Structure comes first: a condition selecting a step, an activity or a path is a when, a condition or a declared decision, and the principle governs only what legitimately stays in prose.
• 32. Cite Resources at Section Grain — a citation is a delivery instruction. What it resolves to (path after resources/, .md stripped, #anchor kept) is the unit the server loads, so a citation names the narrowest section carrying what the prose needs. Grain is a property of the resource across the whole technique: every distinct citation is delivered, so a bare citation beside anchored ones ships the file and those sections. Principle 30 already carried a forward reference to "the section-or-whole economy" that nothing defined; 32 is its citation half.

Five anti-patterns:

ID	Catches
AP-131 resource-id-names-its-content	A resource id that reads as protocol or as a bare artifact name rather than saying what the file is — the rename below
AP-132 deployment-path-in-capability	A deployment path baked into a technique's Capability, coupling the abstract statement to one layout
AP-133 overlapping-rule-scopes	Two rules whose triggers intersect with differing consequences and no ordering — reconcile or consolidate
AP-134 whole-resource-for-one-section	A citation delivering a whole resource where the prose reads one section
AP-135 tool-contract-restated-in-protocol	Protocol spelling out a tool argument's shape, which the tool's own schema states

Four existing entries were extended: AP-46 on destination naming, AP-22 on same-block duplication and its bridge-phrase tell, AP-19 on instruction-shaped rules, and AP-59's Fix now cites principle 31.

Resource rename

complete-wp.md → complete-wp-guide.md (git-tracked rename, seven citation sites updated). The old name read as a protocol step, and the file is a template plus the rules for filling it — AP-131.

Section-grain citations

Twelve techniques cited a resource whole while also anchoring sections of it, so both the file and those sections shipped in the eager bundle. Each now cites what its prose consults, removing 60,092 characters of resource body from the bundles carrying them:

Technique	Now cites
create-readme	Template; step 3 cites Rules, the home of the fill rules it was reaching through the whole file
review-code	Review Criteria
review-test-suite	Review Criteria and Anti-Patterns, which its report template's detection summary needs
summarize-architecture	The artifact template, and Diagram Selection from step 1
retrospective	The Mechanical classes subsection
create-complete-doc · execute-sub-agent · capture-dimension	Template · Schema · Dimensions
respond-to-pr-review · persist-design-specification · analyze-source · create-completion-doc	Both templates · the two sections the artifact is made of · Template + Conventions · Template + Rules

Two sites are deliberately unchanged. review-summary's ten citations cover 86% of review-mode, and validate-specification needs checks, categorization and verdict — in both the sections total more than the file, so the whole-resource citation is the economical one and the residue is the bundler shipping a section body when its parent is already bundled. That is server work, not a definition change.

workflow-retrospective's Mechanical classes heading now names the resolved trace rather than the tool that resolves it, so the section can be cited without a bare tool name reaching the citing Protocol through the anchor slug.

Largest citation sites

The same measurement applied beyond the mixed sites, to the ten pairs where a whole-resource citation cost the most — 149,330 characters off the bundles that carry them:

Technique	Was delivering	Now cites
workflow-engine/TECHNIQUE.md	planning-readme (15,073) as an example of what a resource ref looks like	a code token — the example needed no body at all, and this base technique is bundled very widely
map-vulnerability-domains · score-severity	target-profile (22,668)	Vulnerability Domain Hints · Severity Calibration Benchmark
analyze-architecture · apply-checklist · map-vulnerability-domains · execute-ensemble-pass	audit-template-reference (9,441)	the §X.Y sections each one's identifiers resolve to — §3 for three, §2/§3/§5 for the ensemble pass
review-scope	architecture-review (8,816)	Architectural Significance and Decision-Making Discipline; the ADR template and writing style belong to the activity that writes ADRs
deep-dive	codebase-comprehension (12,291)	Artifact Template and Comprehension Techniques, both already named in its prose
readme-authoring · yaml-authoring	design-principles (15,025) for one principle each, cited as "§11" and "§17" — no resolvable target	the principle by anchor

Verdicts recorded rather than rewritten, per principle 32: audits enumerating every entry (audit-canon, audit-principles, audit-expressiveness), a construct inventory read for literacy, a TDD primer cited as background, and knowledge bases selected from rather than read at a point (probe-catalog, subsystem-map). Whole-resource delivery is correct for all of them.

The tail — roughly a hundred pairs under ~8,000 characters each — is registered as #358, along with the guard opportunity: AP-134's second tell (a bare citation in a technique that also anchors the same resource) needs no judgement and is checkable in scripts/.

Rule consolidation

• dispatch-activity's worker-bag-takes-precedence is absorbed into distrust-then-reconcile: one rule stating that critical routing state read from inspect_session is cross-checked against the worker's activity_complete envelope, that the envelope governs on disagreement because the worker holds ground truth from its own user interaction, and that the discrepancy is logged. Two rules over one invariant was AP-133.
• present-checkpoint-to-user's apply-effects-immediately becomes Protocol step 5. A rule saying do this now was a protocol phase wearing a rule's clothes, and the step numbering already carries the ordering the word "immediately" was doing.

Diagram accuracy

Checked every activity diagram against its YAML. One real defect and two gaps:

• activity 14 wired finalize-test-plan and ensure-docs behind the complexity gate rather than the review-mode gate that actually governs them.
• activity 01 omitted the review-mode fork entirely — the ambiguity checkpoint, the PR-reference checkpoint and its cancel path — plus github-issue-missing on the Jira path.
• activity 13 omitted the private-remote and push confirmations on the stealth path, and the PR-body verification loop with the body-non-conformant checkpoint that follows it. Its build-artifact nodes now read as the checkpoints they are.

Verification

• 17/17 guards pass (npx tsx scripts/check-all.ts --root <this tree>), corpus and repo scope.
• Walk snapshots pass; the path diff is carried in the main-repo PR and is exactly the DI-18/DI-19/DI-21/DI-30/DI-32 step changes.
• The workflow-canon skill's Draft and Audit paths were both run. The audit found four defects in this change's own text — procedure-in-io-contract on a create-complete-doc input, a rule over-reaching into artifacts it does not own, a rule restating its own protocol phase, and two blockquote notes missing their trailing spaces — all fixed before commit. The planning-readme reorganisation above is the no-duplicated-guidance / canonical-fact-home half of that same pass.

Not addressed

Merge order. DI-33's engine half rides in the paired main-repo PR #352: record_usage records one activity_usage history event per completed dispatch, keyed to the activity that ran, and next_activity no longer takes usage. The account-every-dispatch rule and the next_activity call signature here are the caller side of that tool. This PR merges first, to workflows; main keeps pinning the old corpus until #352 lands, so the rule and the tool it names become reachable together.

DI-20's wider class. 47 work-package orphan-input findings remain triaged as accepted debt; this PR closes the three the issue names as in-scope. Of the rest it names, discovered_path was already declared, initiative_name and force_rebuild are correct-by-design caller arguments on shared meta ops in other workflows, and identifying_context / target_content / output_path produce no finding.

Refs #346

🤖 Generated with Claude Code