@neat.is/claude-skill 0.9.2-dev.20260821 → 0.9.2

package/GRAPH_FIRST.md

@@ -1,35 +1,49 @@
-<!-- NEAT graph-first guidance. Paste this block into your agent's project
+<!-- NEAT graph-first directive. Paste this block into your agent's project
      instructions — CLAUDE.md, AGENTS.md, .cursorrules, or the equivalent —
-     so the agent reaches for NEAT's graph before scanning files by hand.
+     so the agent queries NEAT's graph before it scans files by hand.
      Agent-agnostic: it is plain guidance, no Claude Code features required. -->
 
-## Reach for NEAT's graph before grepping
+## Query the graph FIRST
 
-This project has NEAT wired in. NEAT keeps a live semantic graph of the system —
-code, infrastructure, and runtime behaviour fused into one model — reachable over
-MCP (and a REST API). Every edge carries provenance: `EXTRACTED` from source,
-`OBSERVED` from OpenTelemetry, `INFERRED` where the trace stitcher bridges a gap,
-`STALE` when runtime goes quiet — so you know how much to trust each answer.
+This project has NEAT wired in: a live, fused semantic graph of the system —
+code, infrastructure, and runtime behaviour (OpenTelemetry) in one model. Every
+fact carries provenance — `EXTRACTED` from source, `OBSERVED` from OTel,
+`INFERRED` where the trace stitcher bridges a gap, `STALE` when runtime goes
+quiet — plus a confidence, so you know how much to trust each answer.
 
-When you need to understand this codebase, query the graph first. It is usually
-faster and more accurate than `grep`/`glob`/`find`, and it can tell you what the
-system *actually does at runtime*, not only what the source declares.
+**For ANY question about this system's behaviour, dependencies, failures, root
+cause, or blast radius, call `neat ask` FIRST — before Read, Grep, Glob, or
+Bash.** You do not need to know which tool or the exact node id: `ask` is the
+front door. It resolves the entities in your question to graph nodes and routes
+it to the right traversal, returning one compact, provenance-tagged answer.
 
-Reach for these MCP tools before raw text search:
+```
+neat ask "why is checkout failing?"
+neat ask "what breaks if I change the orders table?"
+neat ask "what does the payments service depend on at runtime?"
+```
+
+Same door over MCP: the `ask` tool (`mcp__neat__ask`). Reach for it first.
+
+The graph is live and fused: it is faster and more accurate than
+`grep`/`glob`/`find`, and it can tell you what the system *actually does at
+runtime*, not only what the source declares.
+
+When you already have a node id and want one specific traversal, the structured
+tools answer directly:
 
 - `semantic_search` — find code/nodes by a natural-language description.
-- `get_dependencies` — a node's transitive outgoing dependencies (declared, `EXTRACTED`).
-- `get_observed_dependencies` — only what a node calls *in production* (`OBSERVED` via OTel).
+- `get_dependencies` — a node's transitive outgoing dependencies (`EXTRACTED`).
+- `get_observed_dependencies` — only what a node calls *in production* (`OBSERVED`).
 - `get_divergences` — where the code (`EXTRACTED`) and production (`OBSERVED`) disagree.
-  The most NEAT-shaped query; reach for it on "is anything weird here?"
 - `get_root_cause` — trace a failing node up its dependency graph to the culprit.
-- `get_blast_radius` — everything downstream of a node: what breaks if it changes or fails.
+- `get_blast_radius` — everything downstream: what breaks if a node changes or fails.
 - `get_incident_history` — recent OTel error events recorded against a node.
 - `check_policies` — the project's `policy.json` violations, actual or hypothetical.
 
-Text search is still a fine fallback. If the graph does not have what you need —
-comments, string literals, config minutiae, a file NEAT does not model — go ahead
-and `grep`. The point is order: ask the graph first, then fall back to scanning.
+Fall back to text search only when the graph does not have what you need —
+comments, string literals, config minutiae, a file NEAT does not model. The rule
+is order: ask the graph first, then scan.
 
