@planu/cli 4.10.5 → 4.10.7

package/dist/tools/data-governance/audit-handler.js

@@ -3,6 +3,7 @@ import { specStore, knowledgeStore } from '../../storage/index.js';
 import { ti } from '../../i18n/index.js';
 import { detectPIIInSpec, detectLegalFramework } from '../../engine/pii-detector.js';
 import { readFile } from 'node:fs/promises';
+import { formatKeyValue } from '../output-formatter.js';
 // ---------------------------------------------------------------------------
 // privacy-notice subcommand
 // ---------------------------------------------------------------------------
@@ -40,14 +41,21 @@ export async function handlePrivacyNotice(projectId) {
             },
             {
                 type: 'text',
-                text: JSON.stringify({
+                text: formatKeyValue({
                     subcommand: 'privacy-notice',
                     specsWithPII: privacyItems.length,
                     totalSpecs: specs.length,
-                    noticeText: notice,
-                }, null, 2),
+                    noticeChars: notice.length,
+                }),
             },
         ],
+        structuredContent: {
+            subcommand: 'privacy-notice',
+            specsWithPII: privacyItems.length,
+            totalSpecs: specs.length,
+            noticeText: notice,
+            items: privacyItems,
+        },
     };
 }
 // ---------------------------------------------------------------------------
@@ -105,16 +113,23 @@ export async function handleAudit(projectId) {
             },
             {
                 type: 'text',
-                text: JSON.stringify({
+                text: formatKeyValue({
                     subcommand: 'audit',
                     totalSpecs: specs.length,
                     specsWithPII: auditItems.filter((i) => i.hasPII).length,
                     nonCompliantSpecs: nonCompliant,
                     framework,
-                    items: auditItems,
-                }, null, 2),
+                }),
             },
         ],
+        structuredContent: {
+            subcommand: 'audit',
+            totalSpecs: specs.length,
+            specsWithPII: auditItems.filter((i) => i.hasPII).length,
+            nonCompliantSpecs: nonCompliant,
+            framework,
+            items: auditItems,
+        },
     };
 }
 // ---------------------------------------------------------------------------

package/dist/tools/data-governance/detect-handler.js

@@ -3,6 +3,7 @@ import { specStore, knowledgeStore } from '../../storage/index.js';
 import { ti } from '../../i18n/index.js';
 import { detectPIIInSpec, detectLegalFramework, generateRetentionPolicy, generatePrivacySection, } from '../../engine/pii-detector.js';
 import { readFile } from 'node:fs/promises';
+import { formatKeyValue } from '../output-formatter.js';
 // ---------------------------------------------------------------------------
 // detect subcommand
 // ---------------------------------------------------------------------------
@@ -78,15 +79,24 @@ export async function handleDetect(specId, projectId, inlineContent, projectPath
             },
             {
                 type: 'text',
-                text: JSON.stringify({
+                text: formatKeyValue({
                     subcommand: 'detect',
-                    detectionResult: result,
+                    hasPII: result.hasPII,
+                    piiFields: result.fields.length,
+                    sensitiveSpecialCount: result.sensitiveSpecialCount,
                     framework,
-                    retentionPolicy,
-                    requirement,
-                }, null, 2),
+                    retentionPolicy: 'generated',
+                    challengeRequired: requirement.challengeRequired,
+                }),
             },
         ],
+        structuredContent: {
+            subcommand: 'detect',
+            detectionResult: result,
+            framework,
+            retentionPolicy,
+            requirement,
+        },
     };
 }
 // ---------------------------------------------------------------------------
@@ -115,21 +125,28 @@ export function handleRetentionPolicy(modelName, projectPath) {
             },
             {
                 type: 'text',
-                text: JSON.stringify({
+                text: formatKeyValue({
                     subcommand: 'retention-policy',
                     modelName: effectiveModel,
                     framework,
-                    retentionPolicy: defaultRetentionPolicy,
-                    auditFields: [
-                        'created_at',
-                        'updated_at',
-                        'deleted_at',
-                        'data_owner_id',
-                        'retention_expires_at',
-                    ],
-                }, null, 2),
+                    retentionPolicy: 'generated',
+                    auditFields: 5,
+                }),
             },
         ],
