01 Infrastructure & Canonical Helper

01.0 Goal

One script, scripts/intel-query.sh, is the SSOT for all intelligence DB access from ori_lang. Every rule, skill, command, and hook that needs intelligence calls this script. No integration point ever checks Neo4j availability, activates the venv, or runs a Cypher query directly — that’s the helper’s job.

This follows the SSOT principle from .claude/rules/impl-hygiene.md: “every behavioral decision has exactly ONE file that defines it.”

Output contract (canonical — all references in this plan MUST match):

Default format: JSON (for machine consumption by skills and rules)
--human flag: raw text output for human-readable display — NOT JSON. Skills use --human when query results will be held in Claude’s conversation context (Tier 1+2 integrations per Sections 03-04). Interactive CLI use also passes --human.
On success: {"status":"ok","data":...} to stdout, exit 0
On unavailable: {"status":"unavailable","reason":"<reason>"} to stdout, exit 0
Diagnostic/debug messages: stderr only, never stdout

Ownership split (important distinction):

The shell script owns orchestration and graceful degradation — it sequences the availability checks (directory, venv, Docker, health-check) and returns structured unavailable JSON on any failure. Step 1 (directory check) is pure shell; steps 2-5 invoke Python for the neo4j import probe and health-check semantics.
Python (query_graph.py) owns health/status SEMANTICS — detailed graph queries, node counts, index verification, repo list, JSON formatting, and all query logic. The shell’s job is to orchestrate the check sequence and wrap failures; everything meaningful happens in Python.

These are distinct concerns. The shell answers “can I reach Neo4j?” The Python answers “what is the graph state?“

01.1 Canonical Helper Script

File: scripts/intel-query.sh

Contract:

Usage: scripts/intel-query.sh <command> [args...]
       scripts/intel-query.sh search "pattern matching exhaustiveness"
       scripts/intel-query.sh compare "type inference"
       scripts/intel-query.sh cypher "MATCH (i:Issue) RETURN count(i)"
       scripts/intel-query.sh status
       scripts/intel-query.sh search "type inference" --human

Exit codes:
  0 — always (graceful degradation)

Output (default JSON):
  On success: {"status":"ok","data":...} to stdout
  On unavailable: {"status":"unavailable","reason":"..."} to stdout
  Diagnostic messages to stderr only

  --human: raw text output (NOT JSON) — for conversation context and interactive display

Flags:
  --human   Switch to human-readable display format
  --timeout N  Override default 5s per-step timeout

Availability check sequence (all must pass, checked in order — cheapest first, each with 5s timeout):

../lang_intelligence/ directory exists (filesystem check, instant)
../lang_intelligence/.venv/bin/python -c "import neo4j" succeeds (venv has the package — must pass before we can use the driver)
docker inspect lang-intelligence --format '{{.State.Running}}' returns true (container running)
Neo4j Bolt protocol readiness + auth: ../lang_intelligence/.venv/bin/python ../lang_intelligence/neo4j/query_graph.py --json health-check — a lightweight command that verifies TCP, Bolt handshake, AND auth using the configured credentials (reads NEO4J_URI/NEO4J_USER/NEO4J_PASS env vars or defaults). Credentials stay in one place (Python), not duplicated inline in the shell script.
Full-text index verification: CALL db.indexes() YIELD name WHERE name = 'issue_text' RETURN count(*) > 0 — commands search, compare, fixed, pattern depend on this index from schema.cypher

If any check fails, output the unavailable JSON and exit 0. The caller never sees an error.

Implementation checklist:

01.2 Fix Existing query_graph.py Issues

Real issues found in ~/projects/lang_intelligence/neo4j/query_graph.py that must be fixed before any integration. Function names referenced below; use grep -n 'def func_name' neo4j/query_graph.py for current line numbers.

01.2a Error Handling & Robustness

Unhandled Neo4j exceptions — get_driver() is lazy: driver construction succeeds even when Neo4j is down; the real ServiceUnavailable exception fires at session.run() time inside each command function. Wrapping only get_driver() does nothing. Fix: wrap the command dispatch in main() in a centralized try/except (ServiceUnavailable, AuthError, Exception) that prints an actionable error message and exits non-zero. This catches all command-level failures in one place.
No try/finally on driver.close() — every command function (e.g., cmd_search, cmd_compare) calls driver.close() at the end, but if the session query raises an exception, driver.close() is skipped and the connection leaks. Use context manager (with get_driver() as driver:) or try/finally.
_parse_flags calls int(args[i+1]) on --limit and --depth values with no validation — non-numeric input raises an unhandled ValueError. Validators now raise ValueError, caught by main()’s centralized try/except. Also fix positional numeric args in cmd_related and cmd_fix_chain which do int(args[1]) — same pattern.
No connection timeout — GraphDatabase.driver() uses default timeout, which can hang indefinitely if the Bolt port is open but the server is wedged. Add connection_timeout=5 to the driver constructor.

01.2b Missing Functionality

Implement health-check command in query_graph.py — a lightweight probe that verifies TCP + Bolt handshake + auth using the configured credentials (env vars or defaults). Returns JSON {"status":"ok"} on success, {"status":"error","reason":"..."} on failure. Exit 0 always. This is called by intel-query.sh step 4 to validate connectivity without running a full query. Also verify that the full-text issue_text index exists (needed by search, compare, fixed, pattern).
cmd_label_graph was a TODO stub. Implement the label co-occurrence graph query or remove it from the usage docstring — a silently no-op command is a trap.
No --json output mode — all commands print human-readable text to stdout. Add --json flag that makes every command output structured JSON instead. This is required by intel-query.sh which needs machine-parseable results.
No graph-emptiness detection in cmd_stats — if the graph has zero Issue nodes (e.g., after a fresh schema.cypher without any data import), stats prints empty tables with no warning. Add a “graph is empty — run the fetch pipeline first” message.
Refactor cmd_compare and cmd_pattern to use _parse_flags for argument parsing — both used to do " ".join(args) which would include --json in the search terms. Using _parse_flags to strip global flags before joining ensures --json (and future flags) are intercepted.

01.2c Hardcoded Configuration

Credentials hardcoded: bolt://localhost:7687, neo4j, intelligence were inline constants. Read from environment variables (NEO4J_URI, NEO4J_USER, NEO4J_PASS) with the current values as defaults. This allows different environments (CI, remote, Docker Compose with different ports) without editing source.
Validate Python fixes: test query_graph.py --limit foo exits cleanly with error message (not traceback), test query_graph.py related rust notanumber exits cleanly, test query_graph.py --json stats returns valid JSON
Subsection close-out (01.2) — MANDATORY before starting 01.N:
- All tasks above are [x] and the subsection’s behavior is verified
- Update this subsection’s status in section frontmatter to complete
- Run /improve-tooling retrospectively on THIS subsection — Retrospective 01.2: no tooling gaps. Work was entirely Python changes in an external project (~/projects/lang_intelligence/). Ori compiler tooling (diagnostics, test harness, scripts) was not exercised. No improvements needed.
- Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files. Clean (2026-04-13).

01.R Third Party Review Findings

01.N Completion Checklist

Exit Criteria: scripts/intel-query.sh search "type inference" returns valid JSON with status:ok when Neo4j is running, and scripts/intel-query.sh search "type inference" returns {"status":"unavailable","reason":"..."} with exit 0 when Neo4j is stopped. All 6 test scenarios pass. query_graph.py health-check returns {"status":"ok"} when connected. query_graph.py --json stats returns structured JSON. timeout 150 ./test-all.sh green.