@planu/cli 4.10.6 → 4.10.7

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [4.10.7] - 2026-07-07
+
+### Bug Fixes
+- fix(SPEC-1114): reduce MCP token waste
+
+### Chores
+- chore(deps): update patch/minor dependencies
+- chore(planu): clear released pending specs
+
+
 ## [4.10.6] - 2026-07-07
 
 ### Bug Fixes
@@ -4199,4 +4209,4 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 - Mermaid diagram generation (architecture, sequence, state machine, ER, data flow)
 - Multi-language i18n (EN/ES/PT) for generated specs
 - Clean Architecture (hexagonal) — engine, tools, storage, types layers
-- 10,857 tests with ≥95% coverage
+- 10,857 tests with ≥95% coverage

package/dist/engine/local-first/tool-classification.d.ts

@@ -1,5 +1,6 @@
 import type { ToolClassification } from '../../types/tool-classification.js';
 export declare function getToolClassification(toolName: string): ToolClassification;
+export declare function hasExplicitToolClassification(toolName: string): boolean;
 export declare function isLocalFirstTool(toolName: string): boolean;
 export declare function requiresLlmByDefault(toolName: string): boolean;
 export declare function listToolClassifications(): ToolClassification[];

package/dist/engine/local-first/tool-classification.js

@@ -1,104 +1,295 @@
-const TOOL_CLASSIFICATIONS = new Map([
-    [
-        'create_spec',
-        {
-            toolName: 'create_spec',
-            executionClass: 'llm-required',
-            tokenPolicy: 'llm-product',
-            reason: 'Generates the primary spec artifact and needs language synthesis.',
-        },
-    ],
-    [
-        'validate',
-        {
-            toolName: 'validate',
-            executionClass: 'local',
-            tokenPolicy: 'summarize-first',
-            reason: 'Compares repository state and spec artifacts with deterministic validators.',
-        },
-    ],
-    [
-        'audit',
-        {
-            toolName: 'audit',
-            executionClass: 'local',
-            tokenPolicy: 'summarize-first',
-            reason: 'Runs deterministic checks and returns issue summaries.',
-        },
-    ],
-    [
-        'package_handoff',
-        {
-            toolName: 'package_handoff',
-            executionClass: 'local',
-            tokenPolicy: 'summarize-first',
-            reason: 'Packages existing spec and project context into an artifact reference.',
-        },
-    ],
-    [
-        'list_specs',
-        {
-            toolName: 'list_specs',
-            executionClass: 'local',
-            tokenPolicy: 'summarize-first',
-            reason: 'Lists indexed spec metadata and must stay read-only.',
-        },
-    ],
-    [
-        'summarize_spec',
-        {
-            toolName: 'summarize_spec',
-            executionClass: 'local',
-            tokenPolicy: 'summarize-first',
-            reason: 'Extracts bounded decision fields from an existing spec.',
-        },
-    ],
-    [
-        'generate_tests',
-        {
-            toolName: 'generate_tests',
-            executionClass: 'hybrid',
-            tokenPolicy: 'summarize-first',
-            reason: 'Can generate deterministic scaffolds locally; novel test design may need LLM input.',
-        },
-    ],
-    [
-        'recommend_model',
-        {
-            toolName: 'recommend_model',
-            executionClass: 'local',
-            tokenPolicy: 'no-llm',
-            reason: 'Uses local heuristics and project metadata for routing advice.',
-        },
-    ],
-    [
-        'multi_agent_review',
-        {
-            toolName: 'multi_agent_review',
-            executionClass: 'hybrid',
-            tokenPolicy: 'summarize-first',
-            reason: 'Local orchestration and evidence collection precede any LLM review synthesis.',
-        },
-    ],
-    [
-        'audit_specs_drift',
-        {
-            toolName: 'audit_specs_drift',
-            executionClass: 'local',
-            tokenPolicy: 'summarize-first',
-            reason: 'Diffs spec and implementation artifacts locally.',
-        },
-    ],
-    [
-        'orchestrate_runtime',
-        {
-            toolName: 'orchestrate_runtime',
-            executionClass: 'local',
-            tokenPolicy: 'no-llm',
-            reason: 'Selects runtime behavior from local state and explicit policy.',
-        },
-    ],
+const REGISTERED_TOOL_NAMES = [
+    'agent_run_history',
+    'analyze_spec_dependencies',
+    'approval_status',
+    'approve_spec',
+    'assess_merge_risk',
+    'assign_role',
+    'audit',
+    'audit_claude_config',
+    'audit_log_export',
+    'audit_schema_type_parity',
+    'audit_specs_drift',
+    'bump_spec_version',
+    'challenge_spec',
+    'check_compliance',
+    'check_config_health',
+    'check_spec_accuracy',
+    'check_versions',
+    'clarify_requirements',
+    'code_graph_status',
+    'compliance_coverage_report',
+    'compliance_gap_analysis',
+    'compliance_gate_status',
+    'compliance_score_report',
+    'config_health',
+    'configure_approval_policy',
+    'configure_code_graph',
+    'configure_compliance',
+    'configure_compliance_gate',
+    'configure_memory',
+    'configure_roles',
+    'configure_squad',
+    'configure_workers',
+    'consult_docs',
+    'context_budget',
+    'coverage_gap_analyzer',
+    'create_spec',
+    'data_retention_policy',
+    'define_spec_lint_rule',
+    'define_ui_contract',
+    'delete_spec_lint_rule',
+    'design_schema',
+    'detect_agent',
+    'detect_drift',
+    'discover_docs_url',
+    'discover_mcps',
+    'discover_registry',
+    'ears_lint',
+    'ecosystem_status',
+    'estimate',
+    'eval_rule',
+    'eval_skill',
+    'export_audit_trail',
+    'expose_spec_as_prompt',
+    'fix_schema_type_parity',
+    'free_tool',
+    'generate_adr',
+    'generate_api_client',
+    'generate_checklist',
+    'generate_compliance_report',
+    'generate_compliance_tests',
+    'generate_docs',
+    'generate_docs_site',
+    'generate_execution_plan',
+    'generate_orchestration_script',
+    'generate_rules',
+    'generate_skill',
+    'generate_sub_agent',
+    'generate_tests',
+    'generate_validation_schema',
+    'graph_specs',
+    'guided_tour',
+    'init_constitution',
+    'init_project',
+    'integrate_pm',
+    'issue_reviewer_token',
+    'learn_pattern',
+    'list_spec_lint_rules',
+    'list_spec_prompts',
+    'list_specs',
+    'manage_context',
+    'manage_git',
+    'manage_plugins',
+    'memory_status',
+    'oauth_status',
+    'onboarding_checklist',
+    'onboarding_progress',
+    'orchestrate',
+    'paradigm_report',
+    'pin_version',
+    'pro_tool',
+    'publish_registry',
+    'quick_start',
+    'reconcile_hooks',
+    'reconcile_rules',
+    'reconcile_skills',
+    'reconcile_spec',
+    'red_team',
+    'registry_install',
+    'registry_login',
+    'registry_logout',
+    'registry_publish',
+    'registry_search',
+    'registry_whoami',
+    'request_changes',
+    'reverse_engineer',
+    'rewrite_criteria_ears',
+    'run_mutation_hints',
+    'run_spec_lint',
+    'scaffold_plugin',
+    'scan_orphan_spec_refs',
+    'search_all_projects',
+    'set_locale',
+    'set_work_mode',
+    'skill_install',
+    'skill_search',
+    'spec_obesity_healer',
+    'squad_status',
+    'ssr_back_migration',
+    'start_oauth_flow',
+    'start_onboarding',
+    'suggest_mcp_server',
+    'suggest_mcps',
+    'suggest_stack',
+    'suggest_token_optimizer',
+    'suggest_tooling',
+    'summarize_spec',
+    'sync_ai_configs',
+    'tdd_scaffold',
+    'token_optimizer_status',
+    'tool',
+    'type_safety_gate',
+    'update_registry',
+    'update_status',
+    'update_status_batch',
+    'validate',
+    'validate_api_contract',
+    'validate_criteria_quality',
+    'validate_docs_registry',
+    'verify_spec_compliance',
+    'worker_status',
+];
+const LEGACY_OR_RUNTIME_TOOL_NAMES = [
+    'multi_agent_review',
+    'orchestrate_runtime',
+    'package_handoff',
+    'recommend_model',
+];
+const LLM_REQUIRED_TOOL_NAMES = ['create_spec'];
+const HYBRID_TOOL_NAMES = [
+    'challenge_spec',
+    'clarify_requirements',
+    'consult_docs',
+    'define_ui_contract',
+    'design_schema',
+    'estimate',
+    'eval_skill',
+    'generate_adr',
+    'generate_api_client',
+    'generate_checklist',
+    'generate_compliance_report',
+    'generate_compliance_tests',
+    'generate_docs',
+    'generate_docs_site',
+    'generate_execution_plan',
+    'generate_orchestration_script',
+    'generate_rules',
+    'generate_skill',
+    'generate_sub_agent',
+    'generate_tests',
+    'generate_validation_schema',
+    'multi_agent_review',
+    'paradigm_report',
+    'reconcile_spec',
+    'red_team',
+    'reverse_engineer',
+    'rewrite_criteria_ears',
+    'spec_obesity_healer',
+    'ssr_back_migration',
+    'suggest_mcp_server',
+    'suggest_mcps',
+    'suggest_stack',
+    'suggest_token_optimizer',
+    'suggest_tooling',
+    'tdd_scaffold',
+];
+const NO_LLM_LOCAL_TOOL_NAMES = [
+    'approval_status',
+    'approve_spec',
+    'check_versions',
+    'code_graph_status',
+    'config_health',
+    'configure_approval_policy',
+    'configure_code_graph',
+    'configure_compliance',
+    'configure_compliance_gate',
+    'configure_memory',
+    'configure_roles',
+    'configure_squad',
+    'configure_workers',
+    'context_budget',
+    'detect_agent',
+    'discover_docs_url',
+    'discover_mcps',
+    'discover_registry',
+    'ears_lint',
+    'free_tool',
+    'issue_reviewer_token',
+    'list_spec_lint_rules',
+    'list_spec_prompts',
+    'list_specs',
+    'manage_context',
+    'manage_git',
+    'manage_plugins',
+    'memory_status',
+    'oauth_status',
+    'orchestrate',
+    'orchestrate_runtime',
+    'package_handoff',
+    'pin_version',
+    'pro_tool',
+    'registry_install',
+    'registry_login',
+    'registry_logout',
+    'registry_publish',
+    'registry_search',
+    'registry_whoami',
+    'run_spec_lint',
+    'scan_orphan_spec_refs',
+    'search_all_projects',
+    'set_locale',
+    'set_work_mode',
+    'skill_install',
+    'skill_search',
+    'squad_status',
+    'start_oauth_flow',
+    'summarize_spec',
+    'token_optimizer_status',
+    'tool',
+    'update_registry',
+    'update_status',
+    'update_status_batch',
+    'validate',
+    'worker_status',
+];
+const EXPLICIT_TOOL_NAMES = new Set([
+    ...REGISTERED_TOOL_NAMES,
+    ...LEGACY_OR_RUNTIME_TOOL_NAMES,
 ]);
+const LLM_REQUIRED_TOOLS = new Set(LLM_REQUIRED_TOOL_NAMES);
+const HYBRID_TOOLS = new Set(HYBRID_TOOL_NAMES);
+const NO_LLM_LOCAL_TOOLS = new Set(NO_LLM_LOCAL_TOOL_NAMES);
+function executionClassFor(toolName) {
+    if (LLM_REQUIRED_TOOLS.has(toolName)) {
+        return 'llm-required';
+    }
+    if (HYBRID_TOOLS.has(toolName)) {
+        return 'hybrid';
+    }
+    return 'local';
+}
+function reasonFor(toolName, executionClass) {
+    if (executionClass === 'llm-required') {
+        return 'Creates the primary spec artifact and requires language synthesis from user intent.';
+    }
+    if (executionClass === 'hybrid') {
+        return 'Runs local discovery, validation, or scaffolding first; only synthesis/review steps should use LLM tokens.';
+    }
+    if (NO_LLM_LOCAL_TOOLS.has(toolName)) {
+        return 'Uses deterministic local project state and should not call an LLM by default.';
+    }
+    return 'Processes local project artifacts and returns bounded summaries before any model-facing handoff.';
+}
+function tokenPolicyFor(toolName, executionClass) {
+    if (executionClass === 'llm-required') {
+        return 'llm-product';
+    }
+    if (executionClass === 'local' && NO_LLM_LOCAL_TOOLS.has(toolName)) {
+        return 'no-llm';
+    }
+    return 'summarize-first';
+}
+function buildClassification(toolName) {
+    const executionClass = executionClassFor(toolName);
+    return {
+        toolName,
+        executionClass,
+        tokenPolicy: tokenPolicyFor(toolName, executionClass),
+        reason: reasonFor(toolName, executionClass),
+    };
+}
+const TOOL_CLASSIFICATIONS = new Map([...EXPLICIT_TOOL_NAMES].map((toolName) => [toolName, buildClassification(toolName)]));
 export function getToolClassification(toolName) {
     return (TOOL_CLASSIFICATIONS.get(toolName) ?? {
         toolName,
@@ -107,6 +298,9 @@ export function getToolClassification(toolName) {
         reason: 'Unregistered tools default to local preprocessing with bounded summaries.',
     });
 }
+export function hasExplicitToolClassification(toolName) {
+    return TOOL_CLASSIFICATIONS.has(toolName);
+}
 export function isLocalFirstTool(toolName) {
     return getToolClassification(toolName).executionClass !== 'llm-required';
 }

package/dist/tools/audit.js

@@ -139,8 +139,8 @@ export async function handleAudit(args) {
                     findingsCount: String(result.findings.length),
                 }),
             },
-            { type: 'text', text: JSON.stringify(output, null, 2) },
         ],
