New command group: `hadron coding` — lint the preflight router and the review checklist tree (`coding review lint`, `coding preflight lint`)

[shadowbrush]

Why

The review:* checklist trees and the preflight routers are executable infrastructure, not prose. tasks:review-changes triages checks by reading each one's Applies when … edge label back to the review parent; preflight routes symptom → finding via its outgoing edges. When one of those edges is malformed, the check or route is silently skipped. The node still exists, still looks maintained, and never fires again.

There is currently no way to detect that except by hand — which is how it went unnoticed. A manual audit of two memories this week found:

hadronmemory.com::hadron-portal — 7 of 24 checks had an edge label carrying no condition at all (bare applies-when, and one truncated Applies when with nothing after it). Every one was reachable only by opening the node, so a reviewer scanning the parent's Referenced-by list had nothing to match a diff against.

micromentor.org::mmdata — ~45 checks were fine, but 4 were broken in three distinct ways:

• 2 labelled child-of instead of a trigger (posthog-backend-vs-app-event-routing, role-vs-group-ident-vocabulary)
• 1 whose label was a raw derived edge loc, review:input-type-graphql-type:rel:review — with 4 more :rel:-shaped labels in the same branch, suggesting one bad batch
• 1 (format-sources) triggered on "Applies when Dart sources change" while living in the TypeScript backend memory — it can never match a diff in the repo whose memory it's in

