@planu/cli 4.10.5 → 4.10.7

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [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
+- fix(SPEC-1111): stabilize update_status done gates and evidence state transitions
+- fix(SPEC-1112): preserve validation-report lint evidence during done gate
+
+### Improvements
+- refactor(SPEC-1110): reduce MCP token payloads with local-first tool classification
+
+
 ## [4.10.5] - 2026-07-07
 
 ### Bug Fixes

package/dist/engine/compact/tool-list-compactor.d.ts

@@ -3,5 +3,5 @@ export declare function compactToolList(tools: unknown[]): Record<string, unknow
 /** Returns true when an outgoing JSON-RPC message is a tools/list result. */
 export declare function isToolsListResponse(message: unknown): boolean;
 /** Compact a tools/list JSON-RPC response message. Returns a new object. */
-export declare function compactToolsListMessage(message: Record<string, unknown>): Record<string, unknown>;
+export declare function compactToolsListMessage<T extends Record<string, unknown>>(message: T): T;
 //# sourceMappingURL=tool-list-compactor.d.ts.map

package/dist/engine/evidence-gates/lifecycle-gate.js

@@ -114,9 +114,25 @@ export function checkDoneEvidenceGate(spec, criteria, artifacts) {
             !hasText(row.validationEvidence) ||
             !hasText(row.reviewerEvidence));
         if (incompleteRows.length > 0) {
+            const rowDetails = incompleteRows.map((row) => {
+                const missing = [];
+                if (!rowHasEvidence(row)) {
+                    missing.push('scenario/testEvidence/contractEvidence/manualEvidence');
+                }
+                if (row.changedFiles.length === 0) {
+                    missing.push('changedFiles');
+                }
+                if (!hasText(row.validationEvidence)) {
+                    missing.push('validationEvidence');
+                }
+                if (!hasText(row.reviewerEvidence)) {
+                    missing.push('reviewerEvidence');
+                }
+                return `${row.acceptanceCriterion}: missing ${missing.join(', ')}`;
+            });
             issues.push({
                 code: 'traceability_incomplete_rows',
-                message: 'Traceability rows must include scenario/test/contract/manual evidence, changed files, validation evidence, and reviewer evidence.',
+                message: `Traceability rows must include evidence, changed files, validation evidence, and reviewer evidence. Incomplete rows: ${rowDetails.join('; ')}`,
             });
         }
     }

package/dist/engine/evidence-index/done-drift.js

@@ -33,9 +33,12 @@ export function checkDoneDriftContract(args) {
                 .map((record) => `${entry.criterion}: ${record.value}`);
         });
         if (unapproved.length > 0) {
+            const groundedHint = args.groundedTechnicalPaths.length > 0
+                ? ` Grounded technical paths: ${args.groundedTechnicalPaths.join(', ')}.`
+                : ' No grounded technical paths were found in the approved spec.';
             issues.push({
                 code: 'done_drift_unapproved_scope',
-                message: `Done drift check found changed files outside grounded spec scope: ${unapproved.join('; ')}`,
+                message: `Done drift check found changed files outside grounded spec scope: ${unapproved.join('; ')}.${groundedHint} Add the file to approved technical references or include reviewerEvidence with an approved scope amendment.`,
             });
         }
     }

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

@@ -0,0 +1,7 @@
+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[];
+//# sourceMappingURL=tool-classification.d.ts.map

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

@@ -0,0 +1,313 @@
+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,
+        executionClass: 'hybrid',
+        tokenPolicy: 'summarize-first',
+        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';
+}
+export function requiresLlmByDefault(toolName) {
+    return getToolClassification(toolName).executionClass === 'llm-required';
+}
+export function listToolClassifications() {
+    return [...TOOL_CLASSIFICATIONS.values()].sort((a, b) => a.toolName.localeCompare(b.toolName));
+}
+//# sourceMappingURL=tool-classification.js.map

package/dist/engine/qa-gate.js

@@ -20,7 +20,19 @@ function runCheck(name, command, args, cwd) {
     const durationMs = Date.now() - start;
     const passed = result.status === 0 && !result.error;
     const output = [result.stdout, result.stderr].join('\n').trim().slice(0, 2000);
-    return { name, passed, output, durationMs };
+    const errorCode = result.error && 'code' in result.error
+        ? String(result.error.code)
+        : undefined;
+    const timedOut = errorCode === 'ETIMEDOUT' || result.signal === 'SIGTERM';
+    return {
+        name,
+        passed,
+        output,
+        durationMs,
+        command: [command, ...args].join(' '),
+        timedOut,
+        errorMessage: result.error?.message,
+    };
 }
 export function runQaGate(spec, projectPath) {
     const coverageThreshold = extractCoverageThreshold(spec);

package/dist/engine/scope-boundaries/scope-validator.js

@@ -11,11 +11,23 @@ function normalize(text) {
 /**
  * Extract keywords from an out-of-scope item phrase (>3 chars).
  */
-const STOP_WORDS = new Set(['the', 'and', 'for', 'with', 'that', 'this', 'from', 'will']);
+const STOP_WORDS = new Set(['the', 'and', 'for', 'with', 'that', 'this', 'from', 'will', 'every']);
+const GENERIC_SCOPE_TOKENS = new Set([
+    'code',
+    'file',
+    'files',
+    'module',
+    'modules',
+    'mcp',
+    'response',
+    'responses',
+    'tool',
+    'tools',
+]);
 function keywords(phrase) {
     return normalize(phrase)
         .split(' ')
-        .filter((w) => w.length > 3 && !STOP_WORDS.has(w));
+        .filter((w) => w.length > 2 && !STOP_WORDS.has(w) && !GENERIC_SCOPE_TOKENS.has(w));
 }
 /**
  * Determine whether a file path matches an out-of-scope item.

package/dist/engine/validator/validation-report-writer.js

@@ -9,7 +9,7 @@ export async function writeImplementationReviewReport(input) {
         specCompliance,
         minimalityReport: input.minimalityReport,
     });
-    const mergedGates = await preserveUnobservedBlockingGates(input, gates);
+    const mergedGates = await preserveUnobservedGates(input, gates);
     const passed = mergedGates.every((gate) => gate.passed);
     const reviewer = {
         kind: 'implementation-review-agent',
@@ -56,7 +56,7 @@ export async function writeImplementationReviewReport(input) {
         };
     }
 }
-async function preserveUnobservedBlockingGates(input, nextGates) {
+async function preserveUnobservedGates(input, nextGates) {
     const currentGateNames = new Set(nextGates.map((gate) => gate.name));
     const explicitlyObserved = new Set([
         ...(input.lintPassed !== undefined ? ['lint'] : []),
@@ -71,8 +71,7 @@ async function preserveUnobservedBlockingGates(input, nextGates) {
     if (!existing?.ok) {
         return nextGates;
     }
-    const preserved = existing.payload.gates.filter((gate) => !gate.passed &&
-        currentGateNames.has(gate.name) &&
+    const preserved = existing.payload.gates.filter((gate) => currentGateNames.has(gate.name) &&
         !explicitlyObserved.has(gate.name) &&
         (gate.name === 'lint' ||
             gate.name === 'convention-regression' ||

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 ──────────────────────────────────────────────────────────────────