+        structuredContent: {
+            subcommand: 'retention-policy',
+            modelName: effectiveModel,
+            framework,
+            retentionPolicy: defaultRetentionPolicy,
+            auditFields: [
+                'created_at',
+                'updated_at',
+                'deleted_at',
+                'data_owner_id',
+                'retention_expires_at',
+            ],
+        },
     };
 }
 // Re-export for use by the main handler

package/dist/tools/define-ui-contract.js

@@ -172,10 +172,6 @@ export async function handleDefineUIContract(args) {
                 type: 'text',
                 text: ti('tools.define_ui_contract.success', { componentCount: String(totalComponents) }),
             },
-            {
-                type: 'text',
-                text: JSON.stringify(contract, null, 2),
-            },
             {
                 type: 'text',
                 text: formatStylingContract(stylingContract),
@@ -189,6 +185,7 @@ export async function handleDefineUIContract(args) {
                 text: formatA11yContract(a11yContract),
             },
         ],
+        structuredContent: contract,
     };
 }
 // --- Project context inference ---

package/dist/tools/design-schema.js

@@ -194,11 +194,8 @@ export async function handleDesignSchema(args) {
                     indexCount: String(indexes.length),
                 }),
             },
-            {
-                type: 'text',
-                text: JSON.stringify(schema, null, 2),
-            },
         ],
+        structuredContent: schema,
     };
 }
 // -- SPEC-059: Specialized DB schema dispatch ---------------------------------

package/dist/tools/detect-drift.js

