@planu/cli 4.10.5 → 4.10.7

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

package/dist/tools/package-handoff.js

@@ -3,7 +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 { analyzeContextPreflight, buildTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, toolsFromPolicyGroups, } from '../engine/token-optimizer/index.js';
 import { appendTransitionEvent } from '../storage/transition-log.js';
 import { formatProjectGraphContext, queryProjectGraphSlice, } from '../engine/project-graph/index.js';
 import { analyzeMinimalImplementation, loadMinimalImplementationPolicy, } from '../engine/minimality/index.js';
@@ -137,6 +137,98 @@ function formatHandoff(pkg) {
     }
     return lines.join('\n');
 }
+function topItems(items, limit) {
+    return items.slice(0, limit);
+}
+function buildHandoffSummaryText(args) {
+    const lines = [];
+    lines.push(`# Implementation Handoff Package - ${args.pkg.specId}`);
+    lines.push('');
+    lines.push(`Readiness Score: ${String(args.pkg.readinessScore)}/100`);
+    lines.push(`Blocked: ${args.pkg.blocked ? 'yes' : 'no'}`);
+    if (args.pkg.handoffPath) {
+        lines.push(`Handoff Path: ${args.pkg.handoffPath}`);
+    }
+    if (args.pkg.contextHash) {
+        lines.push(`Context Hash: ${args.pkg.contextHash}`);
+    }
+    lines.push(`Counts: ${String(args.pkg.criteria.length)} criteria, ${String(args.pkg.filesToModify.length)} files to modify, ${String(args.pkg.filesToCreate.length)} files to create, ${String(args.pkg.testPlan.length)} tests, ${String(args.pkg.risks.length)} risks.`);
+    if (args.topBlockers.length > 0) {
+        lines.push(`Top blockers: ${args.topBlockers.join('; ')}`);
+    }
+    if (args.topRisks.length > 0) {
+        lines.push(`Top risks: ${args.topRisks.join('; ')}`);
+    }
+    if (args.minimalityBlocked !== null) {
+        lines.push(`Minimality: ${args.minimalityBlocked ? 'blocked' : 'pass'}`);
+    }
+    if (args.tokenWasteRiskCount !== null) {
+        lines.push(`Token Waste Autopilot risks: ${String(args.tokenWasteRiskCount)}`);
+    }
+    lines.push(`Next Action: ${args.pkg.nextAction}`);
+    lines.push('');
+    lines.push('Full handoff is available via the handoffPath artifact; it is not embedded by default.');
+    return lines.join('\n');
+}
+function summarizeMinimality(report) {
+    if (report === null) {
+        return undefined;
+    }
+    const blockingFindings = report.findings.filter((finding) => finding.blocksDone);
+    return {
+        enabled: report.enabled,
+        blocked: report.blocked,
+        findingCount: report.findings.length,
+        blockingFindingCount: blockingFindings.length,
+        blockersTop3: topItems(blockingFindings, 3).map((finding) => ({
+            ruleId: finding.ruleId,
+            target: finding.target,
+            evidence: finding.evidence,
+        })),
+        safetyExceptionCount: report.safetyExceptions.length,
+        debtEvidenceCount: report.debtEvidence.length,
+    };
+}
+function summarizeTokenWaste(report) {
+    if (report === null) {
+        return undefined;
+    }
+    return {
+        actionsTakenCount: report.actionsTaken.length,
+        recommendationCount: report.recommendations.length,
+        riskCount: report.risks.length,
+        risksTop3: topItems(report.risks, 3).map((risk) => ({
+            decision: risk.decision,
+            target: risk.target,
+            reason: risk.reason,
+            confidence: risk.confidence,
+        })),
+        modelEffort: {
+            effort: report.modelEffort.effort,
+            reason: report.modelEffort.reason,
+        },
+    };
+}
+function summarizeGraphContext(graphContext) {
+    if (graphContext === null || typeof graphContext !== 'object') {
+        return { available: false };
+    }
+    const graph = graphContext;
+    return {
+        available: true,
+        nodeCount: Array.isArray(graph.nodes) ? graph.nodes.length : 0,
+        edgeCount: Array.isArray(graph.edges) ? graph.edges.length : 0,
+        summary: graph.summary,
+        tokenSavings: graph.tokenSavings,
+        freshness: graph.freshness
+            ? {
+                graphPath: graph.freshness.graphPath,
+                stale: graph.freshness.stale,
+                reason: graph.freshness.reason,
+            }
+            : undefined,
+    };
+}
 async function buildHandoffTokenWasteReport(pkg, knowledge, spec) {
     try {
         const { policy } = await loadTokenWastePolicy(knowledge.projectPath);
@@ -277,12 +369,6 @@ export async function handlePackageHandoff(args) {
         ? `${formatHandoff(pkgWithScore)}\n${graphContext.text}`
         : formatHandoff(pkgWithScore);
     const minimalityReport = await buildMinimalImplementationReport(pkgWithScore, knowledge, spec, baseHandoffText);
-    const handoffText = minimalityReport !== null && minimalityReport.markdown.length > 0
-        ? `${baseHandoffText}\n${minimalityReport.markdown}`
-        : baseHandoffText;
-    const formatted = tokenWasteReport !== null
-        ? `${handoffText}\n${formatTokenWasteReport(tokenWasteReport)}`
-        : handoffText;
     void appendTransitionEvent({
         projectId,
         specId,
@@ -296,16 +382,54 @@ export async function handlePackageHandoff(args) {
     }).catch(() => {
         /* best-effort — handoff rendering should not fail because telemetry failed */
     });
+    const topBlockers = topItems(pkgWithScore.blockers, 3);
+    const topRisks = topItems(pkgWithScore.risks, 5);
+    const minimalitySummary = summarizeMinimality(minimalityReport);
+    const tokenWasteSummary = summarizeTokenWaste(tokenWasteReport);
+    const graphSummary = graphContext !== null ? summarizeGraphContext(graphContext.structured) : undefined;
     return {
-        content: [{ type: 'text', text: formatted }],
+        content: [
+            {
+                type: 'text',
+                text: buildHandoffSummaryText({
+                    pkg: pkgWithScore,
+                    topBlockers,
+                    topRisks,
+                    minimalityBlocked: minimalityReport?.blocked ?? null,
+                    tokenWasteRiskCount: tokenWasteReport?.risks.length ?? null,
+                }),
+            },
+        ],
         structuredContent: {
+            specId,
             blocked: pkgWithScore.blocked,
-            blockers: pkgWithScore.blockers,
+            readinessScore: pkgWithScore.readinessScore,
+            blockersCount: pkgWithScore.blockers.length,
+            blockersTop3: topBlockers,
+            risksTop5: topRisks,
+            criteriaTop5: topItems(pkgWithScore.criteria, 5),
+            constraintsTop5: topItems(pkgWithScore.constraints, 5),
+            warningsTop5: topItems(pkgWithScore.warnings, 5),
             handoffPath: pkgWithScore.handoffPath,
             contextHash: pkgWithScore.contextHash,
-            ...(minimalityReport !== null ? { minimality: minimalityReport } : {}),
-            ...(tokenWasteReport !== null ? { tokenWaste: tokenWasteReport } : {}),
-            ...(graphContext !== null ? { graphContext: graphContext.structured } : {}),
+            artifactRefs: {
+                handoff: pkgWithScore.handoffPath,
+            },
+            counts: {
+                criteria: pkgWithScore.criteria.length,
+                filesToModify: pkgWithScore.filesToModify.length,
+                filesToCreate: pkgWithScore.filesToCreate.length,
+                ownership: pkgWithScore.ownership.length,
+                testPlan: pkgWithScore.testPlan.length,
+                risks: pkgWithScore.risks.length,
+                constraints: pkgWithScore.constraints.length,
+                warnings: pkgWithScore.warnings.length,
+                outOfScope: pkgWithScore.outOfScope.length,
+            },
+            nextAction: pkgWithScore.nextAction,
+            ...(minimalitySummary !== undefined ? { minimality: minimalitySummary } : {}),
+            ...(tokenWasteSummary !== undefined ? { tokenWaste: tokenWasteSummary } : {}),
+            ...(graphSummary !== undefined ? { graphContext: graphSummary } : {}),
         },
     };
 }

package/dist/tools/reverse-engineer/handler.js

@@ -278,15 +278,6 @@ export async function handleReverseEngineer(args) {
             type: 'text',
             text: ti('reverseEngineer.completed', { count: String(ca.limit) }),
         },
-        {
-            type: 'text',
-            text: JSON.stringify({
-                specId,
-                title: spec.title,
-                status: 'draft',
-                analysis,
-            }, null, 2),
-        },
     ];
     // AC-10: Add human-readable summary for deep-v2
     if (deepV2Summary) {
@@ -295,6 +286,14 @@ export async function handleReverseEngineer(args) {
             text: deepV2Summary,
         });
     }
-    return { content };
+    return {
+        content,
+        structuredContent: {
+            specId,
+            title: spec.title,
+            status: 'draft',
+            analysis,
+        },
+    };
 }
 //# sourceMappingURL=handler.js.map

