@planu/cli 4.10.5 → 4.10.6

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [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
@@ -4189,4 +4199,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/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,6 @@
+import type { ToolClassification } from '../../types/tool-classification.js';
+export declare function getToolClassification(toolName: string): ToolClassification;
+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,119 @@
+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.',
+        },
+    ],
+]);
+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 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/list-specs.js

@@ -4,16 +4,15 @@ import { buildListSpecsSummary } from '../engine/human-summary.js';
 import { dirname } from 'node:path';
 import { checkBundledVersionGap } from '../engine/version-detector/bundled-version-checker.js';
 import { readLastModifiedTimestamp, formatRelativeDate } from '../engine/spec-changelog/index.js';
-import { discoverAndFlattenSpecs, filterUnprefixedSpecs, importFilesystemSpecs, migrateSpecFolderNames, reconcileSpecPaths, scanForAmbiguousCriteria, } from '../engine/spec-migrator.js';
+import { scanForAmbiguousCriteria } from '../engine/spec-migrator.js';
 import { detectDrift, formatDriftMessage } from '../engine/spec-migrator/drift-detector.js';
 import { AutopilotSummaryCollector } from '../engine/autopilot/summary-collector.js';
-import { withAudit } from '../engine/autopilot/audit-logger.js';
 import { trackCost } from '../engine/cost-tracking/operation-tracker.js';
-import { refreshProjectStatus } from '../engine/autopilot/state-updater.js';
 import { resolveProjectIdOrAutoDetect } from './resolve-project-id.js';
 import { isNativeActive, fastScanSpecs } from '../engine/core-bridge.js';
 /** Track which projects have been auto-discovered this session (once per project). */
 const discoveredProjects = new Set();