(Filed as micromentor-team/mmdata#1599.)

These are all mechanically detectable. That's the ask.

Proposed surface

A new top-level group alongside the existing task / node / edge / memory groups:

hadron coding review lint      [-m <memory>] [--json] [--fix]
hadron coding preflight lint   [-m <memory>] [--json]

coding as the parent because these lint the coding-workflow graph (review gates, preflight routing, coding-guidelines cross-links) rather than arbitrary nodes — leaving room for coding review ls, coding review add (the tasks:add-review-node procedure), coding preflight ls, etc.

coding review lint

For every node under the review parent in the target memory, check:

Check	Rationale
Has an edge to the review parent at all	Missing ⇒ the check is invisible to tasks:review-changes. The highest-severity finding.
Edge label is a condition — starts Applies when, more than the bare stem	Catches child-of, applies-when, related, and the truncated Applies when.
Label isn't a loc — reject anything matching the <loc>:rel:<loc> shape	Catches the leaked-identity batch above.
Label isn't a near-duplicate of another check's	Two checks with the same trigger usually means one was cloned and not re-pointed.
Description carries the condition too	hadron_find_nodes / list output surfaces the description, so a description without a trigger is a second blind spot (use-scoped-message-helpers had exactly this).
Trigger doesn't name a foreign toolchain	Heuristic, warn-only: flag a Dart/Flutter trigger in a TS memory and vice-versa. Would have caught the misfiled format-sources.
seq is unique among siblings	Duplicate seq makes ordering non-deterministic.

coding preflight lint

For the preflight node's outgoing routes:

• every target resolves (no route to a deleted/superseded node — CLAUDE.md's own words: "stale routing is worse than missing routing")
• labels are action-phrased (to do X …), matching preflight's convention
• no route points at a node that has since been retired/tombstoned
• flag routes to nodes that moved memory (the portal findings migrating out of ::dev is exactly this churn)

Flags

• --json for CI consumption — this is the shape that lets a repo gate its own memory hygiene in a workflow.
• --fix on coding review lint for the mechanical subset only: promote the node's description sentence into the edge label when the description carries a trigger and the label doesn't. That covers most of the portal's 7. Everything else (a child-of on a node whose description has no condition either) needs a human and should just be reported.
• Non-zero exit when any error-severity finding is present; warnings alone exit 0.

⚠️ Implementation hazard: edges

Changing an edge label is currently dangerous. MCP exposes only hadron_create_edge — there is no update or delete — so the only route is hadron_update_node(edges:), which replaces the node's entire outgoing edge set. A naive --fix that rewrites one label will silently destroy the node's documented-by / relates-to edges. Four of the seven portal nodes had exactly those siblings.

The CLI talks to GraphQL directly, where updateEdge(edgeRef:) and deleteEdge(edgeRef:) do exist — so --fix should use updateEdge and must never go through a whole-node write. Tracked upstream as hadron-memory/hadron-server#835.

Prior art in this repo

hadron spec lint already exists for the spec corpus (per the add-spec skill). This is the same idea for the coding-workflow graph, and should match its output shape and exit-code conventions.

[shadowbrush]

Looked into this against the live memories and the current CLI/schema. The feature is worth building and mostly well-specified, but two of the proposed checks need respecifying first, and one piece of motivating evidence no longer reproduces. Details below, roughly in order of how much they change the design.

1. The implementation hazard doesn't apply to the CLI — it's already solved here

The MCP-side problem is real, but this repo isn't exposed to it. hadron edge update already exists (internal/cmd/edge/update.go, wired at edge.go:54) and is backed by the UpdateEdge mutation in nodes.graphql:507, where every optional variable carries # @genqlient(omitempty: true):

hadron edge update <edge-id> --name "Applies when …"

That is exactly the surgical single-edge relabel --fix needs — one edge, one field, no whole-node write, sibling documented-by / relates-to edges untouched. Both updateEdge(edgeRef:) and deleteEdge(edgeRef:) are present in the committed schema snapshot (schema/schema.graphql:3311 and :2645).

So hadron-memory/hadron-server#835 is not a blocker for --fix. The ⚠️ section should be rewritten as "MCP callers must not attempt this; the CLI has a safe path" rather than as a constraint on this work.

2. hadronmemory.com::hadron-portal is clean now — the 7/24 finding doesn't reproduce

hadronmemory.com::hadron-portal: 25 incoming checks, 0 suspect

All 25 inbound edges on the review parent start with Applies when and carry a real condition. No bare applies-when, no truncated stem. Either those 7 were fixed between the audit and now, or the audit covered a different set.

Worth reconfirming before sizing this, because the portal case is half the stated motivation — and if it was fixed by hand, that's also the evidence that hand-fixing is tractable at this scale.

3. micromentor.org::mmdata reproduces exactly as described — all 4 are real

Confirmed, and my independent pass agrees with the issue's count:

• review:posthog-backend-vs-app-event-routing → label child-of ✔
• review:role-vs-group-ident-vocabulary → label child-of ✔
• review:input-type-graphql-type → label empty ✔ (but see §5 — not for the stated reason)
• review:format-sources → Applies when Dart sources change, in the TypeScript backend memory ✔

4. The biggest problem: "every node under the review parent" has a >50% false-positive rate

I implemented the issue's own rules as specified and ran them. 9 findings, of which 4 are real and 5 are false positives:

Flagged node	Label	Real defect?
review:posthog-backend-vs-app-event-routing	child-of	✅ yes
review:role-vs-group-ident-vocabulary	child-of	✅ yes
review:input-type-graphql-type	(empty)	✅ yes
preflight	to review your code before opening a PR	❌ the router itself
review:backlog	register of candidate checks for (meta — NOT an applies-when checklist	❌ says so in its own label
tasks:review-changes	related	❌ the consuming task
tasks:build-review-coverage	mirrors	❌ a task
tasks:update-review-parent-node	maintains	❌ a task
patterns:function-signatures	enforces	❌ a pattern node

A linter that cries wolf on 5 of 9 won't get adopted, and this is structural rather than a tuning problem: the review parent legitimately has non-checklist neighbours — the router, the tasks that consume the tree, the meta backlog, pattern nodes.

The spec needs a membership rule for "what is a checklist item," and it doesn't have one. Note that the obvious cheap rule doesn't work: review:backlog sits under the review: loc prefix, so prefix-matching alone still false-positives. Candidates worth deciding between: nodeType, a dedicated tag, an explicit meta opt-out marker, or edge direction/kind. This is the one open question I'd want settled before any code.

5. "Label isn't a loc" is checking the wrong field

The string review:input-type-graphql-type:rel:review is that edge's loc, not its name. The name is empty:

{
  "name": "",
  "loc": "review:input-type-graphql-type:rel:review",
  "otherNodeLoc": "review:input-type-graphql-type"
}

And edge locs are auto-derived by slugifying the name — verified on the healthy ones:

name='Applies when adding or modifying a GraphQL resolver…'
 loc=review:thin-resolver-field:Applies-when-adding-or-modifying-a-GraphQL-resolver-f

So <source>:rel:<target> is simply the derived-loc fallback when the name is empty — a symptom of the empty label, not an independent defect class. There is also exactly 1 such edge in the branch, not "4 more :rel:-shaped labels", so the "one bad batch" read doesn't hold either.

Recommend collapsing that row into "label is empty or missing" (which is what actually went wrong) and treating a :rel: loc as corroborating signal in the message rather than its own rule.

6. preflight lint will surface far more than the issue anticipates

micromentor.org::mmdata preflight: 71 outgoing routes
  24 not action-phrased — labelled generic `routes-to`

A third of the routes fail the proposed "labels are action-phrased (to do X …)" check on day one. That's a legitimate finding, but decide the severity deliberately — as an error it makes the command red until someone relabels 24 edges; as a warning it exits 0 and matches how spec lint treats convention violations.

7. Repo constraints for whoever picks this up

• TestAgenticUsageDocumentsEveryCommand (internal/cmd/agentic_completeness_test.go) fails the build if a new leaf command isn't on its group's surface line in the embedded agentic-usage.md. A new coding group must update that doc in the same PR.
• Match spec lint's exit code, which is 5, not 1. It uses exitcode.Silent(exitcode.Conflict) (lint.go:199) when any error-severity finding is present. The issue says "non-zero"; the existing convention is more specific.
• Paginate. Per CLAUDE.md and spec lint --all / register / describe silently truncate on corpora >100 nodes #23 an unbounded nodes query silently returns one page, so a whole-memory sweep needs scanAllNodes/paginateNodes, and the list-vs-read visibility gap means unreadable ids must be surfaced as unavailable, not dropped.
• spec lint's lintFindingDTO (citation / rule / severity / message) is the shape to mirror.

Suggested amendments

1. Rewrite the ⚠️ hazard section — the CLI path is safe today; #835 is not a dependency.
2. Add a membership rule for checklist items (§4). Blocking.
3. Replace "label isn't a loc" with "label is empty/missing" (§5).
4. Fix the severity of preflight's action-phrasing check (§6).
5. Reconfirm the portal findings (§2).

Happy to write this up as a docs/plans/ design doc with recommended answers to 2–4 if that's useful.