package/dist/tools/rollback-release.js

@@ -2,6 +2,7 @@
 import { runRollback } from '../engine/release/rollback-runner.js';
 import { writePostmortem } from '../engine/release/postmortem-generator.js';
 import { appendTransitionEvent } from '../storage/transition-log.js';
+import { formatKeyValue } from './output-formatter.js';
 // ---------------------------------------------------------------------------
 // Age guard (30 days)
 // ---------------------------------------------------------------------------
@@ -93,7 +94,7 @@ export async function handleRollbackRelease(input) {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify({
+                            text: formatKeyValue({
                                 error: 'rollback_age_exceeded',
                                 code: 422,
                                 fixHint: `Versions older than ${MAX_AGE_DAYS} days require manual operator approval. Re-run with allowAged: true.`,
@@ -102,6 +103,13 @@ export async function handleRollbackRelease(input) {
                         },
                     ],
                     isError: true,
+                    structuredContent: {
+                        error: 'rollback_age_exceeded',
+                        code: 422,
+                        fixHint: `Versions older than ${MAX_AGE_DAYS} days require manual operator approval. Re-run with allowAged: true.`,
+                        ageDays: Math.round(ageDays),
+                        maxAgeDays: MAX_AGE_DAYS,
+                    },
                 };
             }
         }
@@ -178,10 +186,20 @@ export async function handleRollbackRelease(input) {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({ ...output, hints: additionalHints }),
+                text: formatKeyValue({
+                    ok: output.ok,
+                    steps: output.steps.length,
+                    failedSteps: output.steps.filter((step) => step.status === 'failed').length,
+                    skippedSteps: output.steps.filter((step) => step.status === 'skipped').length,
+                    postmortemPath: output.postmortemPath,
+                    smokeTestOk: output.smokeTest?.ok,
+                    hints: additionalHints.length,
+                    firstHint: additionalHints[0],
+                }),
             },
         ],
         isError: !output.ok,
