docs: Add setup instructions for API key to README - #1

Added tests for the emacs support.

Resolves all 7 review comments from gemini-code-assist[bot]:

google-gemini#1 [CRITICAL] write-todos.ts - Replaced clear+recreate with reconciliation
   strategy that matches existing tasks by title, preserving IDs, types,
   parent-child relationships, and dependencies. Only status is updated
   for matched tasks. New items are created, absent items removed. Epics
   and parent tasks created by dedicated tracker tools are never deleted.

google-gemini#2 [SECURITY-HIGH] trackerService.ts - Added path traversal guard:
   deleteTask() now validates ID matches /^[0-9a-f]{6}$/i before any
   filesystem operation.

google-gemini#3 [HIGH] trackerService.ts - Moved child-task deletion guard from tool
   layer into TrackerService.deleteTask() so all callers (tools, SDK,
   tests) get the same referential integrity protection.

google-gemini#4 [HIGH] trackerService.ts - Cascade dependency cleanup now sets
   updatedAt on affected tasks so disk metadata stays consistent.

google-gemini#5 [HIGH] trackerService.ts - createTask() now retries up to 10 times
   if the generated 6-char hex ID collides with an existing task.

google-gemini#6 [HIGH] trackerService.ts - deleteTask() now clears parentId on any
   task that referenced the deleted task as parent, preventing orphaned
   invisible tasks in the UI.

google-gemini#7 [HIGH] trackerTools.ts - TrackerDeleteTaskInvocation.execute() now
   trims and validates the ID parameter with the same regex before
   calling the service, catching bad input at the tool boundary.

Tests: 49 passed (added 4 new: path traversal guard, child-task block
at service layer, updatedAt cascade, ID reconciliation preservation).

Addresses all 11 review comments from gemini-code-assist[bot]:

