@planu/cli 4.7.2 → 4.7.3

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [4.7.3] - 2026-06-19
+
+### Features
+- feat: add reversible context compaction
+
+### Chores
+- chore(deps): update patch and minor dependencies
+
+
 ## [4.7.2] - 2026-06-16
 
 ### Features
@@ -4094,4 +4103,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/config/token-waste-autopilot.json

@@ -17,6 +17,22 @@
       "generic": { "maxLines": 60 }
     }
   },
+  "contextArtifacts": {
+    "enabled": true,
+    "ttlMs": 86400000,
+    "minTokens": 200
+  },
+  "contentCompaction": {
+    "strategies": {
+      "json": { "maxLines": 60, "maxSnippetChars": 240 },
+      "test-log": { "maxLines": 80, "keepFailures": true, "maxSnippetChars": 240 },
+      "runtime-log": { "maxLines": 60, "keepFailures": true, "uniqueOnly": true, "maxSnippetChars": 240 },
+      "search-results": { "maxLines": 80, "uniqueOnly": true, "maxSnippetChars": 180 },
+      "code": { "maxLines": 120, "maxSnippetChars": 240 },
+      "spec-or-handoff": { "maxLines": 120, "maxSnippetChars": 240 },
+      "generic-text": { "maxLines": 60, "maxSnippetChars": 240 }
+    }
+  },
   "tools": {
     "groups": {
       "spec": ["create_spec", "check_readiness", "challenge_spec", "update_status"],

package/dist/engine/compact/compact-middleware.d.ts

@@ -1,10 +1,10 @@
 import type { ToolResult } from '../../types/index.js';
-import type { CompactDecision } from '../../types/compact/compact-mode.js';
+import type { CompactDecision, CompactModeOptions } from '../../types/compact/compact-mode.js';
 /**
  * Apply compact mode formatting to a ToolResult.
  * - Truncates text content blocks to tokenBudget
  * - Preserves structuredContent (essential data: status, scores, blockers)
  * - Adds _meta.compactMode and _meta.contextUsed
  */
-export declare function applyCompactMode(result: ToolResult, decision: CompactDecision): ToolResult;
+export declare function applyCompactMode(result: ToolResult, decision: CompactDecision, options?: CompactModeOptions): ToolResult;
 //# sourceMappingURL=compact-middleware.d.ts.map

package/dist/engine/compact/compact-middleware.js

@@ -1,6 +1,47 @@
 // engine/compact/compact-middleware.ts — SPEC-922: Apply compact mode to tool responses
+import { compactContentAware } from '../token-optimizer/content-aware-compactor.js';
 /** Approximate chars per token for English text. */
 const CHARS_PER_TOKEN = 4;
+function defaultCompactPolicy(tokenBudget) {
+    return {
+        contextArtifacts: {
+            enabled: true,
+            ttlMs: 24 * 60 * 60 * 1000,
+            minTokens: tokenBudget,
+        },
+        contentCompaction: {
+            strategies: {
+                json: { maxLines: tokenBudget },
+                'test-log': { maxLines: tokenBudget },
+                'runtime-log': { maxLines: tokenBudget },
+                'search-results': { maxLines: tokenBudget },
+                code: { maxLines: tokenBudget },
+                'spec-or-handoff': { maxLines: tokenBudget },
+                'generic-text': { maxLines: tokenBudget },
+            },
+        },
+        redaction: {
+            maxSnippetChars: 240,
+            redactPatterns: ['secret', 'token', 'password', 'api_key'],
+        },
+    };
+}
+function withCompactionMeta(result, compaction) {
+    if (compaction === undefined) {
+        return result;
+    }
+    return {
+        ...result,
+        structuredContent: {
+            ...(result.structuredContent ?? {}),
+            compaction,
+        },
+        _meta: {
+            ...(typeof result._meta === 'object' && result._meta !== null ? result._meta : {}),
+            compaction,
+        },
+    };
+}
 /** Truncate a single text block to a token budget. */
 function truncateBlock(text, tokenBudget) {
     const maxChars = tokenBudget * CHARS_PER_TOKEN;
@@ -17,7 +58,7 @@ function truncateBlock(text, tokenBudget) {
  * - Preserves structuredContent (essential data: status, scores, blockers)
  * - Adds _meta.compactMode and _meta.contextUsed
  */
-export function applyCompactMode(result, decision) {
+export function applyCompactMode(result, decision, options = {}) {
     if (decision.mode !== 'compact') {
         // Still add _meta even in verbose mode if contextUsed was provided
         if (decision.contextUsed !== undefined) {
@@ -32,11 +73,31 @@ export function applyCompactMode(result, decision) {
         }
         return result;
     }
-    const truncatedContent = result.content.map((block) => ({
-        ...block,
-        text: truncateBlock(block.text, decision.tokenBudget),
-    }));
-    return {
+    let firstCompaction;
+    const truncatedContent = result.content.map((block) => {
+        if (options.projectPath !== undefined) {
+            const compacted = compactContentAware({
+                text: block.text,
+                policy: defaultCompactPolicy(decision.tokenBudget),
+                projectPath: options.projectPath,
+                sourcePath: options.sourcePath,
+                flow: options.flow,
+                kind: options.flow,
+            });
+            firstCompaction ??= compacted.artifact;
+            return {
+                ...block,
+                text: compacted.text.length < block.text.length
+                    ? `${compacted.text}\n\nArtifact: ${compacted.artifact?.artifactRef ?? 'not stored'}`
+                    : truncateBlock(block.text, decision.tokenBudget),
+            };
+        }
+        return {
+            ...block,
+            text: truncateBlock(block.text, decision.tokenBudget),
+        };
+    });
+    return withCompactionMeta({
         ...result,
         content: truncatedContent,
         _meta: {
@@ -45,6 +106,6 @@ export function applyCompactMode(result, decision) {
             contextUsed: decision.contextUsed,
             tokenBudget: decision.tokenBudget,
         },
-    };
+    }, firstCompaction);
 }
 //# sourceMappingURL=compact-middleware.js.map

package/dist/engine/context-artifacts/index.d.ts

@@ -0,0 +1,2 @@
+export { getContextArtifactStats, retrieveContextArtifact, storeContextArtifact } from './store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/context-artifacts/index.js

@@ -0,0 +1,2 @@
+export { getContextArtifactStats, retrieveContextArtifact, storeContextArtifact } from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/context-artifacts/store.d.ts

@@ -0,0 +1,5 @@
+import type { ContextArtifactStats, RetrieveContextArtifactResult, StoreContextArtifactInput, StoreContextArtifactResult } from '../../types/context-artifacts.js';
+export declare function storeContextArtifact(input: StoreContextArtifactInput): StoreContextArtifactResult;
+export declare function retrieveContextArtifact(projectPath: string, ref: string): RetrieveContextArtifactResult;
+export declare function getContextArtifactStats(projectPath: string): ContextArtifactStats;
+//# sourceMappingURL=store.d.ts.map

package/dist/engine/context-artifacts/store.js

@@ -0,0 +1,176 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSensitivePathRefusal, shouldBypassLeanMode, } from '../context-intelligence/compression-guards.js';
+import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
+const REF_PREFIX = 'ctx_';
+const REF_PATTERN = /^ctx_[a-f0-9]{32}$/;
+const FORBIDDEN_METADATA_KEY = /(?:secret|token|password|credential|api[_-]?key|private[_-]?key)/i;
+function artifactDir(projectPath) {
+    return join(projectDataDir(hashProjectPath(projectPath)), 'context-artifacts');
+}
+function artifactPath(projectPath, ref) {
+    if (!REF_PATTERN.test(ref)) {
+        return null;
+    }
+    return join(artifactDir(projectPath), `${ref}.json`);
+}
+function sha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+function safeMetadata(metadata) {
+    const safe = {};
+    for (const [key, value] of Object.entries(metadata ?? {})) {
+        if (FORBIDDEN_METADATA_KEY.test(key)) {
+            continue;
+        }
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            safe[key] =
+                typeof value === 'string' && FORBIDDEN_METADATA_KEY.test(value) ? '[redacted]' : value;
+        }
+    }
+    return safe;
+}
+function compactionMetadata(artifact) {
+    return {
+        artifactRef: artifact.ref,
+        originalTokens: artifact.originalTokens,
+        compactTokens: artifact.compactTokens,
+        tokensSaved: artifact.tokensSaved,
+        strategy: artifact.strategy,
+        contentType: artifact.contentType,
+        expiresAt: artifact.expiresAt,
+        retrievalHint: `Use artifactRef ${artifact.ref} to retrieve the full local output before ${artifact.expiresAt}.`,
+    };
+}
+function readArtifactFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeArtifactFile(path, artifact) {
+    writeFileSync(path, JSON.stringify(artifact, null, 2), 'utf-8');
+}
+export function storeContextArtifact(input) {
+    if (input.sourcePath) {
+        const refusal = getSensitivePathRefusal(input.sourcePath);
+        if (refusal !== null) {
+            return { stored: false, refusedReason: refusal };
+        }
+    }
+    if (input.flow && shouldBypassLeanMode(input.flow)) {
+        return {
+            stored: false,
+            refusedReason: `Refusing recoverable artifact for sensitive flow ${input.flow}`,
+        };
+    }
+    const contentHash = sha256(input.originalContent);
+    const ref = `${REF_PREFIX}${contentHash.slice(0, 32)}`;
+    const path = artifactPath(input.projectPath, ref);
+    if (path === null) {
+        return { stored: false, refusedReason: 'Invalid generated artifact ref' };
+    }
+    const now = Date.now();
+    const createdAt = new Date(now).toISOString();
+    const expiresAt = new Date(now + input.ttlMs).toISOString();
+    const tokensSaved = Math.max(0, input.originalTokens - input.compactTokens);
+    const previous = existsSync(path) ? readArtifactFile(path) : null;
+    const artifact = {
+        ref,
+        contentHash,
+        createdAt: previous?.createdAt ?? createdAt,
+        expiresAt,
+        ttlMs: input.ttlMs,
+        projectId: hashProjectPath(input.projectPath),
+        contentType: input.contentType,
+        strategy: input.strategy,
+        originalTokens: input.originalTokens,
+        compactTokens: input.compactTokens,
+        tokensSaved,
+        retrievalCount: previous?.retrievalCount ?? 0,
+        metadata: safeMetadata(input.metadata),
+        originalContent: input.originalContent,
+        compactContent: input.compactContent,
+    };
+    mkdirSync(artifactDir(input.projectPath), { recursive: true });
+    writeArtifactFile(path, artifact);
+    return { stored: true, artifact, metadata: compactionMetadata(artifact) };
+}
+export function retrieveContextArtifact(projectPath, ref) {
+    const path = artifactPath(projectPath, ref);
+    if (path === null) {
+        return {
+            found: false,
+            reason: 'invalid-ref',
+            hint: 'Artifact refs are opaque ctx_<hash> identifiers.',
+        };
+    }
+    if (!existsSync(path)) {
+        return {
+            found: false,
+            reason: 'missing',
+            hint: 'The artifact is missing or belongs to a different project.',
+        };
+    }
+    const artifact = readArtifactFile(path);
+    if (artifact === null) {
+        return {
+            found: false,
+            reason: 'corrupt',
+            hint: 'The artifact payload is corrupt and cannot be recovered.',
+        };
+    }
+    if (artifact.projectId !== hashProjectPath(projectPath)) {
+        return {
+            found: false,
+            reason: 'unauthorized',
+            hint: 'The artifact does not belong to this project scope.',
+        };
+    }
+    if (Date.parse(artifact.expiresAt) <= Date.now()) {
+        return {
+            found: false,
+            reason: 'expired',
+            hint: 'The artifact expired; rerun the source operation if exact output is needed.',
+        };
+    }
+    const updated = { ...artifact, retrievalCount: artifact.retrievalCount + 1 };
+    writeArtifactFile(path, updated);
+    return {
+        found: true,
+        artifact: updated,
+        hint: 'Full artifact recovered from local Planu storage.',
+    };
+}
+export function getContextArtifactStats(projectPath) {
+    const dir = artifactDir(projectPath);
+    const stats = {
+        artifactCount: 0,
+        totalOriginalTokens: 0,
+        totalCompactTokens: 0,
+        totalTokensSaved: 0,
+        retrievalCount: 0,
+    };
+    if (!existsSync(dir)) {
+        return stats;
+    }
+    for (const entry of readdirSync(dir)) {
+        if (!entry.endsWith('.json')) {
+            continue;
+        }
+        const artifact = readArtifactFile(join(dir, entry));
+        if (artifact === null || Date.parse(artifact.expiresAt) <= Date.now()) {
+            continue;
+        }
+        stats.artifactCount += 1;
+        stats.totalOriginalTokens += artifact.originalTokens;
+        stats.totalCompactTokens += artifact.compactTokens;
+        stats.totalTokensSaved += artifact.tokensSaved;
+        stats.retrievalCount += artifact.retrievalCount;
+    }
+    return stats;
+}
+//# sourceMappingURL=store.js.map

package/dist/engine/token-optimizer/content-aware-compactor.d.ts

@@ -0,0 +1,4 @@
+import type { ContentAwareCompactionInput, ContentAwareCompactionResult, ContextArtifactContentType } from '../../types/context-artifacts.js';
+export declare function classifyContentType(kind: string | undefined, text: string): ContextArtifactContentType;
+export declare function compactContentAware(input: ContentAwareCompactionInput): ContentAwareCompactionResult;
+//# sourceMappingURL=content-aware-compactor.d.ts.map

package/dist/engine/token-optimizer/content-aware-compactor.js

@@ -0,0 +1,230 @@
+import { countTokens } from './counter.js';
+import { storeContextArtifact } from '../context-artifacts/store.js';
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_MIN_TOKENS = 200;
+function redact(text, patterns) {
+    return patterns.reduce((current, pattern) => {
+        const re = new RegExp(pattern, 'gi');
+        return current.replace(re, '[redacted]');
+    }, text);
+}
+function escapeInert(text) {
+    return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function bounded(value, maxChars) {
+    return value.length <= maxChars ? value : `${value.slice(0, maxChars)}...`;
+}
+function isLikelyJson(text) {
+    const trimmed = text.trim();
+    return ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+        (trimmed.startsWith('[') && trimmed.endsWith(']')));
+}
+function isSearchResult(text) {
+    return text
+        .split('\n')
+        .some((line) => /^[^:\n]+:\d+(?::\d+)?:/.test(line) || /^[^:\n]+\(\d+,\d+\):/.test(line));
+}
+function isCode(text) {
+    const lines = text.split('\n');
+    const codeLines = lines.filter((line) => /^\s*(import|export|function|class|interface|type |const |let |var |def |fn |pub |func |struct |enum )/.test(line));
+    return lines.length > 0 && codeLines.length / lines.length > 0.12;
+}
+function isSpecOrHandoff(text) {
+    return (/\bSPEC-\d+\b/.test(text) ||
+        /\b(acceptance criteria|handoff|validation score|next action)\b/i.test(text));
+}
+export function classifyContentType(kind, text) {
+    const normalized = kind?.toLowerCase() ?? '';
+    if (normalized.includes('json') || isLikelyJson(text)) {
+        return 'json';
+    }
+    if (normalized.includes('test') ||
+        /\b(vitest|jest|failed tests?|test files?|assertionerror)\b/i.test(text)) {
+        return 'test-log';
+    }
+    if (normalized.includes('log') ||
+        /\b(error|warn|exception|stack trace|exit code)\b/i.test(text)) {
+        return 'runtime-log';
+    }
+    if (normalized.includes('search') || isSearchResult(text)) {
+        return 'search-results';
+    }
+    if (normalized.includes('code') || isCode(text)) {
+        return 'code';
+    }
+    if (normalized.includes('spec') || normalized.includes('handoff') || isSpecOrHandoff(text)) {
+        return 'spec-or-handoff';
+    }
+    return 'generic-text';
+}
+function summarizeJsonValue(value, depth = 0) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'number') {
+        return value;
+    }
+    if (typeof value === 'string') {
+        return value.length <= 80 ? value : `${value.slice(0, 80)}...`;
+    }
+    if (Array.isArray(value)) {
+        return {
+            length: value.length,
+            sample: value.slice(0, 3).map((item) => summarizeJsonValue(item, depth + 1)),
+        };
+    }
+    if (typeof value === 'object') {
+        const out = {};
+        for (const [key, child] of Object.entries(value).slice(0, depth > 1 ? 12 : 40)) {
+            if (/^(status|state|count|total|id|uuid|name|ok|success|error|errors|warning|warnings)$/i.test(key)) {
+                out[key] = summarizeJsonValue(child, depth + 1);
+            }
+            else if (depth < 2) {
+                out[key] = summarizeJsonValue(child, depth + 1);
+            }
+        }
+        return out;
+    }
+    if (typeof value === 'undefined') {
+        return 'undefined';
+    }
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    if (typeof value === 'symbol') {
+        return value.description ?? 'symbol';
+    }
+    return '[unsupported]';
+}
+function compactJson(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return JSON.stringify(summarizeJsonValue(parsed), null, 2);
+    }
+    catch {
+        return compactGenericText(text);
+    }
+}
+function compactLog(text, maxLines) {
+    const lines = text.split('\n');
+    const important = lines.filter((line) => /\b(error|fail|failed|failure|exception|stack|trace|warning|warn|duration|total|passed|exit code|exit status)\b/i.test(line));
+    const selected = important.length > 0 ? important : lines;
+    return [...new Set(selected)].slice(0, maxLines).join('\n');
+}
+function compactSearchResults(text, maxLines, maxSnippetChars) {
+    const grouped = new Map();
+    for (const line of text.split('\n')) {
+        const match = /^([^:\n]+):(\d+)(?::\d+)?:\s?(.*)$/.exec(line);
+        if (!match) {
+            continue;
+        }
+        const [, path, lineNumber, snippet] = match;
+        if (path === undefined || lineNumber === undefined) {
+            continue;
+        }
+        const entries = grouped.get(path) ?? [];
+        entries.push(`  ${lineNumber}: ${bounded(snippet ?? '', maxSnippetChars)}`);
+        grouped.set(path, [...new Set(entries)]);
+    }
+    if (grouped.size === 0) {
+        return compactGenericText(text);
+    }
+    const out = [];
+    for (const [path, entries] of grouped.entries()) {
+        out.push(path, ...entries.slice(0, maxLines));
+    }
+    return out.slice(0, maxLines).join('\n');
+}
+function bracesBalanced(text) {
+    let balance = 0;
+    for (const char of text) {
+        if (char === '{') {
+            balance += 1;
+        }
+        else if (char === '}') {
+            balance -= 1;
+        }
+        if (balance < 0) {
+            return false;
+        }
+    }
+    return balance === 0;
+}
+function compactCode(text) {
+    if (!bracesBalanced(text)) {
+        return compactGenericText(text);
+    }
+    const preserved = text
+        .split('\n')
+        .filter((line) => /^\s*(import|export|interface|type |class |function |async function|const [A-Z0-9_]+|enum |struct |def |fn |pub )/.test(line));
+    return preserved.length > 0 ? preserved.join('\n') : compactGenericText(text);
+}
+function compactSpecOrHandoff(text) {
+    const lines = text.split('\n');
+    const important = lines.filter((line) => /\b(SPEC-\d+|title:|status|acceptance criteria|blocker|blocked|files?|validation score|risk|security|privacy|next action|implementation|handoff)\b/i.test(line) ||
+        /^-\s*\[[ xX]\]\s+/.test(line) ||
+        /^#{1,3}\s/.test(line));
+    return (important.length > 0 ? important : lines).slice(0, 80).join('\n');
+}
+function compactGenericText(text) {
+    const lines = text.split('\n').filter((line) => line.trim().length > 0);
+    const important = lines.filter((line) => /^#{1,3}\s/.test(line) ||
+        /\b(error|failed|blocked|warning|todo|next action|pnpm|npm|git|https?:\/\/|\w+\/[\w./-]+\.\w+)\b/i.test(line));
+    return (important.length > 0 ? important : lines).slice(0, 60).join('\n');
+}
+function compactByType(type, text, maxLines, maxSnippetChars) {
+    switch (type) {
+        case 'json':
+            return compactJson(text);
+        case 'test-log':
+        case 'runtime-log':
+            return compactLog(text, maxLines);
+        case 'search-results':
+            return compactSearchResults(text, maxLines, maxSnippetChars);
+        case 'code':
+            return compactCode(text);
+        case 'spec-or-handoff':
+            return compactSpecOrHandoff(text);
+        case 'generic-text':
+            return compactGenericText(text);
+    }
+}
+export function compactContentAware(input) {
+    const contentType = classifyContentType(input.kind, input.text);
+    const strategyConfig = input.policy.contentCompaction?.strategies?.[contentType];
+    const maxLines = strategyConfig?.maxLines ?? 60;
+    const maxSnippetChars = strategyConfig?.maxSnippetChars ?? input.policy.redaction.maxSnippetChars;
+    const redacted = redact(input.text, input.policy.redaction.redactPatterns);
+    const compact = escapeInert(compactByType(contentType, redacted, maxLines, maxSnippetChars));
+    const originalTokens = countTokens(input.text).tokens;
+    const compactTokens = countTokens(compact).tokens;
+    const result = {
+        text: compact,
+        originalTokens,
+        compactTokens,
+        tokensSaved: Math.max(0, originalTokens - compactTokens),
+        strategy: contentType,
+        contentType,
+    };
+    const artifactsEnabled = input.policy.contextArtifacts?.enabled !== false;
+    const minTokens = input.policy.contextArtifacts?.minTokens ?? DEFAULT_MIN_TOKENS;
+    if (!artifactsEnabled || input.projectPath === undefined || originalTokens < minTokens) {
+        return result;
+    }
+    const stored = storeContextArtifact({
+        projectPath: input.projectPath,
+        originalContent: input.text,
+        compactContent: compact,
+        contentType,
+        strategy: contentType,
+        originalTokens,
+        compactTokens,
+        ttlMs: input.policy.contextArtifacts?.ttlMs ?? DEFAULT_TTL_MS,
+        sourcePath: input.sourcePath,
+        flow: input.flow,
+        metadata: input.metadata,
+    });
+    return {
+        ...result,
+        ...(stored.metadata !== undefined ? { artifact: stored.metadata } : {}),
+        ...(stored.refusedReason !== undefined ? { refusedReason: stored.refusedReason } : {}),
+    };
+}
+//# sourceMappingURL=content-aware-compactor.js.map

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

@@ -9,6 +9,7 @@ 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 { classifyContentType, compactContentAware } from './content-aware-compactor.js';
 export { analyzeContextPreflight } from './context-preflight.js';
 export { filterVerboseOutput } from './output-filter.js';
 export { recommendRelevantTools, toolsFromPolicyGroups } from './tool-relevance.js';

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

@@ -10,6 +10,7 @@ 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 { classifyContentType, compactContentAware } from './content-aware-compactor.js';
 export { analyzeContextPreflight } from './context-preflight.js';
 export { filterVerboseOutput } from './output-filter.js';
 export { recommendRelevantTools, toolsFromPolicyGroups } from './tool-relevance.js';

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

@@ -1,3 +1,4 @@
+import { compactContentAware } from './content-aware-compactor.js';
 function escapeInert(text) {
     return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
@@ -46,7 +47,21 @@ 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);
+    let compact = redact(escapeInert(lines.join('\n')), input.policy.redaction.redactPatterns);
+    let compaction;
+    if (input.policy.contextArtifacts?.enabled === true && input.projectPath !== undefined) {
+        const contentAware = compactContentAware({
+            text: input.text,
+            policy: input.policy,
+            kind: input.kind,
+            projectPath: input.projectPath,
+            sourcePath: input.sourcePath,
+            flow: input.flow,
+            metadata: input.metadata,
+        });
+        compact = contentAware.text;
+        compaction = contentAware.artifact;
+    }
     const decisions = [
         {
             decision: originalLines > lines.length ? 'summarize' : 'include',
@@ -59,8 +74,9 @@ export function filterVerboseOutput(input) {
     return {
         text: compact,
         originalLines,
-        returnedLines: lines.length,
+        returnedLines: compact.split('\n').length,
         ...(input.fullOutputRef !== undefined ? { fullOutputRef: input.fullOutputRef } : {}),
+        ...(compaction !== undefined ? { compaction } : {}),
         decisions,
     };
 }

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

@@ -39,6 +39,18 @@ function validatePolicy(value) {
     if (!isRecord(policy.outputs.strategies)) {
         throw new Error('Invalid token waste policy at outputs.strategies: expected object');
     }
+    if (policy.contextArtifacts !== undefined) {
+        if (!Number.isFinite(policy.contextArtifacts.ttlMs) || policy.contextArtifacts.ttlMs < 1) {
+            throw new Error('Invalid token waste policy at contextArtifacts.ttlMs: expected positive number');
+        }
+        if (!Number.isFinite(policy.contextArtifacts.minTokens) ||
+            policy.contextArtifacts.minTokens < 1) {
+            throw new Error('Invalid token waste policy at contextArtifacts.minTokens: expected positive number');
+        }
+    }
+    if (policy.contentCompaction !== undefined && !isRecord(policy.contentCompaction.strategies)) {
+        throw new Error('Invalid token waste policy at contentCompaction.strategies: expected object');
+    }
     if (!isRecord(policy.tools.groups)) {
         throw new Error('Invalid token waste policy at tools.groups: expected object');
     }

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

@@ -18,6 +18,10 @@ export declare class OptimizationReporter {
      * Record a cache hit for a tool.
      */
     recordCacheHit(toolName: string, tokensSaved: number): void;
+    /**
+     * Record measured savings from reversible compaction.
+     */
+    recordCompaction(toolName: string, tokensSaved: number, retrievals?: number): void;
     /**
      * Record a cache miss for a tool.
      */

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

@@ -28,6 +28,16 @@ export class OptimizationReporter {
         record.tokensSaved += tokensSaved;
         this.totalSaved += tokensSaved;
     }
+    /**
+     * Record measured savings from reversible compaction.
+     */
+    recordCompaction(toolName, tokensSaved, retrievals = 0) {
+        const record = this.getOrCreateRecord(toolName);
+        record.compactionTokensSaved = (record.compactionTokensSaved ?? 0) + tokensSaved;
+        record.artifactRetrievals = (record.artifactRetrievals ?? 0) + retrievals;
+        record.tokensSaved += tokensSaved;
+        this.totalSaved += tokensSaved;
+    }
     /**
      * Record a cache miss for a tool.
      */
@@ -106,7 +116,8 @@ export class OptimizationReporter {
             for (const record of toolRecords) {
                 lines.push(`- ${record.toolName}: ${String(record.totalTokens)} tokens, ` +
                     `${String(record.callCount)} calls, ` +
-                    `${String(record.tokensSaved)} saved`);
+                    `${String(record.tokensSaved)} saved ` +
+                    `(compaction ${String(record.compactionTokensSaved ?? 0)}, retrievals ${String(record.artifactRetrievals ?? 0)})`);
             }
         }
         return lines.join('\n');
@@ -134,6 +145,8 @@ export class OptimizationReporter {
                 cacheHits: 0,
                 cacheMisses: 0,
                 tokensSaved: 0,
+                compactionTokensSaved: 0,
+                artifactRetrievals: 0,
             };
             this.toolRecords.set(toolName, record);
         }

package/dist/engine/web-fetcher/docs-fetcher.js

@@ -1,6 +1,7 @@
 // Planu — Web Fetcher: consultDocs orchestration
 import { searchAndRegisterFramework, saveRegistry } from '../registry-updater.js';
 import { loadDocsRegistry, findDocsEntry, setDocsRegistryCache, getStoredRegistryPath, } from './registry-loader.js';
+import { DEFAULT_CONFIG } from './cache.js';
 import { fetchUrl } from './http-client.js';
 import { extractTextContent, extractCodeBlocks, extractBestPractices, buildSummaryFromContent, buildPlaceholderSummary, buildPlaceholderExamples, buildPlaceholderBestPractices, } from './content-extractor.js';
 export async function consultDocsImpl(topic, framework) {
@@ -25,7 +26,10 @@ export async function consultDocsImpl(topic, framework) {
         : `https://www.google.com/search?q=${encodeURIComponent(`${resolvedFramework} ${topic} documentation`)}`;
     const baseUrl = docsEntry?.base ?? '';
     if (baseUrl) {
-        const fetchResult = await fetchUrl(docsUrl);
+        const fetchResult = await fetchUrl(docsUrl, {
+            ...DEFAULT_CONFIG,
+            timeoutMs: 2_500,
+        });
         if (fetchResult) {
             const textContent = extractTextContent(fetchResult.content);
             const codeBlocks = extractCodeBlocks(fetchResult.content);

package/dist/tools/safe-handler.js

@@ -268,7 +268,10 @@ function safeWithTelemetry(toolName, handler) {
             // SPEC-455: Compress verbose JSON outputs to save LLM tokens
             const compressed = compressToolOutput(result);
             // SPEC-922: Apply compact mode middleware
-            const compacted = applyCompactMode(compressed, decision);
+            const compacted = applyCompactMode(compressed, decision, {
+                projectPath,
+                flow: toolName,
+            });
             // Inject pending drift banner (non-blocking, informational only)
             const driftBanner = projectPath !== undefined ? await checkPendingDriftBanner(projectPath) : null;
             const withDrift = injectDriftBanner(compacted, driftBanner);

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

@@ -27,10 +27,12 @@ export function handleTokenUsage(args) {
     let details;
     if (groupBy === 'tool' && toolRecords.length > 0) {
         const lines = toolRecords.map((r) => `| ${r.toolName} | ${String(r.totalTokens)} | ${String(r.callCount)} | ` +
-            `${String(r.cacheHits)}/${String(r.cacheHits + r.cacheMisses)} | ${String(r.tokensSaved)} |`);
+            `${String(r.cacheHits)}/${String(r.cacheHits + r.cacheMisses)} | ` +
+            `${String(r.tokensSaved)} | ${String(r.compactionTokensSaved ?? 0)} | ` +
+            `${String(r.artifactRetrievals ?? 0)} |`);
         details = [
-            '| Tool | Tokens | Calls | Cache H/T | Saved |',
-            '|------|--------|-------|-----------|-------|',
+            '| Tool | Tokens | Calls | Cache H/T | Saved | Compaction Saved | Retrievals |',
+            '|------|--------|-------|-----------|-------|------------------|------------|',
             ...lines,
         ].join('\n');
     }

package/dist/types/compact/compact-mode.d.ts

@@ -20,6 +20,11 @@ export interface CompactDecision {
     contextUsed?: number;
     reason: 'header_above_enter' | 'header_below_exit' | 'hysteresis_keep' | 'no_header';
 }
+export interface CompactModeOptions {
+    projectPath?: string;
+    sourcePath?: string;
+    flow?: string;
+}
 export interface CompactMetrics {
     compactDecisions: number;
     verboseDecisions: number;

package/dist/types/context-artifacts.d.ts

@@ -0,0 +1,96 @@
+export type ContextArtifactContentType = 'json' | 'test-log' | 'runtime-log' | 'search-results' | 'code' | 'spec-or-handoff' | 'generic-text';
+export interface ContextArtifactCompactionMetadata {
+    artifactRef: string;
+    originalTokens: number;
+    compactTokens: number;
+    tokensSaved: number;
+    strategy: string;
+    contentType: ContextArtifactContentType;
+    expiresAt: string;
+    retrievalHint: string;
+}
+export interface ContextArtifact {
+    ref: string;
+    contentHash: string;
+    createdAt: string;
+    expiresAt: string;
+    ttlMs: number;
+    projectId: string;
+    contentType: ContextArtifactContentType;
+    strategy: string;
+    originalTokens: number;
+    compactTokens: number;
+    tokensSaved: number;
+    retrievalCount: number;
+    metadata: Record<string, string | number | boolean>;
+    originalContent: string;
+    compactContent: string;
+}
+export interface StoreContextArtifactInput {
+    projectPath: string;
+    originalContent: string;
+    compactContent: string;
+    contentType: ContextArtifactContentType;
+    strategy: string;
+    originalTokens: number;
+    compactTokens: number;
+    ttlMs: number;
+    sourcePath?: string;
+    flow?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface StoreContextArtifactResult {
+    stored: boolean;
+    artifact?: ContextArtifact;
+    metadata?: ContextArtifactCompactionMetadata;
+    refusedReason?: string;
+}
+export interface RetrieveContextArtifactResult {
+    found: boolean;
+    artifact?: ContextArtifact;
+    reason?: 'missing' | 'expired' | 'corrupt' | 'invalid-ref' | 'unauthorized';
+    hint: string;
+}
+export interface ContextArtifactStats {
+    artifactCount: number;
+    totalOriginalTokens: number;
+    totalCompactTokens: number;
+    totalTokensSaved: number;
+    retrievalCount: number;
+}
+export interface ContentAwareCompactionInput {
+    text: string;
+    policy: {
+        contextArtifacts?: {
+            enabled?: boolean;
+            ttlMs?: number;
+            minTokens?: number;
+        };
+        contentCompaction?: {
+            strategies?: Partial<Record<ContextArtifactContentType, {
+                maxLines?: number;
+                maxSnippetChars?: number;
+            }>>;
+        };
+        redaction: {
+            maxSnippetChars: number;
+            redactPatterns: string[];
+        };
+    };
+    projectPath?: string;
+    kind?: string;
+    sourcePath?: string;
+    flow?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ContentAwareCompactionResult {
+    text: string;
+    originalTokens: number;
+    compactTokens: number;
+    tokensSaved: number;
+    strategy: string;
+    contentType: ContextArtifactContentType;
+    artifact?: ContextArtifactCompactionMetadata;
+    refusedReason?: string;
+}
+//# sourceMappingURL=context-artifacts.d.ts.map

package/dist/types/context-artifacts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context-artifacts.js.map

package/dist/types/index.d.ts

@@ -80,6 +80,7 @@ export * from './workers.js';
 export * from './orchestration-runtime.js';
 export * from './token-optimization.js';
 export * from './token-waste-autopilot.js';
+export * from './context-artifacts.js';
 export * from './minimal-implementation-gate.js';
 export * from './llm-providers.js';
 export * from './plugins.js';

package/dist/types/index.js

@@ -81,6 +81,7 @@ export * from './workers.js';
 export * from './orchestration-runtime.js';
 export * from './token-optimization.js';
 export * from './token-waste-autopilot.js';
+export * from './context-artifacts.js';
 export * from './minimal-implementation-gate.js';
 export * from './llm-providers.js';
 export * from './plugins.js';

package/dist/types/token-optimization.d.ts

@@ -104,6 +104,8 @@ export interface ToolTokenRecord {
     cacheHits: number;
     cacheMisses: number;
     tokensSaved: number;
+    compactionTokensSaved?: number;
+    artifactRetrievals?: number;
 }
 export interface BatchEntry {
     input: unknown;

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

@@ -1,3 +1,4 @@
+import type { ContextArtifactCompactionMetadata } from './context-artifacts.js';
 export type TokenWasteDecisionKind = 'include' | 'summarize' | 'exclude' | 'recommend' | 'avoid' | 'warn' | 'override';
 export type TokenWasteConfidence = 'high' | 'medium' | 'low';
 export type TokenWasteAction = string;
@@ -21,6 +22,7 @@ export interface TokenWasteOutputStrategy {
     keepFailures?: boolean;
     uniqueOnly?: boolean;
     summarizeKeys?: boolean;
+    maxSnippetChars?: number;
 }
 export interface TokenWastePolicy {
     version: 1;
@@ -35,6 +37,14 @@ export interface TokenWastePolicy {
     outputs: {
         strategies: Record<string, TokenWasteOutputStrategy>;
     };
+    contextArtifacts?: {
+        enabled: boolean;
+        ttlMs: number;
+        minTokens: number;
+    };
+    contentCompaction?: {
+        strategies: Record<string, TokenWasteOutputStrategy>;
+    };
     tools: {
         groups: Record<string, string[]>;
         maxRecommended: number;
@@ -83,12 +93,17 @@ export interface VerboseOutputInput {
     text: string;
     policy: TokenWastePolicy;
     fullOutputRef?: string;
+    projectPath?: string;
+    sourcePath?: string;
+    flow?: string;
+    metadata?: Record<string, unknown>;
 }
 export interface VerboseOutputResult {
     text: string;
     originalLines: number;
     returnedLines: number;
     fullOutputRef?: string;
+    compaction?: ContextArtifactCompactionMetadata;
     decisions: TokenWasteDecision[];
 }
 export interface ToolRelevanceInput {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.7.2",
+  "version": "4.7.3",
   "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.7.2",
-    "@planu/core-darwin-x64": "4.7.2",
-    "@planu/core-linux-arm64-gnu": "4.7.2",
-    "@planu/core-linux-arm64-musl": "4.7.2",
-    "@planu/core-linux-x64-gnu": "4.7.2",
-    "@planu/core-linux-x64-musl": "4.7.2",
-    "@planu/core-win32-arm64-msvc": "4.7.2",
-    "@planu/core-win32-x64-msvc": "4.7.2"
+    "@planu/core-darwin-arm64": "4.7.3",
+    "@planu/core-darwin-x64": "4.7.3",
+    "@planu/core-linux-arm64-gnu": "4.7.3",
+    "@planu/core-linux-arm64-musl": "4.7.3",
+    "@planu/core-linux-x64-gnu": "4.7.3",
+    "@planu/core-linux-x64-musl": "4.7.3",
+    "@planu/core-win32-arm64-msvc": "4.7.3",
+    "@planu/core-win32-x64-msvc": "4.7.3"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -129,7 +129,7 @@
   ],
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.104.2",
+    "@anthropic-ai/sdk": "^0.105.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "glob": "^13.0.6",
     "yaml": "^2.9.0",
@@ -191,7 +191,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
-    "happy-dom": "^20.10.5",
+    "happy-dom": "^20.10.6",
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.4.3",
     "knip": "^6.17.1",

package/planu-native.json

@@ -1,20 +1,26 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.7.2",
+  "version": "4.7.3",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {
       "requiresMcp": false,
       "requiresDaemon": false,
-      "hosts": ["codex", "claude-code"],
+      "hosts": [
+        "codex",
+        "claude-code"
+      ],
       "commands": [
         {
           "id": "planu.status",
           "title": "Project status",
           "description": "Show the compact Planu project snapshot without loading the MCP tool graph.",
           "invocation": "planu status",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handlePlanStatus"
@@ -24,7 +30,10 @@
           "title": "Create spec",
           "description": "Create a new spec through the CLI-backed SDD contract.",
           "invocation": "planu spec create \"<title>\"",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleCreateSpec"
@@ -34,7 +43,10 @@
           "title": "List specs",
           "description": "List specs in the current project with optional status/type filters.",
           "invocation": "planu spec list",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleListSpecs"
@@ -44,7 +56,10 @@
           "title": "Validate spec",
           "description": "Validate a spec against the current codebase from the native CLI surface.",
           "invocation": "planu spec validate SPEC-001",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleValidate"
@@ -54,7 +69,10 @@
           "title": "Audit technical debt",
           "description": "Run the read-only project audit path for lightweight debt checks.",
           "invocation": "planu audit debt",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleAudit"
@@ -64,7 +82,10 @@
           "title": "Check release readiness",
           "description": "Check local branch cleanliness and main/develop/release sync readiness.",
           "invocation": "planu release check",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "releaseCommand"

package/planu-plugin.json

@@ -2,9 +2,12 @@
   "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.7.2",
+  "version": "4.7.3",
   "icon": "assets/plugin/icon.svg",
-  "command": ["npx", "@planu/cli@latest"],
+  "command": [
+    "npx",
+    "@planu/cli@latest"
+  ],
   "packageName": "@planu/cli",
   "capabilities": {
     "tools": [
@@ -23,17 +26,42 @@
       "create_skill",
       "skill_search"
     ],
-    "resources": ["planu://specs/list", "planu://specs/{id}", "planu://project/status", "planu://roadmap"],
-    "prompts": ["create-spec-from-idea", "review-spec-readiness", "generate-implementation-plan"],
-    "subagents": ["sdd-orchestrator", "spec-challenger", "test-generator"]
+    "resources": [
+      "planu://specs/list",
+      "planu://specs/{id}",
+      "planu://project/status",
+      "planu://roadmap"
+    ],
+    "prompts": [
+      "create-spec-from-idea",
+      "review-spec-readiness",
+      "generate-implementation-plan"
+    ],
+    "subagents": [
+      "sdd-orchestrator",
+      "spec-challenger",
+      "test-generator"
+    ]
   },
   "compatibility": {
     "minimumHostVersion": "1.0.0",
-    "requiredFeatures": ["mcp-tools", "file-editing"]
+    "requiredFeatures": [
+      "mcp-tools",
+      "file-editing"
+    ]
   },
   "repository": "https://github.com/planu-dev/planu",
   "author": "Planu",
   "license": "MIT",
   "homepage": "https://planu.dev",
-  "keywords": ["sdd", "spec-driven-development", "mcp", "specs", "planning", "ai", "bdd", "tdd"]
+  "keywords": [
+    "sdd",
+    "spec-driven-development",
+    "mcp",
+    "specs",
+    "planning",
+    "ai",
+    "bdd",
+    "tdd"
+  ]
 }