docs(04): create gap closure plan for CLI query interface

Phase 04-04: Expose orphaned getDependents() function - Add handleQuery() routing for stdin query actions - Enable "what uses this file?" queries via CLI - Closes verification gap for INTEL-05 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 10:09:31 -06:00
parent 28c4c19112
commit 04d296471d
2 changed files with 262 additions and 9 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -27,16 +27,18 @@
 **Goal:** Transform syntax-only indexing into semantic understanding with graph-based relationships

 **Depends on:** Phase 3
-**Plans:** 3 plans
+**Plans:** 4 plans (3 core + 1 gap closure)

 Plans:
- [ ] 04-01-PLAN.md — SQLite graph layer with sql.js (Wave 1)
- [ ] 04-02-PLAN.md — Graph-backed rich summary generation (Wave 2)
- [ ] 04-03-PLAN.md — Semantic entity generation via Claude API (Wave 2)
+- [x] 04-01-PLAN.md — SQLite graph layer with sql.js (Wave 1)
+- [x] 04-02-PLAN.md — Graph-backed rich summary generation (Wave 2)
+- [x] 04-03-PLAN.md — Semantic entity generation via Claude API (Wave 2)
+- [ ] 04-04-PLAN.md — CLI query interface for getDependents (Gap closure)

 **Wave Structure:**
 - Wave 1: 04-01 (SQLite foundation)
 - Wave 2: 04-02, 04-03 (parallel - both depend only on 04-01)