-If the tools are not available, the NEAT daemon may not be running (`neatd status`)
+If the tools are not available, the NEAT daemon may not be running (`neat list`)
 or the MCP server may not be wired in (`neat skill --apply`).

package/hooks/neat-search-nudge.mjs

@@ -1,15 +1,27 @@
 #!/usr/bin/env node
-// NEAT search-nudge — a Claude Code PreToolUse hook.
+// NEAT search hook — a Claude Code PreToolUse hook with two modes.
 //
 // When the agent reaches for raw text search — the Grep or Glob tools, or a
 // Bash command that shells out to grep / rg / ag / ack / find / fd — this hook
-// injects a short note suggesting NEAT's graph tools first. NEAT already holds
-// this project's structure, dependencies, and runtime behaviour, so a graph
-// query is usually faster and more accurate than scanning files by hand.
+// steers it to NEAT's graph first. NEAT already holds this project's structure,
+// dependencies, and runtime behaviour, so a graph query is usually faster and
+// more accurate than scanning files by hand.
 //
-// It is a NUDGE, not a gate. The hook only ever adds context; it never denies
-// the call and always exits 0, so the search runs regardless. Anything that is
-// not a text search is a silent no-op.
+//   NUDGE (default) — injects a short "ask the graph first" note and always lets
+//     the search run. It never denies; anything that is not a text search is a
+//     silent no-op.
+//
+//   GATE (opt-in) — DENIES Grep / Glob / grep-family Bash until `neat ask` (the
+//     `mcp__neat__ask` tool or a Bash `neat ask …`) has run at least once this
+//     session, forcing the graph-first orientation. Once the graph has been
+//     consulted, search is allowed as a fallback and the nudge rides along
+//     (we gate the orientation, not every search forever). State is a per-session
+//     marker under ~/.neat/hooks/gate/, keyed by session_id, since each hook call
+//     is a fresh process.
+//
+// Gate is enabled by `neat hooks --apply --gate` (which persists a flag at
+// ~/.neat/hooks/gate-enabled) and/or the env toggle NEAT_SEARCH_GATE=1;
+// NEAT_SEARCH_GATE=0 forces nudge-only even when the flag is set.
 //
 // Wired by `neat hooks --apply`, which copies this script under ~/.neat/hooks/
 // and adds a PreToolUse entry to ~/.claude/settings.json. The hook itself is
@@ -21,16 +33,63 @@
 // two byte-aligned.
 
 import process from 'node:process'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
 
 // grep-family and file-finder binaries. Matched at a word boundary so a path
 // like agent.ts does not trip it, and after a shell separator so the binary in
 // a pipe (... | grep foo) still counts.
 const SEARCH_BINARY = /(?:^|[\s|;&(){}])(?:grep|egrep|fgrep|rg|ripgrep|ag|ack|find|fd)(?=\s|$)/
+// `neat ask …` in a Bash command — the CLI form of consulting the graph.
+const ASK_BASH = /(?:^|[\s|;&(){}])neat\s+ask\b/
 
 function bashLooksLikeSearch(command) {
   return typeof command === 'string' && SEARCH_BINARY.test(command)
 }
 
