@planu/cli 4.5.0 → 4.6.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [4.6.0] - 2026-06-11
+
+### Features
+- feat(SPEC-1084): add token waste autopilot
+
+### Chores
+- chore(deps): sync lockfile
+- chore(deps): update patch dependencies
+
+
 ## [4.5.0] - 2026-06-10
 
 ### Features

package/dist/config/token-waste-autopilot.json

@@ -0,0 +1,48 @@
+{
+  "version": 1,
+  "enabled": true,
+  "context": {
+    "generatedPatterns": ["dist/**", "coverage/**", ".next/**", "build/**"],
+    "stalePatterns": ["*.log", "*.bak", "*.tmp"],
+    "summarizePatterns": ["pnpm-lock.yaml", "package-lock.json", "yarn.lock"],
+    "staleSessionMinutes": 60,
+    "safetyOverrideActions": ["release", "security", "license", "lockfile", "exact-reproduction"]
+  },
+  "outputs": {
+    "strategies": {
+      "test": { "maxLines": 40, "keepFailures": true },
+      "log": { "maxLines": 30, "uniqueOnly": true },
+      "json": { "maxLines": 40, "summarizeKeys": true },
+      "dependency": { "maxLines": 50, "keepFailures": true },
+      "generic": { "maxLines": 60 }
+    }
+  },
+  "tools": {
+    "groups": {
+      "spec": ["create_spec", "check_readiness", "challenge_spec", "update_status"],
+      "handoff": ["package_handoff", "generate_execution_plan"],
+      "status": ["planu_status", "session_checkpoint"],
+      "token": ["token_intelligence", "tokens", "context_budget"]
+    },
+    "maxRecommended": 8
+  },
+  "loops": {
+    "thresholds": {
+      "file_read": 3,
+      "search": 3,
+      "test_run": 2,
+      "failure": 2
+    },
+    "safetyOverrideActions": ["release", "security", "license"]
+  },
+  "modelEffort": {
+    "lowRisk": "low",
+    "default": "medium",
+    "highRisk": "high",
+    "maxRisk": "max"
+  },
+  "redaction": {
+    "maxSnippetChars": 240,
+    "redactPatterns": ["secret", "token", "password", "api_key"]
+  }
+}

package/dist/engine/token-optimizer/autopilot.d.ts

@@ -0,0 +1,5 @@
+import type { TokenWasteAutopilotInput, TokenWasteReport } from '../../types/token-waste-autopilot.js';
+export declare function redactSnippet(text: string, patterns: string[], maxChars: number): string;
+export declare function buildTokenWasteReport(input: TokenWasteAutopilotInput): TokenWasteReport;
+export declare function formatTokenWasteReport(report: TokenWasteReport): string;
+//# sourceMappingURL=autopilot.d.ts.map

package/dist/engine/token-optimizer/autopilot.js

