kenaz 0.3.21 → 0.3.23

package/core/dev/archive/ansuz/investigations/synapse_orphans_indexing_bug_2026-04-11.md

@@ -1,352 +0,0 @@
-# synapse_orphans Indexing Bug Investigation — 2026-04-11
-
-**Task**: TASK_1173  
-**Date**: 2026-04-11  
-**Analyst**: unit agent (backend specialist)  
-**Input**: TASK_1172 verification report — 24/30 false positives confirmed  
-**Scope**: dashboard/src-tauri/src/features/synapse (scanner.rs, calls.rs, imports.rs, index.rs)
-
----
-
-## Input data (from TASK_1172)
-
-TASK_1172 ran `synapse_orphans(min_age_days=30, limit=50)` and grep-verified 30 in-scope candidates:
-
-- **24/30 FALSE_POSITIVE** — live callers confirmed by grep
-- **5/30 CONFIRMED_ORPHAN** — deleted
-- **1/30 AMBIGUOUS** — retained
-
-Key false-positive groups (with confirmed callers):
-
-| Symbol | File | Caller | Caller location |
-|--------|------|--------|-----------------|
-| `hasRemoteFileConflict` | `.formation/tools/remote-conflict.js` | dispatch.js | line 338 |
-| `isCacheStale` | `.formation/tools/remote-conflict.js` | dispatch.js | line 331 |
-| `checkLinks` | `.kenaz/docs/tools/src/registry.ts` | cli.ts | line 274 |
-| `rebuildIndex` | `.kenaz/docs/tools/src/registry.ts` | cli.ts | line 196 |
-| `syncToRag` | `.kenaz/docs/tools/src/registry.ts` | cli.ts | line 250 |
-| `main` (×7) | various .memory/tools and .formation/tools | self-invoked at module scope | tail of each file |
-| `constructor` (×4) | registry.ts, search.ts, field-extractor.ts, token-optimizer.js | `new ClassName()` at call sites | various lines |
-
----
-
-## Graph state queries
-
-### Query 1 — CALLS edges to hasRemoteFileConflict and isCacheStale
-
-```cypher
-MATCH (caller:Symbol)-[r:CALLS]->(callee:Symbol {name:'hasRemoteFileConflict'})
-RETURN caller.file_path, caller.name, count(r)
-```
-**Result**: 0 rows
-
-```cypher
-MATCH (caller:Symbol)-[r:CALLS]->(callee:Symbol {name:'isCacheStale'})
-RETURN caller.file_path, caller.name, count(r)
-```
-**Result**: 0 rows
-
-```cypher
-MATCH (caller:Symbol)-[r:CALLS]->(callee:Symbol {name:'checkLinks'})
-RETURN caller.file_path, caller.name, count(r)
-```
-**Result**: 0 rows
-
-### Query 2 — Caller files in the File table
-
-```cypher
-MATCH (f:File) WHERE f.path CONTAINS 'dispatch.js' OR f.path CONTAINS 'cli.ts'
-RETURN f.path, f.name
-```
-**Result**: BOTH files present:
-- `.kenaz/docs/tools/src/cli.ts`
-- `.formation/tools/dispatch.js`
-
-**Interpretation**: Caller files ARE indexed — this rules out Hypothesis A (files never indexed).
-
-### Query 3 — Symbols defined in caller files
-
-```cypher
-MATCH (f:File {path:'.formation/tools/dispatch.js'})-[:DEFINES]->(s:Symbol)
-RETURN s.name, s.kind, s.start_line ORDER BY s.start_line
-```
-**Result**: 14 symbols — `getSupabaseClient`, `getTaskSync`, `getCommitSync`, `syncCommit`, `broadcastStatus`, `readActiveDispatches`, `writeActiveDispatches`, `registerDispatch`, `unregisterDispatch`, `buildCortexContext`, `checkDependencies`, `dispatch`, `handleDryRun`, `execute`
-
-```cypher
-MATCH (f:File {path:'.kenaz/docs/tools/src/cli.ts'})-[:DEFINES]->(s:Symbol)
-RETURN s.name, s.kind, s.start_line ORDER BY s.start_line
-```
-**Result**: **0 rows** — cli.ts has NO symbols in the graph.
-
-**Interpretation**: Two distinct failure modes:
-- dispatch.js: Phase 2 succeeded (14 symbols) but Phase 3 failed (0 CALLS, 0 IMPORTS)
-- cli.ts: Phase 2 failed entirely (0 symbols extracted)
-
-### Query 4 — IMPORTS edges from dispatch.js
-
-```cypher
-MATCH (f:File {path:'.formation/tools/dispatch.js'})-[r:IMPORTS]->(g:File)
-RETURN g.path, r.imported_symbols, r.confidence
-```
-**Result**: 0 rows. No IMPORTS edges for dispatch.js.
-
-Compare: `run-round2.js`, `legacy-scheduler.js`, `muninn.js`, etc. all have IMPORTS edges.
-
-### Query 5 — Any outgoing CALLS from dispatch.js
-
-```cypher
-MATCH (s:Symbol {file_path:'.formation/tools/dispatch.js'})-[r:CALLS]->(t:Symbol)
-RETURN s.name, t.name, t.file_path, r.call_line LIMIT 10
-```
-**Result**: **0 rows** — no CALLS from ANY dispatch.js symbol, including same-file calls (e.g., `dispatch → checkDependencies`, `execute → registerDispatch`).
-
-### Query 6 — Callee symbol uniqueness
-
-```cypher
-MATCH (s:Symbol {name:'isCacheStale'}) RETURN s.id, s.file_path, s.kind
-MATCH (s:Symbol {name:'hasRemoteFileConflict'}) RETURN s.id, s.file_path, s.kind
-```
-**Result**: Both symbols are globally unique (1 candidate each in symbol_index).
-
-**Interpretation**: The `unique_name` fallback strategy (confidence 0.75) in `find_callee_from_imports` should have matched these symbols. The fact that it didn't confirms Phase 3 was never run for dispatch.js — not that resolution failed.
-
-### Query 7 — CALLS edge coverage across .formation/tools
-
-```cypher
-MATCH (s:Symbol)-[r:CALLS]->(t:Symbol)
-WHERE s.file_path STARTS WITH '.formation/tools/'
-RETURN s.file_path, count(r) AS call_count ORDER BY call_count DESC LIMIT 10
-```
-**Result**: prompt.js (532), loop.js (187), legacy-scheduler.js (171), muninn-watcher.js (127) … **dispatch.js absent** (0 edges).
-
----
-
-## Hypothesis 1
-
-**cli.ts has zero symbols — Commander-pattern CLI files are invisible to Phase 2**
-
-**Evidence**:
-- cli.ts shows 0 DEFINES edges (Query 3)
-- cli.ts content starts with `#!/usr/bin/env node` and uses the Commander.js pattern:
-  ```ts
-  import { Command } from 'commander';
-  const program = new Command();
-  program.command('search <query>').action((query, options) => { ... });
-  ```
-- There are NO top-level `function` declarations or `const foo = () => {}` arrow functions at declaration level. All handlers are inline anonymous callbacks passed to `.action()`.
-- `collect_ts_calls_recursive` in `calls.rs` only tracks calls made **inside named function/method/arrow-function declarations**. Anonymous callbacks in argument position are recursed into but their enclosing scope is the *outer* function — in cli.ts's case, there is no outer named function.
-- `symbols::extract_symbols` in `symbols.rs` extracts `function_declaration`, `method_definition`, and `variable_declarator` with function value — it does NOT extract anonymous callbacks inside method call chains.
-
-**Test to confirm**: Run `synapse_search({ query: "cli kenaz docs command search", file_filter: "cli.ts" })` — no results = confirmed zero symbols.
-
-**Impact**: ALL callers of registry.ts methods originate in cli.ts (`checkLinks`, `rebuildIndex`, `syncToRag`, `validate`, `stats`, `searchWithScores`, `listSystems`). Since cli.ts has 0 symbols, no CALLS edges from cli.ts can ever exist regardless of how well Phase 3 runs.
-
-**Fix scope**: `symbols.rs` symbol extractor needs to detect CLI script entry patterns (`program.command().action(handler)`) and either: (a) synthesize a virtual caller symbol per command, or (b) registry.ts methods should not be flagged as orphans if their file has a corresponding `.cli.ts` caller file.
-
----
-
-## Hypothesis 2
-
-**Module-scope call expressions silently dropped by calls.rs**
-
-**Evidence**:
-- `calls.rs:335-345` (confirmed via code read):
-  ```rust
-  if let Some((caller_name, caller_line)) = enclosing_func {
-      if !is_ts_builtin(&simple_name) {
-          calls.push(CallInfo { ... });
-      }
-  }
-  // No else — module-scope calls silently discarded
-  ```
-- `collect_ts_calls_recursive` is called with `enclosing_func = None` for the top-level program node. Call expressions encountered at file scope (outside any function body) hit this guard and are **never pushed to the calls Vec**.
-- Confirmed false positives caused by this:
-  - `main()` at end of file (7 occurrences): `memory-tools.js:475`, `migrate-failures.js` tail, `security-filter.js:419`, `token-optimizer.js:387`, `cleanup-duplicates.js` tail, `rebuild-registry.js:96`, `run-round2.js` tail
-  - `getArg('--skill')` at module scope in `run-round2.js:24`
-  - `rebuildRegistry()` at module scope in `rebuild-registry.js:96`
-
-**Test to confirm**:
-```bash
-grep -n "^main\(\|^main().catch\|^\s*main()" .formation/tools/run-round2.js
-```
-Line found at module scope → no enclosing_func → no CallInfo → no CALLS edge → `main` appears as orphan.
-
-**Fix scope**: `calls.rs:335` — add `else` branch to push CallInfo with synthetic caller (`"<module>"`, `caller_start_line = 0`) for module-scope calls. Then `resolve_phase3` would need to either skip these (no symbol match) or create a module-level pseudo-symbol.
-
-**Simpler fix**: In `synapse_orphans`, additionally check whether the symbol IS called at module scope via a separate grep-style scan, or filter out symbols whose name is `main` and whose file has a `require.main === module` guard.
-
----
-
-## Hypothesis 3
-
-**Destructured CommonJS require breaks import_map strategy, contributing to Phase 3 staleness for dispatch.js**
-
-**Evidence**:
-- `imports.rs:359-409` — `extract_ts_require` reads the variable name with `child_by_field_name("name")`:
-  ```rust
-  let name = child
-      .child_by_field_name("name")
-      .and_then(|n| n.utf8_text(source_bytes).ok())
-      .unwrap_or("")
-      .to_string();
-  // imported_symbols = vec![name]
-  ```
-- For destructured require `const { refreshCache, hasRemoteConflict, hasRemoteFileConflict, isCacheStale } = require('./remote-conflict')`, the `name` field of `variable_declarator` is an `object_pattern` node. `utf8_text()` on that node returns the raw text `{ refreshCache, hasRemoteConflict, hasRemoteFileConflict, isCacheStale }` as a SINGLE string.
-- Result: `imported_symbols = ["{ refreshCache, hasRemoteConflict, hasRemoteFileConflict, isCacheStale }"]` — one string with braces, not four separate names.
-- In `find_callee_from_imports` (scanner.rs:1901-1910):
-  ```rust
-  if imp.imported_symbols.contains(&simple_name.to_string()) {
-  ```
-  `simple_name = "hasRemoteFileConflict"` → `.contains()` fails → import_map strategy misses.
-- Fallback to `unique_name` (strategy 2): should still work for unique symbols, BUT dispatch.js has 0 CALLS edges even for **same-file** symbols (see Query 5). This means the destructured require bug alone is not the only cause.
-
-**dispatch.js Phase 3 staleness — auxiliary finding**:
-- dispatch.js has 14 symbols (Phase 2 ran), 0 IMPORTS, 0 CALLS (including same-file calls like `dispatch → checkDependencies` at line 252, `execute → registerDispatch` at line 445).
-- Same-file calls use Strategy 1 (`same_file`, confidence 0.90) which operates on `fd.extracted_symbols` — it does NOT depend on imports at all.
-- Conclusion: Phase 3 was **never run for dispatch.js**. The most likely cause: dispatch.js was first indexed in a full index pass that predated the addition of `.formation/tools/remote-conflict.js`. Incremental index only re-processes changed files. Since dispatch.js's content has not changed since that full index, it has been skipped on every subsequent run — its Phase 3 edges were never built.
-- This is a general **incremental index blindspot**: files that existed at full-index time with no subsequent changes never get Phase 3 re-run when *their dependencies* are added/modified.
-
-**Test to confirm destructured require bug**:
-```cypher
-MATCH (f:File {path:'.formation/tools/dispatch.js'})-[r:IMPORTS]->(g:File)
-RETURN g.path, r.imported_symbols
-```
-Expected if bug present: 0 rows (confirmed already). Expected after fix: rows with individual symbol names.
-
-**Fix scope**: `imports.rs:extract_ts_require` — detect when `name` node is `object_pattern`, then iterate its `shorthand_property_identifier_pattern` children to build individual symbol names instead of raw text.
-
----
-
-## Hypothesis 4
-
-**Constructor calls not tracked — `new ClassName()` not modeled as CALLS to constructor**
-
-**Evidence**:
-- `calls.rs` `collect_ts_calls_recursive` matches `"call_expression"` nodes. However, class instantiation uses `new_expression` nodes in tree-sitter-javascript/typescript, not `call_expression`.
-- tree-sitter-javascript AST for `new DocsRegistry(config)`:
-  ```
-  new_expression
-    constructor: (identifier) "DocsRegistry"
-    arguments: (arguments ...)
-  ```
-- The `collect_ts_calls_recursive` `_ => {}` fallback recurses into `new_expression` children, but there is no arm for `"new_expression"` → the constructor identifier is never treated as a callee.
-- Result: 4 constructor symbols appear as orphans: `constructor` in registry.ts, search.ts, field-extractor.ts, token-optimizer.js.
-
-**Test to confirm**:
-```bash
-grep -rn "new DocsRegistry\|new SearchEngine\|new FieldExtractor" .kenaz/docs/tools/src/
-```
-All found in registry.ts → confirmed live callers exist.
-
-**Fix scope**: `calls.rs:collect_ts_calls_recursive` — add `"new_expression"` arm that extracts the `constructor` field as callee (similar to `call_expression`), treating it as a call to the class's `constructor` method. Alternatively, match `new ClassName()` as a call to `ClassName` (the class itself).
-
----
-
-## Root cause
-
-Root cause: Multiple independent indexing gaps in calls.rs, imports.rs, and symbol extractor — not a single bug.
-
-**Details — multiple independent gaps:**
-
-| Root cause | Affected symbols | Fix complexity |
-|------------|-----------------|----------------|
-| **cli.ts zero symbols** (Commander pattern — no top-level named functions) | checkLinks, rebuildIndex, syncToRag, validate, stats, searchWithScores, listSystems (7 symbols) | Medium — need Commander-aware symbol extraction or orphan filter |
-| **Module-scope call dropping** (calls.rs:335 guard drops calls without enclosing function) | main (×7), getArg, rebuildRegistry (9+ symbols) | Small — add synthetic `<module>` caller or filter main/cli patterns in orphan tool |
-| **Destructured require breaks import_map** (imports.rs reads object_pattern as raw text) | dispatch.js cross-file callee resolution (affects import_map only; unique_name still works for unique symbols) | Small — 10 LOC fix in extract_ts_require |
-| **Phase 3 never ran for dispatch.js** (incremental blindspot: file unchanged since before remote-conflict.js was added) | hasRemoteFileConflict, isCacheStale, hasRemoteConflict, refreshCache | Requires forced re-index of dispatch.js or full re-index |
-| **new_expression not tracked** (constructor calls use different AST node) | constructor (×4) | Small — add new_expression arm in calls.rs |
-
-**Primary false positive source** (by count): module-scope call dropping (9+) and cli.ts zero symbols (7).
-**Most load-bearing fix**: module-scope call dropping — affects ANY CLI-style script that calls main() or helpers at file scope.
-
----
-
-## Proposed fix
-
-### Fix 1 — imports.rs: destructured require (≤15 LOC, trivial)
-
-In `extract_ts_require` (imports.rs:366-370), replace raw text extraction with object_pattern child parsing:
-
-```rust
-let imported_symbols = if child
-    .child_by_field_name("name")
-    .map(|n| n.kind() == "object_pattern")
-    .unwrap_or(false)
-{
-    // Destructured: const { X, Y } = require(...)
-    // Walk object_pattern children for shorthand_property_identifier_pattern
-    let mut symbols = vec![];
-    if let Some(pattern) = child.child_by_field_name("name") {
-        let mut c = pattern.walk();
-        for prop in pattern.children(&mut c) {
-            if prop.kind() == "shorthand_property_identifier_pattern" {
-                if let Ok(name) = prop.utf8_text(source_bytes) {
-                    symbols.push(name.to_string());
-                }
-            }
-        }
-    }
-    symbols
-} else {
-    // Simple: const X = require(...)
-    let name = child.child_by_field_name("name")
-        .and_then(|n| n.utf8_text(source_bytes).ok())
-        .unwrap_or("")
-        .to_string();
-    if name.is_empty() { vec![] } else { vec![name] }
-};
-```
-
-### Fix 2 — calls.rs: new_expression tracking (≤20 LOC, trivial)
-
-In `collect_ts_calls_recursive`, add a `"new_expression"` arm after `"call_expression"`:
-
-```rust
-"new_expression" => {
-    if let Some(ctor_node) = child.child_by_field_name("constructor") {
-        let callee = ctor_node.utf8_text(source_bytes).unwrap_or("").to_string();
-        let simple_name = extract_simple_name(&callee);
-        let line = child.start_position().row + 1;
-        if let Some((caller_name, caller_line)) = enclosing_func {
-            if !is_ts_builtin(&simple_name) {
-                calls.push(CallInfo {
-                    callee_name: callee,
-                    callee_simple_name: simple_name,
-                    line,
-                    caller_name: caller_name.to_string(),
-                    caller_start_line: caller_line,
-                });
-            }
-        }
-    }
-    collect_ts_calls_recursive(&child, source_bytes, calls, enclosing_func, depth + 1);
-}
-```
-
-### Fix 3 — Module-scope call tracking (medium, requires design decision)
-
-Option A: Add synthetic `<module>` caller in calls.rs (pushes CallInfo with `caller_name = "<module>"`, `caller_start_line = 0`). Then in resolve_phase3, treat `<module>` caller as a special File-level edge rather than a Symbol-to-Symbol CALLS edge. This requires schema/logic changes.
-
-Option B: Filter `main` and other CLI entry patterns in `synapse_orphans` itself — functions named `main` that are the last expression in a file, or functions with `require.main === module` guard, should be excluded from orphan candidates. This is a heuristic filter, not a graph fix.
-
-Option C: Track module-scope calls as CALLS edges originating from a synthetic `<module_scope>` symbol per file. Add this to Phase 2 as well.
-
-**Recommendation**: Option B for immediate fix (< 5 LOC in lib.rs orphans function), Option A/C for completeness.
-
-### Fix 4 — Forced re-index of dispatch.js
-
-Touching dispatch.js (even adding a comment) will trigger incremental re-index → Phase 3 will run → CALLS edges for `hasRemoteFileConflict`, `isCacheStale` will be created after Fix 1. Not a code fix but an operational remediation.
-
-### Fix 5 — cli.ts symbol extraction (complex, deferred)
-
-Commander-pattern CLI files require either:
-- A new extractor that synthesizes named symbols for each `.command('name').action()` block
-- OR an exclusion in synapse_orphans for symbols in files that have a CLI caller (presence of `cli.ts` or `cli.js` sibling in same directory)
-
-**Recommendation**: Deferred. Document the pattern in synapse_orphans tool description.
-
----
-
-**Status of proposed fixes**: Fix 1 and Fix 2 are trivial (< 30 LOC combined, well within inline patch threshold). Fix 3 Option B is trivial. They constitute the complete patch for this bug.
-
-status: fix_task_proposed

