codesift-mcp 0.5.30 → 0.8.2

package/dist/register-tools.js

@@ -6,7 +6,7 @@ import { wrapTool, registerShortener } from "./server-helpers.js";
 import { detectProjectLanguagesSync } from "./utils/language-detect.js";
 import { STUB_LANGUAGES } from "./parser/stub-languages.js";
 import { getUsageStats, formatUsageReport } from "./storage/usage-stats.js";
-import { indexFolder, indexFile, indexRepo, listAllRepos, invalidateCache, getCodeIndex, searchSymbols, searchText, semanticSearch, getFileTree, getFileOutline, getRepoOutline, suggestQueries, getSymbol, getSymbols, findAndShow, findReferences, findReferencesBatch, findDeadCode, getContextBundle, formatRefsCompact, formatSymbolCompact, formatSymbolsCompact, formatBundleCompact, traceCallChain, traceComponentTree, analyzeHooks, analyzeRenders, buildContextGraph, auditCompilerReadiness, reactQuickstart, impactAnalysis, traceRoute, detectCommunities, assembleContext, getKnowledgeMap, diffOutline, changedSymbols, generateClaudeMd, codebaseRetrieval, analyzeComplexity, findClones, analyzeHotspots, crossRepoSearchSymbols, crossRepoFindReferences, searchPatterns, listPatterns, generateReport, goToDefinition, getTypeInfo, renameSymbol, getCallHierarchy, indexConversations, searchConversations, searchAllConversations, findConversationsForSymbol, scanSecrets, resolvePhpNamespace, tracePhpEvent, findPhpViews, resolvePhpService, phpSecurityScan, phpProjectAudit, consolidateMemories, readMemory, createAnalysisPlan, writeScratchpad, readScratchpad, listScratchpad, updateStepStatus, getPlan, listPlans, frequencyAnalysis, findExtensionFunctions, analyzeSealedHierarchy, traceSuspendChain, analyzeKmpDeclarations, traceFlowChain, traceHiltGraph, traceComposeTree, analyzeComposeRecomposition, traceRoomSchema, extractKotlinSerializationContract, astroAnalyzeIslands, astroHydrationAudit, astroRouteMap, astroActionsAudit, astroAudit, nextjsRouteMap, nextjsMetadataAudit, frameworkAudit, astroConfigAnalyze, astroContentCollections, analyzeProject, getExtractorVersions, getModelGraph, getTestFixtures, findFrameworkWiring, runRuff, parsePyproject, resolveConstantValue, effectiveDjangoViewSecurity, findPythonCallers, taintTrace, analyzeDjangoSettings, runMypy, runPyright, analyzePythonDeps, pythonAudit, traceFastAPIDepends, analyzeAsyncCorrectness, getPydanticModels, reviewDiff, auditScan, indexStatus, auditAgentConfig, testImpactAnalysis, dependencyAudit, migrationLint, planTurn, formatPlanTurnResult, astroMigrationCheck, analyzePrismaSchema, findPerfHotspots, fanInFanOut, coChangeAnalysis, architectureSummary, nestAudit, explainQuery, generateWiki, } from "./register-tool-loaders.js";
+import { indexFolder, indexFile, indexRepo, listAllRepos, invalidateCache, getCodeIndex, searchSymbols, searchText, semanticSearch, getFileTree, getFileOutline, getRepoOutline, suggestQueries, getSymbol, getSymbols, findAndShow, findReferences, findReferencesBatch, findDeadCode, getContextBundle, formatRefsCompact, formatSymbolCompact, formatSymbolsCompact, formatBundleCompact, traceCallChain, traceComponentTree, analyzeHooks, analyzeRenders, buildContextGraph, auditCompilerReadiness, reactQuickstart, impactAnalysis, traceRoute, detectCommunities, assembleContext, getKnowledgeMap, diffOutline, changedSymbols, generateClaudeMd, codebaseRetrieval, analyzeComplexity, findClones, analyzeHotspots, crossRepoSearchSymbols, crossRepoFindReferences, searchPatterns, listPatterns, generateReport, goToDefinition, getTypeInfo, renameSymbol, getCallHierarchy, indexConversations, searchConversations, searchAllConversations, findConversationsForSymbol, scanSecrets, resolvePhpNamespace, tracePhpEvent, findPhpViews, resolvePhpService, phpSecurityScan, phpProjectAudit, yii3MigrationAudit, php8CompatCheck, analyzeYiiModules, analyzeYiiMigrations, analyzeYiiRbac, findPhp8MigrationCandidates, analyzePhpStanBaseline, analyzeYiiConsoleCommands, findYii3AttributeCandidates, consolidateMemories, readMemory, usageHotspots, usageTraceSession, retrosList, retrosAnalyze, memoryCandidateExtract, optimizationCandidates, popeInsightsPushCandidates, createAnalysisPlan, writeScratchpad, readScratchpad, listScratchpad, updateStepStatus, getPlan, listPlans, frequencyAnalysis, findExtensionFunctions, analyzeSealedHierarchy, traceSuspendChain, analyzeKmpDeclarations, traceFlowChain, traceHiltGraph, traceComposeTree, analyzeComposeRecomposition, traceRoomSchema, extractKotlinSerializationContract, astroAnalyzeIslands, astroHydrationAudit, astroRouteMap, astroActionsAudit, astroAudit, nextjsRouteMap, nextjsMetadataAudit, frameworkAudit, astroConfigAnalyze, astroContentCollections, astroMiddlewareAudit, astroSessionsAudit, astroDbAudit, astroEnvValidator, astroImageAudit, astroSvgComponents, analyzeProject, getExtractorVersions, getModelGraph, getTestFixtures, findFrameworkWiring, runRuff, parsePyproject, resolveConstantValue, effectiveDjangoViewSecurity, findPythonCallers, taintTrace, analyzeDjangoSettings, runMypy, runPyright, analyzePythonDeps, pythonAudit, traceFastAPIDepends, analyzeAsyncCorrectness, getPydanticModels, reviewDiff, auditScan, indexStatus, auditAgentConfig, testImpactAnalysis, dependencyAudit, migrationLint, planTurn, formatPlanTurnResult, astroMigrationCheck, analyzePrismaSchema, findPerfHotspots, fanInFanOut, coChangeAnalysis, architectureSummary, nestAudit, explainQuery, generateWiki, } from "./register-tool-loaders.js";
 import { formatSnapshot, getContext, getSessionState } from "./storage/session-state.js";
 import { formatComplexityCompact, formatComplexityCounts, formatClonesCompact, formatClonesCounts, formatHotspotsCompact, formatHotspotsCounts, formatTraceRouteCompact, formatTraceRouteCounts } from "./formatters-shortening.js";
 import { formatSearchSymbols, formatFileTree, formatFileOutline, formatSearchPatterns, formatDeadCode, formatComplexity, formatClones, formatHotspots, formatRepoOutline, formatSuggestQueries, formatSecrets, formatConversations, formatRoles, formatAssembleContext, formatCommunities, formatCallTree, formatTraceRoute, formatKnowledgeMap, formatImpactAnalysis, formatDiffOutline, formatChangedSymbols, formatReviewDiff, formatPerfHotspots, formatFanInFanOut, formatCoChange, formatArchitectureSummary, formatNextjsRouteMap, formatNextjsMetadataAudit, formatFrameworkAudit } from "./formatters.js";
