86%

intel_repo: code-comment ingestion + comment-hygiene detectors

Goal

Ingest CODE comments as queryable graph nodes (linked to symbols/lines) in the intel_repo CPG producer, then build the comment-hygiene detectors that consume them — the ‘bring comments into the graph’ capability the mission calls for.

Implementation Sketch

CPG extractor emits CodeComment nodes; gds computes comment-quality properties; detectors query them; an inaccurate-comment narrowing query points the LLM. Schema/envelope bump paired with consumer pin.

Spec References

intel_repo/neo4j/cpg_extractor.py; gds_enrich; export_json SCHEMA_VERSION <-> importer EXPECTED_SCHEMA_VERSION; COMMENT_HYGIENE_DRIFT subcats; .claude/rules/impl-hygiene.md Comments section.

Work Items

  • CPG extractor: emit CodeComment nodes {text, line, file, kind: line|block|doc} with HAS_COMMENT/ON_SYMBOL edges to the owning Symbol/CfgBlock.
  • gds/enrichment: comment-quality properties (is_narration, is_removal_trail, is_ephemeral_ref, length_over_cap) computed cypher-side or in gds_enrich.
  • Comment-hygiene detectors (graph-native): COMMENT_HYGIENE_DRIFT:narration/length-cap/removal-trail/attribution/editorial-voice via CodeComment props.
  • Inaccurate-comment NARROWING query: comment whose tokens diverge from its symbol signature -> candidate for LLM judgment (the point-the-LLM half).
  • Schema/envelope contract: SCHEMA_VERSION bump paired across export_json <-> importer <-> consumer pin; graceful degradation when cpg_stale.
  • Tests + ori_arc: comment-hygiene findings emitted from the graph.

Items

  • Schema/staleness contract: bump cpg_extractor.py extractor_version for the new CodeComment node type; add the CodeComment id-unique constraint + file/fingerprint indexes to schema.cypher mirroring the CfgBlock template; round-trip cpg_extraction_fingerprint through import_code_graph.py so CodeComment nodes are cleaned/replaced on re-extraction; graceful degradation when cpg_stale (graph-down or stale CPG never halts -> degrade to the existing path). Coordinate the extractor_version bump with sibling s-5d7a6bbe (typed-dataflow), which extends the same extractor + cpg_stale contract.

Fresh intel (regenerated)

{ “schema_version”: 1, “target”: { “kind”: “plan-section”, “ref”: “graph-driven-hygiene/s-fba06229” }, “generated_at”: “2026-06-22T03:42:37.622974+00:00”, “graph_state”: { “head_sha”: “9e4174b6”, “last_code_import_at”: “2026-06-22T03:18:24.361Z”, “embedding_stale”: false, “insights_stale”: false, “cpg_stale”: false }, “surfaces”: {}, “summary”: “intel-package[plan-section:graph-driven-hygiene/s-fba06229] agent-authored dossier”, “degraded”: false, “dossier”: { “objective_symbols”: [], “tiers”: {}, “agent_authored”: true, “difficulty”: { “class”: “routine”, “research_online”: false, “research_mode”: “auto”, “signals”: [], “plan_dir”: “/home/eric/projects/ori_lang/plans/graph-driven-hygiene” } } }

(full dossier: comment-ingestion—s-fba06229.intel.json)