Return database health stats: row counts per table, schema version, DB size, FTS5 availability, embeddings status.

Use this tool to verify the thinking_os database is operational and to get a quick summary of stored data volume.

Returns: str: JSON object with keys: tables (row counts), schema_version, fts5_available, db_size_bytes, rag (embeddings + doc_chunks status).

Record a single agent performance metric after task completion.

Args: agent_type: Type of agent (e.g. "general", "planner", "code-reviewer"). outcome: Result — one of: success, rework, partial, blocked. task_id: Task identifier (e.g. "TASK-143"). Optional. model: Model used (e.g. "sonnet", "opus"). Optional. duration_ms: Duration in milliseconds. Optional. domain: Task domain (e.g. "BACKEND", "FRONTEND", "INFRA"). Optional. complexity: Cynefin classification (e.g. "CLEAR", "COMPLICATED"). Optional.

Returns: str: JSON with inserted row id and status.

Query agent metrics with optional filters.

Args: domain: Filter by domain (e.g. "BACKEND"). Optional. model: Filter by model (e.g. "sonnet"). Optional. outcome: Filter by outcome (e.g. "rework"). Optional. agent_type: Filter by agent type. Optional. date_from: Start date (ISO format, e.g. "2026-03-01"). Optional. date_to: End date (ISO format, e.g. "2026-03-25"). Optional. limit: Max rows (1-100, default 20).

Returns: str: JSON with total count and matching rows.

Get aggregated trend data for agent metrics.

Args: metric: One of: success_rate, rework_rate, count. window_days: Lookback window in days (1-365, default 30). group_by: Grouping dimension: domain, model, agent_type, complexity.

Returns: str: JSON with trends array containing period, counts, and rate.

Query the durable log_events store (WARN+), most-recent first — the agent's "what is broken now".

Record an observation explicitly.

Search observations and learned patterns with 5-signal ranking.

Use during Orient step to find relevant past experience. Read-only over memory rows (writes retrieval telemetry only; reinforcement happens on cos_details, not here — TASK-109).

Stage-1 metadata pre-filter:

• min_confidence drops decayed/low-trust patterns BEFORE ranking. Stale low-signal patterns can otherwise crowd out fresh hits. Default 0.3 skips decayed/unvalidated noise (fresh patterns start at 0.5, so they still pass); pass 0.0 to include everything.

• since_days caps row age. 0 = no cap (default) — age is opt-in so a valuable old decision is never silently hidden from default recall.

Args: query: Search text (e.g. "backend rework", "django migration"). limit: Max results (1-20, default 5). memory_type: Filter by type (pattern/workflow/error/decision/discovery). Optional. min_confidence: Drop learned_patterns with confidence below this value (0.0-1.0). Default 0.3 (skips decayed noise). 0.0 = no filter. since_days: Drop rows older than now-since_days. 0 = no cap. Common: 90 (one quarter) for "recent" queries.

Returns: str: JSON with results list [{id, title, confidence, impact_score, memory_type, source_table}].

Get recent task outcomes and observations timeline.

Args: days: Lookback window (1-365, default 30). domain: Filter by domain (e.g. "BACKEND"). Optional. limit: Max entries (1-50, default 20).

Returns: str: JSON with timeline entries [{id, title, date, outcome, type}].

Get full details of a pattern, observation, or task outcome.

Args: pattern_id: Row ID (or task_id string for task_outcomes). source: Table name — observations, learned_patterns, or task_outcomes.

Returns: str: JSON with full record.

Promote a validated pattern to a rule or feedback memory file.

Requires confidence >= 0.3. Creates file content but does NOT write to disk (caller writes the returned content to the appropriate location).

Args: pattern_id: ID in learned_patterns table. target: Output type — "feedback" or "rule".

Returns: str: JSON with status, filename, and file content to write.

Scan task outcomes to discover recurring patterns.

Detects domain_rework, skill_correlation, and complexity_mismatch patterns. Inserts new patterns into learned_patterns with calculated confidence.

Args: min_occurrences: Minimum occurrences to consider a pattern (default 3).

