@planu/cli 5.3.24 → 5.3.26

package/dist/tools/init-project/handler.js

@@ -422,7 +422,7 @@ export async function handleInitProject(params, server) {
                 .map((outcome) => `${outcome.name}: ${outcome.error ?? 'unknown error'}`);
             const { configResult, migrations } = await configAndMigrations;
             const { planuConfigPath, planuConfigGenerated, whatsNew } = configResult;
-            const { discoveryResult, migrationResult, folderMigrationResult, criticalMigrationFailures, nonCriticalWarnings: nonCriticalMigrationWarnings, migrationReportPath, changedPaths: migrationChangedPaths = [], } = migrations;
+            const { discoveryResult, migrationResult, folderMigrationResult, legacyMigrationDirectives, criticalMigrationFailures, nonCriticalWarnings: nonCriticalMigrationWarnings, migrationReportPath, changedPaths: migrationChangedPaths = [], } = migrations;
             // Auto-install or queue skills (opt-out via planu.json or input param, SPEC-185)
             const autoInstallFromConfig = autoInstallSkills ?? (await readAutoInstallFlag(planuConfigPath));
             const { skillsAutoInstalled, skillsPendingInstall, skillsSkipped } = await orchestrateSkillInstalls(recommendedSkills, projectPath, autoInstallFromConfig);
@@ -578,6 +578,7 @@ export async function handleInitProject(params, server) {
                 migrationResult,
                 discoveryResult,
                 folderMigrationResult,
+                legacyMigrationDirectives,
                 criticalMigrationFailures,
                 nonCriticalMigrationWarnings,
                 migrationReportPath,

package/dist/tools/init-project/migration-runner.d.ts

@@ -1,5 +1,5 @@
 import { reconcilePortableSpecIndex } from './portable-index-reconciler.js';
-import type { ProjectKnowledge, Spec } from '../../types/index.js';
+import type { LegacyMigrationDirective, ProjectKnowledge, Spec } from '../../types/index.js';
 export interface MigrationRunIssue {
     phase: string;
     severity: 'critical' | 'nonCritical';
@@ -25,6 +25,7 @@ export interface MigrationRunResult {
     nonCriticalWarnings: MigrationRunIssue[];
     migrationReportPath: string | null;
     changedPaths?: string[];
+    legacyMigrationDirectives: LegacyMigrationDirective[];
 }
 interface SpecMigrationOptions {
     repositoryMigration?: 'initialization' | 'planu-spec-format-v1';

package/dist/tools/init-project/migration-runner.js

@@ -3,9 +3,10 @@ import { specStore, knowledgeStore } from '../../storage/index.js';
 import { projectDataDir, writeJson } from '../../storage/base-store.js';
 import { filterLegacySpecs, migrateSpecs, filterUnprefixedSpecs, migrateSpecFolderNames, discoverAndFlattenSpecs, reconcileSpecPaths, migrateAllSpecsToLean, } from '../../engine/spec-migrator.js';
 import { reconcilePortableSpecIndex } from './portable-index-reconciler.js';
+import { scanLegacyArtifacts, buildMigrationDirective, } from '../../engine/spec-migrator/legacy-classifier.js';
 import { createHash } from 'node:crypto';
 import { lstat, readFile, readdir, readlink } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { basename, join, relative } from 'node:path';
 async function snapshotPlanuTree(projectPath) {
     const root = join(projectPath, 'planu');
     const snapshot = new Map();
@@ -155,13 +156,24 @@ export async function runSpecMigrations(projectPath, projectId, knowledge, optio
     catch (err) {
         criticalMigrationFailures.push(issueFromError('lean-spec-migration', 'critical', err));
     }
-    // SPEC-630: Merge separate technical.md into unified spec.md
+    const legacyMigrationDirectives = [];
     try {
-        const { migrateAllSpecsToUnified } = await import('../../engine/spec-migrator/index.js');
-        await migrateAllSpecsToUnified(projectPath);
+        const { glob } = await import('glob');
+        const specDirs = await glob(join(projectPath, 'planu/specs/SPEC-*'));
+        for (const specDir of specDirs) {
+            const specId = /^(SPEC-\d+)/i.exec(basename(specDir))?.[1]?.toUpperCase();
+            if (specId === undefined) {
+                continue;
+            }
+            const hits = await scanLegacyArtifacts(specDir);
+            const directive = await buildMigrationDirective(specId, specDir, hits);
+            if (directive !== null) {
+                legacyMigrationDirectives.push(directive);
+            }
+        }
     }
     catch (err) {
-        criticalMigrationFailures.push(issueFromError('unified-spec-migration', 'critical', err));
+        criticalMigrationFailures.push(issueFromError('legacy-artifact-scan', 'critical', err));
     }
     // SPEC-1017: strict managed planu/ cleanup after all legacy migrations.
     try {
@@ -208,6 +220,7 @@ export async function runSpecMigrations(projectPath, projectId, knowledge, optio
         nonCriticalWarnings,
         migrationReportPath,
         changedPaths: repositoryFilesChanged,
+        legacyMigrationDirectives,
     };
 }
 /** Return all specs for the project (needed by caller for health check refs). */

package/dist/tools/init-project/result-builder.js

@@ -149,6 +149,7 @@ export function buildInitProjectResult(input) {
         specMigration: input.migrationResult,
         specDiscovery: input.discoveryResult,
         specFolderMigration: input.folderMigrationResult,
+        legacyMigrationDirectives: input.legacyMigrationDirectives,
         criticalMigrationFailures: input.criticalMigrationFailures ?? [],
         bestEffortWarnings: input.nonCriticalMigrationWarnings ?? [],
         migrationReportPath: input.migrationReportPath ?? null,
@@ -197,6 +198,12 @@ export function buildInitProjectResult(input) {
         : '';
     const tokenTip = `\n\n💡 Token tip: Add CLAUDE_CODE_SUBAGENT_MODEL=haiku to your .env — makes all read-only subagents ` +
         `(search, grep, file reads) use Haiku instead of your session model (4–18x cheaper for those tasks).`;
+    const legacyMigrationNextAction = input.legacyMigrationDirectives.length > 0
+        ? `Legacy spec artifacts found in ${String(input.legacyMigrationDirectives.length)} spec folder(s): ` +
+            `${input.legacyMigrationDirectives.map((d) => d.specId).join(', ')}. For each, synthesize the ` +
+            `content-bearing legacyFiles (see legacyMigrationDirectives in structuredContent) into their ` +
+            `targetSection, then call migrate_legacy_spec with the merged spec.md body and filesToRetire.`
+        : null;
     const narrative = ti('tools.init_project.success', { projectPath: result.projectPath }) +
         `\n\nDetected: **${result.language}** / ${framework} — project ${action}. ` +
         `Run \`create_spec\` to start planning your first feature.` +
@@ -204,6 +211,7 @@ export function buildInitProjectResult(input) {
             ? `\n\n⚠️ Critical spec migration warnings: ${String(input.criticalMigrationFailures?.length ?? 0)} issue(s). ` +
                 `See migrationReportPath in structuredContent${input.migrationReportPath ? ` (${input.migrationReportPath})` : ''}.`
             : '') +
+        (legacyMigrationNextAction ? `\n\n📦 ${legacyMigrationNextAction}` : '') +
         telemetryNote +
         tokenTip;
     // SPEC-491: Build interactiveQuestions for decisions that require user input
@@ -253,6 +261,7 @@ export function buildInitProjectResult(input) {
         structuredContent: {
             ...result,
             ...(hasInteractive ? { interactiveQuestions } : {}),
+            ...(legacyMigrationNextAction ? { nextAction: legacyMigrationNextAction } : {}),
         },
     };
 }

package/dist/tools/list-specs.js

@@ -1,3 +1,5 @@
+// tools/list-specs.ts — List specs with filters
+import { dirname } from 'node:path';
 import { ti } from '../i18n/index.js';
 import { specStore, knowledgeStore } from '../storage/index.js';
 import { buildListSpecsSummary } from '../engine/human-summary.js';
@@ -5,9 +7,34 @@ import { checkBundledVersionGap } from '../engine/version-detector/bundled-versi
 import { formatRelativeDate } from '../engine/time/relative-date.js';
 import { scanForAmbiguousCriteria } from '../engine/spec-migrator.js';
 import { detectDrift, formatDriftMessage } from '../engine/spec-migrator/drift-detector.js';
+import { buildMigrationDirective, scanLegacyArtifacts, } from '../engine/spec-migrator/legacy-classifier.js';
 import { AutopilotSummaryCollector } from '../engine/autopilot/summary-collector.js';
 import { trackCost } from '../engine/cost-tracking/operation-tracker.js';
 import { resolveProjectIdOrAutoDetect } from './resolve-project-id.js';
+async function scanLegacyMigrationDirectives(specs) {
+    const directives = [];
+    for (const spec of specs) {
+        if (!spec.specPath) {
+            continue;
+        }
+        const specDir = dirname(spec.specPath);
+        const hits = await scanLegacyArtifacts(specDir);
+        const directive = await buildMigrationDirective(spec.id, specDir, hits);
+        if (directive !== null) {
+            directives.push(directive);
+        }
+    }
+    return directives;
+}
+function buildLegacyMigrationNextAction(directives) {
+    if (directives.length === 0) {
+        return undefined;
+    }
+    return (`Legacy spec artifacts found in ${String(directives.length)} spec folder(s): ` +
+        `${directives.map((d) => d.specId).join(', ')}. For each, synthesize the content-bearing ` +
+        `legacyFiles into their targetSection, then call migrate_legacy_spec with the merged spec.md ` +
+        `body and filesToRetire.`);
+}
 /** Track which projects have been auto-discovered this session (once per project). */
 const discoveredProjects = new Set();
 const MAX_STRUCTURED_SPECS = 50;
@@ -264,6 +291,16 @@ export async function handleListSpecs(params) {
                     /* best-effort — never block list_specs */
                 }
             }
+            let legacyMigrationDirectives = [];
+            if (detail === 'full') {
+                try {
+                    legacyMigrationDirectives = await scanLegacyMigrationDirectives(allSpecs);
+                }
+                catch {
+                    /* best-effort — never block list_specs */
+                }
+            }
+            const legacyMigrationNextAction = buildLegacyMigrationNextAction(legacyMigrationDirectives);
             const structuredContent = {
                 projectId,
                 filters: {
@@ -291,6 +328,8 @@ export async function handleListSpecs(params) {
                 migrationIssues: migrationIssues ?? undefined,
                 interactiveQuestions: interactiveQuestions ?? undefined,
                 staleStatusWarnings: staleStatusWarnings.length > 0 ? staleStatusWarnings : undefined,
+                legacyMigrationDirectives: legacyMigrationDirectives.length > 0 ? legacyMigrationDirectives : undefined,
+                nextAction: legacyMigrationNextAction,
             };
             return {
                 content: [

package/dist/tools/migrate-legacy-spec.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolResult } from '../types/index.js';
+export declare function migrateLegacySpec(params: {
+    projectPath: string;
+    specId: string;
+    mergedBody?: string;
+    filesToRetire: string[];
+}): Promise<ToolResult>;
+export declare function registerMigrateLegacySpecTool(server: McpServer): void;
+//# sourceMappingURL=migrate-legacy-spec.d.ts.map

package/dist/tools/migrate-legacy-spec.js

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import { cp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { glob } from 'glob';
+import { atomicWriteFile } from '../engine/safety/atomic-write-file.js';
+import { safeUnlink } from '../engine/spec-migrator/git-aware-fs.js';
+import { safe } from './safe-handler.js';
+const execFileAsync = promisify(execFile);
+const migrateLegacySpecInputSchema = {
+    projectPath: z.string().describe('Absolute path to the project root containing planu/specs'),
+    specId: z.string().min(1).describe('Spec identifier, e.g. "SPEC-1570"'),
+    mergedBody: z
+        .string()
+        .optional()
+        .describe('Full replacement content for spec.md, synthesized by the host LLM from the retired ' +
+        'content-bearing legacy files. Omit when only retiring transient files.'),
+    filesToRetire: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe('Paths relative to the spec folder to back up, delete, and git-untrack (files or directories)'),
+};
+async function resolveSpecDir(specId, projectPath) {
+    const pattern = join(projectPath, 'planu', 'specs', `${specId}-*/`);
+    const dirs = await glob(pattern, { absolute: true });
+    return dirs[0] ?? null;
+}
+async function gitRmCachedRecursive(projectPath, relPath) {
+    if (!existsSync(join(projectPath, '.git'))) {
+        return;
+    }
+    try {
+        await execFileAsync('git', ['rm', '--cached', '--quiet', '--ignore-unmatch', '-r', relPath], {
+            cwd: projectPath,
+            timeout: 5_000,
+        });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function escapesSpecDir(specDir, relPath) {
+    const resolvedSpecDir = resolve(specDir);
+    const absolute = resolve(specDir, relPath);
+    const relativeToSpecDir = relative(resolvedSpecDir, absolute);
+    return (relativeToSpecDir === '..' ||
+        relativeToSpecDir.startsWith(`..${sep}`) ||
+        isAbsolute(relativeToSpecDir));
+}
+async function retireEntry(projectPath, specDir, relPath) {
+    const absolute = join(specDir, relPath);
+    const timestamp = Date.now();
+    const isDirectory = (await stat(absolute).catch(() => null))?.isDirectory() ?? false;
+    if (isDirectory) {
+        await cp(absolute, `${absolute}.bak.${timestamp}`, { recursive: true });
+        await gitRmCachedRecursive(projectPath, relative(projectPath, absolute));
+        await rm(absolute, { recursive: true, force: true });
+        return;
+    }
+    const content = await readFile(absolute).catch(() => null);
+    if (content !== null) {
+        await writeFile(`${absolute}.bak.${timestamp}`, content);
+    }
+    await safeUnlink(projectPath, absolute);
+    await rm(absolute, { force: true });
+}
+export async function migrateLegacySpec(params) {
+    const { projectPath, specId, mergedBody, filesToRetire } = params;
+    const specDir = await resolveSpecDir(specId, projectPath);
+    if (specDir === null) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Spec folder for ${specId} not found under ${join(projectPath, 'planu', 'specs')}. Verify the specId and projectPath, then retry.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    if (mergedBody !== undefined) {
+        await atomicWriteFile(join(specDir, 'spec.md'), mergedBody, {
+            forceEdit: {
+                reason: `SPEC-1570 migrate_legacy_spec is merging legacy content into spec.md for ${specId}.`,
+            },
+        });
+    }
+    const retired = [];
+    const rejected = [];
+    for (const relPath of filesToRetire) {
+        if (escapesSpecDir(specDir, relPath)) {
+            rejected.push(relPath);
+            continue;
+        }
+        await retireEntry(projectPath, specDir, relPath);
+        retired.push(relPath);
+    }
+    if (rejected.length > 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Migrated ${specId}: ${mergedBody !== undefined ? 'spec.md updated, ' : ''}retired ${String(retired.length)} legacy artifact(s) (${retired.join(', ')}). Rejected ${String(rejected.length)} filesToRetire entr${rejected.length === 1 ? 'y' : 'ies'} escaping the spec directory: ${rejected.join(', ')}. Pass paths relative to the spec folder only.`,
+                },
+            ],
+            isError: true,
+            structuredContent: { specId, specMdUpdated: mergedBody !== undefined, retired, rejected },
+        };
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Migrated ${specId}: ${mergedBody !== undefined ? 'spec.md updated, ' : ''}retired ${String(retired.length)} legacy artifact(s) (${retired.join(', ')}).`,
+            },
+        ],
+        isError: false,
+        structuredContent: { specId, specMdUpdated: mergedBody !== undefined, retired },
+    };
+}
+export function registerMigrateLegacySpecTool(server) {
+    server.registerTool('migrate_legacy_spec', {
+        description: 'Persist a host-LLM-synthesized spec.md body and retire the legacy files it replaces: ' +
+            'each retired file/directory is backed up with a timestamped .bak copy, deleted, and ' +
+            'git-untracked. Call this after synthesizing mergedBody from the legacyFiles listed in a ' +
+            'migrate_legacy_spec directive (from init_project, list_specs, or heal_spec_docs).',
+        inputSchema: migrateLegacySpecInputSchema,
+        annotations: { readOnlyHint: false, destructiveHint: true, title: 'Migrate Legacy Spec' },
+    }, safe((args) => migrateLegacySpec(args)));
+}
+//# sourceMappingURL=migrate-legacy-spec.js.map

package/dist/tools/register-spec-tools/analysis-tools.js

@@ -18,6 +18,7 @@ import { handleScanOrphanSpecRefs, ScanOrphanSpecRefsInputSchema, } from '../sca
 import { registerGraphSpecsTool } from '../graph-specs.js';
 import { registerAuditSpecsDriftTool } from '../audit-specs-drift.js';
 import { handleSsrBackMigration } from '../ssr-back-migration.js';
+import { registerMigrateLegacySpecTool } from '../migrate-legacy-spec.js';
 /**
  * Registers drift detection, analysis, and discovery tools (tools 11–19) on the MCP server.
  */
@@ -294,6 +295,7 @@ export function registerAnalysisTools(server) {
     registerGraphSpecsTool(server);
     // SPEC-744: audit_specs_drift
     registerAuditSpecsDriftTool(server);
+    registerMigrateLegacySpecTool(server);
     // SPEC-752: ssr_back_migration — fold legacy split-file specs into unified spec.md
     server.registerTool('ssr_back_migration', {
         description: 'Migrate legacy 2-file format specs into the unified spec.md format. ' +

package/dist/tools/schema-generator-handler.js

@@ -5,6 +5,7 @@ import { dirname } from 'node:path';
 import { getSpec } from '../storage/spec-store.js';
 import { hashProjectPath } from '../storage/base-store.js';
 import { generateSchemas, generateApiClient } from '../engine/schema-generator.js';
+import { assertPathWithinBase } from '../engine/safety/assert-within-project.js';
 async function readSpecText(spec) {
     const parts = [];
     if (spec.description !== undefined) {
@@ -51,6 +52,7 @@ export async function handleGenerateValidationSchema(input) {
         }
         // Write files if outputPath is provided
         if (outputPath !== undefined) {
+            assertPathWithinBase(projectPath, outputPath);
             for (const schema of result.schemas) {
                 const ext = outputFormat === technologyValue('technology-typescript-969545') ? '.ts' : '.js';
                 const libSuffix = library === 'all' ? `.${schema.library}` : '';
@@ -105,6 +107,7 @@ export async function handleGenerateApiClient(input) {
             };
         }
         if (outputPath !== undefined) {
+            assertPathWithinBase(projectPath, outputPath);
             await writeOutputFile(outputPath, result.code);
         }
         return {

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

@@ -76,6 +76,20 @@ export declare const ListSpecsOutputSchema: {
         commitSha: z.ZodString;
         suggestedAction: z.ZodLiteral<"auto-fix-available">;
     }, z.core.$strip>>>;
+    legacyMigrationDirectives: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        specId: z.ZodString;
+        legacyFiles: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            classification: z.ZodEnum<{
+                "content-bearing": "content-bearing";
+                transient: "transient";
+            }>;
+            targetSection: z.ZodOptional<z.ZodString>;
+            inlinedContent: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        directive: z.ZodLiteral<"migrate_legacy_spec">;
+    }, z.core.$strip>>>;
+    nextAction: z.ZodOptional<z.ZodString>;
 };
 /** Canonical DTO inferred from the exact MCP output contract. */
 export declare const ListSpecsOutputObjectSchema: z.ZodObject<{
@@ -155,6 +169,20 @@ export declare const ListSpecsOutputObjectSchema: z.ZodObject<{
         commitSha: z.ZodString;
         suggestedAction: z.ZodLiteral<"auto-fix-available">;
     }, z.core.$strip>>>;
+    legacyMigrationDirectives: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        specId: z.ZodString;
+        legacyFiles: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            classification: z.ZodEnum<{
+                "content-bearing": "content-bearing";
+                transient: "transient";
+            }>;
+            targetSection: z.ZodOptional<z.ZodString>;
+            inlinedContent: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        directive: z.ZodLiteral<"migrate_legacy_spec">;
+    }, z.core.$strip>>>;
+    nextAction: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ListSpecsStructuredContent = z.infer<typeof ListSpecsOutputObjectSchema>;
 export declare const EstimateOutputSchema: {

package/dist/tools/schemas/output-schemas.js

@@ -92,6 +92,19 @@ export const ListSpecsOutputSchema = {
         suggestedAction: z.literal('auto-fix-available'),
     }))
         .optional(),
+    legacyMigrationDirectives: z
+        .array(z.object({
+        specId: z.string(),
+        legacyFiles: z.array(z.object({
+            path: z.string(),
+            classification: z.enum(['content-bearing', 'transient']),
+            targetSection: z.string().optional(),
+            inlinedContent: z.string().optional(),
+        })),
+        directive: z.literal('migrate_legacy_spec'),
+    }))
+        .optional(),
+    nextAction: z.string().optional(),
 };
 /** Canonical DTO inferred from the exact MCP output contract. */
 export const ListSpecsOutputObjectSchema = z.object(ListSpecsOutputSchema);

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

@@ -3,10 +3,8 @@ import { writeFile } from 'node:fs/promises';
 import { listSpecs } from '../storage/spec-store.js';
 import { hashProjectPath } from '../storage/base-store.js';
 import { filterSpecs, specsToCsv, specsToMarkdownTable, ALL_COLUMNS, } from '../engine/spec-exporter.js';
+import { assertPathWithinBase } from '../engine/safety/assert-within-project.js';
 import { formatSuccess, formatError, toolResult } from './response-helpers.js';
-// ---------------------------------------------------------------------------
-// Shared logic
-// ---------------------------------------------------------------------------
 async function buildExport(input, format) {
     const projectId = hashProjectPath(input.projectPath);
     const allSpecs = await listSpecs(projectId);
@@ -15,8 +13,15 @@ async function buildExport(input, format) {
     const content = format === 'csv' ? specsToCsv(filtered, columns) : specsToMarkdownTable(filtered, columns);
     let filePath;
     if (input.outputPath) {
-        await writeFile(input.outputPath, content, 'utf8');
-        filePath = input.outputPath;
+        let resolvedOutputPath;
+        try {
+            resolvedOutputPath = assertPathWithinBase(input.projectPath, input.outputPath);
+        }
+        catch (error) {
+            return { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+        await writeFile(resolvedOutputPath, content, 'utf8');
+        filePath = resolvedOutputPath;
     }
     const result = {
         rowCount: filtered.length,
@@ -25,7 +30,7 @@ async function buildExport(input, format) {
         content,
         filePath,
     };
-    return { text: content, result };
+    return { ok: true, text: content, result };
 }
 // ---------------------------------------------------------------------------
 // CSV handler
@@ -34,7 +39,11 @@ export async function handleExportSpecsCsv(args) {
     if (!args.projectPath || args.projectPath.trim().length === 0) {
         return toolResult(formatError('projectPath is required', 'Provide the absolute path to your project root.'), undefined, true);
     }
-    const { text, result } = await buildExport(args, 'csv');
+    const built = await buildExport(args, 'csv');
+    if (!built.ok) {
+        return toolResult(formatError(`Invalid outputPath: ${built.message}`, 'Choose a path within projectPath.'), undefined, true);
+    }
+    const { text, result } = built;
     const summary = [
         `Exported ${String(result.rowCount)} specs to CSV`,
         `Columns: ${result.columns.join(', ')}`,
@@ -51,7 +60,11 @@ export async function handleExportSpecsMarkdown(args) {
     if (!args.projectPath || args.projectPath.trim().length === 0) {
         return toolResult(formatError('projectPath is required', 'Provide the absolute path to your project root.'), undefined, true);
     }
-    const { text, result } = await buildExport(args, 'markdown');
+    const built = await buildExport(args, 'markdown');
+    if (!built.ok) {
+        return toolResult(formatError(`Invalid outputPath: ${built.message}`, 'Choose a path within projectPath.'), undefined, true);
+    }
+    const { text, result } = built;
     const summary = [
         `Exported ${String(result.rowCount)} specs to Markdown table`,
         `Columns: ${result.columns.join(', ')}`,

package/dist/tools/storage-bundle-handler.js

@@ -1,11 +1,27 @@
 import { exportStorageBundle, importStorageBundle } from '../storage/storage-bundle.js';
+import { assertPathWithinBase } from '../engine/safety/assert-within-project.js';
 export async function handleStorageExport(input) {
-    const bundle = await exportStorageBundle(input.projectId, input.outputPath);
+    let resolvedOutputPath;
+    try {
+        resolvedOutputPath = assertPathWithinBase(process.cwd(), input.outputPath);
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Invalid outputPath: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const bundle = await exportStorageBundle(input.projectId, resolvedOutputPath);
     const payload = {
         schemaVersion: 1,
         exported: true,
         projectId: bundle.projectId,
-        outputPath: input.outputPath,
+        outputPath: resolvedOutputPath,
         checksum: bundle.checksum,
     };
     return {
@@ -14,12 +30,27 @@ export async function handleStorageExport(input) {
     };
 }
 export async function handleStorageImport(input) {
-    const bundle = await importStorageBundle(input.inputPath);
+    let resolvedInputPath;
+    try {
+        resolvedInputPath = assertPathWithinBase(process.cwd(), input.inputPath);
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Invalid inputPath: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const bundle = await importStorageBundle(resolvedInputPath);
     const payload = {
         schemaVersion: 1,
         imported: true,
         projectId: bundle.projectId,
-        inputPath: input.inputPath,
+        inputPath: resolvedInputPath,
     };
     return {
         content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],

package/dist/types/project/planu-config.d.ts

@@ -8,6 +8,7 @@ import type { OrchestratorInfo, ComposeMultiplatformInfo } from './platform-spec
 import type { ProjectKnowledge, ProjectCompleteness } from './core.js';
 import type { ProjectHealthReport } from './health-checker.js';
 import type { DiscoveredRegistrySkill } from '../skill-bootstrap.js';
+import type { LegacyMigrationDirective } from '../spec-format.js';
 export interface PlanuConfig {
     version: string;
     specLocation: string;
@@ -79,6 +80,8 @@ export interface InitProjectResultInput {
         migratedCount: number;
         errors: string[];
     } | null;
+    /** SPEC-1570: content-bearing/transient legacy artifacts pending host-LLM migration. */
+    legacyMigrationDirectives: LegacyMigrationDirective[];
     criticalMigrationFailures?: {
         phase: string;
         severity: 'critical' | 'nonCritical';

package/dist/types/spec/core.d.ts

@@ -179,13 +179,6 @@ export interface ModelBudget {
     model: 'haiku' | 'sonnet' | 'opus';
     budget: 800 | 2000 | 4000;
 }
-/** SPEC-630: Result of merging technical.md into spec.md. */
-export interface UnifiedMigrationResult {
-    specDir: string;
-    merged: boolean;
-    reason: 'ok' | 'already-unified' | 'no-technical-md' | 'error';
-    error?: string;
-}
 export interface SpecSummary {
     specId: string;
     title: string;

package/dist/types/spec-format.d.ts

@@ -91,6 +91,23 @@ export interface StrictPlanuValidationOptions {
     specPath?: string;
     includeRoot?: boolean;
 }
+export interface LegacyArtifactRule {
+    id: string;
+    pattern: string;
+    classification: 'content-bearing' | 'transient';
+    targetSection?: string;
+}
+export interface LegacyArtifactHit {
+    path: string;
+    classification: 'content-bearing' | 'transient';
+    targetSection?: string;
+    inlinedContent?: string;
+}
+export interface LegacyMigrationDirective {
+    specId: string;
+    legacyFiles: LegacyArtifactHit[];
+    directive: 'migrate_legacy_spec';
+}
 export interface UpdateStatusBatchInput {
     specIds: string[];
     status: Exclude<SpecStatus, 'done'>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.24",
+  "version": "5.3.26",
   "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",
@@ -36,14 +36,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "5.3.24",
-    "@planu/core-darwin-x64": "5.3.24",
-    "@planu/core-linux-arm64-gnu": "5.3.24",
-    "@planu/core-linux-arm64-musl": "5.3.24",
-    "@planu/core-linux-x64-gnu": "5.3.24",
-    "@planu/core-linux-x64-musl": "5.3.24",
-    "@planu/core-win32-arm64-msvc": "5.3.24",
-    "@planu/core-win32-x64-msvc": "5.3.24"
+    "@planu/core-darwin-arm64": "5.3.26",
+    "@planu/core-darwin-x64": "5.3.26",
+    "@planu/core-linux-arm64-gnu": "5.3.26",
+    "@planu/core-linux-arm64-musl": "5.3.26",
+    "@planu/core-linux-x64-gnu": "5.3.26",
+    "@planu/core-linux-x64-musl": "5.3.26",
+    "@planu/core-win32-arm64-msvc": "5.3.26",
+    "@planu/core-win32-x64-msvc": "5.3.26"
   },
   "engines": {
     "node": ">=24.0.0"

package/planu-native.json

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