0%

Section 05: Intel Graph Ingestion

Goal: The intel graph’s :SpecClause nodes and Plan/Bug<->SpecClause edges are ingested directly from the JSON corpus, replacing prose-token-scrape as the PRIMARY mechanism (prose-scrape remains a fallback).

Success Criteria:

  • JSON-driven ingestion MERGEs into the SAME 822 existing :SpecClause nodes via the clause_id key (bare dotted-numeric, per Section 02’s pinned invariant) — zero duplicate nodes created
  • New structured Plan/Bug<->SpecClause edges exist, backed by Section 06’s additive spec_clause_refs[] schema field
  • New /query-intel presets exist (e.g. spec-clause <id>, clause-refs <plan-or-bug>) and return correct results against a known sample

Context: Scope is DELIBERATELY narrower than originally drafted: this plan’s own Step 8B /tp-help round corrected an initial mistaken premise (a wrong-node-label query had suggested the code-to-spec REALIZES_CLAUSE mechanism was dead at 0 edges; the correct query — MATCH (s:Symbol)-[r:REALIZES_CLAUSE]->(sc:SpecClause) — shows 99 live edges from // Spec: Clause N.M source-comment scraping). REALIZES_CLAUSE is therefore explicitly OUT OF SCOPE here: it is a live, working, DIFFERENT mechanism (code-to-spec traceability, not clause-to-plan/clause-to-bug linking) and this section does not touch it.

Reference implementations:

  • intel_repo intel_repo/neo4j/import_code_graph.py upsert_file_spec_clauses: the exact MERGE-key pattern (clause_id alone, globally unique) this section’s ingestion must match

Depends on: Section 03 (JSON corpus exists); Section 06 (schema field, for the structured-edges subsection — may proceed with node-ingestion first if 06 lags).

Intelligence Reconnaissance

Queries run 2026-07-09:

  • scripts/intel-query.sh cypher 'MATCH (s:Symbol)-[r:REALIZES_CLAUSE]->(sc:SpecClause) RETURN count(r)' -> 99 (corrected verification; REALIZES_CLAUSE is live, out of scope)
  • scripts/intel-query.sh cypher 'MATCH (cr:CodeReference)-[:RESOLVES_TO]->(s:SpecClause) RETURN count(cr)' -> 1414 (the live prose-scrape mechanism this section’s structured edges supplement, not replace outright)

Results summary [ori]: 822 SpecClause nodes + 1414 prose-scrape edges are the pre-existing baseline this section’s ingestion must MERGE into cleanly, never duplicate.

05.1 JSON-Driven SpecClause Ingestion

File(s): intel_repo/neo4j/import_spec_corpus.py (new)

  • Implement ingestion reading the JSON corpus directly, MERGEing :SpecClause nodes on clause_id with richer properties: full title, normative/informative flag, heading_depth, and source: "json-corpus" (the exact property name/value Section 08’s north-star gate query filters on)

  • Subsection close-out (05.1)

    • Post-ingestion node count unchanged at 822 (MERGE, not duplicate-create) verified via scripts/intel-query.sh cypher 'MATCH (c:SpecClause) RETURN count(c)'

05.2 Structured Plan/Bug Edges

  • Extend ingestion to create structured Plan/Bug<->SpecClause edges from the Section 06 spec_clause_refs[] field (additive to, not replacing, the existing 1414 prose-scrape RESOLVES_TO edges)

  • Subsection close-out (05.2)

    • Structured edges created for every plan/bug carrying the new field; prose-scrape edges untouched

05.3 Cross-Reference Edges + Query Presets

File(s): .claude/skills/query-intel/ (new presets)

  • Add clause-to-clause cross-reference edges from each Clause’s CrossRefCallout blocks, and clause-to-grammar-production edges from GrammarProduction.cross_refs (populated by Section 03.2 from the SAME CrossRefCallout{kind: grammar} blocks matched by section_grouping — this section consumes that field, it does not re-derive cross-references from grammar.ebnf text independently)

  • Add /query-intel presets: spec-clause <id>, clause-refs <plan-or-bug>

  • Subsection close-out (05.3)

    • Presets return correct results against a known sample (e.g. a clause with a known existing cross-reference)

05.R Third Party Review Findings

  • None. (See Context: the REALIZES_CLAUSE scope correction from Step 8B round 2.)

05.N Completion Checklist

  • All subsections (05.1-05.3) [x], status complete
  • SpecClause node count unchanged (822) post-ingestion
  • New /query-intel presets tested
  • /tpr-review passed
  • /impl-hygiene-review passed

Exit Criteria: JSON-driven :SpecClause ingestion MERGEs cleanly into the existing graph; structured Plan/Bug edges exist; new query presets work.