Returns: str: JSON with extracted patterns list and analysis stats.

Return relevant patterns for the current task context.

Includes spaced repetition: fading patterns (0.2-0.4 confidence) that were once validated get priority for re-validation.

Args: domain: Task domain (e.g. "BACKEND"). Optional. complexity: Cynefin classification. Optional. task_type: Type of task (e.g. "feat"). Optional. limit: Max suggestions (1-20, default 5).

Returns: str: JSON with suggestions list [{id, pattern, confidence, reason}].

Record whether a suggested pattern was helpful.

Updates confidence using brain-inspired formulas:

• Helpful: LTP with diminishing returns + temporal proximity bonus

• Not helpful: LTD proportional penalty

Args: pattern_id: ID in learned_patterns table. was_helpful: Whether the pattern was useful (default True).

Returns: str: JSON with old/new confidence and validation status.

Record what was learned from a difficult task (breakthrough narrative).

Call this after a rework→success breakthrough to capture:

• What approaches failed and why

• What finally worked

• The reusable key insight

Creates a high-impact learned pattern for future suggestions.

Args: task_id: Task identifier (e.g. "TASK-100"). what_failed: Approaches that didn't work. what_worked: The solution that resolved the issue. key_insight: Reusable lesson learned (required).

Returns: str: JSON with status, history_id, pattern_id.

Recommend optimal model based on historical outcome data.

Cold start (<10 outcomes): returns static default from performance.md. Warm: queries success rates per model for the given complexity+domain.

Args: complexity: Cynefin classification (CLEAR/COMPLICATED/COMPLEX/CHAOTIC). dimensions: Number of problem dimensions (default 1). domain: Task domain (e.g. "BACKEND"). Optional.

Returns: str: JSON with recommended_model, confidence, reason, fallback_model.

Recommend skills based on historical outcome data.

Cold start: returns static defaults from skill-enforcement.md. Warm: augments with historically successful skills.

Args: domain: Task domain (e.g. "BACKEND", "FRONTEND"). task_type: Type of task (e.g. "feat", "fix"). Optional. complexity: Cynefin classification. Optional.

Returns: str: JSON with skills list [{name, confidence, reason}].

Persist a project trajectory snapshot for the current session.

Records WHERE the project is heading (phase, focus, architectural decisions, anti-patterns discovered, open questions) so future sessions have strategic context beyond task history. Each call creates a new row linked to the previous snapshot via supersedes_id.

Args: session_id: Current session identifier. phase: Current development phase (e.g. "v2 hardening"). current_focus: What the team is focused on right now. architectural_decisions: JSON array of {decision, rationale} objects. anti_patterns_discovered: JSON array of {pattern, context} objects. open_questions: JSON array of {question, priority} objects or plain strings. next_logical_step: Single-sentence description of what comes next. confidence: Confidence in this trajectory assessment (0.0-1.0).

Returns: JSON with {status, id, supersedes_id}.

Return the most recent project trajectory snapshot(s).

Use at session start to understand WHERE the project is heading before looking at the task board. Returns phase, current focus, architectural decisions made, anti-patterns discovered, and open questions.

Args: limit: Number of recent snapshots to return (1-20, default 1).

Returns: JSON with {snapshots: [...], count: int}.

Aggregate structured failure anatomy from backtrack_events.

Returns which root_cause categories recur most frequently, with examples. Use before planning to avoid known failure modes. Requires migration v25 (structured backtrack anatomy columns).

root_cause filter values: wrong_model | scope_too_large | missing_context | tool_failure | spec_ambiguity | env_mismatch | other

Args: root_cause: Optional filter to a specific root cause category. domain: Reserved for future per-domain filtering. limit: Max pattern groups to return (1-50, default 10).

Returns: JSON with {patterns: [{root_cause, count, examples}], total_structured, total_backtrack}.

Semantic + lexical search over project documentation chunks.

Stage-1 metadata pre-filter (since migration v22): domain, layer, since_iso, and include_inactive narrow the chunk universe BEFORE vector / FTS ranking. Vector search finds meaning; metadata enforces reality (correct era, correct domain, not superseded). Combine with source_types for cheap, indexed pre-filtering.