+        structuredContent: { ...output, hints: additionalHints },
     };
 }
 //# sourceMappingURL=rollback-release.js.map

package/dist/tools/spec-diff-handler.js

@@ -1,5 +1,5 @@
 // tools/spec-diff-handler.ts — Handlers for diff_spec_versions and spec_history (SPEC-284)
-import { compactResult } from './output-formatter.js';
+import { compactJson, compactResult } from './output-formatter.js';
 import { projectDataDir } from '../storage/index.js';
 import { computeSpecVersionDiff, formatDiffAsText, listSpecVersionHistory, } from '../engine/spec-differ.js';
 /** Handler for the diff_spec_versions tool. */
@@ -21,7 +21,7 @@ export async function handleDiffSpecVersions(args) {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({
+                        text: compactJson({
                             specId: diff.specId,
                             fromTag: diff.fromTag,
                             toTag: diff.toTag,
@@ -30,7 +30,7 @@ export async function handleDiffSpecVersions(args) {
                             linesRemoved: diff.removed.length,
                             criteriaChanges: diff.criteriaChanges,
                             sectionChanges: diff.sectionChanges,
-                        }, null, 2),
+                        }),
                     },
                 ],
             };

package/dist/tools/status-handler.js

@@ -308,7 +308,12 @@ export async function handlePlanStatus(args) {
             ...(sessionTip !== undefined ? { sessionTip } : {}),
             ...(tokenWasteHint !== undefined ? { tokenWasteHint } : {}),
             ...(graphFreshnessHint !== undefined ? { graphFreshnessHint } : {}),
-            ...(btwHint !== undefined ? { btw_hint: btwHint } : {}),
+            ...(btwHint !== undefined
+                ? {
+                    btwHintAvailable: true,
+                    btwHintReason: 'Use /btw for side questions when the current implementation context is large.',
+                }
+                : {}),
             ...(updateBanner !== undefined ? { update_banner: updateBanner } : {}),
             // SPEC-751: pending cleanup counters
             pending_cleanup: pendingCleanup,

package/dist/tools/suggest-mcp-server.js

@@ -80,10 +80,8 @@ export async function handleSuggestMcpServer(args) {
         `Estimated effort: ${hours}h`,
     ].join('\n');
     return {
-        content: [
-            { type: 'text', text: summary },
-            { type: 'text', text: JSON.stringify(recommendation, null, 2) },
-        ],
+        content: [{ type: 'text', text: summary }],
+        structuredContent: recommendation,
     };
 }
 //# sourceMappingURL=suggest-mcp-server.js.map