+// ~/.neat, overridable via NEAT_HOME (matches the CLI + tests).
+function neatHome() {
+  const override = process.env.NEAT_HOME
+  return override && override.length > 0 ? path.resolve(override) : path.join(os.homedir(), '.neat')
+}
+
+// Gate on when NEAT_SEARCH_GATE=1, or when `neat hooks --apply --gate` persisted
+// the flag. NEAT_SEARCH_GATE=0 forces it off regardless. Default: nudge only.
+function gateEnabled() {
+  const env = process.env.NEAT_SEARCH_GATE
+  if (env === '0') return false
+  if (env === '1') return true
+  try {
+    return fs.existsSync(path.join(neatHome(), 'hooks', 'gate-enabled'))
+  } catch {
+    return false
+  }
+}
+
+// Per-session "ask has run" marker. The first `ask` writes it; every search
+// reads it. session_id scopes the gate to one Claude Code session.
+function markerFor(sessionId) {
+  const safe = (sessionId || 'nosession').replace(/[^\w.-]/g, '_')
+  return path.join(neatHome(), 'hooks', 'gate', `ask-ran-${safe}`)
+}
+function askHasRun(sessionId) {
+  try {
+    return fs.existsSync(markerFor(sessionId))
+  } catch {
+    return false
+  }
+}
+function recordAskRan(sessionId) {
+  try {
+    const p = markerFor(sessionId)
+    fs.mkdirSync(path.dirname(p), { recursive: true })
+    fs.writeFileSync(p, new Date().toISOString())
+  } catch {
+    // best-effort — a missing marker just means the gate stays closed
+  }
+}
+
 function nudge(toolName) {
   return [
     'NEAT is wired into this project — its live graph already knows this codebase',
@@ -38,6 +97,7 @@ function nudge(toolName) {
     'asking the graph over MCP; it answers with structured, provenance-tagged results',
     'rather than line matches:',
     '',
+    '  - ask — one plain-language question, routed to the right graph query',
     '  - semantic_search — find code/nodes by a natural-language description',
     '  - get_dependencies / get_observed_dependencies — what a thing calls, as declared',
     '    in code (EXTRACTED) vs. what it actually calls in production (OBSERVED)',
@@ -49,6 +109,17 @@ function nudge(toolName) {
   ].join('\n')
 }
 
+function denyReason(toolName) {
+  return (
+    'NEAT gate: consult the graph before text search. Call `neat ask "<your question>"` ' +
+    '(or the `ask` MCP tool) first — it resolves the entities in your question and answers ' +
+    'with structured, provenance-tagged facts (EXTRACTED from code, OBSERVED from runtime), ' +
+    'faster and with production truth that ' + (toolName || 'grep') + ' cannot see. After you have ' +
+    'asked the graph once this session, text search is available as a fallback for what the graph ' +
+    'does not model (comments, string literals, config minutiae).'
+  )
+}
+
 function readStdin() {
   return new Promise((resolve) => {
     let data = ''
@@ -67,19 +138,50 @@ let payload
 try {
   payload = JSON.parse(raw)
 } catch {
-  // No parseable payload — nothing to nudge about. Let the call proceed.
+  // No parseable payload — nothing to act on. Let the call proceed.
   process.exit(0)
 }
 
 const toolName = typeof payload?.tool_name === 'string' ? payload.tool_name : ''
 const toolInput = payload?.tool_input ?? {}
+const sessionId = typeof payload?.session_id === 'string' ? payload.session_id : ''
 
+// 1. Did the agent consult the graph? Any `ask` — the MCP tool or the CLI verb —
+//    opens the gate for the rest of this session.
+const isAsk =
+  toolName === 'mcp__neat__ask' ||
+  toolName === 'ask' ||
+  (toolName === 'Bash' && typeof toolInput.command === 'string' && ASK_BASH.test(toolInput.command))
+if (isAsk) {
+  recordAskRan(sessionId)
+  process.exit(0)
+}
+
+// 2. Is this a raw text search? Anything else is a silent no-op.
 let isSearch = false
 if (toolName === 'Grep' || toolName === 'Glob') isSearch = true
 else if (toolName === 'Bash') isSearch = bashLooksLikeSearch(toolInput.command)
 
 if (!isSearch) process.exit(0)
 
+// 3. GATE: a search before the graph has been consulted → deny and tell the
+//    agent what to do instead. Proven to fire even under
+//    --dangerously-skip-permissions.
+if (gateEnabled() && !askHasRun(sessionId)) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: denyReason(toolName),
+      },
+    }),
+  )
+  process.exit(0)
+}
+
+// 4. NUDGE: default mode, or gate mode after `ask` has run — allow the search
+//    and inject the graph-first note. Never denies.
 process.stdout.write(
   JSON.stringify({
     hookSpecificOutput: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neat.is/claude-skill",
-  "version": "0.9.2-dev.20260821",
+  "version": "0.9.2",
   "description": "Claude Code skill drop-in for NEAT — wires the @neat.is/mcp server into Claude's MCP config",
   "license": "BUSL-1.1",
   "homepage": "https://neat.is",