@duckmind/dm-linux-x64 0.63.9 → 0.64.2

package/extensions/dm-lens/skills/pi-lens-lsp-navigation/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: dm-lens-lsp-navigation
+description: Navigate code with IDE features and run proactive LSP diagnostics on files/folders/batches. Use as PRIMARY for code intelligence and type/error checks.
+---
+
+# LSP Navigation and Diagnostics
+
+Use `lsp_navigation` as **PRIMARY** for code intelligence. Use `lsp_diagnostics` as **PRIMARY** for proactive type/error checks. Do NOT use grep/glob/ast-grep first for code intelligence.
+
+## Diagnostics
+
+Use `lsp_diagnostics` before builds/tests or after touching several files:
+
+| Need | Tool call |
+|---|---|
+| Check one file | `lsp_diagnostics({ path: "src/file.ts" })` |
+| Check a folder | `lsp_diagnostics({ path: "src/", severity: "error" })` |
+| Check exact touched files | `lsp_diagnostics({ paths: ["src/a.ts", "src/b.ts"], concurrency: 8 })` |
+| Slow server (Rust, Java) | `lsp_diagnostics({ paths: files, waitMs: 2000 })` |
+| Include warnings | `lsp_diagnostics({ paths: files, severity: "all" })` |
+
+Prefer explicit `paths` batches after multi-file edits — bounded concurrency, no unrelated directory noise.
+
+## Navigation (Code Intelligence)
+
+| Question | Operation | Parameters |
+|---|---|---|
+| Where is this defined? | `definition` | path, line, character |
+| Where is this symbol's *type* defined? | `typeDefinition` | path, line, character |
+| Where is this declared (vs defined)? | `declaration` | path, line, character |
+| Find all usages | `references` | path, line, character |
+| What type is this? | `hover` | path, line, character |
+| Call signature | `signatureHelp` | path, line, character (at arg position) |
+| Symbols in this file | `documentSymbol` | path |
+| Find symbol across project | `workspaceSymbol` | query + path (strongly recommended) |
+| Quick fixes available | `codeAction` | path, line, character, endLine, endCharacter |
+| Rename symbol safely | `rename` | path, line, character, newName |
+| Who implements this? | `implementation` | path, line, character |
+| Who calls this function? | `prepareCallHierarchy` → `incomingCalls` | path, line, character |
+| What does this call? | `prepareCallHierarchy` → `outgoingCalls` | path, line, character |
+| What commands does the server offer? | `capabilities` | (optional path) — lists advertised commands |
+| Run a server command (e.g. organize imports) | `executeCommand` | command (+ commandArguments); dry-run unless `apply:true` |
+
+## Call Hierarchy Pattern
+
+```
+// Step 1
+lsp_navigation(operation="prepareCallHierarchy", path="src/api.ts", line=42, character=10)
+// → returns callHierarchyItem
+
+// Step 2
+lsp_navigation(operation="incomingCalls", callHierarchyItem=<item from step 1>)
+lsp_navigation(operation="outgoingCalls", callHierarchyItem=<item from step 1>)
+```
+
+## Operational Notes
+
+- **`definition` returns nothing?** The file may not be open/indexed yet. Read it first, then retry.
+- **`workspaceSymbol` empty?** Always pass `path`. Unscoped queries are best-effort and frequently return nothing. If TypeScript returns "No Project", open the scoped file first.
+- **`references`** — query from the *definition site* for full cross-file coverage; usage-site queries can be partial.
+- **`signatureHelp`** — only valid at call-site argument positions; declaration positions return empty.
+- **`workspaceDiagnostics`** — tracked push snapshot only, not an active check. Use `lsp_diagnostics` when you need fresh results.
+- **`codeAction`** — distinguish `quickfix` from generic refactors ("Move to new file"). Generic refactors are not error fixes.
+- **`prepareCallHierarchy`** — server-capability dependent; if unsupported, skip incoming/outgoing calls.
+
+## When NOT to Use LSP Navigation
+
+| Task | Use Instead |
+|---|---|
+| Find patterns (`console.log`) | `ast_grep_search` |
+| Find text / TODOs | `grep` |
+| Find files by name | `glob` |
+| Read file content | `read` |
+
+## Golden Rule
+
+**Code intelligence → `lsp_navigation` first. Type/error validation → `lsp_diagnostics` first. Text/pattern search → grep/ast-grep.**