package/dist/tools/token-recording.d.ts

@@ -5,12 +5,13 @@
 export declare function recordToolTokens(toolName: string, projectPath: string, inputArgs: unknown, outputText: string, sessionId: string): void;
 /**
  * Extract output text from a ToolResult for token counting.
- * Concatenates all text content items into a single string.
+ * Concatenates visible text and compacted structuredContent into a single string.
  */
 export declare function extractOutputText(result: {
     content: {
         type: string;
         text?: string;
     }[];
+    structuredContent?: Record<string, unknown>;
 }): string;
 //# sourceMappingURL=token-recording.d.ts.map

package/dist/tools/token-recording.js

@@ -4,6 +4,20 @@ import { join } from 'node:path';
 import { countTokens, estimateCost } from '../engine/token-optimizer/counter.js';
 import { recordEntry } from '../storage/token-ledger-store.js';
 import { hashProjectPath } from '../storage/base-store.js';
+const SECRET_KEY_PATTERN = /(api[-_]?key|auth|bearer|credential|password|secret|token)/i;
+function stringifyForTokenCounting(value) {
+    try {
+        return JSON.stringify(value, (key, entryValue) => {
+            if (SECRET_KEY_PATTERN.test(key)) {
+                return '[redacted]';
+            }
+            return entryValue;
+        });
+    }
+    catch {
+        return '[unserializable structuredContent]';
+    }
+}
 /**
  * Record a tool call's token usage to the persistent ledger.
  * Always fire-and-forget — never throws, never blocks the response.
@@ -39,11 +53,16 @@ export function recordToolTokens(toolName, projectPath, inputArgs, outputText, s
 }
 /**
  * Extract output text from a ToolResult for token counting.
- * Concatenates all text content items into a single string.
+ * Concatenates visible text and compacted structuredContent into a single string.
  */
 export function extractOutputText(result) {
-    return result.content
+    const text = result.content
         .flatMap((item) => (item.type === 'text' && typeof item.text === 'string' ? [item.text] : []))
         .join('\n');
+    if (result.structuredContent === undefined) {
+        return text;
+    }
+    const structuredText = stringifyForTokenCounting(result.structuredContent);
+    return text.length > 0 ? `${text}\n${structuredText}` : structuredText;
 }
 //# sourceMappingURL=token-recording.js.map

package/dist/tools/update-status/dod-gates.d.ts

@@ -28,6 +28,7 @@ export type ValidateGateResult = {
     score: number | null;
     forced: true;
     forcedReason: string;
+    scoreSource: 'forced-best-effort-validateSpec';
 };
 /**
  * SPEC-721 / SPEC-222 Trigger 1: Run validate engine before marking done.
@@ -99,8 +100,7 @@ export interface ComplianceGateResult {
  * Never blocks the transition if the compliance engine is unavailable or fails.
  */
 export declare function checkComplianceGate(specId: string, projectId: string, projectPath: string | undefined): Promise<ComplianceGateResult>;
-/** SPEC-642: Block done if QA gate has not run and passed. */
-export declare function checkQaGate(specId: string, projectPath: string | undefined, force: boolean): Promise<ToolResult | null>;
+export { checkQaGate } from './qa-gate.js';
 /**
  * SPEC-716 / SPEC-780: Format gate for transition to 'approved'.
  *