@@ -78,6 +78,15 @@ async function handleDetectDriftInner(args) {
     // 5. Check PLAN.md progress if spec has a plan
     const planProgress = await loadPlanProgress(spec.planPath);
     const statusEmoji = report.isCompliant ? 'PASS' : 'FAIL';
+    const constitutionCompliance = constitution
+        ? {
+            totalPrinciples: constitution.principles.length,
+            strictCount: constitution.principles.filter((p) => p.enforceLevel === 'strict').length,
+            checkedAt: new Date().toISOString(),
+        }
+        : undefined;
+    const criticalPrivacyDriftCount = privacyDrifts.filter((d) => d.severity === 'critical').length;
+    const breakingEventSchemaDriftCount = eventSchemaDrifts.filter((d) => d.severity === 'breaking').length;
     // Dispatch on_drift_detected hook event when drift is found (fire-and-forget)
     if (!report.isCompliant) {
         void dispatchHookEvent(projectId, buildDriftDetectedPayload(projectId, specId, report.driftScore, `${report.drifts.length} drift(s) detected`)).catch((err) => {
@@ -95,20 +104,20 @@ async function handleDetectDriftInner(args) {
                 text: formattedOutput,
             },
             ...(planProgress !== null
-                ? [{ type: 'text', text: JSON.stringify({ planProgress }, null, 2) }]
+                ? [
+                    {
+                        type: 'text',
+                        text: `Plan progress: ${Object.entries(planProgress)
+                            .map(([key, value]) => `${key}=${String(value)}`)
+                            .join(', ')}`,
+                    },
+                ]
                 : []),
             ...(constitution
                 ? [
                     {
                         type: 'text',
-                        text: JSON.stringify({
-                            constitutionCompliance: {
-                                totalPrinciples: constitution.principles.length,
-                                strictCount: constitution.principles.filter((p) => p.enforceLevel === 'strict')
-                                    .length,
-                                checkedAt: new Date().toISOString(),
-                            },
-                        }, null, 2),
+                        text: `Constitution compliance: ${constitution.principles.length} principles, ${constitutionCompliance?.strictCount ?? 0} strict`,
                     },
                 ]
                 : []),
@@ -117,14 +126,11 @@ async function handleDetectDriftInner(args) {
                 ? [
                     {
                         type: 'text',
-                        text: JSON.stringify({
-                            privacyDrift: {
-                                count: privacyDrifts.length,
-                                criticalCount: privacyDrifts.filter((d) => d.severity === 'critical').length,
-                                drifts: privacyDrifts,
-                                message: 'Privacy drift detected. Review missing privacy criteria before merging.',
-                            },
-                        }, null, 2),
+                        text: `Privacy drift: ${privacyDrifts.length} issue(s), ${criticalPrivacyDriftCount} critical. ` +
+                            `Types: ${privacyDrifts
+                                .map((drift) => drift.driftType)
+                                .slice(0, 5)
+                                .join(', ')}. Review missing privacy criteria before merging.`,
                     },
                 ]
                 : []),
@@ -133,21 +139,35 @@ async function handleDetectDriftInner(args) {
                 ? [
                     {
                         type: 'text',
-                        text: JSON.stringify({
-                            eventSchemaDrift: {
-                                type: 'event-schema-mismatch',
-                                count: eventSchemaDrifts.length,
-                                /* v8 ignore next 2 */
-                                breakingCount: eventSchemaDrifts.filter((d) => d.severity === 'breaking')
-                                    .length,
-                                drifts: eventSchemaDrifts,
-                                message: 'Event schema drift detected. Implementation diverges from versioned contract.',
-                            },
-                        }, null, 2),
+                        text: `Event schema drift: ${eventSchemaDrifts.length} mismatch(es), ${breakingEventSchemaDriftCount} breaking. Implementation diverges from versioned contract.`,
                     },
                 ]
                 : []),
         ],
+        structuredContent: {
+            drift: report,
+            ...(planProgress !== null ? { planProgress } : {}),
+            ...(constitutionCompliance ? { constitutionCompliance } : {}),
+            ...(privacyDrifts.length > 0
+                ? {
+                    privacyDrift: {
+                        count: privacyDrifts.length,
+                        criticalCount: criticalPrivacyDriftCount,
+                        drifts: privacyDrifts,
+                    },
+                }
+                : {}),
+            ...(eventSchemaDrifts.length > 0
+                ? {
+                    eventSchemaDrift: {
+                        type: 'event-schema-mismatch',
+                        count: eventSchemaDrifts.length,
+                        breakingCount: breakingEventSchemaDriftCount,
+                        drifts: eventSchemaDrifts,
+                    },
+                }
+                : {}),
+        },
     };
 }
 // --- Output formatters ---

package/dist/tools/flag-spec-gap.js

@@ -2,6 +2,7 @@
 // Records a spec implementation gap with severity classification and hash-chained persistence.
 import { specStore } from '../storage/index.js';
 import { appendGapEntry } from '../storage/gaps-log.js';
+import { formatKeyValue } from './output-formatter.js';
 const SPEC_ID_RE = /^SPEC-\d{3,4}$/;
 const VALID_SEVERITIES = ['low', 'medium', 'high'];
 /**
@@ -20,7 +21,7 @@ export async function handleFlagSpecGap(input) {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify({
+                    text: formatKeyValue({
                         error: 'invalid_input',
                         code: 422,
                         field: 'severity',
@@ -29,6 +30,13 @@ export async function handleFlagSpecGap(input) {
                 },
             ],
             isError: true,
+            structuredContent: {
+                error: 'invalid_input',
+                code: 422,
+                field: 'severity',
+                validSeverities: VALID_SEVERITIES,
+                fixHint: `severity must be one of: ${VALID_SEVERITIES.join(', ')}`,
+            },
         };
     }
     // ── Validate affectedSpecs format ─────────────────────────────────────────
@@ -38,14 +46,22 @@ export async function handleFlagSpecGap(input) {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({
+                        text: formatKeyValue({
                             error: 'invalid_affected_spec',
                             code: 422,
+                            specId: id,
                             fixHint: `${id} does not match the required format SPEC-NNN or SPEC-NNNN`,
                         }),
                     },
                 ],
                 isError: true,
+                structuredContent: {
+                    error: 'invalid_affected_spec',
+                    code: 422,
+                    specId: id,
+                    expectedFormat: 'SPEC-NNN or SPEC-NNNN',
+                    fixHint: `${id} does not match the required format SPEC-NNN or SPEC-NNNN`,
+                },
             };
         }
     }
@@ -58,14 +74,22 @@ export async function handleFlagSpecGap(input) {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({
+                        text: formatKeyValue({
                             error: 'invalid_affected_spec',
                             code: 422,
+                            specId: id,
                             fixHint: `${id} not found in project ${projectId}`,
                         }),
                     },
                 ],
                 isError: true,
+                structuredContent: {
+                    error: 'invalid_affected_spec',
+                    code: 422,
+                    specId: id,
+                    projectId,
+                    fixHint: `${id} not found in project ${projectId}`,
+                },
             };
         }
     }
@@ -81,25 +105,36 @@ export async function handleFlagSpecGap(input) {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({
+                text: formatKeyValue({
                     ok: true,
                     id: entry.id,
                     specId: entry.specId,
-                    description: entry.description,
                     severity: entry.severity,
-                    affectedSpecs: entry.affectedSpecs,
+                    affectedSpecs: entry.affectedSpecs.length,
                     timestamp: entry.timestamp,
                     sha: entry.sha,
-                    defaults: {
-                        severity: input.severity === undefined ? 'medium (default)' : undefined,
-                        affectedSpecs: !input.affectedSpecs || input.affectedSpecs.length === 0
-                            ? `[${specId}] (default)`
-                            : undefined,
-                    },
+                    severityDefaulted: input.severity === undefined,
+                    affectedSpecsDefaulted: !input.affectedSpecs || input.affectedSpecs.length === 0,
                 }),
             },
         ],
         isError: false,
+        structuredContent: {
+            ok: true,
+            id: entry.id,
+            specId: entry.specId,
+            description: entry.description,
+            severity: entry.severity,
+            affectedSpecs: entry.affectedSpecs,
+            timestamp: entry.timestamp,
+            sha: entry.sha,
+            defaults: {
+                severity: input.severity === undefined ? 'medium (default)' : undefined,
+                affectedSpecs: !input.affectedSpecs || input.affectedSpecs.length === 0
+                    ? `[${specId}] (default)`
+                    : undefined,
+            },
+        },
     };
 }
 //# sourceMappingURL=flag-spec-gap.js.map

package/dist/tools/generate-sub-agent.js

@@ -87,10 +87,8 @@ export async function handleGenerateSubAgent(args) {
     }
     const hasExtra = Object.keys(responseData).length > 0;
     return {
-        content: [
-            { type: 'text', text: lines.join('\n') },
-            ...(hasExtra ? [{ type: 'text', text: JSON.stringify(responseData, null, 2) }] : []),
-        ],
+        content: [{ type: 'text', text: lines.join('\n') }],
+        ...(hasExtra ? { structuredContent: responseData } : {}),
     };
 }
 //# sourceMappingURL=generate-sub-agent.js.map

package/dist/tools/list-specs.js

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

package/dist/tools/orchestrate-locking.js

@@ -156,8 +156,19 @@ export function handleUnlockState(state, sessionId, resourcePath, specId) {
 // ---------------------------------------------------------------------------
 function errResult(msg) {
     return {
-        content: [{ type: 'text', text: JSON.stringify({ error: msg }, null, 2) }],
+        content: [{ type: 'text', text: `Error: ${msg}` }],
         isError: true,
+        structuredContent: { error: msg },
+    };
+}
+function orchestrateToolResult(result) {
+    const status = result.granted === false ? 'blocked' : 'ok';
+    const details = result;
+    const resource = details.resourceId ? ` | resource: ${details.resourceId}` : '';
+    const message = result.message ? ` | ${result.message}` : '';
+    return {
+        content: [{ type: 'text', text: `${result.action}: ${status}${resource}${message}` }],
+        structuredContent: result,
     };
 }
 export function toHeartbeatResult(sessionId, state, lockTtlMinutes) {
@@ -170,7 +181,7 @@ export function toHeartbeatResult(sessionId, state, lockTtlMinutes) {
     }
     return {
         mutated: out.state,
-        toolResult: { content: [{ type: 'text', text: JSON.stringify(out.result, null, 2) }] },
+        toolResult: orchestrateToolResult(out.result),
     };
 }
 export function toLockResult(sessionId, state, resourcePath, specId, lockTtlMinutes, fileOwnership) {
@@ -183,7 +194,7 @@ export function toLockResult(sessionId, state, resourcePath, specId, lockTtlMinu
     }
     return {
         mutated: out.state,
-        toolResult: { content: [{ type: 'text', text: JSON.stringify(out.result, null, 2) }] },
+        toolResult: orchestrateToolResult(out.result),
     };
 }
 export function toUnlockResult(sessionId, state, resourcePath, specId) {
@@ -196,7 +207,7 @@ export function toUnlockResult(sessionId, state, resourcePath, specId) {
     }
     return {
         mutated: out.state,
-        toolResult: { content: [{ type: 'text', text: JSON.stringify(out.result, null, 2) }] },
+        toolResult: orchestrateToolResult(out.result),
     };
 }
 //# sourceMappingURL=orchestrate-locking.js.map

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

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