@@ -0,0 +1,93 @@
+function collectEvidence(decisions) {
+    return decisions.flatMap((decision) => decision.evidence);
+}
+function modelAdvice(input) {
+    const risk = input.spec?.risk ?? 'medium';
+    const effort = risk === 'critical'
+        ? input.policy.modelEffort.maxRisk
+        : risk === 'high'
+            ? input.policy.modelEffort.highRisk
+            : risk === 'low'
+                ? input.policy.modelEffort.lowRisk
+                : input.policy.modelEffort.default;
+    return {
+        effort,
+        reason: `Selected ${effort} effort from spec risk ${risk}.`,
+        evidence: [
+            { source: 'spec', key: 'risk', value: risk },
+            { source: 'policy', key: 'modelEffort' },
+        ],
+    };
+}
+function escapeInert(text) {
+    return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function redactSnippet(text, patterns, maxChars) {
+    const truncated = text.slice(0, maxChars);
+    return patterns.reduce((current, pattern) => {
+        const re = new RegExp(pattern, 'gi');
+        return current.replace(re, '[redacted]');
+    }, truncated);
+}
+function sanitizeDecision(decision, patterns, maxChars) {
+    return {
+        ...decision,
+        target: redactSnippet(decision.target, patterns, maxChars),
+        reason: redactSnippet(decision.reason, patterns, maxChars),
+        evidence: decision.evidence.map((item) => ({
+            ...item,
+            ...(typeof item.value === 'string'
+                ? { value: redactSnippet(item.value, patterns, maxChars) }
+                : {}),
+        })),
+    };
+}
+function sanitizeDecisions(decisions, input) {
+    return decisions.map((decision) => sanitizeDecision(decision, input.policy.redaction.redactPatterns, input.policy.redaction.maxSnippetChars));
+}
+export function buildTokenWasteReport(input) {
+    const actionsTaken = sanitizeDecisions([
+        ...(input.context?.summarize ?? []),
+        ...(input.context?.exclude ?? []),
+        ...(input.output?.decisions ?? []),
+    ], input);
+    const recommendations = sanitizeDecisions([...(input.context?.include ?? []), ...(input.tools?.recommended ?? [])], input);
+    const risks = sanitizeDecisions([...(input.tools?.avoided ?? []), ...(input.loops?.warnings ?? [])], input);
+    const modelEffort = modelAdvice(input);
+    return {
+        actionsTaken,
+        recommendations,
+        risks,
+        evidence: [
+            ...collectEvidence(actionsTaken),
+            ...collectEvidence(recommendations),
+            ...collectEvidence(risks),
+            ...modelEffort.evidence,
+        ],
+        modelEffort,
+    };
+}
+export function formatTokenWasteReport(report) {
+    const lines = ['## Token Waste Autopilot', ''];
+    lines.push(`Model effort: ${escapeInert(report.modelEffort.effort)} — ${escapeInert(report.modelEffort.reason)}`);
+    if (report.actionsTaken.length > 0) {
+        lines.push('', 'Actions taken:');
+        for (const item of report.actionsTaken.slice(0, 6)) {
+            lines.push(`- ${escapeInert(item.decision)}: ${escapeInert(item.target)} — ${escapeInert(item.reason)}`);
+        }
+    }
+    if (report.recommendations.length > 0) {
+        lines.push('', 'Recommendations:');
+        for (const item of report.recommendations.slice(0, 6)) {
+            lines.push(`- ${escapeInert(item.target)}: ${escapeInert(item.reason)}`);
+        }
+    }
+    if (report.risks.length > 0) {
+        lines.push('', 'Risks:');
+        for (const item of report.risks.slice(0, 6)) {
+            lines.push(`- ${escapeInert(item.target)}: ${escapeInert(item.reason)}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=autopilot.js.map

package/dist/engine/token-optimizer/context-preflight.d.ts

@@ -0,0 +1,3 @@
+import type { ContextPreflightInput, ContextPreflightResult } from '../../types/token-waste-autopilot.js';
+export declare function analyzeContextPreflight(input: ContextPreflightInput): ContextPreflightResult;
+//# sourceMappingURL=context-preflight.d.ts.map

package/dist/engine/token-optimizer/context-preflight.js

@@ -0,0 +1,64 @@
+function globToRegExp(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*/g, '::DOUBLE_STAR::')
+        .replace(/\*/g, '[^/]*')
+        .replace(/::DOUBLE_STAR::/g, '.*');
+    return new RegExp(`^${escaped}$`);
+}
+function matchesAny(path, patterns) {
+    return patterns.find((pattern) => globToRegExp(pattern).test(path));
+}
+function decision(kind, target, reason, key) {
+    return {
+        decision: kind,
+        target,
+        reason,
+        evidence: [{ source: 'policy', key }],
+        confidence: 'high',
+    };
+}
+function hasSafetyOverride(action, policy) {
+    return policy.context.safetyOverrideActions.includes(action);
+}
+function classifyCandidate(candidate, input) {
+    if (hasSafetyOverride(input.action, input.policy)) {
+        return decision('override', candidate.path, `Action ${input.action} requires exact context according to policy.`, 'context.safetyOverrideActions');
+    }
+    const generated = matchesAny(candidate.path, input.policy.context.generatedPatterns);
+    if (generated !== undefined) {
+        return decision('exclude', candidate.path, `Matches generated context pattern ${generated}.`, 'context.generatedPatterns');
+    }
+    const stale = matchesAny(candidate.path, input.policy.context.stalePatterns);
+    if (stale !== undefined) {
+        return decision('exclude', candidate.path, `Matches stale context pattern ${stale}.`, 'context.stalePatterns');
+    }
+    const summarize = matchesAny(candidate.path, input.policy.context.summarizePatterns);
+    if (summarize !== undefined) {
+        return decision('summarize', candidate.path, `Matches summarizable context pattern ${summarize}.`, 'context.summarizePatterns');
+    }
+    return {
+        decision: 'include',
+        target: candidate.path,
+        reason: candidate.reason ?? 'Candidate context is relevant and not excluded by policy.',
+        evidence: [{ source: 'runtime', key: 'candidate.path', value: candidate.path }],
+        confidence: 'medium',
+    };
+}
+export function analyzeContextPreflight(input) {
+    const result = { include: [], summarize: [], exclude: [] };
+    for (const candidate of input.candidates) {
+        const item = classifyCandidate(candidate, input);
+        if (item.decision === 'exclude') {
+            result.exclude.push(item);
+        }
+        else if (item.decision === 'summarize') {
+            result.summarize.push(item);
+        }
+        else {
+            result.include.push(item);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=context-preflight.js.map

package/dist/engine/token-optimizer/index.d.ts

@@ -8,5 +8,11 @@ export { BudgetManager } from './budget.js';
 export { OptimizationReporter } from './reporter.js';
 export { TokenOptimizer } from './optimizer.js';
 export { aggregateEntries, computeDailyBreakdown, detectTrend, detectAnomalies, computeBudgetStatus, getTopConsumers, computeOptimizationSavings, } from './analytics.js';
+export { loadTokenWastePolicy } from './policy-loader.js';
+export { analyzeContextPreflight } from './context-preflight.js';
+export { filterVerboseOutput } from './output-filter.js';
+export { recommendRelevantTools, toolsFromPolicyGroups } from './tool-relevance.js';
+export { detectTokenWasteLoops } from './loop-detector.js';
+export { buildTokenWasteReport, formatTokenWasteReport, redactSnippet } from './autopilot.js';
 export type { DailyBreakdown, TrendResult, Anomaly, TopConsumer, OptimizationSavings, } from './analytics.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/engine/token-optimizer/index.js

@@ -9,4 +9,10 @@ export { BudgetManager } from './budget.js';
 export { OptimizationReporter } from './reporter.js';
 export { TokenOptimizer } from './optimizer.js';
 export { aggregateEntries, computeDailyBreakdown, detectTrend, detectAnomalies, computeBudgetStatus, getTopConsumers, computeOptimizationSavings, } from './analytics.js';
+export { loadTokenWastePolicy } from './policy-loader.js';
+export { analyzeContextPreflight } from './context-preflight.js';
+export { filterVerboseOutput } from './output-filter.js';
+export { recommendRelevantTools, toolsFromPolicyGroups } from './tool-relevance.js';
+export { detectTokenWasteLoops } from './loop-detector.js';
+export { buildTokenWasteReport, formatTokenWasteReport, redactSnippet } from './autopilot.js';
 //# sourceMappingURL=index.js.map

package/dist/engine/token-optimizer/loop-detector.d.ts

@@ -0,0 +1,3 @@
+import type { TokenWasteLoopResult, TokenWastePolicy, TokenWasteRuntimeEvent } from '../../types/token-waste-autopilot.js';
+export declare function detectTokenWasteLoops(events: TokenWasteRuntimeEvent[], policy: TokenWastePolicy, action?: string): TokenWasteLoopResult;
+//# sourceMappingURL=loop-detector.d.ts.map

package/dist/engine/token-optimizer/loop-detector.js

@@ -0,0 +1,32 @@
+export function detectTokenWasteLoops(events, policy, action = 'default') {
+    if (policy.loops.safetyOverrideActions.includes(action)) {
+        return { warnings: [] };
+    }
+    const counts = new Map();
+    for (const event of events) {
+        if (event.changedSincePrevious === true) {
+            continue;
+        }
+        const key = `${event.type}:${event.key}`;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const warnings = [];
+    for (const [key, count] of counts) {
+        const [type = 'unknown', target = key] = key.split(':');
+        const threshold = policy.loops.thresholds[type] ?? Number.POSITIVE_INFINITY;
+        if (count >= threshold) {
+            warnings.push({
+                decision: 'warn',
+                target,
+                reason: `Repeated ${type} operation detected ${String(count)} times without an intervening change.`,
+                evidence: [
+                    { source: 'policy', key: `loops.thresholds.${type}`, value: threshold },
+                    { source: 'runtime', key: 'event.count', value: count },
+                ],
+                confidence: 'high',
+            });
+        }
+    }
+    return { warnings };
+}
+//# sourceMappingURL=loop-detector.js.map

package/dist/engine/token-optimizer/output-filter.d.ts

@@ -0,0 +1,3 @@
+import type { VerboseOutputInput, VerboseOutputResult } from '../../types/token-waste-autopilot.js';
+export declare function filterVerboseOutput(input: VerboseOutputInput): VerboseOutputResult;
+//# sourceMappingURL=output-filter.d.ts.map

package/dist/engine/token-optimizer/output-filter.js

@@ -0,0 +1,67 @@
+function escapeInert(text) {
+    return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function redact(text, patterns) {
+    return patterns.reduce((current, pattern) => {
+        const re = new RegExp(pattern, 'gi');
+        return current.replace(re, '[redacted]');
+    }, text);
+}
+function uniqueLines(lines) {
+    return [...new Set(lines)];
+}
+function failureLines(lines) {
+    const failures = lines.filter((line) => /\b(error|fail|failed|exception|critical)\b/i.test(line));
+    return failures.length > 0 ? failures : lines;
+}
+function jsonSummary(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return [`JSON object keys: ${Object.keys(parsed).join(', ')}`];
+        }
+        if (Array.isArray(parsed)) {
+            return [`JSON array length: ${String(parsed.length)}`];
+        }
+    }
+    catch {
+        // Fall through to normal line handling.
+    }
+    return text.split('\n');
+}
+function selectStrategy(input) {
+    const strategy = input.policy.outputs.strategies[input.kind] ?? input.policy.outputs.strategies.generic;
+    if (strategy === undefined) {
+        throw new Error('Token waste policy must define outputs.strategies.generic');
+    }
+    return strategy;
+}
+function compactLines(input, strategy) {
+    const rawLines = strategy.summarizeKeys === true ? jsonSummary(input.text) : input.text.split('\n');
+    const selected = strategy.keepFailures === true ? failureLines(rawLines) : rawLines;
+    const unique = strategy.uniqueOnly === true ? uniqueLines(selected) : selected;
+    return unique.slice(0, strategy.maxLines);
+}
+export function filterVerboseOutput(input) {
+    const strategy = selectStrategy(input);
+    const originalLines = input.text.split('\n').length;
+    const lines = compactLines(input, strategy);
+    const compact = redact(escapeInert(lines.join('\n')), input.policy.redaction.redactPatterns);
+    const decisions = [
+        {
+            decision: originalLines > lines.length ? 'summarize' : 'include',
+            target: input.kind,
+            reason: `Applied policy output strategy for ${input.kind}.`,
+            evidence: [{ source: 'policy', key: `outputs.strategies.${input.kind}` }],
+            confidence: input.policy.outputs.strategies[input.kind] !== undefined ? 'high' : 'medium',
+        },
+    ];
+    return {
+        text: compact,
+        originalLines,
+        returnedLines: lines.length,
+        ...(input.fullOutputRef !== undefined ? { fullOutputRef: input.fullOutputRef } : {}),
+        decisions,
+    };
+}
+//# sourceMappingURL=output-filter.js.map

package/dist/engine/token-optimizer/policy-loader.d.ts

@@ -0,0 +1,3 @@
+import type { LoadedTokenWastePolicy, TokenWastePolicyLoadOptions } from '../../types/token-waste-autopilot.js';
+export declare function loadTokenWastePolicy(projectPath?: string, options?: TokenWastePolicyLoadOptions): Promise<LoadedTokenWastePolicy>;
+//# sourceMappingURL=policy-loader.d.ts.map

package/dist/engine/token-optimizer/policy-loader.js

@@ -0,0 +1,83 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function configPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), '../../config/token-waste-autopilot.json');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function mergeDeep(base, override) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        const current = result[key];
+        result[key] = isRecord(current) && isRecord(value) ? mergeDeep(current, value) : value;
+    }
+    return result;
+}
+function assertStringArray(value, path) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new Error(`Invalid token waste policy at ${path}: expected string[]`);
+    }
+}
+function validatePolicy(value) {
+    if (!isRecord(value)) {
+        throw new Error('Invalid token waste policy: expected object');
+    }
+    if (value.version !== 1) {
+        throw new Error('Invalid token waste policy: version must be 1');
+    }
+    const policy = value;
+    assertStringArray(policy.context.generatedPatterns, 'context.generatedPatterns');
+    assertStringArray(policy.context.stalePatterns, 'context.stalePatterns');
+    assertStringArray(policy.context.summarizePatterns, 'context.summarizePatterns');
+    if (!Number.isFinite(policy.context.staleSessionMinutes) ||
+        policy.context.staleSessionMinutes < 1) {
+        throw new Error('Invalid token waste policy at context.staleSessionMinutes: expected positive number');
+    }
+    assertStringArray(policy.context.safetyOverrideActions, 'context.safetyOverrideActions');
+    if (!isRecord(policy.outputs.strategies)) {
+        throw new Error('Invalid token waste policy at outputs.strategies: expected object');
+    }
+    if (!isRecord(policy.tools.groups)) {
+        throw new Error('Invalid token waste policy at tools.groups: expected object');
+    }
+    for (const [group, tools] of Object.entries(policy.tools.groups)) {
+        assertStringArray(tools, `tools.groups.${group}`);
+    }
+    if (!Number.isFinite(policy.tools.maxRecommended) || policy.tools.maxRecommended < 1) {
+        throw new Error('Invalid token waste policy at tools.maxRecommended: expected positive number');
+    }
+    if (!isRecord(policy.loops.thresholds)) {
+        throw new Error('Invalid token waste policy at loops.thresholds: expected object');
+    }
+    assertStringArray(policy.loops.safetyOverrideActions, 'loops.safetyOverrideActions');
+    assertStringArray(policy.redaction.redactPatterns, 'redaction.redactPatterns');
+    return policy;
+}
+async function readJson(path) {
+    return JSON.parse(await readFile(path, 'utf-8'));
+}
+export async function loadTokenWastePolicy(projectPath, options = {}) {
+    const defaultPolicyPath = options.defaultPolicyPath ?? configPath();
+    const defaultPolicy = validatePolicy(await readJson(defaultPolicyPath));
+    const evidence = [
+        { source: 'policy', key: defaultPolicyPath },
+    ];
+    let merged = defaultPolicy;
+    if (projectPath !== undefined) {
+        const planuConfigPath = join(projectPath, 'planu.json');
+        try {
+            const config = await readJson(planuConfigPath);
+            if (isRecord(config) && isRecord(config.tokenWasteAutopilot)) {
+                merged = validatePolicy(mergeDeep(defaultPolicy, config.tokenWasteAutopilot));
+                evidence.push({ source: 'project-config', key: 'planu.json.tokenWasteAutopilot' });
+            }
+        }
+        catch {
+            // Missing or malformed project config does not block default policy loading.
+        }
+    }
+    return { policy: merged, evidence };
+}
+//# sourceMappingURL=policy-loader.js.map

package/dist/engine/token-optimizer/tool-relevance.d.ts

@@ -0,0 +1,6 @@
+import type { TokenWastePolicy, ToolRelevanceInput, ToolRelevanceResult } from '../../types/token-waste-autopilot.js';
+export declare function toolsFromPolicyGroups(policy: TokenWastePolicy): {
+    name: string;
+}[];
+export declare function recommendRelevantTools(input: ToolRelevanceInput): ToolRelevanceResult;
+//# sourceMappingURL=tool-relevance.d.ts.map

package/dist/engine/token-optimizer/tool-relevance.js

@@ -0,0 +1,57 @@
+function normalized(text) {
+    return text.toLowerCase();
+}
+function matchesIntent(tool, signals) {
+    const haystack = normalized(`${tool.name} ${tool.description ?? ''}`);
+    return signals.some((signal) => haystack.includes(normalized(signal)));
+}
+function groupNamesForTool(toolName, groups) {
+    return Object.entries(groups)
+        .filter(([, tools]) => tools.includes(toolName))
+        .map(([group]) => group);
+}
+export function toolsFromPolicyGroups(policy) {
+    return [...new Set(Object.values(policy.tools.groups).flat())].map((name) => ({ name }));
+}
+export function recommendRelevantTools(input) {
+    const unsupported = new Set(input.hostUnsupportedTools ?? []);
+    const actionSignals = [input.action, ...input.intentSignals].map(normalized);
+    const recommended = [];
+    const avoided = [];
+    for (const tool of input.tools) {
+        const groups = groupNamesForTool(tool.name, input.policy.tools.groups);
+        const isUnsupported = unsupported.has(tool.name);
+        const isRelevant = !isUnsupported &&
+            (matchesIntent(tool, actionSignals) ||
+                groups.some((group) => actionSignals.includes(normalized(group))));
+        if (isRelevant && recommended.length < input.policy.tools.maxRecommended) {
+            recommended.push({
+                decision: 'recommend',
+                target: tool.name,
+                reason: 'Tool matches the current action, intent signals, or policy tool group.',
+                evidence: [
+                    { source: 'policy', key: 'tools.groups', value: groups.join(',') },
+                    { source: 'runtime', key: 'intentSignals', value: input.intentSignals.join(',') },
+                ],
+                confidence: groups.length > 0 ? 'high' : 'medium',
+            });
+            continue;
+        }
+        avoided.push({
+            decision: 'avoid',
+            target: tool.name,
+            reason: isUnsupported
+                ? 'Host capability marks this tool unsupported.'
+                : 'Tool does not match the current action or intent and can add avoidable tool metadata overhead.',
+            evidence: [
+                {
+                    source: isUnsupported ? 'host-capability' : 'policy',
+                    key: isUnsupported ? 'unsupportedTools' : 'tools.groups',
+                },
+            ],
+            confidence: isUnsupported ? 'high' : 'medium',
+        });
+    }
+    return { recommended, avoided };
+}
+//# sourceMappingURL=tool-relevance.js.map

package/dist/tools/create-spec/post-creation.d.ts

@@ -1,5 +1,6 @@
-import type { Spec, PostCreationSuggestion, ProjectKnowledge } from '../../types/index.js';
+import type { Spec, PostCreationSuggestion, ProjectKnowledge, TokenWasteReport } from '../../types/index.js';
 export declare function getAsyncAnalysisPath(projectPath: string, specId: string): string;
+export declare function buildInitialTokenWasteMetadata(specId: string, projectPath: string, description: string): Promise<TokenWasteReport | null>;
 /** Auto-setup git branch (non-blocking). Returns branch info or undefined. */
 export declare function setupGitBranch(projectId: string, specId: string): Promise<{
     branch: string;

package/dist/tools/create-spec/post-creation.js

@@ -12,11 +12,42 @@ import { writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
 import { appendAutopilotLogEntry } from '../../storage/autopilot-log-store.js';
+import { analyzeContextPreflight, buildTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, toolsFromPolicyGroups, } from '../../engine/token-optimizer/index.js';
 const ASYNC_ANALYSIS_HOOK = 'create-spec-async-analysis';
 export function getAsyncAnalysisPath(projectPath, specId) {
     const projectId = hashProjectPath(projectPath);
     return join(projectDataDir(projectId), 'analysis', `${specId}.json`);
 }
+export async function buildInitialTokenWasteMetadata(specId, projectPath, description) {
+    try {
+        const { policy } = await loadTokenWastePolicy(projectPath);
+        if (!policy.enabled) {
+            return null;
+        }
+        const context = analyzeContextPreflight({
+            action: 'create_spec',
+            policy,
+            candidates: [{ path: 'planu/specs', reason: 'New spec workspace metadata.' }],
+            spec: { id: specId },
+        });
+        const tools = recommendRelevantTools({
+            action: 'create_spec',
+            intentSignals: ['spec', ...description.split(/\s+/).slice(0, 12)],
+            tools: toolsFromPolicyGroups(policy),
+            policy,
+        });
+        return buildTokenWasteReport({
+            action: 'create_spec',
+            policy,
+            context,
+            tools,
+            spec: { id: specId },
+        });
+    }
+    catch {
+        return null;
+    }
+}
 /** Auto-setup git branch (non-blocking). Returns branch info or undefined. */
 export async function setupGitBranch(projectId, specId) {
     const result = await tryAutoSetupGit(projectId, specId);
@@ -182,6 +213,7 @@ export function runAutopilotAsync(specId, projectPath, _description) {
                 specId,
                 completedAt: new Date().toISOString(),
                 pendingAnalysis: false,
+                tokenWasteAutopilot: await buildInitialTokenWasteMetadata(specId, projectPath, _description),
             };
             const analysisPath = getAsyncAnalysisPath(projectPath, specId);
             await mkdir(dirname(analysisPath), { recursive: true });

package/dist/tools/package-handoff.js

@@ -3,6 +3,7 @@ import { specStore, knowledgeStore } from '../storage/index.js';
 import { checkSpecReadiness } from '../engine/readiness-checker.js';
 import { packageHandoff } from '../engine/handoff-packager.js';
 import { detectParadigms } from '../engine/paradigm-detector.js';
+import { analyzeContextPreflight, buildTokenWasteReport, formatTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, toolsFromPolicyGroups, } from '../engine/token-optimizer/index.js';
 import { appendTransitionEvent } from '../storage/transition-log.js';
 // ── Formatting helpers ───────────────────────────────────────────────────────
 function formatHandoff(pkg) {
@@ -134,6 +135,47 @@ function formatHandoff(pkg) {
     }
     return lines.join('\n');
 }
+async function buildHandoffTokenWasteReport(pkg, knowledge, spec) {
+    try {
+        const { policy } = await loadTokenWastePolicy(knowledge.projectPath);
+        if (!policy.enabled) {
+            return null;
+        }
+        const context = analyzeContextPreflight({
+            action: 'package_handoff',
+            policy,
+            candidates: [...pkg.filesToModify, ...pkg.filesToCreate].map((path) => ({
+                path,
+                reason: 'Referenced by handoff package.',
+            })),
+            spec: {
+                id: spec.id,
+                risk: spec.risk,
+                target: spec.target,
+            },
+        });
+        const tools = recommendRelevantTools({
+            action: 'package_handoff',
+            intentSignals: ['handoff', spec.scope ?? '', spec.target ?? ''].filter(Boolean),
+            tools: toolsFromPolicyGroups(policy),
+            policy,
+        });
+        return buildTokenWasteReport({
+            action: 'package_handoff',
+            policy,
+            context,
+            tools,
+            spec: {
+                id: spec.id,
+                risk: spec.risk,
+                scope: spec.scope,
+            },
+        });
+    }
+    catch {
+        return null;
+    }
+}
 // ── Handler ──────────────────────────────────────────────────────────────────
 export async function handlePackageHandoff(args) {
     const { projectId, specId } = args;
@@ -188,7 +230,10 @@ export async function handlePackageHandoff(args) {
         readinessScore: readinessReport.score,
         constraints: paradigmConstraints,
     };
-    const formatted = formatHandoff(pkgWithScore);
+    const tokenWasteReport = await buildHandoffTokenWasteReport(pkgWithScore, knowledge, spec);
+    const formatted = tokenWasteReport !== null
+        ? `${formatHandoff(pkgWithScore)}\n${formatTokenWasteReport(tokenWasteReport)}`
+        : formatHandoff(pkgWithScore);
     void appendTransitionEvent({
         projectId,
         specId,
@@ -209,6 +254,7 @@ export async function handlePackageHandoff(args) {
             blockers: pkgWithScore.blockers,
             handoffPath: pkgWithScore.handoffPath,
             contextHash: pkgWithScore.contextHash,
+            ...(tokenWasteReport !== null ? { tokenWaste: tokenWasteReport } : {}),
         },
     };
 }

package/dist/tools/schemas/token-intelligence.d.ts

@@ -15,6 +15,7 @@ export declare const TokenIntelligenceViewEnum: z.ZodEnum<{
     summary: "summary";
     budget: "budget";
     detailed: "detailed";
+    autopilot: "autopilot";
     reconciliation: "reconciliation";
     trends: "trends";
 }>;

package/dist/tools/schemas/token-intelligence.js

@@ -9,10 +9,11 @@ export const TokenIntelligenceGroupByEnum = z
     .describe('Group results by: tool (per MCP tool name), model (per AI model), ' +
     'spec (per spec ID), day (daily breakdown)');
 export const TokenIntelligenceViewEnum = z
-    .enum(['summary', 'detailed', 'budget', 'reconciliation', 'trends'])
+    .enum(['summary', 'detailed', 'budget', 'reconciliation', 'trends', 'autopilot'])
     .describe('Dashboard view: summary (high-level overview with top consumers), ' +
     'detailed (full per-tool and per-model breakdown), ' +
     'budget (spending vs monthly limits with projections), ' +
     'reconciliation (estimated vs actual cost accuracy per spec), ' +
-    'trends (usage patterns over time, week-over-week changes, and anomaly alerts)');
+    'trends (usage patterns over time, week-over-week changes, and anomaly alerts), ' +
+    'autopilot (policy-driven recommendations to reduce wasted context, output, and tool usage)');
 //# sourceMappingURL=token-intelligence.js.map

package/dist/tools/status-handler.js

@@ -17,6 +17,7 @@ import { calculateSLAStatus } from '../engine/approval-workflow.js';
 import { readPlanuConfig } from '../engine/planu-config-writer.js';
 import { computePlanuDriftScore } from '../engine/dashboard/drift-score.js';
 import { findStaleBranches, findStaleWorktrees, findStaleStashes, } from '../engine/housekeeping/index.js';
+import { loadTokenWastePolicy } from '../engine/token-optimizer/index.js';
 // SPEC-1011 Bug G: fire-and-forget status.json reconciliation
 import { reconcileStatusFromDisk } from '../engine/status-reconciler/index.js';
 const execFile = promisify(execFileCb);
@@ -127,7 +128,7 @@ function buildSuggestion(snapshot) {
 // Output builder
 // ---------------------------------------------------------------------------
 function buildOutput(params) {
-    const { snapshot, git, ci, slaBreaches, workMode, updateBanner, autoCompleted, sessionTip } = params;
+    const { snapshot, git, ci, slaBreaches, workMode, updateBanner, autoCompleted, sessionTip, tokenWasteHint, } = params;
     const lines = ['Planu Status', '━━━━━━━━━━━━━━━'];
     if (snapshot.active !== null) {
         const title = snapshot.active.title.slice(0, 40);
@@ -162,6 +163,9 @@ function buildOutput(params) {
     if (sessionTip !== undefined) {
         lines.push(`SESSION TIP  ${sessionTip}`);
     }
+    if (tokenWasteHint !== undefined) {
+        lines.push(`TOKEN WASTE ${tokenWasteHint}`);
+    }
     lines.push(`SUGGEST   ${buildSuggestion(snapshot)}`);
     if (workMode !== undefined) {
         lines.push(`WORK MODE ${workMode}`);
@@ -206,7 +210,7 @@ export async function handlePlanStatus(args) {
             /* best-effort */
         });
     }
-    const [snapshot, git, ci, slaBreaches, planuConfig, autoCompleted, sessionState, driftScore, pendingCleanup,] = await Promise.all([
+    const [snapshot, git, ci, slaBreaches, planuConfig, autoCompleted, sessionState, driftScore, pendingCleanup, tokenWastePolicy,] = await Promise.all([
         getStatusSpecSnapshot(projectId),
         getGitState(args.projectPath),
         getCiState(args.projectPath),
@@ -237,6 +241,9 @@ export async function handlePlanStatus(args) {
                 return { branches: 0, worktrees: 0, stashes: 0 };
             }
         })(),
+        loadTokenWastePolicy(args.projectPath)
+            .then((loaded) => loaded.policy)
+            .catch(() => null),
     ]);
     // SPEC-1012: Detect stale release status (best-effort, non-blocking)
     let staleStatusWarnings = [];
@@ -252,6 +259,12 @@ export async function handlePlanStatus(args) {
     const sessionTip = sessionAgeMinutes !== null && sessionAgeMinutes > SESSION_TIP_THRESHOLD_MIN
         ? `Last checkpoint ${String(sessionAgeMinutes)}min ago — run session_handoff then start a fresh session to cut token costs`
         : undefined;
+    const tokenWasteThresholdMin = tokenWastePolicy?.context.staleSessionMinutes;
+    const tokenWasteHint = tokenWasteThresholdMin !== undefined &&
+        sessionAgeMinutes !== null &&
+        sessionAgeMinutes > tokenWasteThresholdMin
+        ? `checkpoint is stale; package or hand off context before continuing`
+        : undefined;
     const workMode = planuConfig?.workMode;
     const updateBanner = consumeUpdateBanner() ?? undefined;
     const text = buildOutput({
@@ -263,6 +276,7 @@ export async function handlePlanStatus(args) {
         updateBanner,
         autoCompleted,
         sessionTip,
+        tokenWasteHint,
     });
     // SPEC-256: Always show /btw hint as educational tip (no context percent available from MCP layer)
     const DEMO_CONTEXT_PERCENT = 65;
@@ -286,6 +300,7 @@ export async function handlePlanStatus(args) {
             lastAuditAt: driftScore?.lastAuditAt ?? null,
             ...(autoCompleted.length > 0 ? { autoCompleted } : {}),
             ...(sessionTip !== undefined ? { sessionTip } : {}),
+            ...(tokenWasteHint !== undefined ? { tokenWasteHint } : {}),
             ...(btwHint !== undefined ? { btw_hint: btwHint } : {}),
             ...(updateBanner !== undefined ? { update_banner: updateBanner } : {}),
             // SPEC-751: pending cleanup counters

package/dist/tools/token-intelligence-handler.js

@@ -1,5 +1,6 @@
 import { getEntries, getAggregation } from '../storage/token-ledger-store.js';
 import { hashProjectPath } from '../storage/base-store.js';
+import { buildTokenWasteReport, detectTokenWasteLoops, formatTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, } from '../engine/token-optimizer/index.js';
 import { join } from 'node:path';
 // ---------------------------------------------------------------------------
 // Constants
@@ -348,6 +349,47 @@ function renderTrends(entries, period) {
     }
     return lines.join('\n');
 }
+async function renderAutopilot(entries, agg, period, projectPath) {
+    const { policy } = await loadTokenWastePolicy(projectPath);
+    if (!policy.enabled) {
+        return [
+            '# Token Intelligence Dashboard — Autopilot View',
+            '',
+            `**Period:** ${periodLabel(period)}`,
+            '',
+            'Token Waste Autopilot is disabled by policy.',
+            '',
+        ].join('\n');
+    }
+    const loops = detectTokenWasteLoops(entries.map((entry) => ({
+        type: 'tool',
+        key: entry.toolName,
+        timestamp: entry.timestamp,
+        changedSincePrevious: false,
+    })), policy, 'token_intelligence');
+    const tools = recommendRelevantTools({
+        action: 'token_intelligence',
+        intentSignals: ['token', 'status', 'budget'],
+        tools: Object.keys(agg.tokensByTool).map((name) => ({ name })),
+        policy,
+    });
+    const report = buildTokenWasteReport({
+        action: 'token_intelligence',
+        policy,
+        loops,
+        tools,
+    });
+    return [
+        '# Token Intelligence Dashboard — Autopilot View',
+        '',
+        `**Period:** ${periodLabel(period)}`,
+        '',
+        `Analyzed ${String(entries.length)} ledger entries across ${String(agg.uniqueTools)} tools.`,
+        '',
+        formatTokenWasteReport(report),
+        '',
+    ].join('\n');
+}
 // ---------------------------------------------------------------------------
 // Empty state
 // ---------------------------------------------------------------------------
@@ -387,7 +429,7 @@ export async function handleTokenIntelligence(input) {
         getEntries(projectHash, dataDir, filter),
         getAggregation(projectHash, dataDir, filter),
     ]);
-    if (entries.length === 0 && view !== 'reconciliation') {
+    if (entries.length === 0 && view !== 'reconciliation' && view !== 'autopilot') {
         return { content: [{ type: 'text', text: renderEmpty(view, period) }] };
     }
     let text;
@@ -404,6 +446,9 @@ export async function handleTokenIntelligence(input) {
         case 'trends':
             text = renderTrends(entries, period);
             break;
+        case 'autopilot':
+            text = await renderAutopilot(entries, agg, period, projectPath);
+            break;
         default:
             text = renderSummary(agg, entries, period, groupBy);
             break;

package/dist/types/index.d.ts

@@ -79,6 +79,7 @@ export * from './runtime-security.js';
 export * from './workers.js';
 export * from './orchestration-runtime.js';
 export * from './token-optimization.js';
+export * from './token-waste-autopilot.js';
 export * from './llm-providers.js';
 export * from './plugins.js';
 export * from './github.js';

package/dist/types/index.js

@@ -80,6 +80,7 @@ export * from './runtime-security.js';
 export * from './workers.js';
 export * from './orchestration-runtime.js';
 export * from './token-optimization.js';
+export * from './token-waste-autopilot.js';
 export * from './llm-providers.js';
 export * from './plugins.js';
 export * from './github.js';

package/dist/types/token-waste-autopilot.d.ts

@@ -0,0 +1,142 @@
+export type TokenWasteDecisionKind = 'include' | 'summarize' | 'exclude' | 'recommend' | 'avoid' | 'warn' | 'override';
+export type TokenWasteConfidence = 'high' | 'medium' | 'low';
+export type TokenWasteAction = string;
+export interface TokenWastePolicyLoadOptions {
+    defaultPolicyPath?: string;
+}
+export interface TokenWasteEvidence {
+    source: 'policy' | 'project-config' | 'runtime' | 'spec' | 'tool-registry' | 'host-capability';
+    key: string;
+    value?: string | number | boolean;
+}
+export interface TokenWasteDecision {
+    decision: TokenWasteDecisionKind;
+    target: string;
+    reason: string;
+    evidence: TokenWasteEvidence[];
+    confidence: TokenWasteConfidence;
+}
+export interface TokenWasteOutputStrategy {
+    maxLines: number;
+    keepFailures?: boolean;
+    uniqueOnly?: boolean;
+    summarizeKeys?: boolean;
+}
+export interface TokenWastePolicy {
+    version: 1;
+    enabled: boolean;
+    context: {
+        generatedPatterns: string[];
+        stalePatterns: string[];
+        summarizePatterns: string[];
+        staleSessionMinutes: number;
+        safetyOverrideActions: string[];
+    };
+    outputs: {
+        strategies: Record<string, TokenWasteOutputStrategy>;
+    };
+    tools: {
+        groups: Record<string, string[]>;
+        maxRecommended: number;
+    };
+    loops: {
+        thresholds: Record<string, number>;
+        safetyOverrideActions: string[];
+    };
+    modelEffort: {
+        lowRisk: string;
+        default: string;
+        highRisk: string;
+        maxRisk: string;
+    };
+    redaction: {
+        maxSnippetChars: number;
+        redactPatterns: string[];
+    };
+}
+export interface LoadedTokenWastePolicy {
+    policy: TokenWastePolicy;
+    evidence: TokenWasteEvidence[];
+}
+export interface ContextCandidate {
+    path: string;
+    reason?: string;
+}
+export interface ContextPreflightInput {
+    action: TokenWasteAction;
+    policy: TokenWastePolicy;
+    candidates: ContextCandidate[];
+    spec?: {
+        id?: string;
+        status?: string;
+        risk?: string;
+        target?: string;
+    };
+}
+export interface ContextPreflightResult {
+    include: TokenWasteDecision[];
+    summarize: TokenWasteDecision[];
+    exclude: TokenWasteDecision[];
+}
+export interface VerboseOutputInput {
+    kind: string;
+    text: string;
+    policy: TokenWastePolicy;
+    fullOutputRef?: string;
+}
+export interface VerboseOutputResult {
+    text: string;
+    originalLines: number;
+    returnedLines: number;
+    fullOutputRef?: string;
+    decisions: TokenWasteDecision[];
+}
+export interface ToolRelevanceInput {
+    action: TokenWasteAction;
+    intentSignals: string[];
+    tools: {
+        name: string;
+        description?: string;
+    }[];
+    policy: TokenWastePolicy;
+    hostUnsupportedTools?: string[];
+}
+export interface ToolRelevanceResult {
+    recommended: TokenWasteDecision[];
+    avoided: TokenWasteDecision[];
+}
+export interface TokenWasteRuntimeEvent {
+    type: string;
+    key: string;
+    timestamp?: string;
+    changedSincePrevious?: boolean;
+}
+export interface TokenWasteLoopResult {
+    warnings: TokenWasteDecision[];
+}
+export interface TokenWasteModelAdvice {
+    effort: string;
+    reason: string;
+    evidence: TokenWasteEvidence[];
+}
+export interface TokenWasteAutopilotInput {
+    action: TokenWasteAction;
+    policy: TokenWastePolicy;
+    context?: ContextPreflightResult;
+    output?: VerboseOutputResult;
+    tools?: ToolRelevanceResult;
+    loops?: TokenWasteLoopResult;
+    spec?: {
+        id?: string;
+        risk?: string;
+        scope?: string;
+    };
+}
+export interface TokenWasteReport {
+    actionsTaken: TokenWasteDecision[];
+    recommendations: TokenWasteDecision[];
+    risks: TokenWasteDecision[];
+    evidence: TokenWasteEvidence[];
+    modelEffort: TokenWasteModelAdvice;
+}
+//# sourceMappingURL=token-waste-autopilot.d.ts.map

package/dist/types/token-waste-autopilot.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=token-waste-autopilot.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -34,14 +34,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.5.0",
-    "@planu/core-darwin-x64": "4.5.0",
-    "@planu/core-linux-arm64-gnu": "4.5.0",
-    "@planu/core-linux-arm64-musl": "4.5.0",
-    "@planu/core-linux-x64-gnu": "4.5.0",
-    "@planu/core-linux-x64-musl": "4.5.0",
-    "@planu/core-win32-arm64-msvc": "4.5.0",
-    "@planu/core-win32-x64-msvc": "4.5.0"
+    "@planu/core-darwin-arm64": "4.6.0",
+    "@planu/core-darwin-x64": "4.6.0",
+    "@planu/core-linux-arm64-gnu": "4.6.0",
+    "@planu/core-linux-arm64-musl": "4.6.0",
+    "@planu/core-linux-x64-gnu": "4.6.0",
+    "@planu/core-linux-x64-musl": "4.6.0",
+    "@planu/core-win32-arm64-msvc": "4.6.0",
+    "@planu/core-win32-x64-msvc": "4.6.0"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -182,7 +182,7 @@
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@supabase/supabase-js": "^2.108.1",
-    "@types/node": "^25.9.2",
+    "@types/node": "^25.9.3",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vitest/coverage-v8": "^4.1.8",
     "@vue/test-utils": "^2.4.11",
@@ -205,6 +205,6 @@
     "typescript-eslint": "^8.61.0",
     "vite": "^8.0.16",
     "vitest": "^4.1.8",
-    "vue": "^3.5.35"
+    "vue": "^3.5.38"
   }
 }

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "icon": "assets/plugin/icon.svg",
   "command": [
     "npx",