diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 93d9f0c86..c915bf269 100644 --- 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* diff --git a/.planning/phases/04-semantic-intelligence/04-04-PLAN.md b/.planning/phases/04-semantic-intelligence/04-04-PLAN.md new file mode 100644 index 000000000..413534b18 --- /dev/null +++ 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" +--- + + +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. + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.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 + + + + + + Task 1: Add query action routing to stdin handler + hooks/gsd-intel-index.js + +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} 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 + + +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. + + +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. + + + + + Task 2: Add usage documentation as code comment + hooks/gsd-intel-index.js + +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. + + +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" +``` + + +CLI query interface is documented in the file header for discoverability. + + + + + + +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"} +``` + + + +- [ ] `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?" + + + +After completion, create `.planning/phases/04-semantic-intelligence/04-04-SUMMARY.md` +