@@ -208,6 +208,15 @@ const FRAMEWORK_TOOL_GROUPS = {
         "resolve_php_service",
         "php_security_scan",
         "php_project_audit",
+        "yii3_migration_audit",
+        "php8_compat_check",
+        "analyze_yii_modules",
+        "analyze_yii_migrations",
+        "analyze_yii_rbac",
+        "find_php8_migration_candidates",
+        "analyze_phpstan_baseline",
+        "analyze_yii_console_commands",
+        "find_yii3_attribute_candidates",
         // PHP stacks (Yii2/Laravel/Symfony) overwhelmingly run on MySQL/Postgres with
         // raw .sql migrations and ActiveRecord models. The SQL toolchain is the
         // missing entry-point for schema/drift/lint/dml work — auto-revealing it
@@ -322,6 +331,70 @@ const FRAMEWORK_TOOL_GROUPS = {
         "analyze_prisma_schema",
         "migration_lint",
     ],
+    // Astro — detected by astro.config.{mjs,ts,cjs,js}. Auto-loads the full
+    // 13-tool Astro toolkit (7 core + 6 Astro 5 sub-tools from Tasks 2-7).
+    // astro_audit is the meta-tool entry point; sub-tools are listed for
+    // direct invocation via describe_tools.
+    "astro.config.mjs": [
+        "astro_route_map",
+        "astro_config_analyze",
+        "astro_content_collections",
+        "astro_actions_audit",
+        "astro_migration_check",
+        "astro_analyze_islands",
+        "astro_audit",
+        "astro_middleware",
+        "astro_sessions",
+        "astro_db_audit",
+        "astro_env_validator",
+        "astro_image_audit",
+        "astro_svg_components",
+    ],
+    "astro.config.ts": [
+        "astro_route_map",
+        "astro_config_analyze",
+        "astro_content_collections",
+        "astro_actions_audit",
+        "astro_migration_check",
+        "astro_analyze_islands",
+        "astro_audit",
+        "astro_middleware",
+        "astro_sessions",
+        "astro_db_audit",
+        "astro_env_validator",
+        "astro_image_audit",
+        "astro_svg_components",
+    ],
+    "astro.config.cjs": [
+        "astro_route_map",
+        "astro_config_analyze",
+        "astro_content_collections",
+        "astro_actions_audit",
+        "astro_migration_check",
+        "astro_analyze_islands",
+        "astro_audit",
+        "astro_middleware",
+        "astro_sessions",
+        "astro_db_audit",
+        "astro_env_validator",
+        "astro_image_audit",
+        "astro_svg_components",
+    ],
+    "astro.config.js": [
+        "astro_route_map",
+        "astro_config_analyze",
+        "astro_content_collections",
+        "astro_actions_audit",
+        "astro_migration_check",
+        "astro_analyze_islands",
+        "astro_audit",
+        "astro_middleware",
+        "astro_sessions",
+        "astro_db_audit",
+        "astro_env_validator",
+        "astro_image_audit",
+        "astro_svg_components",
+    ],
 };
 /**
  * React-specific tools — auto-enabled when a React project is detected.
@@ -685,7 +758,7 @@ export const OutputSchemas = {
         edits: z.array(z.object({ file: z.string(), changes: z.number() })),
     }),
     /** usage_stats */