Args: query: Natural language search query (e.g. "commission rate calculation"). source_types: Optional comma-separated filter — restrict to specific source types (e.g. "prd,architecture,adr"). Empty = all types. limit: Maximum results (1-50, default 5). mode: "auto" (default) | "semantic" | "lexical". domain: Frontmatter domain: filter (BACKEND, FRONTEND, OPS, DOCS, …). Empty = any. Indexed. layer: Frontmatter layer: filter (adr, playbook, spec, policy, reference, runbook, postmortem, task). Empty = any. Indexed. since_iso: Lower bound on frontmatter updated: (YYYY-MM-DD). Use when the agent asks about "recent" or "current" state and a stale older doc would be the wrong answer. Empty = any age. include_inactive: When False (default), hide chunks marked is_active=0 because the source doc was deleted or superseded. Set True for decision-history retrieval that must surface superseded specs. auto_context: When True (default), soft-default domain from the active task's swimlane ($COS_AGENT_DIR/.swimlane). Explicit domain argument always wins. Set False to disable.

Response meta carries filter_hints — heuristic suggestions extracted from the query (date phrasing, domain keywords, layer cues). Suggestions are NEVER auto-applied; the agent decides whether to re-query with them. Mental model: Filter → Search → Summarize. Vector finds meaning, metadata enforces correctness.

Returns: str: JSON envelope with results list and count. Each result carries source_path, source_type, heading_path, content, score, priority, mtime, chunk_index, retrieval_source.

Return a single doc's header without reading the body.

Bulk header-only scan filtered by frontmatter.

Semantic search over the task store with optional status/domain filters.

Use this when you need to find tasks related to a concept — even when exact keywords don't match. Falls back to LIKE on title + goal when embeddings are unavailable.

Args: query: Natural language query (e.g. "payment splitting multi vendor"). status: Optional status filter — one of open/wip/done/blocked. Empty = all. domain: Optional domain filter (BACKEND/FRONTEND/DOCS/INFRA/...). Empty = all. limit: Maximum results (1-100, default 10).

Returns: JSON with results and count. Each result: task_id, title, domain, status, file_path, goal_text, dependencies, score.

Return the tasks that task_id directly depends on.

Use before starting a task to verify prerequisites are done. Returns only direct (first-level) dependencies — use repeated calls for transitive traversal.

Args: task_id: Task identifier (e.g. "TASK-199").

Returns: JSON with task_id, dependencies list, and count.

Return the tasks that declare task_id as a dependency.

Use for impact analysis: "If I change TASK-195, what downstream tasks need to be re-verified?" Returns only direct dependents — non-transitive.

Args: task_id: Task identifier (e.g. "TASK-195").

Returns: JSON with task_id, dependents list, and count.

List tasks matching an optional status and/or domain filter.

No semantic query — pure structured filter. Use when you need "all open backend tasks" or "all blocked tasks" without a specific concept.

Args: status: Filter by status (open/wip/done/blocked). Empty = all. domain: Filter by domain (BACKEND/FRONTEND/DOCS/...). Empty = all. limit: Maximum results (1-100, default 20).

Returns: JSON with results list (sorted by task_id ASC) and count.

Create a new Scrumban task file + sync to DB.

Prefer this over hand-writing YAML. Validates swimlane against scrumban-config.yaml and kind against the 8-value enum. Pass ready=True to mark the task pullable in one shot; for bug-kind tasks pass acceptance= (G/W/T lines) and repro= so the create satisfies its own DoR in one call.

Return the board state grouped by (swimlane, status) with WIP info. Complete/archive columns are keyset-paginated (pass cursor + status_filter to load more).

Show a single task's frontmatter fields and full markdown body — in-session alternative to raw ls/grep/Read on docs/tasks.

Full actor-attributed task history — creation, status transitions, field edits, and git commits.

Edit a task's frontmatter fields and/or body; each change is recorded to the actor-attributed edit history.

Set a task's optional external_ref (e.g. github#42) — forge auto-detected; metadata only, never the id.