package/extensions/dm-lens/skills/pi-lens-write-ast-grep-rule/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: dm-lens-write-ast-grep-rule
+description: Use when writing a new dm-lens ast-grep rule YAML file — covers schema, drop path, gotchas, and NAPI runner constraints
+---
+
+# Writing a dm-lens ast-grep Rule
+
+Drop path: `rules/ast-grep-rules/rules/<id>.yml`  
+Same `id` as a built-in overrides it. Multiple rules per file: separate with `---`.
+
+## Minimal template
+
+```yaml
+id: no-foo-bar
+language: TypeScript        # PascalCase — see languages below
+severity: warning           # error | warning | hint | info — pick by evidence, see below
+message: "Avoid foo.bar() — use baz() instead"
+note: |
+  Longer explanation / fix guidance here.
+rule:
+  pattern: foo.bar($ARG)
+```
+
+**Pick the severity by the evidence behind the rule, not by feel:**
+
+- **`error`** — only with a documented zero-false-positive audit in the `note`.
+  Only `error` maps to semantic `blocking` and stops a turn.
+- **`warning`** — a real finding with a known, bounded false-positive rate.
+- **`hint` / `info`** — style opinions. They render as advisory text, never
+  block, and lose the report budget to warnings when a report is capped.
+
+Full policy and the `error`-promotion procedure: AGENTS.md's "Severity policy
+(#1777)" section. Read it before shipping anything above `warning`.
+
+## Before promoting to error
+
+Three things must all be true, and the rule's `note` must record them:
+
+1. **A multi-corpus false-positive census**, not a single-tree count. Run the
+   rule over dm-lens's `clients/`/`tests/` plus at least one real external
+   codebase of the kind the rule targets, classify every hit, and put the
+   table in the note.
+2. **Structural narrowing before exemption.** Suppress a legitimate idiom
+   with a relational constraint (`inside`/`has`/`follows`, scoped path
+   globs), not with prose telling readers to ignore the hit. Narrow first —
+   don't reach for a lower tier as the easy way out. `no-non-null-assertion`
+   was demoted to `hint` (`0124608a`), then reverted back to `warning` once
+   the same false positives were closed with a structural exclusion instead
+   (`b3e1fd79`).
+3. **Self-scan wiring.** Tag the rule `metadata.category: dm-lens-self-scan`
+   so `npm run astgrep:self-scan` holds this tree at zero in CI. An `error`
+   rule that never runs against dm-lens's own source is an unaudited claim.
+
+If the post-narrowing residual is still tens of legitimate hits, stop and
+report the numbers instead of shipping at `error`.
+
+## Language values
+
+`TypeScript` `JavaScript` `Python` `Go` `Rust` `Java` `C` `Cpp` `CSharp` `Kotlin` `Ruby` `Php`
+
+## Rule conditions
+
+```yaml
+rule:
+  pattern: foo($X)          # ast-grep pattern — $X single, $$$ARGS multi
+  kind: call_expression     # AST node kind (alternative to pattern)
+  regex: "secret|token"     # regex on node text
+  has:                      # descendant must match
+    pattern: await $$$
+  not:
+    kind: comment
+  any:
+    - pattern: foo($X)
+    - pattern: bar($X)
+  all:
+    - pattern: $OBJ.send($$$)
+    - not: { kind: await_expression }
+```
+
+## Relational & constraint conditions — all supported (native napi, #206)
+
+The runner matches every rule through napi's native engine (`root.findAll({rule,
+constraints})`), fed by a faithful `js-yaml` parse. The **full ast-grep grammar works** —
+nest freely; nothing is silently skipped:
+
+```yaml
+rule:
+  kind: call_expression
+  inside:                     # ancestor must match
+    kind: function_declaration
+    stopBy: end               # ↑ search ALL ancestors (default is direct parent)
+  has:                        # descendant must match (default: DIRECT child)
+    field: arguments          # field constraints work
+  follows:                    # immediately-preceding sibling
+    pattern: const $X = $V
+constraints:                  # metavariable regex constraints work
+  X:
+    regex: "Error$"
+```
+
+⚠ **`has`/`inside` default to the immediate child/parent (`stopBy: neighbor`).** For a
+recursive descendant/ancestor search add `stopBy: end`. This is the #1 migration
+gotcha — see the `has` note in `reference.md`.
+
+⚠ **`stopBy: end` alone is not a boundary.** It's a search-depth control — how far
+the walk searches — not a stop condition; the `any:` kind list only decides what
+CAN satisfy the match, not where the walk halts. To scope a relation to the
+nearest enclosing function (or any other boundary), give `stopBy` its own rule.
+See "Scoping to the nearest enclosing X" in `reference.md` (#1794 F1 — this bug
+shipped twice in one window).
+
+## YAML quoting — REQUIRED (js-yaml will reject the rule otherwise)
+
+The parser is a real YAML parser, so unquoted special chars throw and the rule is
+**silently dropped**:
+
+```
+❌ message: !!value to coerce boolean    # `!!` is a YAML tag → js-yaml THROWS, rule dropped
+✅ message: "!!value to coerce boolean"
+❌ message: foo: bar baz                  # bare `:` → parsed as a nested mapping
+✅ message: "foo: bar baz"
+   Quote any scalar starting with  ! & * ? | > % @ `  or containing  : #
+   Quote keyword-like kinds:  kind: "true"   (bare `true` becomes a boolean → invalid kind)
+```
+
+## Gotchas
+
+```
+❌ Overly broad patterns — filtered out automatically
+   $VAR  $NAME  $_  $X  $EXPR  (single bare metavar)
+
+❌ PascalCase language is required
+   language: typescript  →  language: TypeScript
+
+❌ $VAR inside strings — matches literal "$VAR", not a metavar
+   "from $PATH"  →  use tree-sitter or grep instead
+
+✅ Test in playground: https://ast-grep.github.io/playground.html
+✅ Schema + autocomplete: rules/ast-grep-rules/rule-schema.json
+✅ Docs: docs/custom-rules.md
+```
+
+## Reference doc — read before writing a NAPI-runner-specific or hard-to-express rule
+
+`reference.md` (same directory) covers: ReDoS-safe regex authoring, node-text
+string-escape quirks, `has`/`inside` `stopBy` defaults (and when to override
+them), scoping a relation to the nearest enclosing node with a `stopBy`
+boundary rule, the `-js` twin dedup behavior (#657), boolean-parameter
+matching across the TS/JS grammars, and precision-over-recall heuristics for
+denylist-shaped rules. Read it when a rule isn't matching (or over-matching)
+the way you expect, or before shipping a `regex`/`has`-heavy rule.
+
+## Testing a suppression
+
+Every relational suppression (a `has`/`inside`/`not` exclusion for a
+legitimate idiom) needs two fixtures per bound metavariable, not one:
+
+1. **A same-binding valid case** — the idiom the exclusion is meant to
+   suppress, with the metavariable bound consistently (same receiver, same
+   key).
+2. **A mutation-guard invalid case** — the same shape with the binding
+   broken: a different key, a different receiver, or a boundary-crossing
+   lookalike (the guard lives in the wrong scope). This proves the
+   exclusion checks the BINDING, not just the pattern's presence somewhere
+   in the file.
+
+`rules/ast-grep-rules/rule-tests/no-non-null-assertion-test.yml` is the model: alongside the
+get-after-has/pop-after-length valid cases, it fixtures a different-key
+guard, a different-map guard, and an outer-function guard that must NOT
+suppress an inner closure — each one red if the corresponding binding check
+is deleted.
+
+Corpus silence is not evidence. A valve with zero corpus hits needs
+adversarial fixtures MORE, not less — `redundant-unsafe-function` targets
+Rust, so it has no dm-lens corpus to census against, and its `# Safety`
+valve still shipped an unbounded backward scan that over-suppressed real
+detections, caught only by adversarial fixtures in review (`00284bcc`). A
+documented blind spot (an idiom the rule knowingly can't distinguish from a
+bug) becomes an `invalid`-direction fixture with a comment naming the gap,
+never silence.
+
+Regenerate the catalog doc with `npm run docs:rule-catalogs` after adding or
+changing a rule — never hand-edit the generated catalog.
+
+## Validating a candidate rule against the REAL engine (not the warm MCP cache)
+
+Live-binary discipline (AGENTS.md shape 16) applies here too: verify parsing
+and match behavior against a real `ast-grep` run before you write it into a
+rule note or a test fixture — a hand-written fixture pins a guess, not a fact.
+
+```
+
+# inspect how a PATTERN parses → find the node kind you actually need
+
+ast-grep run -p 'x = false' --lang ts --debug-query=cst file.ts
+
+# match by kind (──kind and ──pattern are mutually exclusive in `run`)
+
+ast-grep run --kind required_parameter --lang ts file.ts
+
+# run ONE rule from an sgconfig against a sample
+
+ast-grep scan -c <sgconfig.yml> --filter '^<id>$' sample.ts
+
+# run the fixture harness for one rule
+
+ast-grep test -c rules/ast-grep-rules/.sgconfig.yml --skip-snapshot-tests --filter '<id>'
+
+```

package/extensions/dm-lens/skills/pi-lens-write-ast-grep-rule/reference.md

@@ -0,0 +1,170 @@
+# dm-lens ast-grep Rule Reference
+
+Deep-dive companion to `SKILL.md`. Read this when you're debugging a rule
+that isn't matching (or over-matching) the way you expect: ReDoS-safe regex
+authoring, string-escape quirks in node text, `has`/`inside` `stopBy`
+defaults and when to override them, boolean-parameter matching across two
+grammars, and precision-over-recall heuristics for denylist-shaped rules.
+
+## Hard-won gotchas (NAPI runner specifics — verified)
+
+```
+⚠ `has`/`inside` default to DIRECT child/parent — add `stopBy: end` for a recursive search.
+   This cuts BOTH ways, so think about where the target node actually lives:
+   - Target is a grandchild+ → you MUST add `stopBy: end` or the `has` never matches.
+     `switch-without-default` = `switch_statement` not has `switch_default`: the default
+     lives under `switch_body`, so without `stopBy: end` it matches nothing and every
+     switch (even ones WITH a default) is flagged. Same for `nested-ternary` catching a
+     parenthesized `a ? (b ? c : d) : e`.
+   - Target is the direct child → leave it at `neighbor` (default). Adding `stopBy: end`
+     OVER-reports: `throw_statement` has `string` + `stopBy: end` flags `throw new
+     Error("x")` (the string is nested), and `expression_statement` has `new_expression`
+     + `stopBy: end` flags `fn(new Error())` as a discarded error. Keep these direct.
+   napi's `has` never matches the node itself, so a self-referential `kind: X` has
+   `kind: X` (with `stopBy: end`) correctly flags only genuinely-nested X.
+
+✅ Prefer `regex` on the matched node's OWN text over `has` when you only need to
+   inspect the node — avoids recursive-descendant false positives:
+     kind: export_statement
+     regex: '^export\s+(let|var)\b'      # precise; no has-recursion FP
+   (NAPI evaluates `regex` with JS RegExp on node.text() — keep it LINEAR so the
+   detector can't itself ReDoS.)
+
+⚠ String-literal regexes match SOURCE text, not the runtime string value.
+   Inspect the exact node text before writing constraints:
+     ast-grep run --kind string --lang ts sample.ts --json=compact
+   Example: source `"\\|"` is node text `"\\\\|"` in JSON; to match a
+   source-level escaped backslash (`\\`) followed by a non-backslash, the rule
+   regex needs FOUR regex backslashes, preferably in a YAML block scalar:
+     regex: >-
+       ^["'`]\\\\[^\\A-Za-z0-9$]
+   This is how `incomplete-string-escaping` catches both `"\\|"` and
+   `'\\"'`. Avoid shell here-doc probes for this class — shell/JSON escaping
+   can silently eat a backslash and make the rule look broken.
+
+⚠ `-js` twins: remember there are TWO execution surfaces.
+   <!-- verified: clients/dispatch/runners/ast-grep-napi.ts:205-216,450-455, c170d94b -->
+   - ast-grep CLI/LSP language-gates by `language:`. A `language: TypeScript`
+     rule is not enough for standalone `.js` coverage, so shipped user-facing
+     TS/JS rules that should fire under the ast-grep LSP usually need a `-js`
+     twin with `language: JavaScript` plus its own fixture.
+   - the in-process NAPI fallback (`ast-grep-napi.ts` — dm-lens source checkout
+     only, not present in the installed package) already DEDUPES by grammar
+     (#657): `ruleLanguageForFile` (`ast-grep-napi.ts:205-216`) maps each file
+     extension to its actual grammar, and the matcher (`:450-455`) skips any
+     `language:`-tagged rule whose tag doesn't match that grammar. A TS rule
+     and its JS twin no longer double-fire on the same file in fallback mode.
+   - **`-js` twins are needed only when the rule body itself is
+     grammar-divergent** (different node kinds/fields between the TS and JS
+     grammars). A grammar-agnostic body doesn't need a twin for fallback
+     coverage — the dedup above already scopes it correctly; ship a twin only
+     when standalone `.js` coverage through the ast-grep CLI/LSP baseline is
+     required (see the first bullet).
+   - **Grammar-divergent bodies** still need separate variants regardless:
+     e.g. `no-flag-argument` uses `required_parameter` in TS and
+     `assignment_pattern` in JS.
+
+✅ Node-kind facts (tree-sitter-typescript grammar — NOT the TS compiler / Roslyn):
+   - let / const  → `lexical_declaration`     (var is NOT here)
+   - var          → `variable_declaration`
+   - a regex literal's pattern text  → `regex_pattern`
+   - x[i] index access  → `subscript_expression`   (NOT element_access_expression)
+   - obj.prop access    → `member_expression`      (NOT property_access_expression)
+   - !x / -x / typeof x → `unary_expression`
+   - a ? b : c          → `ternary_expression`
+
+❌ Wrong-grammar kind names = silent dead rule. `element_access_expression`,
+   `property_access_expression`, `binary_operator`, etc. are TS-compiler/Roslyn names, not
+   tree-sitter's. napi REJECTS the whole rule ("invalid kind matcher") so it never runs.
+   Verify a kind exists before shipping:
+     node -e 'import("@ast-grep/napi").then(s=>{const r=s.ts.parse("x[i]").root();
+       const f=(n,k)=>{let c=n.kind()===k?1:0;for(const x of n.children())c+=f(x,k);return c};
+       console.log(f(r,"subscript_expression"))})'   # >0 means the kind is real
+
+✅ Test through the REAL runner from the dm-lens source checkout's repo root — it loads the actual shipped
+   rules from rules/ast-grep-rules/rules. Assert on diagnostic `rule` ids:
+     const res = await runner.run(ctx);  // ctx.filePath = temp .ts, cwd = repo  (dm-lens source checkout only — not present in the installed package)
+   For pattern/kind/regex-only rules (CLI-identical semantics) `ast-grep scan` is fine.
+
+✅ Before shipping any text/regex detector, FP-scan the codebase:
+     ast-grep scan -r <rule>.yml clients tools
+   Real safe variants bite (e.g. ReDoS: (ba+)+ is safe — a mandatory prefix makes
+   the partition unique; flag only a single quantified atom inside the group).
+```
+
+## Scoping to the nearest enclosing X (#1794 F1)
+
+`stopBy` controls how far the ancestor/descendant walk searches. It is not a
+stop CONDITION. An `any:` kind list inside `inside`/`has` decides which
+nodes the walk is ALLOWED to match — it does not tell the walk where to
+halt. `stopBy: end` alone searches every ancestor up to the file root, so a
+guard several scopes out can suppress a finding inside an unrelated closure.
+
+To scope a relation to the nearest enclosing function (or any other
+boundary), give `stopBy` its OWN rule — the same kind list used as the
+match target — so the walk stops at the first satisfying ancestor and can
+never escalate past it:
+
+```yaml
+inside:
+  stopBy:                       # the BOUNDARY: halts the walk here
+    any:
+      - kind: function_declaration
+      - kind: method_definition
+      - kind: arrow_function
+      - kind: function_expression
+  any:                          # the MATCH TARGET: same list, different job
+    - kind: function_declaration
+    - kind: method_definition
+    - kind: arrow_function
+    - kind: function_expression
+  has:
+    stopBy: end
+    pattern: $M.has($K)
+```
+
+This is the fix for #1794 F1: an earlier `no-non-null-assertion` exclusion
+used `stopBy: end` with only the `any:` kind list as the match target, so a
+`.has()`/`.length` guard in an OUTER function suppressed a closure's `!`
+several scopes in. The same defect shape — `stopBy: end` mistaken for a
+boundary — shipped twice in the same 2026-08-20 window: once here, and once
+in `redundant-unsafe-function`'s `# Safety` valve (an unbounded backward
+comment scan, fixed in `00284bcc`). See
+`rules/ast-grep-rules/rules/no-non-null-assertion.yml` for the full working
+rule.
+
+## Matching things a pattern can't express (#305)
+
+```
+❌ A parameter default is NOT a `$X = false` pattern. `pattern: $FLAG = false` parses as
+   an `assignment_expression` (statement context) and never matches a function parameter.
+   Match the PARAM NODE + its child literal instead, capturing the name for reuse:
+     # TS grammar
+     - kind: required_parameter
+       all:
+         - has: { field: pattern, pattern: $FLAG }
+         - has: { any: [ { kind: "true" }, { kind: "false" } ] }
+     # JS grammar (assignment_pattern, with fields left/right)
+     - kind: assignment_pattern
+       all:
+         - has: { field: left, pattern: $FLAG }
+         - has: { field: right, any: [ { kind: "true" }, { kind: "false" } ] }
+
+✅ Metavar consistency works ACROSS sibling clauses of an `all` — a metavar bound in one
+   `has` must match the SAME text everywhere it reappears. Use it to CORRELATE nodes, which
+   is what makes a structural rule precise:
+     all:
+       - has: { stopBy: end, kind: required_parameter, has: { field: pattern, pattern: $FLAG } }
+       - has: { stopBy: end, any: [ { pattern: "if ($FLAG) $$$" }, { pattern: "if (!$FLAG) $$$" } ] }
+   This fires ONLY when the function branches on the SAME param it declared boolean — a
+   boolean default that's never branched on, or a branch on a different var, won't match.
+
+❌ Two `has:` keys in one mapping silently OVERWRITE (YAML: last key wins). For multiple
+   descendant constraints use `all:` with a LIST of `has` entries, never repeated `has:`.
+
+✅ Prefer a high-precision structural guard over an unbounded denylist. Message-chain
+   (Demeter) floods on fluent/promise/builder chains; rather than denylist every fluent
+   method name, REQUIRE the chain's first calls to be accessors (`get*`/`is*`/`has*`) via
+   `constraints` regex — promise/fluent/builder methods aren't accessor-named, so they're
+   excluded by construction. Precision over recall.
+```