+- Gap closure: 04-04 (expose orphaned getDependents function)

 **Why this phase:**
 - Current system provides "2-3 ls commands worth of information" (Claude's own assessment)
@@ -48,6 +50,7 @@ Plans:
 - Entity-based semantic documentation (Claude writes understanding, not just syntax)
 - Semantic `/gsd:analyze-codebase` that creates initial entities
 - Rich summary generation from accumulated semantic knowledge
+- CLI query interface for "what uses this file?" queries

 **Requirements:**
 - INTEL-04: Entity files capture semantic understanding (purpose, what exports do)
@@ -70,11 +73,11 @@ Plans:
 | INTEL-01 | Phase 1 | ✓ Complete |
 | INTEL-02 | Phase 2 | ✓ Complete |
 | INTEL-03 | Phase 3 | ✓ Complete |
-| INTEL-04 | Phase 4 | Pending |
-| INTEL-05 | Phase 4 | Pending |
-| INTEL-06 | Phase 4 | Pending |
-| INTEL-07 | Phase 4 | Pending |
+| INTEL-04 | Phase 4 | ✓ Complete (04-03) |
+| INTEL-05 | Phase 4 | Gap closure (04-04) |
+| INTEL-06 | Phase 4 | ✓ Complete (04-03) |
+| INTEL-07 | Phase 4 | ✓ Complete (04-02) |

 ---
 *Created: 2026-01-19*
-*Updated: 2026-01-20 — Phase 4 planned (3 plans in 2 waves)*
+*Updated: 2026-01-20 — Added 04-04 gap closure plan for CLI query interface*
--- a/.planning/phases/04-semantic-intelligence/04-04-PLAN.md
+++ b/.planning/phases/04-semantic-intelligence/04-04-PLAN.md
@@ -0,0 +1,250 @@
+---
+phase: 04-semantic-intelligence
+plan: 04
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - hooks/gsd-intel-index.js
+autonomous: true
+gap_closure: true
+
+must_haves:
+  truths:
+    - "Claude can query 'what uses src/lib/db.ts?' via CLI"
+    - "getDependents() is callable through stdin query action"
+    - "Query results return as JSON to stdout"
+  artifacts:
+    - path: "hooks/gsd-intel-index.js"
+      provides: "CLI query interface for graph database"
+      contains: "action.*query"
+  key_links:
+    - from: "stdin handler"
+      to: "getDependents()"
+      via: "query action routing"
+      pattern: "action.*query.*getDependents"
+---
+
+<objective>
+Expose the orphaned getDependents() function via CLI query interface so Claude can answer "what uses this file?" questions during sessions.
+
+Purpose: Close the verification gap - INTEL-05 is blocked because getDependents() exists but has no interface. The infrastructure is complete; this adds the "last mile" wiring.
+
+Output: Modified gsd-intel-index.js that accepts query actions via stdin and returns JSON results to stdout.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-plan.md
+@~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+# Gap source
+@.planning/phases/04-semantic-intelligence/04-VERIFICATION.md
+
+# Target file (contains getDependents at line 125)
+@hooks/gsd-intel-index.js
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add query action routing to stdin handler</name>
+  <files>hooks/gsd-intel-index.js</files>
+  <action>
+Modify the stdin 'end' handler (starting at line 930) to detect and route query actions before the existing Write/Edit handling.
+
+Add this routing logic after `const data = JSON.parse(input);` (line 932):
+
+```javascript
+// Handle query actions (graph queries)
+if (data.action === 'query') {
+  handleQuery(data).then(result => {
+    console.log(JSON.stringify(result));
+    process.exit(0);
+  }).catch(err => {
+    console.log(JSON.stringify({ error: err.message }));
+    process.exit(1);
+  });
+  return; // Don't fall through to Write/Edit handling
+}
+```
+
+Then add the `handleQuery` async function before the stdin handler (around line 925):
+
+```javascript
+/**
+ * Handle CLI query actions
+ * Routes to appropriate graph query function based on query type
+ *
+ * @param {Object} data - Query action data
+ * @param {string} data.action - Must be 'query'
+ * @param {string} data.type - Query type: 'dependents' | 'hotspots'
+ * @param {string} [data.target] - Entity ID for dependents query (e.g., 'src-lib-db')
+ * @param {number} [data.limit] - Max results (default: 10 for dependents, 5 for hotspots)
+ * @param {number} [data.maxDepth] - Max traversal depth for dependents (default: 5)
+ * @returns {Promise<Object>} Query results
+ */
+async function handleQuery(data) {
+  const { db, dbPath } = await loadGraphDatabase();
+
+  try {
+    switch (data.type) {
+      case 'dependents': {
+        if (!data.target) {
+          return { error: 'target is required for dependents query' };
+        }
+        const results = getDependents(db, data.target, data.maxDepth || 5);
+        const limited = data.limit ? results.slice(0, data.limit) : results.slice(0, 10);
+        return {
+          query: 'dependents',
+          target: data.target,
+          count: results.length,
+          results: limited
+        };
+      }
+
+      case 'hotspots': {
+        const results = getHotspots(db, data.limit || 5);
+        return {
+          query: 'hotspots',
+          count: results.length,
+          results
+        };
+      }
+
+      default:
+        return { error: `Unknown query type: ${data.type}. Valid types: dependents, hotspots` };
+    }
+  } finally {
+    db.close();
+  }
+}
+```
+
+Key implementation notes:
+- Query mode does NOT persist to disk (read-only queries)
+- db.close() in finally block ensures cleanup
+- Default limit of 10 prevents huge output for files with many dependents
+- Output goes to stdout as JSON for Claude to parse
+  </action>
+  <verify>
+Test query interface with heredoc:
+
+```bash
+# Test dependents query (should return empty or results depending on graph state)
+node hooks/gsd-intel-index.js <<'EOF'
+{"action":"query","type":"dependents","target":"src-lib-db"}
+EOF
+
+# Test hotspots query
+node hooks/gsd-intel-index.js <<'EOF'
+{"action":"query","type":"hotspots","limit":3}
+EOF
+
+# Test error handling (missing target)
+node hooks/gsd-intel-index.js <<'EOF'
+{"action":"query","type":"dependents"}
+EOF
+
+# Test unknown query type
+node hooks/gsd-intel-index.js <<'EOF'
+{"action":"query","type":"invalid"}
+EOF
+```
+
+All commands should output valid JSON to stdout.
+  </verify>
+  <done>
+Query actions route to handleQuery(), which returns JSON results via stdout. Claude can invoke `echo '{"action":"query",...}' | node hooks/gsd-intel-index.js` to query the graph.
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add usage documentation as code comment</name>
+  <files>hooks/gsd-intel-index.js</files>
+  <action>
+Add a documentation comment block at the top of the file (after line 4) explaining the CLI query interface:
+
+```javascript
+/**
+ * CLI Query Interface
+ *
+ * In addition to PostToolUse indexing (Write/Edit actions), this hook supports
+ * direct graph queries via stdin:
+ *
+ * Query dependents (what uses this file?):
+ *   echo '{"action":"query","type":"dependents","target":"src-lib-db"}' | node hooks/gsd-intel-index.js
+ *
+ * Query hotspots (most depended-on files):
+ *   echo '{"action":"query","type":"hotspots","limit":5}' | node hooks/gsd-intel-index.js
+ *
+ * Options:
+ *   - target: Entity ID (required for dependents, e.g., 'src-lib-db' for src/lib/db.ts)
+ *   - limit: Max results (default: 10 for dependents, 5 for hotspots)
+ *   - maxDepth: Traversal depth for dependents (default: 5)
+ *
+ * Output: JSON to stdout with query results
+ */
+```
+
+This makes the CLI interface discoverable for future Claude sessions.
+  </action>
+  <verify>
+Read first 30 lines of file to confirm documentation is present:
+
+```bash
+head -30 hooks/gsd-intel-index.js | grep -q "CLI Query Interface" && echo "Documentation added"
+```
+  </verify>
+  <done>
+CLI query interface is documented in the file header for discoverability.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+After both tasks complete, verify the gap is closed:
+
+1. **Query interface works:**
+```bash
+# Create test graph.db if needed (empty is fine)
+mkdir -p .planning/intel
+node hooks/gsd-intel-index.js <<'EOF'
+{"action":"query","type":"hotspots"}
+EOF
+# Should output: {"query":"hotspots","count":0,"results":[]}
+```
+
+2. **getDependents is no longer orphaned:**
+```bash
+grep -n "getDependents" hooks/gsd-intel-index.js
+# Should show: definition (line ~125) AND call in handleQuery
+```
+
+3. **Error handling works:**
+```bash
+node hooks/gsd-intel-index.js <<'EOF'
+{"action":"query","type":"dependents"}
+EOF
+# Should output: {"error":"target is required for dependents query"}
+```
+</verification>
+
+<success_criteria>
+- [ ] `handleQuery()` function added and routes query actions
+- [ ] getDependents() called from handleQuery() (no longer orphaned)
+- [ ] Query results output as JSON to stdout
+- [ ] CLI documentation added to file header
+- [ ] Error handling returns JSON error objects
+- [ ] INTEL-05 requirement unblocked: Claude can query "what uses this file?"
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/04-semantic-intelligence/04-04-SUMMARY.md`
+</output>