+        structuredContent: output,
     };
 }
 function scoreToGrade(score) {

package/dist/tools/challenge-spec.js

@@ -32,6 +32,7 @@ const ALL_FOCUS_AREAS = [
     'security',
     'data-consistency',
 ];
+const ACTIONABLE_RELEVANCE_MIN = 15;
 /**
  * SPEC-615 AC3: detect contradictions between spec criteria and prior decisions.
  * Mutates failureScenarios in place. Best-effort — never throws.
@@ -242,8 +243,16 @@ export async function handleChallengeSpec(args, server) {
         const match = prioritized.find((p) => p.scenario === s.scenario);
         return match !== undefined ? { ...s, relevanceScore: match.relevanceScore } : s;
     });
+    const prioritizedScenarios = new Set(prioritized.map((scenario) => scenario.scenario));
+    const actionableFailureScenarios = failureScenariosScored.filter((scenario) => prioritizedScenarios.has(scenario.scenario) ||
+        scenario.impact === 'critical' ||
+        scenario.impact === 'high' ||
+        isDomainRelevantScenario(scenario, specContent, knowledge) ||
+        (scenario.relevanceScore ?? computeScenarioRelevanceFallback(scenario)) >=
+            ACTIONABLE_RELEVANCE_MIN);
+    const suppressedScenarioCount = failureScenariosScored.length - actionableFailureScenarios.length;
     const analysis = {
-        failureScenarios: failureScenariosScored,
+        failureScenarios: actionableFailureScenarios,
         concurrencyAnalysis,
         scalabilityAssessment,
         overallRisk,
@@ -262,6 +271,8 @@ export async function handleChallengeSpec(args, server) {
         },
         summary: {
             totalScenarios: failureScenarios.length,
+            actionableScenarios: actionableFailureScenarios.length,
+            suppressedLowRelevanceScenarios: suppressedScenarioCount,
             shownByDefault: 3,
             mustAddressBeforeCoding: prioritizedSummary,
             criticalImpact: failureScenarios.filter((s) => s.impact === 'critical').length,
@@ -354,9 +365,48 @@ export async function handleChallengeSpec(args, server) {
                     scenarioCount: String(failureScenarios.length),
                 }),
             },
-            { type: 'text', text: JSON.stringify(analysisPayload, null, 2) },
+            {
+                type: 'text',
+                text: `Actionable scenarios: ${String(actionableFailureScenarios.length)}` +
+                    ` | Suppressed low-relevance: ${String(suppressedScenarioCount)}` +
+                    ` | Overall risk: ${overallRisk}`,
+            },
             { type: 'text', text: humanSummary },
         ],
+        structuredContent: analysisPayload,
     };
 }
+function computeScenarioRelevanceFallback(scenario) {
+    if (scenario.impact === 'critical') {
+        return 100;
+    }
+    if (scenario.impact === 'high') {
+        return 70;
+    }
+    if (scenario.probability === 'high') {
+        return 35;
+    }
+    return 0;
+}
+function isDomainRelevantScenario(scenario, specContent, knowledge) {
+    const haystack = `${scenario.scenario} ${scenario.currentHandling} ${scenario.requiredHandling}`
+        .toLowerCase()
+        .trim();
+    const specText = specContent.toLowerCase();
+    const framework = knowledge.framework?.toLowerCase() ?? '';
+    const isGameProject = knowledge.projectCategory === 'game' ||
+        ['unity', 'godot', 'unreal', 'bevy', 'phaser', 'pygame'].includes(framework);
+    if (isGameProject && /\b(game|physics|cheat|balance|save|hud|player)\b/.test(haystack)) {
+        return true;
+    }
+    if (/\b(database|query|index|pagination|transaction|cache)\b/.test(haystack) &&
+        /\b(database|query|index|pagination|transaction|cache|sql|postgres|sqlite)\b/.test(specText)) {
+        return true;
+    }
+    if (/\b(api|auth|jwt|session|csrf|injection|tenant|bola)\b/.test(haystack) &&
+        /\b(api|auth|jwt|session|csrf|injection|tenant|bola)\b/.test(specText)) {
+        return true;
+    }
+    return false;
+}
 //# sourceMappingURL=challenge-spec.js.map

package/dist/tools/check-readiness.js

@@ -6,6 +6,9 @@ import { buildCheckReadinessSummary } from '../engine/human-summary.js';
 import { validateSpecFormat } from '../core/spec-validator.js';
 import { resolveProjectId } from './resolve-project-id.js';
 // ── Formatting helpers ───────────────────────────────────────────────────────
+const MAX_VISIBLE_BLOCKERS = 8;
+const MAX_VISIBLE_WARNINGS = 8;
+const MAX_VISIBLE_RECOMMENDATIONS = 5;
 function formatScore(score) {
     if (score >= 90) {
         return `${score}/100 (Excellent)`;
@@ -50,34 +53,38 @@ function formatReport(report) {
     if (report.issues.blockers.length > 0) {
         lines.push('## Blockers');
         lines.push('');
-        for (const blocker of report.issues.blockers) {
+        for (const blocker of report.issues.blockers.slice(0, MAX_VISIBLE_BLOCKERS)) {
             lines.push(`- BLOCKER: ${blocker}`);
         }
+        if (report.issues.blockers.length > MAX_VISIBLE_BLOCKERS) {
+            lines.push(`- ...and ${String(report.issues.blockers.length - MAX_VISIBLE_BLOCKERS)} more`);
+        }
         lines.push('');
     }
     // Warnings
     if (report.issues.warnings.length > 0) {
         lines.push('## Warnings');
         lines.push('');
-        for (const warning of report.issues.warnings) {
+        for (const warning of report.issues.warnings.slice(0, MAX_VISIBLE_WARNINGS)) {
             lines.push(`- WARNING: ${warning}`);
         }
+        if (report.issues.warnings.length > MAX_VISIBLE_WARNINGS) {
+            lines.push(`- ...and ${String(report.issues.warnings.length - MAX_VISIBLE_WARNINGS)} more`);
+        }
         lines.push('');
     }
     // Recommendations
     if (report.recommendations.length > 0) {
         lines.push('## Recommendations');
         lines.push('');
-        for (const rec of report.recommendations) {
+        for (const rec of report.recommendations.slice(0, MAX_VISIBLE_RECOMMENDATIONS)) {
             lines.push(`- ${rec}`);
         }
+        if (report.recommendations.length > MAX_VISIBLE_RECOMMENDATIONS) {
+            lines.push(`- ...and ${String(report.recommendations.length - MAX_VISIBLE_RECOMMENDATIONS)} more`);
+        }
         lines.push('');
     }
-    // SPEC-042: Config health hint
-    lines.push('## Config Health');
-    lines.push('');
-    lines.push('- Run `check_config_health` to detect silent misconfigurations (tsconfig coverage, CI script references, build artifact gaps) that block DoR.');
-    lines.push('');
     return lines.join('\n');
 }
 // ── Handler ──────────────────────────────────────────────────────────────────

package/dist/tools/data-governance/audit-handler.js

@@ -3,6 +3,7 @@ import { specStore, knowledgeStore } from '../../storage/index.js';
 import { ti } from '../../i18n/index.js';
 import { detectPIIInSpec, detectLegalFramework } from '../../engine/pii-detector.js';
 import { readFile } from 'node:fs/promises';
+import { formatKeyValue } from '../output-formatter.js';
 // ---------------------------------------------------------------------------
 // privacy-notice subcommand
 // ---------------------------------------------------------------------------
@@ -40,14 +41,21 @@ export async function handlePrivacyNotice(projectId) {
             },
             {
                 type: 'text',
-                text: JSON.stringify({
+                text: formatKeyValue({
                     subcommand: 'privacy-notice',
                     specsWithPII: privacyItems.length,
                     totalSpecs: specs.length,
-                    noticeText: notice,
-                }, null, 2),
+                    noticeChars: notice.length,
+                }),
             },
         ],
+        structuredContent: {
+            subcommand: 'privacy-notice',
+            specsWithPII: privacyItems.length,
+            totalSpecs: specs.length,
+            noticeText: notice,
+            items: privacyItems,
+        },
     };
 }
 // ---------------------------------------------------------------------------
@@ -105,16 +113,23 @@ export async function handleAudit(projectId) {
             },
             {
                 type: 'text',
-                text: JSON.stringify({
+                text: formatKeyValue({
                     subcommand: 'audit',
                     totalSpecs: specs.length,
                     specsWithPII: auditItems.filter((i) => i.hasPII).length,
                     nonCompliantSpecs: nonCompliant,
                     framework,
-                    items: auditItems,
-                }, null, 2),
+                }),
             },
         ],
+        structuredContent: {
+            subcommand: 'audit',
+            totalSpecs: specs.length,
+            specsWithPII: auditItems.filter((i) => i.hasPII).length,
+            nonCompliantSpecs: nonCompliant,
+            framework,
+            items: auditItems,
+        },
     };
 }
 // ---------------------------------------------------------------------------