+const MAX_STRUCTURED_SPECS = 50;
 /** Build markdown table rows for summary mode */
 function buildSummaryTable(specs) {
     const header = '| ID | Title | Status | Type | Tags |';
@@ -21,48 +20,11 @@ function buildSummaryTable(specs) {
     const rows = specs.map((s) => `| ${s.id} | ${s.title} | ${s.status} | ${s.type} | ${s.tags.join(', ')} |`);
     return [header, divider, ...rows].join('\n');
 }
-async function autoDiscoverProject(projectId, projectPath, collector) {
+async function collectReadOnlyProjectSignals(projectId, projectPath, collector) {
     if (discoveredProjects.has(projectId)) {
         return;
     }
     discoveredProjects.add(projectId);
-    try {
-        await withAudit(projectPath, 'list_specs', 'discoverAndFlattenSpecs', () => discoverAndFlattenSpecs(projectPath));
-    }
-    catch {
-        /* best-effort — don't fail list_specs */
-    }
-    try {
-        await withAudit(projectPath, 'list_specs', 'importFilesystemSpecs', () => importFilesystemSpecs(projectPath, {
-            listSpecs: specStore.listSpecs,
-            createSpec: specStore.createSpec,
-        }, projectId), (imported) => ({ imported: Array.isArray(imported) ? imported.length : 0 }));
-    }
-    catch {
-        /* best-effort */
-    }
-    try {
-        await withAudit(projectPath, 'list_specs', 'reconcileSpecPaths', () => reconcileSpecPaths(projectPath, {
-            listSpecs: specStore.listSpecs,
-            updateSpec: specStore.updateSpec,
-        }, projectId));
-    }
-    catch {
-        /* best-effort */
-    }
-    try {
-        const allStoredSpecs = await specStore.listSpecs(projectId);
-        const unprefixed = filterUnprefixedSpecs(allStoredSpecs);
-        if (unprefixed.length > 0) {
-            await withAudit(projectPath, 'list_specs', 'migrateSpecFolderNames', () => migrateSpecFolderNames(projectPath, unprefixed, {
-                listSpecs: specStore.listSpecs,
-                updateSpec: specStore.updateSpec,
-            }), (migrated) => ({ count: Array.isArray(migrated) ? migrated.length : 0 }));
-        }
-    }
-    catch {
-        /* best-effort */
-    }
     // SPEC-1017: list_specs enforces the strict planu/ policy in check mode.
     // Mutating cleanup is handled by init/update/validate/housekeeping; list_specs
     // stays read-mostly and surfaces exact offenders if any remain.
@@ -88,21 +50,6 @@ async function autoDiscoverProject(projectId, projectPath, collector) {
     catch {
         /* best-effort — never block list_specs */
     }
-    try {
-        const { configureGitignoreForPlanu } = await import('./init-project/git-setup.js');
-        await withAudit(projectPath, 'list_specs', 'configureGitignoreForPlanu', () => configureGitignoreForPlanu(projectPath));
-        collector.pushOk('gitignore', 'Updated .gitignore with planu/ rules');
-    }
-    catch {
-        /* best-effort */
-    }
-    // SPEC-493: Silently repair status.json totalSpecs count from actual store data
-    try {
-        await withAudit(projectPath, 'list_specs', 'refreshProjectStatus', () => refreshProjectStatus(projectPath, projectId));
-    }
-    catch {
-        /* best-effort */
-    }
 }
 export async function handleListSpecs(params) {
     // SPEC-584: list_specs is read-mostly and its migration-issue questions are opt-in.
@@ -152,9 +99,10 @@ export async function handleListSpecs(params) {
             if (isNativeActive() && knowledge.projectPath) {
                 nativeBriefs = fastScanSpecs(knowledge.projectPath);
             }
-            // Auto-discover, flatten, rename, and fix specs (once per session per project)
+            // Read-only project signals only. Mutating discovery/migration/repair belongs
+            // to init, validate, housekeeping, or explicit migration tools.
             if (knowledge.projectPath) {
-                await autoDiscoverProject(projectId, knowledge.projectPath, collector);
+                await collectReadOnlyProjectSignals(projectId, knowledge.projectPath, collector);
             }
             // Get all specs
             let specs = await specStore.listSpecs(projectId);
@@ -247,6 +195,8 @@ export async function handleListSpecs(params) {
                     updatedAt: s.updatedAt,
                     lastModified: lastModifiedMap.get(s.id) ?? '\u2014',
                 }));
+            const structuredSpecs = specsData.slice(0, MAX_STRUCTURED_SPECS);
+            const specsOmitted = Math.max(0, specsData.length - structuredSpecs.length);
             // Build text content: markdown table in summary mode, JSON in full mode
             let textContent;
             if (detail === 'summary') {
@@ -262,7 +212,13 @@ export async function handleListSpecs(params) {
                     },
                     count: specs.length,
                     totalCount: allSpecs.length,
-                    specs: specsData,
+                    specs: structuredSpecs,
+                    pagination: {
+                        limit: MAX_STRUCTURED_SPECS,
+                        returned: structuredSpecs.length,
+                        total: specsData.length,
+                        omitted: specsOmitted,
+                    },
                     summary: {
                         byStatus: statusCounts,
                         byType: typeCounts,

package/dist/tools/output-compressor.d.ts

@@ -1,8 +1,21 @@
 import type { ToolResult } from '../types/index.js';
+export interface StructuredContentCompactionOptions {
+    maxArrayItems?: number;
+    maxStringChars?: number;
+    maxObjectKeys?: number;
+    maxDepth?: number;
+}
+/**
+ * Compacts structuredContent without changing its broad contract shape.
+ * Arrays remain arrays, objects remain objects, and compaction metadata is added
+ * at top level when a successful response would otherwise return a large payload.
+ */
+export declare function compactStructuredContent(structuredContent: Record<string, unknown>, options?: StructuredContentCompactionOptions): Record<string, unknown>;
 /**
  * Post-processes a ToolResult to compress verbose content blocks.
  * Applied to ALL tool outputs via safeWithTelemetry.
- * Preserves structuredContent untouched — only compresses text blocks.
+ * Also bounds structuredContent so token recording reflects the actual visible
+ * payload instead of unbounded internal data.
  */
 export declare function compressToolOutput(result: ToolResult): ToolResult;
 //# sourceMappingURL=output-compressor.d.ts.map

package/dist/tools/output-compressor.js

@@ -9,6 +9,14 @@ const MIN_COMPRESS_LENGTH = 800;
 const HARD_CAP_CHARS = 2400;
 /** Max lines kept from a long markdown text block */
 const MAX_MARKDOWN_LINES = 40;
+/** Default number of structured array items to keep in MCP responses. */
+const MAX_STRUCTURED_ARRAY_ITEMS = 20;
+/** Default max string length inside structuredContent. */
+const MAX_STRUCTURED_STRING_CHARS = 2000;
+/** Default object key budget inside structuredContent. */
+const MAX_STRUCTURED_OBJECT_KEYS = 60;
+/** Default recursion depth for structuredContent compaction. */
+const MAX_STRUCTURED_DEPTH = 8;
 /**
  * Detects if a string is a JSON dump (starts with { or [).
  * Quick heuristic — avoids parsing large strings unnecessarily.
@@ -133,10 +141,114 @@ function compressTextBlock(text) {
     }
     return hardCap(truncateMarkdown(text));
 }
+function pushArrayMeta(meta, value) {
+    meta.arrays.push(value);
+}
+function pushStringMeta(meta, value) {
+    meta.strings.push(value);
+}
+function pushObjectMeta(meta, value) {
+    meta.objects.push(value);
+}
+function pushDepthMeta(meta, path) {
+    meta.depthLimited.push(path);
+}
+function compactStructuredValue(value, path, depth, options, meta) {
+    if (typeof value === 'string') {
+        if (value.length <= options.maxStringChars) {
+            return value;
+        }
+        pushStringMeta(meta, {
+            path,
+            originalChars: value.length,
+            shownChars: options.maxStringChars,
+        });
+        return `${value.slice(0, options.maxStringChars)}\n... (${String(value.length - options.maxStringChars)} chars omitted)`;
+    }
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (depth >= options.maxDepth) {
+        pushDepthMeta(meta, path);
+        return '[structuredContent depth limit reached]';
+    }
+    if (Array.isArray(value)) {
+        const shown = value.slice(0, options.maxArrayItems);
+        if (value.length > shown.length) {
+            pushArrayMeta(meta, {
+                path,
+                total: value.length,
+                shown: shown.length,
+                omitted: value.length - shown.length,
+            });
+        }
+        return shown.map((item, index) => compactStructuredValue(item, `${path}[${String(index)}]`, depth + 1, options, meta));
+    }
+    const entries = Object.entries(value);
+    const keptEntries = entries.slice(0, options.maxObjectKeys);
+    if (entries.length > keptEntries.length) {
+        pushObjectMeta(meta, {
+            path,
+            totalKeys: entries.length,
+            shownKeys: keptEntries.length,
+            omitted: entries.length - keptEntries.length,
+        });
+    }
+    const out = {};
+    for (const [key, entryValue] of keptEntries) {
+        out[key] = compactStructuredValue(entryValue, path === '$' ? `$.${key}` : `${path}.${key}`, depth + 1, options, meta);
+    }
+    return out;
+}
+/**
+ * Compacts structuredContent without changing its broad contract shape.
+ * Arrays remain arrays, objects remain objects, and compaction metadata is added
+ * at top level when a successful response would otherwise return a large payload.
+ */
+export function compactStructuredContent(structuredContent, options = {}) {
+    const resolved = {
+        maxArrayItems: options.maxArrayItems ?? MAX_STRUCTURED_ARRAY_ITEMS,
+        maxStringChars: options.maxStringChars ?? MAX_STRUCTURED_STRING_CHARS,
+        maxObjectKeys: options.maxObjectKeys ?? MAX_STRUCTURED_OBJECT_KEYS,
+        maxDepth: options.maxDepth ?? MAX_STRUCTURED_DEPTH,
+    };
+    const meta = {
+        structuredContentCompacted: true,
+        arrays: [],
+        strings: [],
+        objects: [],
+        depthLimited: [],
+    };
+    const compacted = compactStructuredValue(structuredContent, '$', 0, resolved, meta);
+    if (meta.arrays.length === 0 &&
+        meta.strings.length === 0 &&
+        meta.objects.length === 0 &&
+        meta.depthLimited.length === 0) {
+        return structuredContent;
+    }
+    if (compacted !== null && typeof compacted === 'object' && !Array.isArray(compacted)) {
+        const obj = compacted;
+        const existingCompaction = obj.compaction !== null && typeof obj.compaction === 'object'
+            ? obj.compaction
+            : {};
+        return {
+            ...obj,
+            compaction: {
+                ...existingCompaction,
+                ...meta,
+            },
+        };
+    }
+    return {
+        value: compacted,
+        compaction: meta,
+    };
+}
 /**
  * Post-processes a ToolResult to compress verbose content blocks.
  * Applied to ALL tool outputs via safeWithTelemetry.
- * Preserves structuredContent untouched — only compresses text blocks.
+ * Also bounds structuredContent so token recording reflects the actual visible
+ * payload instead of unbounded internal data.
  */
 export function compressToolOutput(result) {
     // Don't compress error results — they need full context for debugging
@@ -151,6 +263,13 @@ export function compressToolOutput(result) {
         ...block,
         text: compressTextBlock(block.text),
     }));
-    return { ...result, content: compressed };
+    const structuredContent = result.structuredContent !== undefined
+        ? compactStructuredContent(result.structuredContent)
+        : undefined;
+    return {
+        ...result,
+        content: compressed,
+        ...(structuredContent !== undefined ? { structuredContent } : {}),
+    };
 }
 //# sourceMappingURL=output-compressor.js.map