100%

Hygiene query primitives + reviewer pre-pass

Goal

Expose hygiene-oriented query primitives and a phase-2.5-graph-recon pre-pass that seeds /impl-hygiene-review’s candidate lists.

Implementation Sketch

Wire query_graph.py subcommands for the hygiene primitives, hardening the minimal proof-of-pipe slice walking-skeleton (s-9ba53a79, completed) landed via w-f99e47f3 (a minimal god-functions primitive + recon consumer proving the end-to-end pipe). Production wiring is grouped by primitive-readiness tier:

  • Current-graph-ready (ship first) — god-functions, scattered-emits, hub-rank run directly against the de-noised CALLS graph from section 01; no GDS dependency. god-functions extends the walking-skeleton proof slice to production coverage.
  • GDS-gated (unblocked by gds-activation, s-4e62453e) — dead-code + layering-check WRAP the GDS properties gds-activation computes and materializes on :Symbol (WCC / Bridges / SCC signals). They READ those materialized properties; they do NOT recompute them from section 01’s raw de-noised CALLS graph. The exact :Symbol property keys these wrappers read are is_dead_code_candidate, is_layering_violation, blast_radius, scattered_knowledge, and phase_order_violation (the generic dead_code key is unpopulated in the live graph and MUST NOT be relied on). Each wrapper returns the violating dependency paths / cycles, not just a boolean, so /impl-hygiene-review gets actionable context.
  • HAS_VARIANT-gated (relocated) — enum-variants requires a new HAS_VARIANT extraction edge (sum_type -> variant), an extraction-layer prerequisite that does not yet exist and is out of this section’s wrap-scope. Its work_item (w-d20d2c41) is relocated forward to scip-from-oric (s-61848b41) per INV-20; not part of this section’s close gate.

A phase-2.5-graph-recon pre-pass runs the ready primitives (batched into a single macro command to avoid per-call Neo4j connection overhead) and feeds candidates into /impl-hygiene-review Phase 2/3. Per the forward-deliverable handoff from walking-skeleton w-f99e47f3, the FULL recon consumer routes through scripts/impl_hygiene_review_runtime/ (dispatch / state / prompts helpers + next_action.schema.json + pytest) per the recon.py docstring and script-first.md — the skill body owns only decision-handoff text + structured next_action consumption.

Work Items

  • Wire god-functions, scattered-emits, hub-rank primitives (work on the current graph). Harden the minimal god-functions proof slice landed by walking-skeleton w-f99e47f3 to production coverage; scattered-emits and hub-rank are new.
  • Wire co-change (Commit/TOUCHED) and blast-radius primitives with documented corpus/resolution caveats.
  • Wire dead-code and layering-check primitives that read the GDS properties materialized on :Symbol by gds-activation (s-4e62453e) — specifically the is_dead_code_candidate, is_layering_violation, blast_radius, scattered_knowledge, and phase_order_violation keys (NOT the unpopulated dead_code key). Unblocked by that section’s GDS computation, NOT by section 01’s raw de-noised CALLS alone. Return the violating dependency paths / cycles for actionable context. (The cross-section dependency on gds-activation is declared at section level — s-9fb83bc7 hint_needs: ; work-item hint_needs carry only w- predecessors, so this item’s is empty by design.)
  • Wire a phase-2.5-graph-recon pre-pass feeding /impl-hygiene-review Phase 2/3 candidate lists. Inherits the FULL recon consumer deferred by walking-skeleton w-f99e47f3: route through scripts/impl_hygiene_review_runtime/ (dispatch / state / prompts + next_action.schema.json + pytest) per script-first.md, matching the recon.py docstring. Batch the primitive queries into one macro command to avoid per-call connection overhead.

Test Coverage

The existing success criterion sc-8f4d933e is a shell-probe + presence check (intel-query.sh god-functions exits 0 and the /impl-hygiene-review recon pre-pass is present) that walking-skeleton itself rules insufficient — shell probes alone do not pin regressions and cannot verify the five primitives are correctly wired against the live graph. Every completed sibling (walking-skeleton, calls-resolution-precision, gds-activation) pins its deliverable test-first with pytest; this section matches that bar.

Pin the deliverable with pytest against the live graph, mirroring gds-activation’s sc-89902b3f (pytest + live-graph probe):

  • Primitive pytests (intel_repo/tests/test_query_graph_hygiene.py): one test per in-scope primitive (god-functions, scattered-emits, hub-rank, co-change, blast-radius, dead-code, layering-check — every primitive across w-eb0bc6c5 / w-01bd8837 / w-ae23d73a) asserting the subcommand returns the documented result shape against a seeded live-graph fixture — not merely a zero exit code. (enum-variants is relocated to scip-from-oric s-61848b41 and tested there.) dead-code and layering-check tests assert the returned violating paths / cycles, and that the primitive reads the is_dead_code_candidate / is_layering_violation / blast_radius / scattered_knowledge / phase_order_violation keys (a primitive reading the unpopulated dead_code key returns empty and the test fails).
  • Recon pre-pass pytests (scripts/impl_hygiene_review_runtime/tests/): assert the dispatch / state / prompts helpers produce a next_action validating against next_action.schema.json, and that the batched recon macro command seeds the /impl-hygiene-review Phase 2/3 candidate lists.

Route-substrate (script-only — surfaced as a note in the editor handoff): append a pytest-pinned success_criterion to this section mirroring sc-89902b3f (probe_ref = the pytest module above, expected = pass) via the write API; sc-8f4d933e is retained as the shell smoke probe but is not the close gate.

References

intel_repo/neo4j/query_graph.py; intel_repo/tests/test_query_graph_hygiene.py; scripts/intel-query.sh; scripts/impl_hygiene_review_runtime/ (recon.py + tests); .claude/skills/query-intel/SKILL.md; plans/completed/intel-graph-evolution/00-overview.md §07; plans/completed/intel-graph-precision walking-skeleton (s-9ba53a79) w-f99e47f3; gds-activation (s-4e62453e) sc-89902b3f.