package/extensions/dm-lens/skills/pi-lens-write-tree-sitter-rule/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: dm-lens-write-tree-sitter-rule
+description: Use when writing a new dm-lens tree-sitter query rule YAML file — covers schema, S-expression syntax, capture names, predicates, and gotchas
+---
+
+# Writing a dm-lens tree-sitter Rule
+
+Drop path: `rules/tree-sitter-queries/<language>/<id>.yml`  
+Language dir is **lowercase**: `typescript` `javascript` `tsx` `python` `go` `rust` `java` `csharp` `kotlin` `php` `ruby` `cpp` `c` `css`
+
+Project rules merge with built-ins (both run). To disable a language's built-ins: rename dir to `<lang>-disabled/`.
+
+## Minimal template
+
+```yaml
+id: no-eval
+severity: error
+inline_tier: blocking       # blocking | warning | review
+language: typescript        # lowercase, inferred from dir if omitted
+message: "eval() is dangerous — use a safer alternative"
+query: |
+  (call_expression
+    function: (identifier) @FN
+    (#eq? @FN "eval"))
+metavars: [FN]
+has_fix: false
+```
+
+## S-expression query syntax
+
+```scheme
+; Node with field
+(call_expression
+  function: (identifier) @NAME
+  arguments: (arguments) @ARGS)
+
+; Alternatives — ALL branches must use the SAME capture names
+[
+  (function_declaration name: (identifier) @FN)
+  (arrow_function) @FN
+]
+
+; Predicates (inline)
+(#eq? @NAME "fetch")        ; exact match
+(#match? @NAME "^on[A-Z]")  ; regex match
+```
+
+## Predicates via YAML (faster — runs in WASM)
+
+```yaml
+predicates:
+  - type: eq       # eq | match | any-of
+    var: "@FN"
+    value: "dangerousMethod"
+  - type: match
+    var: "@NAME"
+    value: "^(get|set)[A-Z]"
+```
+
+## inline_tier
+
+| Value | Effect |
+|---|---|
+| `blocking` | Blocks agent turn — 🔴 injected immediately |
+| `warning` | Advisory only |
+| `review` | Low-priority suggestion |
+
+## Gotchas
+
+```
+❌ Mixed capture names in [...] alternatives — zero matches, no error
+   [ (fn_decl name: (id) @NAME) (method body: (block) @BODY) ]
+   → split into two separate [...] blocks
+
+❌ Field value as alternative
+   right: [(identifier) (call_expression)]   ← INVALID
+   → use separate query blocks instead
+
+❌ @lowercase captures — convention is @UPPER_SNAKE
+   @fn  →  @FN
+
+✅ Find node kinds: use --debug-query CST in ast-grep playground
+   or https://tree-sitter.github.io/tree-sitter/playground
+✅ Schema + autocomplete: rules/tree-sitter-queries/rule-schema.json
+✅ Docs: docs/custom-rules.md
+```
+
+## Hard-won gotchas (verified, not theoretical)
+
+```
+❌ `_` matches NAMED nodes only — never anonymous tokens (operators, punctuation)
+   To match/capture an operator, use the literal token string:
+     (binary_expression operator: _ @OP)        ← captures NOTHING for `==`
+     (binary_expression ["==" "!="] @OP)         ← correct (anonymous tokens)
+   Anonymous-token alternation `["==" "!="]` works as a CHILD; as a FIELD value
+   it may not compile under the WASM grammar — prefer the child form.
+
+❌ The bundled WASM grammar ≠ the playground / @ast-grep/napi grammar (version skew)
+   Real example: WASM tree-sitter-typescript wraps the for-loop condition in an
+   `expression_statement` and exposes NO `condition:` field:
+     (for_statement condition: (binary_expression ...))   ← 0 matches (no such field)
+     (for_statement (expression_statement (binary_expression ...)))  ← correct
+   Always verify field names / nesting against the WASM grammar, not the playground.
+
+❌ A query that fails to compile returns 0 matches SILENTLY (no error thrown).
+   So "0 matches" can mean "wrong query", not "nothing to find".
+   → Probe incrementally: start `(target_kind) @X`, confirm >0, then add one
+     layer (field, child, predicate) at a time until it narrows correctly.
+
+✅ Verify with the production path, not just the playground:
+     client.runQueryOnFile(queryDef, filePath, "typescript")
+   (TreeSitterClient compiles via the same WASM the runner uses.)
+
+✅ For rule-bug fixes, also add a real-runner regression test through
+   treeSitterRunner.run() via makeRealRunnerCtx (tests/support/real-runner-ctx.ts) —
+   runQueryOnFile bypasses dispatch (skip_test_files, tiers, delta, rule cache).
+   Template: tests/clients/dispatch/runners/tree-sitter-skip-test-files.test.ts.
+   (These test paths exist only in a dm-lens source checkout — the installed
+   npm package ships no tests/ directory.)
+
+✅ JS files also run typescript/ rules (shared grammar) — one rule in
+   rules/tree-sitter-queries/typescript/ covers BOTH .ts and .js. No -js copy needed.
+
+✅ Match a header-field child precisely without a field name by relying on direct
+   children: for_statement's children are lexical_declaration (init),
+   expression_statement (condition), update_expression (increment), statement_block
+   (body) — so a binary_expression nested in the condition's expression_statement is
+   unambiguous, and the body's nodes are inside statement_block (not matched).
+```

