feat(cli): implement deterministic gatekeeper subcommand and optimize Tokio runtime

instructions.md

@@ -0,0 +1,133 @@
+# MCP Memory Server Guidelines
+
+This server provides an OS-agnostic, persistent Knowledge Graph and working memory. The following guidelines dictate **when** and **how** to best utilize these tools.
+
+## 1. Ephemeral Working Memory (Sticky Notes)
+- **Tools:** dd_sticky_note, ␍ead_sticky_notes
+- **When to use:** 
+  - When you need to remember a specific context, broken build state, or pending task across conversation boundaries (e.g., "We are in the middle of refactoring main.rs, next step is testing").
+  - When saving short-term scratchpad thoughts that don't belong in the permanent knowledge graph.
+- **Behavior:** Notes have a 24-hour TTL and are pruned automatically. Always consider reading sticky notes at the start of a session if picking up an ongoing task.
+
+## 2. The Knowledge Graph (Entities & Relations)
+- **Tools:** search_nodes, open_nodes, ␍ead_graph
+- **When to use search_nodes:** Use this for **fuzzy searching** when you aren't 100% sure of the exact entity name, or you want to find everything related to a topic (e.g., "Docker", "Jenkins"). It uses Jaro-Winkler distance and token matching.
+- **When to use open_nodes:** Use this for **1-hop traversal**. If you know a specific entity name (e.g., "auth-service") and want to see how it connects to other services, open_nodes will pull the entity AND all directly connected neighbors.
+
+## 3. Graph Maintenance & Condensation
+- **Tool:** condense_entity
+- **When to use:** Proactively use this tool if you notice an entity's observations array is getting excessively long (e.g., >10 items) or repetitive. Condense the list into a shorter, more concise summary of the core facts to preserve token limits.
+
+## 4. The Audit Ledger (Code Changes)
+- **Tools:** log_code_change, query_recent_changes
+- **When to use log_code_change:** *MANDATORY.* Immediately after successfully making significant file modifications (e.g., refactoring a script, fixing a bug). Log the file path and a short description.
+- **When to use query_recent_changes:** When the user asks "What did we do yesterday?", "What changed recently?", or when trying to debug a newly introduced issue. (The ledger retains 7 days of history, max 1000 items).
+
+## 5. Architectural Visualization
+- **Tool:** isualize_graph
+- **When to use:** When you need to explain complex system relationships, dependencies, or architectures to the user. This tool outputs a raw Mermaid.js string. Put the output inside a ``mermaid` markdown block in an Artifact so the user can see a visual diagram.
+
+## 6. Structured Task Queue (Agentic Kanban)
+- **Tools:** `add_task`, `update_task_status`, `list_active_tasks`
+- **When to use:** Use this for structured checklist tracking of complex, multi-day features or goals (e.g., when the user initiates a `/goal`).
+- **Behavior:** Log tasks with a title and description. When resuming sessions, always run `list_active_tasks` to see what is still `pending`, `in_progress`, or `blocked`, and pick up where you left off. Use `update_task_status` to transition tasks to `done`.
+
+## 7. Snippet & Command Vault
+- **Tools:** `store_snippet`, `search_snippets`, `delete_snippet`
+- **When to use:** Use the Vault to store exactly multi-line code snippets, Nushell pipelines, or complex commands that the user relies on frequently.
+- **Behavior:** The vault guarantees precise syntactic preservation of the script (unlike Graph observations). Search snippets when trying to recall an exact query or pipeline.
+
+## 8. Context Namespaces (Project Scopes)
+- **Feature:** `namespace` optional parameter
+- **When to use:** When using `read_graph`, `search_nodes`, or `visualize_graph`, you can now pass `namespace` to isolate graph queries to a specific project scope (e.g. "scascanner").
+- **Behavior:** When calling `create_entities` or `create_relations`, you can inject `namespace: "your_project"` into the entity schema to isolate it from the global scope.
+
+## 9. Architectural Decision Records (ADRs)
+- **Tools:** log_decision, query_decisions
+- **When to use:** Use this whenever you make a non-trivial architectural, environmental, or tooling decision (e.g. choosing a specific framework, a specific deployment flag, bypassing a rule with a workaround).
+- **Behavior:** This permanently stores the context, decision, and consequence of *why* something is done the way it is, preventing future agents from second-guessing or reverting it.
+
+## 10. Graph Refactoring & Maintenance
+- **Tools:** merge_entities, ind_orphans
+- **When to use:** Run ind_orphans periodically or when you notice graph clutter to safely delete unused nodes. Use merge_entities when you notice duplicated semantic concepts (e.g. API_Gateway vs APIGateway).
+- **Behavior:** merge_entities will safely combine their observations and automatically remap all relations pointing to or from the deleted duplicate.
+
+## 11. Dynamic Learned Preferences
+- **Tools:** learn_preference, ␍ead_preferences
+- **When to use:** When the user corrects you on a specific local nuance (e.g. "Actually, use Python 3.10 instead of 3.12 for this repo").
+- **Behavior:** Use this Key-Value store to record dynamic behavioral preferences to ensure you adapt instantly without modifying global Markdown files.
+
+## Error Vault / Troubleshooting
+When you spend time resolving a tricky environment issue, build error, or logic bug, immediately record the fix to save future time.
+- **log_error_fix:** Provide the signature (the exact error string or stack trace snippet) and the solution.
+- **search_error_fixes:** When encountering a weird bug, query this vault first before debugging from scratch.
+
+## Pinned Workspaces (Hot Files)
+To maintain focus on the active "working set" of files in large repositories, use pins.
+- **pin_file / unpin_file:** Pin the 3-5 files you are actively modifying to the current 
+amespace (project).
+- **list_pinned_files:** When starting a new session or returning to a project, always list pinned files first to instantly regain context on what was being worked on.
+
+## Rolling Session Summaries (Project Timeline)
+To maintain a chronological narrative of the project's evolution beyond just code diffs.
+- **add_session_summary:** At the end of every major coding session, write a 2-sentence summary of what was accomplished and add it to the 
+amespace.
+- **get_project_timeline:** When rejoining a project after a long time, read the timeline to instantly understand the recent architectural history.
+
+## Agent Handoffs (The Inbox)
+When working in a multi-session or multi-agent environment, agents need to communicate context across time.
+- **leave_handoff_memo:** Leave a quick message describing current progress, roadblocks, or the literal next step to take.
+- **read_handoff_memos:** ALWAYS check for memos when waking up in a new project namespace.
+- **clear_handoff_memos:** Clear the memo after you have successfully read it and absorbed its context.
+
+## Environment & Blueprint Tracker
+Stop wasting tokens rediscovering how to run or configure the project.
+- **update_env_fingerprint:** Run this when you set up a new project to snapshot the OS, shell, and key language versions (e.g. python, ␍ustc).
+- **read_env_fingerprint:** Query this to instantly know how the project is run.
+- **log_env_requirement:** Log required .env variables (e.g. DATABASE_URL) without logging the secret itself.
+
+## Milestones (Epics)
+Organize granular tasks into high-level phases.
+- **add_milestone:** Group a large subset of work into a cohesive phase (e.g., "V1 MVP", "CI/CD Setup").
+- **update_milestone:** Mark a milestone as active, blocked, or completed.
+- **list_milestones:** Use this to ensure task priorities align with the current active milestone.
+
+## Standup Reports
+When asked for a progress update or standup report, do not guess or read raw git logs.
+- **generate_standup_report:** Generates a structured JSON containing all 	asks updated, code_changes logged, and session_summaries added within the last N hours. Format this cleanly as a markdown report for the user.
+
+## Infrastructure & Environment Registry
+Avoid asking the user for URLs or connection details repeatedly.
+- **register_environment:** Save connection details for Dev, QA, Staging, or Prod environments.
+- **get_environment_details:** Query this to know how to connect to databases, APIs, or VPNs.
+
+## Pre-Push / PR Quality Checklists
+Ensure high code quality and prevent incomplete pull requests.
+- **add_pr_checklist_item:** Add recurring repository chores (e.g., "Run cargo fmt", "Update CHANGELOG").
+- **get_pr_checklist:** Query and explicitly verify EVERY item on this list before triggering git push or merging PRs.
+- **clear_pr_checklist:** Clear if the project lifecycle changes dramatically.
+
+## Tech Debt & Refactor Backlog
+Keep the main task board clean by isolating "hacky" workarounds.
+- **log_tech_debt:** Record why a shortcut was taken and what the ideal solution should be.
+- **resolve_tech_debt:** Mark a debt as paid off once refactored.
+- **list_tech_debt:** Query this before starting a refactoring session.
+
+## Context Workspaces
+When shifting context rapidly (e.g. from building a feature to fixing a prod bug), save your state.
+- **save_context_workspace:** Save your active pinned files and task IDs under a named workspace (e.g., "Feature X").
+- **load_context_workspace:** Retrieve a saved workspace to instantly restore your context when returning to that task.
+- **list_context_workspaces:** List all saved workspaces in a project.
+
+## Omni-Search (Global Vault Search)
+When you remember a vague keyword but don't know which specific vault it's stored in.
+- **omni_search:** Searches across the Knowledge Graph, Tasks, Snippets, ADRs, Tech Debt, Memos, and Error Fixes simultaneously.
+
+## Project Health Dashboard
+When starting a new session, get a numerical aggregate of the project's current state.
+- **get_project_health:** Returns a quick digest of active tasks, unread memos, unresolved tech debt, and pending PR checklist items.
+
+## Git Context Binding (VCS Sync)
+To maintain absolute traceability, we link memory items directly to the exact git commits they occurred on.
+- When calling **log_code_change**, **log_error_fix**, or **log_tech_debt**, you should execute git rev-parse HEAD and git branch --show-current in the project directory first (if it's a git repo).
+- Pass the resulting hash and branch name into the git_commit and git_branch arguments of those tools to permanently link the memory item to the VCS state.