Return per-agent presence state and live-session inventory.

Reads .coding-os/<agent>/sessions/*.json (the same files agent-presence.sh writes) and applies the SSOT rules in board_os.presence. When agent is empty, every adapter registered in adapters//adapter.yaml is reported.

Used by cos daily, CI gates, and the live-agents board UI to verify zombie sessions are gone after deploy.

Transition a task through the Scrumban state machine.

Update Scrumban status and/or swimlane (MD frontmatter + sync).

Add or remove the 'ready' label that gates icebox→in_progress.

Reclaim zombie in_progress tasks (idle + owner session inactive) to icebox+ready.

Triage stranded in_progress/testing tasks with completion evidence + a review recommendation (read-only).

Return top candidate tasks to start next, ranked by priority.

Atomically select+claim the top runnable task for this session (or claimed=null).

Produce the daily standup summary.

Weekly retro metrics (cycle time, throughput, emergency count).

Lightweight check of current WIP counts vs. configured caps.

Append one Work Log line to a task. Critical for Codex sessions.

Mark retrieval rows as actively cited by the agent.

Call this after using one or more chunks/patterns/tasks in a meaningful way (read them carefully, applied them). Cited retrievals get ~4× the weight when priority-learning runs, so the signal is only useful if it reflects actual use — do NOT cite passive retrievals.

Args: retrieval_ids: Comma-separated list of retrieval ids (int), returned as retrieval_ids in prior cos_search / cos_doc_search / cos_task_search responses. e.g. "12,17,24".

Returns: JSON with {updated, unknown} — updated count + list of ids that did not exist.

Adjust document_chunks.priority based on recent retrieval outcomes.

Walks retrievals with a known outcome in the lookback window and:

• chunk cited in a success task → priority += 0.02

• chunk cited in a rework/blocked task → priority −= 0.01

• passive retrievals ±0.005 (weaker signal)

Clamped to [0.1, 0.9]. Intended to run nightly via cron or after a batch of task-done events.

Args: lookback_days: How many days of retrievals to consider (default 7). dry_run: When True, compute changes without writing.

Returns: {adjusted, gained, lost, changes[], status} envelope.

Refresh .coding-os/digest.md from current memory state.

The digest is a ≤ 2.4 KB rolling snapshot of the agent's identity: active beliefs, fading patterns, recent breakthroughs, preferences. Session-startup reads this file to give the agent a coherent memory anchor before any retrieval fires.

Args: project_root: Override project root. Empty (default) uses cwd.

Returns: {path, size_chars, truncated, status} envelope.

Report mean retrieval precision over the lookback window.

Precision is derived from (was_cited, outcome) pairs on the retrievals table, so it's honest: a retrieval that was cited and led to success counts as 1.0; a cited retrieval that led to rework counts as 0.0. Used to decide whether contextual enrichment is worth the LLM cost.

Args: lookback_days: Window in days (default 14). layer: Optional layer filter ("memory"|"docs"|"tasks").

Returns: {mean_precision, samples, below_gate, gate, layer, status}.

Recommend whether to enable contextual retrieval enrichment.

The underlying LLM enrichment path is intentionally a stub — this tool exists so the decision is metric-driven and auditable before anyone pays the Haiku bill.

Args: lookback_days: Window of retrieval quality data (default 14).

Returns: {recommend: bool, reason, cost_warning?, summary}.

Return the next action the main agent should take: dispatch a formula-agent, backtrack, or signal done. Call repeatedly after recording each formula output via cos_supervise_record_output. Never spawns agents itself — only tells the main agent what to dispatch.

Append a formula-agent's output to the session EvidenceBundle and record the dispatch in formula_dispatches. Call after each formula-agent returns. status: ok|fail|timeout.

Return the rendered agent prompt and input slice for a formula-agent. The main agent uses this to construct the subagent dispatch. Does NOT spawn the subagent — returns prompt text only.

Run the 7-criteria Anti-Ambiguity gate over the session EvidenceBundle. Returns violations (formula, criterion, detail). Empty list = gate passes. Fires once at PLAN→EXECUTE; CLEAR 1 tasks skip this check.

Read-only audit: verify that tasks have doc anchors and that recent formula dispatches have matching evidence in the bundle. Idempotent and non-blocking. scope: task|project.

Record a backtrack event. Returns {count, advisory, suggested_action, root_cause_summary}. advisory fires at ≥3/≥5 backtracks. suggested_action gives a concrete next step when root_cause is supplied. root_cause_summary shows per-cause counts for this session.

Capture a mid-work discovery. decision=backtrack_now triggers an immediate backtrack recommendation. decision=record_for_later stores the discovery for session summary review.

Classify a set of signals into a situational dispatch chain id (incident-response, onboarding, scope-change, external-integration, design-review, existing-project-takeover) or null if none match. The matched situation overrides persona primary_formulas.

Bootstrap an existing-project-takeover session: sets the situation to existing-project-takeover, picks legacy-maintainer persona, and returns the first dispatch action (Analyst in reverse mode). Use when inheriting a legacy repo with no docs.

Extract TaskSignals (domain, action, novelty, urgency, scope, external_dependency, is_takeover, breaking_change, ...) from a prompt + optional memory/graph context. Replaces persona keyword matching. Under 500ms; cached per task_marker.

Compose an ordered formula-role chain from TaskSignals. Strategy: situation override > preset match > per-role scoring composer > hard fallback. Returns ComposedChain with provenance (preset_id, preset_version, effective_threshold, activations).

Return metadata for a formula-role (researcher..refactorer): prompt_prefix, tools_budget, intensity_steps, backtrack_triggers, criteria_required. Useful for the main agent before dispatch.

EXPLICIT, OPT-IN sub-agent spawn for one role. Costs ~5k tokens per call (system prompt + input slice + completion) and rebuilds context inside the sub-agent. PREFER lazy-loading: read src/core/thinking_os/agents/.md inline and produce the output schema yourself — same accuracy, far fewer tokens, no context rebuild penalty. Use this tool only when (a) the role's work is long-running and would dominate the main loop, or (b) you explicitly want a separate session for parallelism. If no SDK is available, returns status='skipped' and the main agent should execute the role's procedure inline.

Spawn multiple formula-agents concurrently via asyncio.gather. Use when the supervisor returns action='dispatch_parallel' (e.g. security_auditor layers). Each output is persisted to the bundle. Returns list of DispatchResults in input order.

Heuristic Cynefin + dimensions classifier. Reads a user prompt and returns {complexity, dimensions, reasoning, signals}. Optionally writes the gate marker so enforce-task-start.sh passes. Replaces the manual write-state.sh .thinking_os-gate step. Sub-second; deterministic; no LLM call.

Look up a symbol by a KNOWN short term, path, or uid (lexical + graph expansion). For a natural-language DESCRIPTION of code whose name you don't know, use cos_graph_search instead.

TIP: prefer SHORT terms ("sdk_dispatcher", "ClaudeSDKDispatcher.dispatch") or a literal path / uid. Long natural-language queries return weaker matches because the index is built from labels + docstrings, not free text.

UID scheme (also accepted as q): code:file: · code:function::: · code:class::: code:method:::. · code:module: doc:file: · doc:heading:#: · folder:

When the query looks like a path or uid and the lexical pass returns nothing, the tool falls back to a direct uid lookup so the agent gets a single-item hit instead of empty results.

Args: q: Short term, path, or uid (non-empty). NL queries work but degrade. kinds: Comma-separated filter of node kinds (e.g. "function,class,method"). Empty = all. limit: Max results (default 10). max_hops: Walk expansion depth (default 2). confidence_min: Edge confidence floor (default 0.3). include_spine: S3 — attach the CONTAINS-ancestor chain to each result for breadcrumbs.

Returns: JSON envelope with results array. See docs/engineering/graph_os-queries.md.

Return callers + callees + siblings + referenced docs around a symbol.

Args: uid_or_name: Node uid or fuzzy label. Uid scheme: code:file:<path> | code:function:<path>::<name> | code:class:<path>::<name> | code:module:<dotted> | doc:file:<path> | doc:heading:<path>#<slug>:<level> | folder:<path>. Raw repo paths (core/foo.py) are auto-resolved to code:file: / doc:file: / folder:; if all variants miss, a fuzzy label match is tried. Run cos_graph_query first to discover candidates. direction: "in" | "out" | "both". depth: BFS depth (default 1). include_content: When True, each returned node gains a content field with source text read from file_path:start_line..end_line (capped at 2000 chars, with truncated: bool). Silently skipped when the file is missing or the node has no file_path. (B21) include_evidence: JOIN evidence rows (costs ~2× tokens). include_spine: S3 — pulls the CONTAINS-ancestor chain (file → folder → …) so the UI can render breadcrumbs.

Group affected nodes by risk tier (will_break / should_review / context).

Args: uid: Fully-qualified node uid. Scheme: code:file:<path> | code:function:<path>::<name> | code:class:<path>::<name> | code:module:<dotted> | doc:file:<path> | folder:<path>. Raw repo paths (core/foo.py) are auto-resolved to code:file: / doc:file: / folder:. If unsure, run cos_graph_query first to discover the right uid. direction: "downstream" (callers — break if uid changes) | "upstream" (deps uid calls/imports) | "both". depth: BFS hop limit (default 3). confidence_min: Drop edges below this score (default 0.3, matching the function + HTTP route). visit_limit: BFS node-visit cap (1..50000, default 500). Raise when meta.walk_truncated is true.

Map changed files to affected symbols + downstream tasks + risk level.

Args: files: Comma-separated file paths (empty → echo empty envelope). scope: Label only; "working" | "staged" | "HEAD~1..HEAD". analyze_downstream: Walk transitive blast radius.

Forward execution walk from entry_uid until terminals.

Args: entry_uid: Function/method uid to start from, e.g. code:function:core/foo.py::bar. Raw paths or names are auto-resolved (file → code:file: then entry-point heuristic). Run cos_graph_query first if unsure. terminals: Comma-separated edge labels that stop the walk. max_steps: Hard cap on emitted steps.

Return the top-K nodes most similar to uid (difflib baseline).

Args: uid: Fully-qualified node uid (see cos_graph_impact for scheme). Raw repo paths are auto-resolved to code:file: / doc:file: / folder:. top_k: Number of similar nodes to return. confidence_min: Minimum similarity score (0.0–1.0).

Find code symbols from a NATURAL-LANGUAGE description (semantic + lexical + centrality). For a KNOWN name / path / uid, use cos_graph_query instead.

Args: query: Natural-language or code-ish query (e.g. "validate jwt token"). top_k: Number of results to return (1–50).

List inbound edges — "who references this?".

Args: uid: Fully-qualified node uid. Scheme: code:file:<path> | code:function:<path>::<name> | code:class:<path>::<name> | code:module:<dotted> | doc:file:<path> | folder:<path>. Raw repo paths are auto-resolved. kinds: Comma-separated edge types. Empty string (default) picks edge types automatically per node-kind — class nodes get constructs+has_param_type+is_decorated_by+inherits_from, function/method get calls+accesses_field+imports, files get imports+links_to+references_doc+contains. R4-02. limit: Max edges returned (default 100).

Shortest path between two nodes (either direction).

Args: source_uid: Origin uid (auto-resolves raw paths; see cos_graph_impact for the scheme). target_uid: Destination uid (same rules as source_uid). max_hops: BFS depth limit (default 5).

Export a subgraph as json | mermaid | dot.

Args: format: Output format (json / mermaid / dot). root_uid: Optional seed; empty walks the edge table. edge_types: Comma-separated edge filter (empty = all). max_nodes: Hard cap on node count. include_spine: S3 — also include the CONTAINS ancestor chain. mode: TASK-141 view-mode blend when no root is pinned — auto (semantic + contains, default), containment, dependencies, or processes. exclude_kinds: Comma-separated noise kinds to drop. Sentinel __default__ (default) applies the built-in noise list; empty string disables filtering.

Plan a rename — call-sites, docs, tests, strings, risk.

Args: uid: Symbol to rename. Scheme: code:function:<path>::<name> | code:class:<path>::<name> | code:module:<dotted>. Raw paths are auto-resolved when applicable. new_name: Replacement symbol name. check_strings: Also scan string literals for the old name.

Enumerate every handler declared in the graph (HTTP / MCP / gRPC / events / WS).

Top-N scored entry points (main / cli / http / cron / test) — TASK-081.

Louvain process clusters — response key is processes (not communities).

Resolve a natural-language label, path, or partial uid to canonical uids.

Use this BEFORE other cos_graph_* tools when you don't know the exact uid. Tries: direct uid → path/qualname → FTS5 full-text → LIKE fallback.

UID scheme: code:file: · code:function::: · code:class::: code:method:::. · code:module: doc:file: · doc:heading:#: · folder:

Args: q: Natural language ("the dispatcher function"), label ("ClaudeSDKDispatcher"), path ("adapters/claude/sdk_dispatcher.py"), or qualname ("Class.method"). kinds: Comma-separated kind filter (e.g. "function,method,class"). Empty = all. top: Max results (default 10).

Returns: JSON envelope with results (ranked list of {uid, kind, label, …}) and strategy (which resolution path matched).

Hub detection — surface high-degree (or high-betweenness) nodes.

Use to identify chokepoints / refactor priorities / nodes that demand extra review.

Args: metric: "degree" (cheap, default) or "betweenness" (expensive). top: Max nodes returned (default 20). kind: Optional kind filter (e.g. "function", "class"). Empty = all.

Returns: JSON envelope with nodes ranked by centrality score.

PageRank — node importance, optionally personalised by query.

Use for: knowledge condensation (top-N canonical concepts), query-personalised search ranking, documentation sourcing.

Args: query: Optional personalisation query ("auth", "graph backend"). Empty = global PageRank. top: Max nodes returned (default 20). kind: Optional kind filter. Empty = all. damping: PageRank damping factor (default 0.85). iterations: Power-iteration count (default 30).

Returns: JSON envelope with nodes ranked by PageRank score.

Detect circular dependencies as strongly-connected components.

Args: scope: "imports" (module-level circular deps, the design smell) or "calls" (function cycles incl. legitimate mutual recursion). top: Max cycles returned (default 20). min_size: Minimum SCC size to report (default 2).

Returns: JSON envelope with cycles (each {size, members}) + total_count.

List in-repo symbols with zero non-test inbound references (dead-code candidates).

Surfaces functions / methods / classes that nothing (outside tests) calls, constructs, subclasses, or type-references — the inverse of centrality. Candidates only: dynamic-dispatch / CLI-registered / externally-called symbols may appear; verify with cos_graph_references before deleting.

Args: kind: Optional filter — function | method | class. Empty = all three. top: Max candidates returned (default 50, max 500). include_tests: Count test-sourced edges + include test files (default False).

Returns: JSON envelope with dead (list) + total_count.

List prod function/method/class with zero inbound edge from any test (untested symbols).

Candidates only: indirect exercise (CLI / fixtures / dynamic dispatch) may not appear as a graph edge. Shell excluded (no call-graph).

Args: kind: Optional filter — function | method | class. Empty = all three. top: Max returned (default 50, max 500).

Returns: JSON envelope with untested (list) + total_count.

Graph blast-radius of a git revision range (base..head).

Resolves changed files via git diff --name-only base..head, then maps them to affected symbols + downstream consumers + risk (PR/review view).

Args: base: Base git revision (default HEAD~1). head: Head git revision (default HEAD). analyze_downstream: Walk transitive consumers (default True).

Returns: JSON envelope with range, files, symbols, downstream_consumers, risk_level.

Graph health snapshot — orphans, dangling edges, duplicates, backend status.

Call when graph queries return nothing or meta.backend_fallback=true.

Args: fix: If True, attempt safe repairs (delete dangling edges). Default False — use the report-only mode to see what would change first.

Returns: JSON envelope with healthy boolean, issues list, stats dict.