-    usageStats: z.object({ report: z.string() }),
+    usageStats: z.object({ report: z.string() }).passthrough(),
     /** list_repos */
     repoList: z.union([z.array(z.string()), z.array(z.object({ name: z.string() }).passthrough())]),
 };
@@ -716,6 +789,13 @@ export const CORE_TOOL_NAMES = new Set([
     "trace_call_chain", // 15 calls, 100% direct
     "suggest_queries", // 13 calls, 13 sessions
     "usage_stats", // 11 calls, 100% direct
+    "usage_hotspots", // PopeInsights: find expensive CodeSift patterns
+    "usage_trace_session", // PopeInsights: inspect one CodeSift session
+    "retros_list", // PopeInsights: inspect Zuvo retros
+    "retros_analyze", // PopeInsights: aggregate Zuvo friction
+    "memory_candidate_extract", // PopeInsights: extract memory candidates
+    "optimization_candidates", // PopeInsights: rank tool/skill improvements
+    "pope_insights_push_candidates",
     "get_knowledge_map", // 10 calls, 100% direct
     "get_repo_outline", // 9 calls, 100% direct
     "trace_route", // 9 calls, 100% direct
@@ -2713,6 +2793,206 @@ const TOOL_DEFINITIONS = [
             return await phpProjectAudit(args.repo, opts);
         },
     },
+    {
+        name: "yii3_migration_audit",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "yii2 yii3 migration audit decision support upgrade php8 active record module rbac authmanager service locator yii::$app legacy modernization effort estimate",
+        description: "Yii2→Yii3 migration audit. Inventories Yii2-specific API usage across 21 categories (service-locator, ActiveRecord, Module, RBAC, console, migrations, widgets, view, url-manager, ...) with severity, sample evidence, and an effort_estimate. Returns a decision_signal (stay-on-yii2 / consider-yii3 / high-effort-yii3 / blocked) so engineering leadership can choose between staying on Yii 2.0.49+ with PHP 8 vs migrating to Yii3.",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Substring filter on file paths"),
+            max_samples_per_category: z.number().optional().describe("Cap on sample evidence per category (default 5)"),
+            include_vendor: z.boolean().optional().describe("Include vendor/ paths in scan (default false)"),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.file_pattern === "string")
+                opts.file_pattern = args.file_pattern;
+            if (typeof args.max_samples_per_category === "number") {
+                opts.max_samples_per_category = args.max_samples_per_category;
+            }
+            if (typeof args.include_vendor === "boolean")
+                opts.include_vendor = args.include_vendor;
+            return await yii3MigrationAudit(args.repo, opts);
+        },
+    },
+    {
+        name: "php8_compat_check",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "php 8 upgrade compatibility breaking changes deprecation each create_function real cast money_format array_key_exists null string param utf8 spread operator dynamic property merge gate yii2 2.0.49",
+        description: "PHP 7→8 upgrade compatibility check. Pre-merge gating tool: scans for breaking changes (8.0) and deprecations (8.1/8.2) and flags Yii < 2.0.49 (which has known PHP 8 bugs). Run before merging the PHP 8 upgrade branch into main. Returns blocker_for_merge=true when any breaking_8_0 finding is present.",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Substring filter on file paths"),
+            max_samples_per_rule: z.number().optional().describe("Cap on sample evidence per rule (default 5)"),
+            include_vendor: z.boolean().optional().describe("Include vendor/ paths in scan (default false)"),
+            rules: z.string().optional().describe("Comma-separated rule IDs to run (default: all)"),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.file_pattern === "string")
+                opts.file_pattern = args.file_pattern;
+            if (typeof args.max_samples_per_rule === "number") {
+                opts.max_samples_per_rule = args.max_samples_per_rule;
+            }
+            if (typeof args.include_vendor === "boolean")
+                opts.include_vendor = args.include_vendor;
+            if (typeof args.rules === "string" && args.rules.trim()) {
+                opts.rules = args.rules.split(",").map((s) => s.trim()).filter(Boolean);
+            }
+            return await php8CompatCheck(args.repo, opts);
+        },
+    },
+    {
+        name: "analyze_yii_modules",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "yii2 module modules controllerNamespace structure routing inventory submodule per-module migrations views",
+        description: "Inventory Yii2 modules in a codebase. For each module returns id, controllerNamespace (declared or default), controllers + actions, views_count, migrations_path/count, sub-modules, and URL prefixes resolved from urlManager rules. Yii2 advanced/standard template friendly.",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            module_id: z.string().optional().describe("Filter to a single module id"),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.module_id === "string")
+                opts.module_id = args.module_id;
+            return await analyzeYiiModules(args.repo, opts);
+        },
+    },
+    {
+        name: "analyze_yii_migrations",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "yii2 migration migrations PHP DSL safeUp safeDown createTable dropTable addColumn dropColumn alterColumn addForeignKey createIndex online ddl ALGORITHM INPLACE LOCK NONE irreversible audit",
+        description: "Audit Yii2 PHP-DSL migrations. Parses extends Migration classes — createTable / dropTable / addColumn / dropColumn / alterColumn / createIndex / addForeignKey / etc — into structured operations and runs per-migration audit checks: missing-safe-down, alter-without-online-ddl (high — destructive ops on large tables without ALGORITHM=INPLACE/LOCK=NONE hint), fk-without-index (medium — addForeignKey without preceding createIndex), raw-sql-without-comment. Closes the gap that the generic SQL toolchain (migration_lint) misses because it only parses .sql files.",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Substring filter on migration file paths"),
+            rules: z.string().optional().describe("Comma-separated rule IDs to run (default: all). Available: missing-safe-down, alter-without-online-ddl, fk-without-index, raw-sql-without-comment, drop-without-safety"),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.file_pattern === "string")
+                opts.file_pattern = args.file_pattern;
+            if (typeof args.rules === "string" && args.rules.trim()) {
+                opts.rules = args.rules.split(",").map((s) => s.trim()).filter(Boolean);
+            }
+            return await analyzeYiiMigrations(args.repo, opts);
+        },
+    },
+    {
+        name: "analyze_yii_rbac",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "yii2 rbac authManager createPermission createRole addChild can() AccessControl behaviors orphan unused permission audit dektrium dbmanager phpmanager",
+        description: "Yii2 RBAC permission graph audit. Cross-references permission/role definitions in seed migrations + RBAC seeders against runtime checks (Yii::$app->user->can() + AccessControl behaviors). Returns orphan_checks (checked but never defined — typo / dead code), unused_definitions (defined but never checked — dead seed), controllers_without_access_control (classes named *Controller without AccessControl in behaviors() and no can() calls), and dynamic_creates (createPermission(\\$var) sites that need manual review).",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            include_vendor: z.boolean().optional().describe("Include vendor/ paths (default false)"),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.include_vendor === "boolean")
+                opts.include_vendor = args.include_vendor;
+            return await analyzeYiiRbac(args.repo, opts);
+        },
+    },
+    {
+        name: "find_php8_migration_candidates",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "php 8 modernization candidates promoted constructor typed properties readonly enum match docblock @var migration upgrade modernize",
+        description: "Find PHP 8 modernization candidates after a 7→8 upgrade. Surfaces 6 rule classes: promotable-ctor (collapse self-assignment ctor to promoted form), docblock-to-typed-property (convert /** @var T */ to inline `public T $x`), nullable-flag-to-syntax (`@var T|null` → `?T`), readonly-candidate (ctor-only assigned property → add readonly), enum-from-class-consts (pre-enum bag-of-constants → backed enum), match-from-switch (all-return switch → match expression). Each finding includes a suggested_replacement string and confidence rating; the tool never auto-applies changes.",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Substring filter on file paths"),
+            max_samples_per_rule: z.number().optional().describe("Cap on sample evidence per rule (default 5)"),
+            include_vendor: z.boolean().optional().describe("Include vendor/ paths (default false)"),
+            rules: z.string().optional().describe("Comma-separated rule IDs to run (default: all)"),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.file_pattern === "string")
+                opts.file_pattern = args.file_pattern;
+            if (typeof args.max_samples_per_rule === "number") {
+                opts.max_samples_per_rule = args.max_samples_per_rule;
+            }
+            if (typeof args.include_vendor === "boolean")
+                opts.include_vendor = args.include_vendor;
+            if (typeof args.rules === "string" && args.rules.trim()) {
+                opts.rules = args.rules.split(",").map((s) => s.trim()).filter(Boolean);
+            }
+            return await findPhp8MigrationCandidates(args.repo, opts);
+        },
+    },
+    {
+        name: "analyze_phpstan_baseline",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "phpstan baseline neon parse error categorize quick wins debt ledger triage",
+        description: "Parse a phpstan-baseline.neon file and triage ignored errors. Returns by_path (files ranked by error count), by_category (no-return-type, undefined-property, iterable-no-value-type, ...), quick_wins (files with ≤3 errors — fastest to clear), and full entries list. Universal PHP tool — works on any project that uses PHPStan, not Yii2-only.",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            baseline_path: z.string().optional().describe("Override baseline file path (default: phpstan-baseline.neon)"),
+            max_paths: z.number().optional().describe("Cap on by_path entries (default 50)"),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.baseline_path === "string")
+                opts.baseline_path = args.baseline_path;
+            if (typeof args.max_paths === "number")
+                opts.max_paths = args.max_paths;
+            return await analyzePhpStanBaseline(args.repo, opts);
+        },
+    },
+    {
+        name: "analyze_yii_console_commands",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "yii2 console commands controllers cron jobs cli action arguments ExitCode flags risk audit unbounded",
+        description: "Inventory Yii2 console controllers (extends yii\\console\\Controller). For each action returns CLI id, typed argument list, variadic flag, docstring, and risk flags: exits-without-return-status (cron can't tell success from failure), has-unbounded-all (memory bomb), has-no-error-handling (no try/catch), uses-output-via-echo (use stdout/stderr instead). Cross-controller `high_risk_actions` summary surfaces actions with ≥2 flags.",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            controller_id: z.string().optional().describe("Filter to a single controller cli_id"),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.controller_id === "string")
+                opts.controller_id = args.controller_id;
+            return await analyzeYiiConsoleCommands(args.repo, opts);
+        },
+    },
+    {
+        name: "find_yii3_attribute_candidates",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "yii3 attribute candidates conversion behaviors rules urlManager route migration php8 attributes",
+        description: "Find Yii2→Yii3 attribute conversion candidates. Three rule classes: behaviors-to-attributes (behaviors() with TimestampBehavior etc → #[Behavior(class)]), rules-to-attributes (rules() entries → #[Required], #[Email], etc on properties), urlmanager-rule-to-route (urlManager rules → #[Route(method, path)] on controller actions, with <id:\\d+> placeholders converted to {id}). Each candidate ships current_form, suggested_replacement, confidence, and blockers[] for cases that need manual review (closures in config, regex constraints, module-prefixed targets).",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Substring filter on file paths"),
+            max_samples_per_rule: z.number().optional().describe("Cap on sample evidence per rule (default 5)"),
+            include_vendor: z.boolean().optional().describe("Include vendor/ paths (default false)"),
+            rules: z.string().optional().describe("Comma-separated rule IDs to run (default: all)"),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.file_pattern === "string")
+                opts.file_pattern = args.file_pattern;
+            if (typeof args.max_samples_per_rule === "number") {
+                opts.max_samples_per_rule = args.max_samples_per_rule;
+            }
+            if (typeof args.include_vendor === "boolean")
+                opts.include_vendor = args.include_vendor;
+            if (typeof args.rules === "string" && args.rules.trim()) {
+                opts.rules = args.rules.split(",").map((s) => s.trim()).filter(Boolean);
+            }
+            return await findYii3AttributeCandidates(args.repo, opts);
+        },
+    },
     // --- Memory consolidation ---
     {
         name: "consolidate_memories",
@@ -2897,15 +3177,132 @@ const TOOL_DEFINITIONS = [
         searchHint: "usage statistics tool calls tokens timing metrics",
         outputSchema: OutputSchemas.usageStats,
         description: "Show usage statistics for all CodeSift tool calls (call counts, tokens, timing, repos)",
-        schema: lazySchema(() => ({})),
-        handler: async () => {
-            const stats = await getUsageStats();
+        schema: lazySchema(() => ({
+            since: z.string().optional().describe("ISO date/time lower bound, e.g. 2026-05-01"),
+            repo: z.string().optional().describe("Exact CodeSift repo key"),
+            tool: z.string().optional().describe("Exact tool name"),
+            session_id: z.string().optional().describe("Exact CodeSift session id"),
+        })),
+        handler: async (args) => {
+            const filters = {};
+            if (typeof args.since === "string")
+                filters.since = args.since;
+            if (typeof args.repo === "string")
+                filters.repo = args.repo;
+            if (typeof args.tool === "string")
+                filters.tool = args.tool;
+            if (typeof args.session_id === "string")
+                filters.session_id = args.session_id;
+            const stats = await getUsageStats(filters);
             const { createRequire } = await import("node:module");
             const req = createRequire(import.meta.url);
             const pkgVersion = req("../package.json").version;
-            return { version: pkgVersion, report: formatUsageReport(stats) };
+            return { version: pkgVersion, filters: args, stats, report: formatUsageReport(stats) };
         },
     },
+    {
+        name: "usage_hotspots",
+        category: "meta",
+        searchHint: "PopeInsights usage hotspots slow tools high tokens duplicate calls optimize CodeSift",
+        description: "Analyze ~/.codesift/usage.jsonl for slow tools, token-heavy outputs, and repeated calls.",
+        schema: lazySchema(() => ({
+            since: z.string().optional().describe("ISO date/time lower bound, e.g. 2026-05-01"),
+            repo: z.string().optional().describe("Exact CodeSift repo key"),
+            tool: z.string().optional().describe("Exact tool name"),
+            session_id: z.string().optional().describe("Exact CodeSift session id"),
+            limit: zNum().describe("Optional row limit for returned repeated calls"),
+        })),
+        handler: async (args) => usageHotspots(args),
+    },
+    {
+        name: "usage_trace_session",
+        category: "meta",
+        searchHint: "PopeInsights trace usage session timeline tool calls elapsed tokens",
+        description: "Show the timeline of CodeSift tool calls for one usage.jsonl session.",
+        schema: lazySchema(() => ({
+            session_id: z.string().describe("CodeSift session id"),
+            limit: zNum().describe("Max calls to return"),
+        })),
+        handler: async (args) => {
+            const input = { session_id: args.session_id };
+            if (typeof args.limit === "number")
+                input.limit = args.limit;
+            return usageTraceSession(input);
+        },
+    },
+    {
+        name: "retros_list",
+        category: "meta",
+        searchHint: "PopeInsights Zuvo retros list project skill friction retrospective",
+        description: "List Zuvo retros from ~/.zuvo/retros.log and ~/.zuvo/retros.md with filters.",
+        schema: lazySchema(() => ({
+            project: z.string().optional().describe("Project key, e.g. codesift-mcp"),
+            skill: z.string().optional().describe("Zuvo skill name"),
+            friction_category: z.string().optional().describe("Friction category"),
+            since: z.string().optional().describe("ISO date/time lower bound"),
+            limit: zNum().describe("Max retros to return"),
+            zuvo_dir: z.string().optional().describe("Override Zuvo dir. Default ~/.zuvo"),
+        })),
+        handler: async (args) => retrosList(args),
+    },
+    {
+        name: "retros_analyze",
+        category: "meta",
+        searchHint: "PopeInsights Zuvo retros analyze friction skill gaps missing templates routing failures",
+        description: "Aggregate Zuvo retros into friction, project, and missing-template hotspots.",
+        schema: lazySchema(() => ({
+            project: z.string().optional().describe("Project key, e.g. codesift-mcp"),
+            skill: z.string().optional().describe("Zuvo skill name"),
+            friction_category: z.string().optional().describe("Friction category"),
+            since: z.string().optional().describe("ISO date/time lower bound"),
+            limit: zNum().describe("Max retros to analyze"),
+            zuvo_dir: z.string().optional().describe("Override Zuvo dir. Default ~/.zuvo"),
+        })),
+        handler: async (args) => retrosAnalyze(args),
+    },
+    {
+        name: "memory_candidate_extract",
+        category: "meta",
+        searchHint: "PopeInsights memory candidates extract Zuvo proposals promote PopeMemory evidence",
+        description: "Extract evidence-backed memory candidates from Zuvo retros proposals.",
+        schema: lazySchema(() => ({
+            project: z.string().optional().describe("Project key"),
+            skill: z.string().optional().describe("Zuvo skill name"),
+            since: z.string().optional().describe("ISO date/time lower bound"),
+            limit: zNum().describe("Max candidates to return"),
+            zuvo_dir: z.string().optional().describe("Override Zuvo dir. Default ~/.zuvo"),
+        })),
+        handler: async (args) => memoryCandidateExtract(args),
+    },
+    {
+        name: "optimization_candidates",
+        category: "meta",
+        searchHint: "PopeInsights optimization candidates usage retros CodeSift tools Zuvo skills",
+        description: "Combine usage hotspots and Zuvo retros into ranked optimization candidates.",
+        schema: lazySchema(() => ({
+            since: z.string().optional().describe("ISO date/time lower bound"),
+            repo: z.string().optional().describe("Exact CodeSift repo key for usage filtering"),
+            project: z.string().optional().describe("Zuvo project key for retros filtering"),
+            skill: z.string().optional().describe("Zuvo skill name"),
+            zuvo_dir: z.string().optional().describe("Override Zuvo dir. Default ~/.zuvo"),
+        })),
+        handler: async (args) => optimizationCandidates(args),
+    },
+    {
+        name: "pope_insights_push_candidates",
+        category: "meta",
+        searchHint: "PopeInsights push candidates PopeBot API dry run",
+        description: "Push generated optimization candidates to PopeBot /api/insights/ingest. Defaults to dry_run=true.",
+        schema: lazySchema(() => ({
+            server: z.string().optional().describe("PopeBot base URL or /api/insights URL"),
+            api_key: z.string().optional().describe("PopeBot API key. Required only with dry_run=false"),
+            dry_run: zBool().describe("Return payload without network write. Default true"),
+            since: z.string().optional().describe("ISO date/time lower bound"),
+            repo: z.string().optional().describe("Exact CodeSift repo key for usage filtering"),
+            zuvo_dir: z.string().optional().describe("Override Zuvo dir. Default ~/.zuvo"),
+        })),
+        handler: async (args) => popeInsightsPushCandidates(args),
+    },
     // ── Session context tools ───────────────────────────────────────────────
     {
         name: "get_session_snapshot",
@@ -3560,6 +3957,115 @@ const TOOL_DEFINITIONS = [
             return await astroAudit(opts);
         },
     },
+    // --- Astro 5 sub-tools (Task 12). Discoverable via describe_tools — NOT in CORE. ---
+    {
+        name: "astro_middleware",
+        category: "analysis",
+        searchHint: "astro middleware onRequest sequence guards routes protected auth flows",
+        description: "Parses src/middleware.ts (or .js) — detects onRequest exports, sequence(...) ordering, and guard if-blocks lacking redirect/throw/return Response. Issue codes MW00–MW03.",
+        schema: lazySchema(() => ({
+            project_root: z.string().optional().describe("Absolute path to project root (default: auto-detected)"),
+            repo: z.string().optional(),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (args.project_root != null)
+                opts.project_root = args.project_root;
+            if (args.repo != null)
+                opts.repo = args.repo;
+            return await astroMiddlewareAudit(opts);
+        },
+    },
+    {
+        name: "astro_sessions",
+        category: "analysis",
+        searchHint: "astro sessions experimental session adapter compatibility node vercel cloudflare",
+        description: "Astro 5 Sessions API audit. Detects Astro.session.* / context.session.* usage; cross-checks experimental.session config + adapter compatibility. Issue codes SE01–SE04.",
+        schema: lazySchema(() => ({
+            project_root: z.string().optional(),
+            repo: z.string().optional(),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (args.project_root != null)
+                opts.project_root = args.project_root;
+            if (args.repo != null)
+                opts.repo = args.repo;
+            return await astroSessionsAudit(opts);
+        },
+    },
+    {
+        name: "astro_db_audit",
+        category: "analysis",
+        searchHint: "astro db defineTable schema columns foreign key index n+1 query loop",
+        description: "Astro DB audit. Parses db/config.ts defineTable schemas; detects N+1 query patterns (db.select inside loops via AST), missing FK indexes (per-table scoped), reference cycles. Codes DB00–DB04.",
+        schema: lazySchema(() => ({
+            project_root: z.string().optional(),
+            repo: z.string().optional(),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (args.project_root != null)
+                opts.project_root = args.project_root;
+            if (args.repo != null)
+                opts.repo = args.repo;
+            return await astroDbAudit(opts);
+        },
+    },
+    {
+        name: "astro_env_validator",
+        category: "analysis",
+        searchHint: "astro env envField schema astro:env client server context import.meta.env",
+        description: "Astro 5 astro:env validator. Parses env.schema (envField) and cross-checks against import.meta.env + astro:env/{client,server} imports. Codes EV01–EV04.",
+        schema: lazySchema(() => ({
+            project_root: z.string().optional(),
+            repo: z.string().optional(),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (args.project_root != null)
+                opts.project_root = args.project_root;
+            if (args.repo != null)
+                opts.repo = args.repo;
+            return await astroEnvValidator(opts);
+        },
+    },
+    {
+        name: "astro_image_audit",
+        category: "analysis",
+        searchHint: "astro image img alt accessibility Picture astro:assets getImage optimization",
+        description: "Scans .astro pages for image usage: raw <img> vs <Image>/<Picture>, missing/empty alt attributes, getImage() without astro:assets import. Codes IM01–IM04.",
+        schema: lazySchema(() => ({
+            project_root: z.string().optional(),
+            repo: z.string().optional(),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (args.project_root != null)
+                opts.project_root = args.project_root;
+            if (args.repo != null)
+                opts.repo = args.repo;
+            return await astroImageAudit(opts);
+        },
+    },
+    {
+        name: "astro_svg_components",
+        category: "analysis",
+        searchHint: "astro svg component import legacy ?component native astro 5",
+        description: "Detects *.svg?component imports, tracks per-file usage, flags legacy ?component on Astro 5+, surfaces PascalCase tags used without imports. Codes SV01–SV03.",
+        schema: lazySchema(() => ({
+            project_root: z.string().optional(),
+            repo: z.string().optional(),
+        })),
+        handler: async (args) => {
+            const opts = {};
+            if (args.project_root != null)
+                opts.project_root = args.project_root;
+            if (args.repo != null)
+                opts.repo = args.repo;
+            return await astroSvgComponents(opts);
+        },
+    },
     // --- Hono framework tools (Task 23) ---
     {
         name: "trace_middleware_chain",
@@ -4129,12 +4635,24 @@ export function extractToolParams(def) {
 export function getToolDefinition(name) {
     return TOOL_DEFINITION_MAP.get(name);
 }
+// Cache for describeTools results. Schemas are deterministic per name set and
+// never change within a process — telemetry showed 263/559 calls were duplicates
+// within a session. Key = sorted-joined names, value = computed result. No TTL.
+const describeToolsCache = new Map();
+/** Reset the describeTools cache. Test-only — not exported via index. */
+export function resetDescribeToolsCacheForTesting() {
+    describeToolsCache.clear();
+}
 /**
  * Return full param details for a specific list of tool names.
  * Unknown names are collected in not_found.
  */
 export function describeTools(names) {
     const capped = names.slice(0, 100); // CQ6 cap
+    const cacheKey = [...capped].sort().join("");
+    const cached = describeToolsCache.get(cacheKey);
+    if (cached)
+        return cached;
     const tools = [];
     const not_found = [];
     for (const name of capped) {
@@ -4151,7 +4669,9 @@ export function describeTools(names) {
             params: extractToolParams(def),
         });
     }
-    return { tools, not_found };
+    const result = { tools, not_found };
+    describeToolsCache.set(cacheKey, result);
+    return result;
 }
 /**
  * Search tool catalog by keyword. Returns matching tools with descriptions.