Security (CRITICAL + HIGH):
- Add validateToolParamValues to ASTSearchTool with path validation
  using resolveDefensiveToolPath + resolveToRealPath + validatePathAccess,
  preventing path traversal attacks (comments google-gemini#1, google-gemini#2, google-gemini#8, google-gemini#9)

Parsing correctness (HIGH):
- findClosingBrace: track parenthesis depth to ignore braces inside
  inline object types in function params (comment google-gemini#3)
- findClosingBrace: return lines.length-1 instead of startLine+50
  when brace matching fails, for honest boundary reporting (comment google-gemini#7)
- extractSymbols: track block comment state (/* ... */) to skip
  commented-out code declarations (comment google-gemini#4)
- findIndentEnd: track Python triple-quoted strings to avoid
  early termination on docstrings with low indentation (comment google-gemini#5)
- extractSymbols: fix enum body skipping, enums now advance the
  line pointer past their body like classes/functions (comment google-gemini#10)

Documentation:
- collectSourceFiles: document .gitignore/.geminiignore limitation
  and plan for FileDiscoveryService integration (comment google-gemini#6)
- findClosingBrace: document escaped-quote limitation in the
  string-literal stripping regex (comment google-gemini#11)

Fixes 5 comments from third review round:

CRITICAL/HIGH (google-gemini#1,google-gemini#2): Map scope path traversal - file_path for "map"
  scope now goes through resolveDefensiveToolPath + validatePathAccess
  before reaching getCodebaseMap. handleMapScope accepts safePath param.

HIGH (google-gemini#3): Block comment stripping rewritten from state-tracking to
  character-level replacement. New stripBlockComments() replaces comment
  content with spaces, preserving line numbers. Handles mid-line comments
  and multi-line blocks correctly.

HIGH (google-gemini#4): validateToolParamValues now trims symbol_name and file_path
  at the top before any checks, preventing whitespace-only values.

HIGH (google-gemini#5): handleSymbolScope accepts trimmed symbolName as a parameter
  instead of reading raw this.params.symbol_name, so LLM-injected
  whitespace does not cause lookup mismatches.

HIGH (google-gemini#1): extractSymbols now passes cleaned (block-comment-stripped)
  lines to findIndentEnd, findClosingBrace, and extractMembers instead
  of raw lines. Prevents commented-out braces or members from corrupting
  boundary detection.

HIGH (google-gemini#2): findClosingBrace fallback changed from lines.length-1 to
  startLine. When brace matching fails (template literals, regex literals,
  syntax errors), returning startLine localizes the failure to one symbol
  instead of skipping every subsequent declaration in the file.

google-gemini#1 [SECURITY-CRITICAL] tool-names.ts - Removed write_todos->tracker_list_tasks
   alias. write_todos is a state-modifying tool; aliasing it to a read-only
   tool would let read-only auto-approve policies bypass write protection.

google-gemini#2 [HIGH] trackerService.ts - Moved fs.unlink() AFTER reference cleanup in
   deleteTask(). If a crash occurs mid-operation, the DB stays consistent:
   orphaned dep/parent references would permanently break validateCanClose
   and validateNoCircularDependencies on the affected tasks.

google-gemini#3 [HIGH] tool-names.test.ts - Removed test for the deleted alias.

48 tests passing. Session 1+2 CLI E2E verified.

…n (round-6)

google-gemini#1 [HIGH] write-todos.ts - Replaced O(N) array scans with Map-indexed
   O(1) lookups: tasksById for getDepth(), childrenByParent for
   hasPreservedDescendants(). Added visited.delete(id) backtracking
   so sibling subtrees are traversed independently.

google-gemini#2 [HIGH] trackerService.ts - Normalized ID to lowercase in both
   getTask() and deleteTask() before filesystem operations, preventing
   ENOENT on case-sensitive filesystems (Linux) when ID contains
   uppercase hex chars (e.g. 'ABCDEF' vs 'abcdef.json').

48 tests passing. Session 1+2 CLI E2E verified.

HIGH (google-gemini#1): stripBlockComments rewritten with full state-tracking parser.
  Now correctly ignores block comment delimiters inside string literals
  (single/double/template quotes with escape handling) and single-line
  comments (// ...). Prevents false positives like const x = "/*" from
  triggering comment stripping.

HIGH (google-gemini#2): Top-level indentation limit for brace-based languages raised
  from 2 to 8 spaces. Supports 4-space indented codebases and symbols
  nested inside namespaces/modules without being silently skipped.

google-gemini#1 [HIGH] write-todos.ts:154 - createTask not wrapped in try-catch;
   a single failure (validation/disk I/O) aborts the entire write_todos
   operation. Now catches errors as warnings so reconciliation continues.

google-gemini#2 [HIGH] trackerService.ts:212 - deleteTask ID validation used !id
   instead of typeof check; a non-string value would pass the regex
   (via implicit coercion) but crash on .toLowerCase(). Now matches
   getTask's robust typeof id !== 'string' guard.

48 tests. Session 1+2 verified.

HIGH (google-gemini#1): String literal regex in findClosingBrace now handles escaped
  quotes via negated character class with backslash alternation:
  /(TICK)(?:[^(TICK)\\]|\\.)*TICK/g pattern for all three quote types.
  Resolves the documented limitation for strings like "a \" {".

HIGH (google-gemini#2): Triple-quote tracking in findIndentEnd rewritten to track
  the specific opener (""" vs TICK TICK TICK). A block started with """
  can only be closed by """, preventing cross-type toggle bugs.

HIGH (google-gemini#3): Directory walk depth limit raised from 6 to 15. Supports
  deep monorepo structures like packages/core/src/tools/definitions/
  model-family-sets/ (depth 7) without silently omitting files.

CRITICAL (google-gemini#1): getFileOutline now validates resolved path is a subpath
  of targetDir before any fs access. Traversal returns null.

CRITICAL (google-gemini#2): getCodebaseMap validates searchDir stays within targetDir.
  Traversal returns an error string instead of walking arbitrary dirs.

HIGH (google-gemini#3,google-gemini#4): stripBlockComments now accepts language parameter.
  Uses # for Python line comments, // for others. String literal
  contents are blanked (replaced with spaces) while preserving
  delimiters, preventing false keyword matches inside strings and
  incorrect brace counting from template literal contents.

Review fixes:
- HIGH (google-gemini#1): Python member regex removed leading \s+ since trimmed
  lines have no leading whitespace. Methods now extracted correctly.
- HIGH (google-gemini#2): getCodebaseMap uses resolvedTargetDir for path.relative
  instead of raw this.targetDir, preventing incorrect relative paths.
- HIGH (google-gemini#3): Python test expanded to assert class method children
  (Handler.run as method child).

Bugs found via thorough manual testing:
- extractSymbols indent check now uses original lines[i] instead of
  cleaned[i]. Block comment blanking inflates indentation of the
  cleaned line (e.g. "/* comment */ export class A" becomes 19 spaces
  of indent), causing false top-level rejection.

HIGH (google-gemini#1): getFileOutline now checks file size via fs.stat before
  reading. Files over 2MB (minified bundles, logs, db dumps) are
  rejected with null return, preventing OOM or event loop blocking.

HIGH (google-gemini#2): stripBlockComments resets single-char inString (single
  and double quotes) at end of each line. An unclosed quote from a
  syntax error or unescaped character no longer bleeds into subsequent
  lines and corrupts the rest of the file. Multi-line delimiters
  (backtick, triple quotes) intentionally persist across lines.

HIGH (google-gemini#1): Single-line comment text now blanked with spaces in
  stripBlockComments (only // or # prefix preserved). Prevents
  false declaration matches from keywords inside trailing comments
  like "const x = 1; // class MyClass".

HIGH (google-gemini#2): handleSymbolScope uses recursive findSymbolRecursive
  helper instead of shallow flatMap. Correctly locates symbols
  nested more than 1 level deep (methods inside nested classes,
  symbols inside namespace/module blocks).

HIGH (google-gemini#1): findClosingBrace now strips regex literals alongside string
  literals. Patterns like /[{}]/ and /a{1,3}/ no longer corrupt brace
  depth tracking. Added regex alternation to the existing strip regex.

HIGH (google-gemini#2): collectSourceFiles optimized for large repos. Entries sorted
  alphabetically at each directory level for deterministic traversal.
  Hard cap of 10,000 files prevents OOM in huge monorepos. Per-level
  sorting means the walk produces near-sorted output, reducing final
  sort overhead.

…e getFileOutline call

Addresses round-16 gemini-code-assist review (HIGH x 1):

handleSymbolScope previously called findSymbolBounds (which internally
calls getFileOutline) and then called getFileOutline again to retrieve
symbol metadata, resulting in the same file being read from disk and
parsed with regex heuristics twice per symbol lookup.

Fix: replace the two-call pattern with a single getFileOutline call,
then use recursive search on the returned outline to find the target
symbol. Both bounds and metadata (kind, signature) are now extracted
from the same parse result.

Call chain before (2 file reads):
  handleSymbolScope -> findSymbolBounds -> getFileOutline (read google-gemini#1)
                    -> getFileOutline (read google-gemini#2) -> findSymbolRecursive

Call chain after (1 file read):
  handleSymbolScope -> getFileOutline (read google-gemini#1) -> findSymbolRecursive

Runtime verified: gemini-cli headless session confirms ast_search in
registered tool list alongside read_file, grep_search, glob, etc.

Resolves all 7 review comments from gemini-code-assist[bot]:

google-gemini#1 [CRITICAL] write-todos.ts - Replaced clear+recreate with reconciliation
   strategy that matches existing tasks by title, preserving IDs, types,
   parent-child relationships, and dependencies. Only status is updated
   for matched tasks. New items are created, absent items removed. Epics
   and parent tasks created by dedicated tracker tools are never deleted.

google-gemini#2 [SECURITY-HIGH] trackerService.ts - Added path traversal guard:
   deleteTask() now validates ID matches /^[0-9a-f]{6}$/i before any
   filesystem operation.

google-gemini#3 [HIGH] trackerService.ts - Moved child-task deletion guard from tool
   layer into TrackerService.deleteTask() so all callers (tools, SDK,
   tests) get the same referential integrity protection.

google-gemini#4 [HIGH] trackerService.ts - Cascade dependency cleanup now sets
   updatedAt on affected tasks so disk metadata stays consistent.

google-gemini#5 [HIGH] trackerService.ts - createTask() now retries up to 10 times
   if the generated 6-char hex ID collides with an existing task.

google-gemini#6 [HIGH] trackerService.ts - deleteTask() now clears parentId on any
   task that referenced the deleted task as parent, preventing orphaned
   invisible tasks in the UI.

google-gemini#7 [HIGH] trackerTools.ts - TrackerDeleteTaskInvocation.execute() now
   trims and validates the ID parameter with the same regex before
   calling the service, catching bad input at the tool boundary.

Tests: 49 passed (added 4 new: path traversal guard, child-task block
at service layer, updatedAt cascade, ID reconciliation preservation).

google-gemini#1 [SECURITY-CRITICAL] tool-names.ts - Removed write_todos->tracker_list_tasks
   alias. write_todos is a state-modifying tool; aliasing it to a read-only
   tool would let read-only auto-approve policies bypass write protection.

google-gemini#2 [HIGH] trackerService.ts - Moved fs.unlink() AFTER reference cleanup in
   deleteTask(). If a crash occurs mid-operation, the DB stays consistent:
   orphaned dep/parent references would permanently break validateCanClose
   and validateNoCircularDependencies on the affected tasks.

google-gemini#3 [HIGH] tool-names.test.ts - Removed test for the deleted alias.

48 tests passing. Session 1+2 CLI E2E verified.

…n (round-6)

google-gemini#1 [HIGH] write-todos.ts - Replaced O(N) array scans with Map-indexed
   O(1) lookups: tasksById for getDepth(), childrenByParent for
   hasPreservedDescendants(). Added visited.delete(id) backtracking
   so sibling subtrees are traversed independently.

google-gemini#2 [HIGH] trackerService.ts - Normalized ID to lowercase in both
   getTask() and deleteTask() before filesystem operations, preventing
   ENOENT on case-sensitive filesystems (Linux) when ID contains
   uppercase hex chars (e.g. 'ABCDEF' vs 'abcdef.json').

48 tests passing. Session 1+2 CLI E2E verified.

google-gemini#1 [HIGH] write-todos.ts:154 - createTask not wrapped in try-catch;
   a single failure (validation/disk I/O) aborts the entire write_todos
   operation. Now catches errors as warnings so reconciliation continues.

google-gemini#2 [HIGH] trackerService.ts:212 - deleteTask ID validation used !id
   instead of typeof check; a non-string value would pass the regex
   (via implicit coercion) but crash on .toLowerCase(). Now matches
   getTask's robust typeof id !== 'string' guard.

48 tests. Session 1+2 verified.