package/core/dev/archive/ansuz/investigations/synapse_orphans_reindex_verification_2026-04-11.md

@@ -1,48 +0,0 @@
-# Synapse Orphans Re-index Verification — 2026-04-11
-
-**Task**: TASK_1177  
-**Dependency**: TASK_1174 (imports.rs destructured require fix) — confirmed DONE  
-**Date**: 2026-04-11  
-**Operator**: unit (Formation agent)
-
----
-
-## Before
-
-Snapshot taken before forced full re-index. Source: `synapse_orphans(min_age_days=30)` + `synapse_context` per symbol.
-
-| Symbol | File | Callers (BEFORE) | In orphans(min_age_days=30)? |
-|--------|------|-----------------|------------------------------|
-| `hasRemoteFileConflict` | `.formation/tools/remote-conflict.js` | 0 | No (EXPORTS edge from module.exports) |
-| `isCacheStale` | `.formation/tools/remote-conflict.js` | 0 | No (EXPORTS edge from module.exports) |
-| `hasRemoteConflict` | `.formation/tools/remote-conflict.js` | 2 (legacy-scheduler.js only) | No (has callers) |
-| `refreshCache` | `.formation/tools/remote-conflict.js` | 1 (legacy-scheduler.js only) | No (has callers) |
-
-**Interpretation**: The four symbols were NOT surfaced as orphans because `remote-conflict.js` exports them via `module.exports`, giving them EXPORTS edges that excluded them from orphan detection. However, `hasRemoteFileConflict` and `isCacheStale` had **0 callers** — confirming the Phase 3 CALLS/IMPORTS edge build never ran for `dispatch.js`. The destructured require at `dispatch.js:21` was present in code but not recognized by the pre-TASK_1174 parser.
-
-**Re-index method used**: `POST /api/synapse/index` with `force: true` — triggered a full re-index (bypassing Layer 2 SHA1 hash check). The incremental `synapse_index` MCP call returned "No changes detected" as expected (SHA1 unchanged since dispatch.js content was correct but un-re-parsed).
-
----
-
-## After
-
-Snapshot taken after full re-index completed (relationships stabilized at 23,670, symbol_entries at 21,751).
-
-| Symbol | File | Callers (AFTER) | Caller from dispatch.js? |
-|--------|------|----------------|--------------------------|
-| `hasRemoteFileConflict` | `.formation/tools/remote-conflict.js` | 1 | ✅ Yes (`dispatch` function) |
-| `isCacheStale` | `.formation/tools/remote-conflict.js` | 1 | ✅ Yes (`dispatch` function) |
-| `hasRemoteConflict` | `.formation/tools/remote-conflict.js` | 3 | ✅ Yes (`dispatch` function + legacy-scheduler.js x2) |
-| `refreshCache` | `.formation/tools/remote-conflict.js` | 2 | ✅ Yes (`dispatch` function + legacy-scheduler.js x1) |
-
-**dispatch.js byte-identity**: Confirmed — `git diff --stat .formation/tools/dispatch.js` returned no output (no changes).
-
----
-
-## Notes
-
-- The `synapse_index` MCP tool (incremental) is insufficient to re-parse dispatch.js when content is unchanged — Layer 2 SHA1 hash check short-circuits Phase 3. A forced full re-index via the HTTP API (`force: true`) was required.
-- TASK_1174's fix to `imports.rs` (destructured require parsing) is confirmed effective: all four symbols now have dispatch.js as a caller.
-- The orphans false-positive framing in TASK_1173 was partially inaccurate: the symbols were never in `orphans(min_age_days=30)` due to EXPORTS edges. The real signal was the missing CALLS edges (0 callers for hasRemoteFileConflict and isCacheStale).
-
-Verdict: all_four_cleared