package/extensions/dm-lens/tools/activate-tools.js

@@ -0,0 +1,58 @@
+import { Type } from "../clients/deps/typebox.js";
+export function createActivateToolsTool(pi, lazyTools, options = {}) {
+  const lazyNames = lazyTools.map((t) => t.name);
+  const lazyNameSet = new Set(lazyNames);
+  const catalog = lazyTools.map((t) => `${t.name} — ${t.summary}`).join(`
+`);
+  return {
+    name: "dm_lens_activate_tools",
+    label: "Activate dm-lens Tools",
+    description: "Activate one or more situational dm-lens tools that stay registered but inactive by default, so the default tool list stays lean. " + "Call this ONCE with the tools you need before using them — they become callable starting the NEXT turn. " + `Available:
+${catalog}`,
+    promptSnippet: "Activate situational ast-grep / lsp_navigation tools before using them",
+    parameters: Type.Object({
+      tools: Type.Array(Type.String({ enum: lazyNames }), {
+        minItems: 1,
+        description: "Names of situational tools to activate (see this tool's description for the catalog)."
+      })
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const requested = Array.isArray(params.tools) ? params.tools.filter((t) => typeof t === "string" && lazyNameSet.has(t)) : [];
+      if (requested.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No valid tool names given. Available: ${lazyNames.join(", ")}`
+            }
+          ],
+          isError: true,
+          details: { matches: [], added: [] }
+        };
+      }
+      options.onActivated?.(requested);
+      const active = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
+      const activeSet = new Set(active);
+      const added = requested.filter((name) => !activeSet.has(name));
+      const merged = [...new Set([...active, ...added])];
+      if (added.length > 0 && typeof pi.setActiveTools === "function") {
+        pi.setActiveTools(merged);
+        options.onMutation?.({
+          addedCount: added.length,
+          removedCount: 0,
+          reason: "lazy_activation",
+          deferralApplies: options.deferredToolSupport?.(ctx) ?? false
+        });
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Activated: ${requested.join(", ")}. Available starting next turn.`
+          }
+        ],
+        details: { matches: requested, added }
+      };
+    }
+  };
+}