@planu/cli 4.10.6 → 4.10.7

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/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/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/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/update-status/dod-gates.js

@@ -10,6 +10,7 @@ import { randomUUID } from 'node:crypto';
 import { withEscalation } from '../../engine/escalator/with-escalation.js';
 import { writeImplementationReviewReport } from '../../engine/validator/validation-report-writer.js';
 import { writeSpecReviewFeedback } from '../../engine/validator/spec-review-writer.js';
+import { formatKeyValue } from '../output-formatter.js';
 /**
  * SPEC-721 / SPEC-222 Trigger 1: Run validate engine before marking done.
  *
@@ -163,29 +164,36 @@ export async function checkDodGate(spec, specId, projectId, projectPath, _force)
     }).catch((err) => {
         console.error('[planu] DoD feedback event failed:', err);
     });
-    const failedItems = requiredItems
-        .filter((i) => i.status === 'failed')
-        .map((i) => ({ id: i.id, description: i.description, category: i.category }));
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({
-                    error: 'DoD gate failed',
-                    message: humanMessage,
+                text: [
+                    humanMessage,
                     expertSummary,
-                    blockingItems,
-                    failedItems,
-                    warningItems,
-                    fixHints,
-                    gateResults: dod.gateResults ?? null,
-                    hint: '💡 Alternatively: use force:true to bypass all gates',
-                }, null, 2),
+                    ...fixHints.slice(0, 3),
+                    ...warningItems.slice(0, 2).map((item) => `Warning: ${item}`),
+                    blockingItems.length > 3 ? `More blockers: ${blockingItems.length - 3}` : undefined,
+                    warningItems.length > 0 ? `Warnings: ${warningItems.length}` : undefined,
+                    'Alternatively: use force:true to bypass all gates.',
+                ]
+                    .filter(Boolean)
+                    .join('\n'),
             },
         ],
         isError: true,
         structuredContent: {
-            error: 'dod_gate_failed',
+            error: 'DoD gate failed',
+            errorCode: 'dod_gate_failed',
+            message: humanMessage,
+            expertSummary,
+            blockingItems,
+            failedItems: requiredItems
+                .filter((i) => i.status === 'failed')
+                .map((i) => ({ id: i.id, description: i.description, category: i.category })),
+            warningItems,
+            fixHints,
+            hint: 'Alternatively: use force:true to bypass all gates',
             code: 422,
             context: {
                 specId,
@@ -408,13 +416,14 @@ function validationReportGateError(args) {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({
+                text: formatKeyValue({
                     error: args.error,
                     message: args.message,
                     artifactPath,
-                    gates: args.gates,
+                    failedGates: args.gates.filter((gate) => !gate.passed).length,
+                    totalGates: args.gates.length,
                     fixHint: args.fixHint,
-                }, null, 2),
+                }, 'Validation report gate failed'),
             },
         ],
         isError: true,
@@ -432,13 +441,14 @@ function specReviewGateError(args) {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({
+                text: formatKeyValue({
                     error: args.error,
                     message: args.message,
                     artifactPath,
-                    blockers: args.blockers,
+                    blockers: args.blockers.length,
+                    firstBlocker: args.blockers[0],
                     fixHint: args.fixHint,
-                }, null, 2),
+                }, 'Spec review gate failed'),
             },
         ],
         isError: true,
@@ -556,17 +566,22 @@ export async function checkApprovedFormatGate(spec, newStatus, forceApprove = fa
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({
+                text: formatKeyValue({
                     error: 'SPEC_FORMAT_INVALID',
                     message: `Spec format validation failed with ${String(result.errors.length)} error(s) — fix before approving, or pass forceApprove: true to bypass with warnings.`,
-                    errors: result.errors,
-                    warnings: result.warnings,
-                }, null, 2),
+                    errors: result.errors.length,
+                    warnings: result.warnings.length,
+                    firstError: result.errors[0]?.message,
+                    firstErrorPath: result.errors[0]?.path,
+                }, 'Spec format invalid'),
             },
         ],
         isError: true,
         structuredContent: {
             error: 'SPEC_FORMAT_INVALID',
+            message: `Spec format validation failed with ${String(result.errors.length)} error(s) — fix before approving, or pass forceApprove: true to bypass with warnings.`,
+            errors: result.errors,
+            warnings: result.warnings,
             code: 422,
             context: {
                 specId: spec.id,