package/core/dev/archive/ansuz/investigations/synapse_orphans_verification_2026-04-11.md

@@ -1,170 +0,0 @@
-# synapse_orphans Verification Report — 2026-04-11
-
-**Task**: TASK_1172  
-**Date**: 2026-04-11  
-**Snapshot**: synapse_orphans(min_age_days=30, limit=50)  
-**Scope paths**: .kenaz/docs/tools, .memory/tools, .formation/tools/run-round2.js, .formation/tools/remote-conflict.js  
-**Analyst**: unit agent  
-**Paired task**: TASK_1173 (synapse_orphans indexing bug investigation)
-
----
-
-## Summary
-
-false_positive_rate: 24/30
-
-| Category | Count | Notes |
-|---|---|---|
-| CONFIRMED_ORPHAN | 5 | Zero non-definition callers; safe to delete |
-| FALSE_POSITIVE | 24 | Actual callers found (code, docs, or self-invocation) |
-| AMBIGUOUS | 1 | Exported API, no external callers discovered |
-| **Total in-scope** | **30** | Of 50 returned by synapse_orphans |
-
-**Key finding**: 80% false-positive rate. Root cause appears to be synapse_orphans failing to model: (a) module-scope self-invocation (CLI `main()` calls), (b) class instantiation callers (`new ClassName()`), (c) cross-module require chains. TASK_1173 should investigate these indexing gaps.
-
----
-
-## Candidates
-
-Full list of in-scope candidates from synapse_orphans snapshot:
-
-| # | Symbol | File | Lines | LOC Impact | Classification |
-|---|---|---|---|---|---|
-| 1 | `checkLinks` | `.kenaz/docs/tools/src/registry.ts` | 594–637 | 44 | FALSE_POSITIVE |
-| 2 | `syncToRag` | `.kenaz/docs/tools/src/registry.ts` | 475–514 | 40 | FALSE_POSITIVE |
-| 3 | `validate` | `.kenaz/docs/tools/src/registry.ts` | 516–551 | 36 | FALSE_POSITIVE |
-| 4 | `rebuildIndex` | `.kenaz/docs/tools/src/registry.ts` | 142–173 | 32 | FALSE_POSITIVE |
-| 5 | `__init__` | `.kenaz/docs/tools/sync_to_rag.py` | 59–81 | 23 | FALSE_POSITIVE |
-| 6 | `stats` | `.kenaz/docs/tools/src/registry.ts` | 553–574 | 22 | FALSE_POSITIVE |
-| 7 | `searchWithScores` | `.kenaz/docs/tools/src/registry.ts` | 106–124 | 19 | FALSE_POSITIVE |
-| 8 | `addSystem` | `.kenaz/docs/tools/src/registry.ts` | 576–584 | 9 | CONFIRMED_ORPHAN |
-| 9 | `removeSystem` | `.kenaz/docs/tools/src/registry.ts` | 586–592 | 7 | CONFIRMED_ORPHAN |
-| 10 | `constructor` | `.kenaz/docs/tools/src/registry.ts` | 37–39 | 3 | FALSE_POSITIVE |
-| 11 | `listSystems` | `.kenaz/docs/tools/src/registry.ts` | 134–136 | 3 | FALSE_POSITIVE |
-| 12 | `main` | `.memory/tools/memory-tools.js` | 376–472 | 97 | FALSE_POSITIVE |
-| 13 | `main` | `.memory/tools/migrate-failures.js` | 263–342 | 80 | FALSE_POSITIVE |
-| 14 | `smartTrim` | `.memory/tools/token-optimizer.js` | 180–246 | 67 | FALSE_POSITIVE |
-| 15 | `main` | `.memory/tools/security-filter.js` | 358–417 | 60 | FALSE_POSITIVE |
-| 16 | `main` | `.memory/tools/token-optimizer.js` | 334–384 | 51 | FALSE_POSITIVE |
-| 17 | `constructor` | `.memory/tools/token-optimizer.js` | 31–36 | 6 | FALSE_POSITIVE |
-| 18 | `hasSensitiveData` | `.memory/tools/security-filter.js` | 352–355 | 4 | AMBIGUOUS |
-| 19 | `main` | `.memory/tools/cleanup-duplicates.js` | 100–144 | 45 | FALSE_POSITIVE |
-| 20 | `rebuildRegistry` | `.memory/tools/rebuild-registry.js` | 65–94 | 30 | FALSE_POSITIVE |
-| 21 | `search` | `.kenaz/docs/tools/src/search.ts` | 32–74 | 43 | FALSE_POSITIVE |
-| 22 | `getSearchStats` | `.kenaz/docs/tools/src/search.ts` | 191–232 | 42 | CONFIRMED_ORPHAN |
-| 23 | `constructor` | `.kenaz/docs/tools/src/field-extractor.ts` | 27–61 | 35 | FALSE_POSITIVE |
-| 24 | `registerSystem` | `.kenaz/docs/tools/src/field-extractor.ts` | 155–157 | 3 | CONFIRMED_ORPHAN |
-| 25 | `getRegisteredSystems` | `.kenaz/docs/tools/src/field-extractor.ts` | 162–164 | 3 | CONFIRMED_ORPHAN |
-| 26 | `constructor` | `.kenaz/docs/tools/src/search.ts` | 24–24 | 1 | FALSE_POSITIVE |
-| 27 | `main` | `.formation/tools/run-round2.js` | 90–116 | 27 | FALSE_POSITIVE |
-| 28 | `getArg` | `.formation/tools/run-round2.js` | 16–22 | 7 | FALSE_POSITIVE |
-| 29 | `hasRemoteFileConflict` | `.formation/tools/remote-conflict.js` | 69–89 | 21 | FALSE_POSITIVE |
-| 30 | `isCacheStale` | `.formation/tools/remote-conflict.js` | 94–96 | 3 | FALSE_POSITIVE |
-
----
-
-## Confirmed orphans
-
-Five symbols with zero non-definition callers across all file extensions (.js, .ts, .py, .sh, .md, .yaml, .yml, .json, .toml):
-
-### 1. `addSystem` — `.kenaz/docs/tools/src/registry.ts` lines 576–584
-
-```
-grep -rn 'addSystem' --include='*.{js,ts,py,sh,md,yaml,yml,json,toml}' .
-```
-Result: Only definition site (registry.ts:576). No callers.  
-**Action**: Deleted.
-
-### 2. `removeSystem` — `.kenaz/docs/tools/src/registry.ts` lines 586–592
-
-```
-grep -rn 'removeSystem' --include='*.{js,ts,py,sh,md,yaml,yml,json,toml}' .
-```
-Result: Only definition site (registry.ts:586). No callers.  
-**Action**: Deleted.
-
-### 3. `getSearchStats` — `.kenaz/docs/tools/src/search.ts` lines 191–232
-
-```
-grep -rn 'getSearchStats' --include='*.{js,ts,py,sh,md,yaml,yml,json,toml}' .
-```
-Result: Only definition site (search.ts:191). No callers.  
-**Action**: Deleted.
-
-### 4. `registerSystem` — `.kenaz/docs/tools/src/field-extractor.ts` lines 155–157
-
-```
-grep -rn 'registerSystem' --include='*.{js,ts,py,sh,md,yaml,yml,json,toml}' .
-```
-Result: Only definition site (field-extractor.ts:155). No callers.  
-**Action**: Deleted.
-
-### 5. `getRegisteredSystems` — `.kenaz/docs/tools/src/field-extractor.ts` lines 162–164
-
-```
-grep -rn 'getRegisteredSystems' --include='*.{js,ts,py,sh,md,yaml,yml,json,toml}' .
-```
-Result: Only definition site (field-extractor.ts:162). No callers.  
-**Action**: Deleted.
-
----
-
-## False positives
-
-24 symbols reported as orphans by synapse_orphans that have live callers:
-
-| Symbol | File | Caller Evidence |
-|---|---|---|
-| `checkLinks` | registry.ts | `.kenaz/docs/tools/src/cli.ts:274` — `registry.checkLinks()` |
-| `syncToRag` | registry.ts | `.kenaz/docs/tools/src/cli.ts:250` — `registry.syncToRag(!options.force)` |
-| `validate` | registry.ts | `.kenaz/docs/tools/src/cli.ts:201,295` — `registry.validate()` |
-| `rebuildIndex` | registry.ts | `.kenaz/docs/tools/src/cli.ts:196` — `registry.rebuildIndex()` |
-| `stats` | registry.ts | `.kenaz/docs/tools/src/cli.ts:212,321` — `registry.stats()` |
-| `searchWithScores` | registry.ts | `.kenaz/docs/tools/src/cli.ts:31` — `registry.searchWithScores(query, {...})` |
-| `listSystems` | registry.ts | `.kenaz/docs/tools/src/cli.ts:107` — `registry.listSystems()` |
-| `constructor` | registry.ts:37 | `registry.ts:56,61` — `new DocsRegistry(...)` |
-| `__init__` | sync_to_rag.py | `registry.ts:478` spawns script; `RAG_INTEGRATION_GUIDE.md:73` — `DocsSyncManager(Path.cwd())` |
-| `search` | search.ts | `registry.ts:95,122` — `searchEngine.search(query, options)` |
-| `constructor` | search.ts:24 | `registry.ts:95,122` — `new SearchEngine(allDocs)` |
-| `constructor` | field-extractor.ts:27 | `registry.ts:38` — `new FieldExtractor()` |
-| `main` | memory-tools.js | `memory-tools.js:475` — self-invoked at module scope (`main()`) |
-| `main` | migrate-failures.js | `migrate-failures.js` tail — self-invoked (`main()`) |
-| `smartTrim` | token-optimizer.js | `.memory/README.md:263`, `.memory/SECURITY_TOKEN_OPTIMIZATION.md:117` — documented API import; exported |
-| `main` | security-filter.js | `security-filter.js:419-420` — guarded CLI entry (`if (require.main === module) { main(); }`) |
-| `main` | token-optimizer.js | `token-optimizer.js:387` — self-invoked at module scope |
-| `constructor` | token-optimizer.js:31 | class `MemoryCache` instantiated internally |
-| `main` | cleanup-duplicates.js | `cleanup-duplicates.js` tail — self-invoked (`main()`) |
-| `rebuildRegistry` | rebuild-registry.js | `rebuild-registry.js:96` — self-invoked at module scope |
-| `main` | run-round2.js | `run-round2.js` tail — `main().catch(e => { process.exit(1); })` |
-| `getArg` | run-round2.js | `run-round2.js:24` — called at module scope (`getArg('--skill')`) |
-| `hasRemoteFileConflict` | remote-conflict.js | `.formation/tools/dispatch.js:338` — `hasRemoteFileConflict(scopePaths)` |
-| `isCacheStale` | remote-conflict.js | `.formation/tools/dispatch.js:331` — `isCacheStale()` |
-
-**Root causes of false positives:**
-1. **Module-scope self-invocation**: synapse_orphans misses calls at file scope (e.g., `main()` at end of file). Affects 7 `main()` + 2 internal helpers.
-2. **Class instantiation**: `new ClassName()` calls are not tracked as CALLS edges to `constructor`. Affects 4 constructor methods.
-3. **Subprocess spawn**: Python CLI scripts spawned via `child_process.spawn` don't create graph edges.
-4. **Cross-module import resolution**: `require('./security-filter')` → exported API not mapped to callers.
-5. **Documented-only callers**: Functions referenced only in `.md` docs (smartTrim) are not detected.
-
----
-
-## Ambiguous
-
-### `hasSensitiveData` — `.memory/tools/security-filter.js` lines 352–355
-
-A 4-line utility function exported via `module.exports.hasSensitiveData`. No external file imports or calls it. However it is part of the exported public API alongside `filterSensitiveData` and `filterMemoryEntry` (which are used by memory-tools.js). It may be dead code or an intentional public API without current consumers.
-
-**Decision**: Not deleted. Requires explicit owner review. Low LOC impact (4 lines).
-
----
-
-## Synapse_orphans indexing gaps (for TASK_1173)
-
-The following indexing failures were observed and should inform TASK_1173:
-
-1. **Module-scope calls not tracked**: `main()` called at file scope (e.g., `main().catch(...)`) produces no CALLS edge in the graph. This caused 7 false positives.
-2. **Constructor calls not tracked**: `new ClassName()` does not create a CALLS edge to the class `constructor` method. This caused 4 false positives.
-3. **Python subprocess spawn not tracked**: `child_process.spawn('python', [scriptPath])` in registry.ts:478 does not create any cross-language edge.
-4. **Cross-language import not tracked**: `from sync_to_rag import DocsSyncManager` (Python import, in doc examples) not modeled.
-5. **Intra-file module-scope references**: `getArg` called at file scope in run-round2.js — no CALLS edge despite local definition.