@planu/cli 5.3.24 → 5.3.26

package/dist/engine/scope-boundaries/contradiction-checker.js

@@ -66,12 +66,16 @@ function splitClauses(text) {
         .map((clause) => clause.trim())
         .filter(Boolean);
 }
+const AFFIRMATIVE_ACTION_VERBS = /\b(?:changes?|modif(?:y|ies)|alters?|adds?|introduces?|implements?|enables?|exposes?|exposed|mutat(?:e|es|ing))\b/;
+function assertsForbiddenAction(text) {
+    return AFFIRMATIVE_ACTION_VERBS.test(normalize(text));
+}
 function hasAffirmativeDrift(text, outOfScopeItem) {
-    const action = /\b(?:changes?|modif(?:y|ies)|alters?|adds?|introduces?|implements?|enables?|exposes?|exposed)\b/g;
+    const action = new RegExp(AFFIRMATIVE_ACTION_VERBS, 'g');
     const actionSegments = text.split(/\band\b/i).map(normalize);
     for (const [index, segment] of actionSegments.entries()) {
         const inheritsRelevantSubject = index > 0 &&
-            /^(?:changes?|modif(?:y|ies)|alters?|adds?|introduces?|implements?|enables?|exposes?|exposed)\b/.test(segment) &&
+            new RegExp(`^${AFFIRMATIVE_ACTION_VERBS.source}`).test(segment) &&
             clauseMatchesScope(actionSegments[index - 1] ?? '', outOfScopeItem);
         for (const match of segment.matchAll(action)) {
             const before = segment.slice(Math.max(0, match.index - 24), match.index);
@@ -133,7 +137,9 @@ function contradicts(criterionText, outOfScopeItem) {
     if (keywords(outOfScopeItem).length === 0) {
         return false;
     }
-    return clauses.some((clause) => clauseMatchesScope(clause, outOfScopeItem));
+    const scopeAssertsForbiddenAction = assertsForbiddenAction(outOfScopeItem);
+    return clauses.some((clause) => clauseMatchesScope(clause, outOfScopeItem) &&
+        (!scopeAssertsForbiddenAction || assertsForbiddenAction(clause)));
 }
 /**
  * Check acceptance criteria against the spec's outOfScope declarations.

package/dist/engine/spec-format/read-technical-section.js

@@ -41,13 +41,14 @@ export function extractSectionBody(body, sectionName) {
     // match `## Technical Notes` etc. Use `[ \\t]*` (not `\\s*`) to avoid
     // consuming the line terminator via greedy backtrack. (SPEC-1010 PR-C
     // dual-Opus review)
-    const headingRe = new RegExp(`^##\\s+${escapeRegex(sectionName)}[ \\t]*$`, 'm');
+    const headingRe = new RegExp(`^(#{1,6})[ \\t]+${escapeRegex(sectionName)}[ \\t]*$`, 'm');
     const match = headingRe.exec(masked);
     if (!match) {
         return '';
     }
+    const level = match[1]?.length ?? 2;
     const afterHeading = match.index + match[0].length;
-    const nextRe = /^##\s+\S/gm;
+    const nextRe = new RegExp(`^#{1,${level}}[ \\t]+\\S`, 'gm');
     nextRe.lastIndex = afterHeading;
     const next = nextRe.exec(masked);
     const end = next ? next.index : normalized.length;

package/dist/engine/spec-format/unified-spec-builder.js

@@ -37,9 +37,36 @@ export function buildCanonicalUnifiedSpecContent(input) {
         renderSection('Acceptance Criteria', acceptance),
         renderSection('Files', renderOwnedFiles(input.files)),
         renderSection('Out of scope', outOfScope),
+        ...extractAuthorSections(source),
     ];
     return `${frontmatter ? `${frontmatter}\n\n` : ''}${sections.join('\n\n')}\n`;
 }
+const CANONICAL_SECTION_NAMES = new Set([
+    'Problem',
+    'Goal',
+    'Technical',
+    'Implementation Contract',
+    'Acceptance Criteria',
+    'Files',
+    'Out of scope',
+].map((name) => name.toLowerCase()));
+function extractAuthorSections(source) {
+    const scannable = stripFencedCodeBlocks(source);
+    const headingRe = /^##[ \t]+(\S.*?)[ \t]*$/gm;
+    const preserved = [];
+    let match;
+    while ((match = headingRe.exec(scannable)) !== null) {
+        const name = match[1] ?? '';
+        if (CANONICAL_SECTION_NAMES.has(name.toLowerCase())) {
+            continue;
+        }
+        const body = extractTopLevelSectionBody(source, name);
+        if (body !== null && body.length > 0) {
+            preserved.push(renderSection(name, body));
+        }
+    }
+    return preserved;
+}
 /**
  * Combine a generated lean spec.md body and a generated lean technical.md body
  * into a single unified spec.md content. The technical body's YAML frontmatter

package/dist/engine/spec-migrator/index.d.ts

@@ -9,7 +9,6 @@ export { hasLegacyConfig } from './version-detection.js';
 export { validateMigrationResult, mergeMigrationResults, emptyMigrationResult, } from './migration-validator.js';
 export { migrateAllSpecsToLean, migrateSpecToLean, isOldFormat } from './lean-migration.js';
 export { scanForAmbiguousCriteria } from './criteria-scanner.js';
-export { migrateToUnified, migrateAllSpecsToUnified } from './unified-migration.js';
 export { findLegacyMultiFileSpecs } from './find-legacy-multifile-specs.js';
 export { foldTechnicalIntoSpec } from './fold-technical.js';
 export { foldProgressIntoSpec, isBoilerplateProgress } from './fold-progress.js';

package/dist/engine/spec-migrator/index.js

@@ -21,7 +21,6 @@ export { migrateAllSpecsToLean, migrateSpecToLean, isOldFormat } from './lean-mi
 // SPEC-487: Scan lean specs for ambiguous criteria (score < 50)
 export { scanForAmbiguousCriteria } from './criteria-scanner.js';
 // SPEC-630: Merge technical.md into unified spec.md
-export { migrateToUnified, migrateAllSpecsToUnified } from './unified-migration.js';
 // SPEC-752: SSR back-migration — fold legacy technical.md/progress.md into spec.md
 export { findLegacyMultiFileSpecs } from './find-legacy-multifile-specs.js';
 export { foldTechnicalIntoSpec } from './fold-technical.js';

package/dist/engine/spec-migrator/legacy-classifier.d.ts

@@ -0,0 +1,4 @@
+import type { LegacyArtifactHit, LegacyMigrationDirective } from '../../types/index.js';
+export declare function scanLegacyArtifacts(specDir: string): Promise<LegacyArtifactHit[]>;
+export declare function buildMigrationDirective(specId: string, specDir: string, hits: LegacyArtifactHit[]): Promise<LegacyMigrationDirective | null>;
+//# sourceMappingURL=legacy-classifier.d.ts.map

package/dist/engine/spec-migrator/legacy-classifier.js

@@ -0,0 +1,70 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { ConfigLoader } from '../config-loader.js';
+const legacyArtifactRuleSchema = z.object({
+    id: z.string().min(1).describe('Unique identifier for this legacy artifact rule'),
+    pattern: z
+        .string()
+        .min(1)
+        .describe('Basename (file) or directory name to match inside a spec folder'),
+    classification: z
+        .enum(['content-bearing', 'transient'])
+        .describe('content-bearing requires host-LLM synthesis into targetSection; transient is deleted with no synthesis'),
+    targetSection: z
+        .string()
+        .optional()
+        .describe('spec.md section this artifact folds into, required for content-bearing rules'),
+});
+const legacyArtifactRulesSchema = z
+    .array(legacyArtifactRuleSchema)
+    .describe('Registry of legacy spec-folder artifact classifications');
+const loader = new ConfigLoader('legacy-artifacts', legacyArtifactRulesSchema);
+function loadRules() {
+    return loader.load();
+}
+export async function scanLegacyArtifacts(specDir) {
+    const rules = loadRules();
+    let entries;
+    try {
+        entries = await readdir(specDir);
+    }
+    catch {
+        return [];
+    }
+    const hits = [];
+    for (const entry of entries) {
+        if (entry === 'spec.md') {
+            continue;
+        }
+        const rule = rules.find((r) => r.pattern === entry);
+        if (!rule) {
+            continue;
+        }
+        hits.push({
+            path: entry,
+            classification: rule.classification,
+            ...(rule.targetSection !== undefined ? { targetSection: rule.targetSection } : {}),
+        });
+    }
+    return hits;
+}
+export async function buildMigrationDirective(specId, specDir, hits) {
+    if (hits.length === 0) {
+        return null;
+    }
+    const legacyFiles = [];
+    for (const hit of hits) {
+        if (hit.classification !== 'content-bearing') {
+            legacyFiles.push(hit);
+            continue;
+        }
+        const inlinedContent = await readFile(join(specDir, hit.path), 'utf-8').catch(() => undefined);
+        legacyFiles.push({
+            ...hit,
+            ...(inlinedContent !== undefined ? { inlinedContent } : {}),
+        });
+    }
+    return { specId, legacyFiles, directive: 'migrate_legacy_spec' };
+}
+//# sourceMappingURL=legacy-classifier.js.map

package/dist/engine/spec-migrator/planu-canonical-policy.js

@@ -1,5 +1,18 @@
 // engine/spec-migrator/planu-canonical-policy.ts — SPEC-1017
 // Single source of truth for the strict Planu managed directory contract.
+import { z } from 'zod';
+import { ConfigLoader } from '../config-loader.js';
+const legacyArtifactRuleSchema = z.object({
+    id: z.string().min(1),
+    pattern: z.string().min(1),
+    classification: z.enum(['content-bearing', 'transient']),
+    targetSection: z.string().optional(),
+});
+const legacyArtifactRulesLoader = new ConfigLoader('legacy-artifacts', z.array(legacyArtifactRuleSchema));
+const LEGACY_CONTENT_BEARING_PATTERNS = legacyArtifactRulesLoader
+    .load()
+    .filter((rule) => rule.classification === 'content-bearing')
+    .map((rule) => rule.pattern);
 export const PLANU_CANONICAL_POLICY = {
     canonicalRootFiles: [
         'conventions.json',
@@ -33,15 +46,7 @@ export const PLANU_CANONICAL_POLICY = {
         'planu/specs/*/implementation-brief.md',
         'planu/specs/*/risk-register.md',
     ],
-    legacyMergeBeforeDeleteFiles: [
-        'technical.md',
-        'plan.md',
-        'PLAN.md',
-        'progress.md',
-        'HU.md',
-        'FICHA-TECNICA.md',
-        'PROGRESS.md',
-    ],
+    legacyMergeBeforeDeleteFiles: LEGACY_CONTENT_BEARING_PATTERNS,
 };
 const ROOT_FILE_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootFiles);
 const ROOT_DIR_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootDirs);

package/dist/engine/spec-migrator/strict-planu-cleanup.d.ts

@@ -1,6 +1,8 @@
-import type { StrictPlanuCleanupResult, StrictPlanuValidationOptions, StrictPlanuValidationResult, HousekeepingAuthority } from '../../types/index.js';
+import type { StrictPlanuCleanupResult, StrictPlanuValidationOptions, StrictPlanuValidationResult, HousekeepingAuthority, LegacyArtifactHit } from '../../types/index.js';
 import { PLANU_CANONICAL_POLICY } from './planu-canonical-policy.js';
+declare function classifyPendingLegacySpecFile(specDir: string, fileName: string): Promise<LegacyArtifactHit>;
+export declare function findTrackedNonCanonicalSpecFiles(projectPath: string): Promise<string[]>;
 export declare function runStrictPlanuCleanup(projectPath: string, authority?: HousekeepingAuthority): Promise<StrictPlanuCleanupResult>;
 export declare function validateStrictPlanuLayout(projectPath: string, options?: StrictPlanuValidationOptions): Promise<StrictPlanuValidationResult>;
-export { PLANU_CANONICAL_POLICY };
+export { PLANU_CANONICAL_POLICY, classifyPendingLegacySpecFile };
 //# sourceMappingURL=strict-planu-cleanup.d.ts.map

package/dist/engine/spec-migrator/strict-planu-cleanup.js

@@ -7,6 +7,7 @@ import { promisify } from 'node:util';
 import { dirname, isAbsolute, join, relative } from 'node:path';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
 import { safeUnlink } from './git-aware-fs.js';
+import { scanLegacyArtifacts } from './legacy-classifier.js';
 import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalReleaseFile, isCanonicalSpecDir, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
 const execFileAsync = promisify(execFile);
 async function pathIsDirectory(path) {
@@ -41,37 +42,10 @@ async function gitRmCached(projectPath, relPath) {
         /* best-effort */
     }
 }
-function stripFrontmatter(content) {
-    return content.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
-}
-function appendSectionIfMissing(specContent, heading, body) {
-    if (body.trim().length === 0 || new RegExp(`\\n## ${heading}(\\n|$)`).test(specContent)) {
-        return specContent;
-    }
-    return `${specContent.trimEnd()}\n\n## ${heading}\n\n${body.trim()}\n`;
-}
-async function mergeLegacySpecFile(projectPath, specDir, fileName) {
-    const specPath = join(specDir, 'spec.md');
-    const legacyPath = join(specDir, fileName);
-    const [specContent, legacyContent] = await Promise.all([
-        readFile(specPath, 'utf-8'),
-        readFile(legacyPath, 'utf-8'),
-    ]);
-    const body = stripFrontmatter(legacyContent);
-    const section = fileName === 'progress.md' || fileName === 'PROGRESS.md'
-        ? 'Progress'
-        : fileName === 'technical.md' || fileName === 'FICHA-TECNICA.md'
-            ? 'Technical'
-            : 'Files';
-    const merged = appendSectionIfMissing(specContent, section, body);
-    if (merged !== specContent) {
-        await atomicWriteFile(specPath, merged, {
-            forceEdit: {
-                reason: `SPEC-1017 strict cleanup is merging legacy ${fileName} into canonical spec.md.`,
-            },
-        });
-    }
-    await safeUnlink(projectPath, legacyPath);
+async function classifyPendingLegacySpecFile(specDir, fileName) {
+    const hits = await scanLegacyArtifacts(specDir);
+    const hit = hits.find((h) => h.path === fileName);
+    return hit ?? { path: fileName, classification: 'content-bearing' };
 }
 async function removePath(projectPath, absolutePath) {
     const rel = relative(projectPath, absolutePath);
@@ -83,16 +57,9 @@ async function removePath(projectPath, absolutePath) {
     await safeUnlink(projectPath, absolutePath);
     await rm(absolutePath, { force: true });
 }
-async function updateGitignore(projectPath) {
-    const gitignorePath = join(projectPath, '.gitignore');
-    let current = '';
-    try {
-        current = await readFile(gitignorePath, 'utf-8');
-    }
-    catch {
-        /* missing .gitignore is fine */
-    }
-    const required = [
+const PLANU_GITIGNORE_BLOCK_HEADER = '# Planu generated/runtime';
+function buildPlanuIgnoreBlock() {
+    return [
         'planu/*.html',
         'planu/status.json',
         'planu/CHANGELOG.md',
@@ -102,27 +69,71 @@ async function updateGitignore(projectPath) {
         'planu/data/',
         'planu/state/',
         'planu/.locks/',
-        'planu/specs/data/',
-        'planu/specs/**/.analysis.json',
-        'planu/specs/**/technical-report.html',
-        'planu/specs/**/reference/',
-        'planu/specs/**/*.bak.*',
+        'planu/specs/**',
+        '!planu/specs/**/',
+        '!planu/specs/**/spec.md',
     ];
-    const missing = required.filter((entry) => !current.split('\n').includes(entry));
-    if (missing.length === 0) {
+}
+function removePlanuGitignoreBlock(lines) {
+    let result = lines;
+    let startIndex = result.findIndex((line) => line.trim() === PLANU_GITIGNORE_BLOCK_HEADER);
+    while (startIndex !== -1) {
+        let endIndex = result.length;
+        for (let i = startIndex + 1; i < result.length; i++) {
+            if (result[i]?.trim() === '') {
+                endIndex = i;
+                break;
+            }
+        }
+        result = [...result.slice(0, startIndex), ...result.slice(endIndex)];
+        startIndex = result.findIndex((line) => line.trim() === PLANU_GITIGNORE_BLOCK_HEADER);
+    }
+    return result;
+}
+async function updateGitignore(projectPath) {
+    const gitignorePath = join(projectPath, '.gitignore');
+    let original = '';
+    try {
+        original = await readFile(gitignorePath, 'utf-8');
+    }
+    catch {
+        /* missing .gitignore is fine */
+    }
+    const cleaned = removePlanuGitignoreBlock(original.split('\n')).join('\n');
+    const separator = cleaned === '' || cleaned.endsWith('\n') ? '' : '\n';
+    const updatedContent = `${cleaned}${separator}${PLANU_GITIGNORE_BLOCK_HEADER}\n${buildPlanuIgnoreBlock().join('\n')}\n`;
+    if (updatedContent === original) {
         return false;
     }
-    const separator = current === '' || current.endsWith('\n') ? '' : '\n';
-    await atomicWriteFile(gitignorePath, `${current}${separator}# Planu generated/runtime\n${missing.join('\n')}\n`);
+    await atomicWriteFile(gitignorePath, updatedContent);
     return true;
 }
+async function listTrackedFiles(projectPath, relPath) {
+    if (!existsSync(join(projectPath, '.git'))) {
+        return [];
+    }
+    try {
+        const { stdout } = await execFileAsync('git', ['ls-files', relPath], {
+            cwd: projectPath,
+            timeout: 5_000,
+        });
+        return stdout.trim().split('\n').filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+export async function findTrackedNonCanonicalSpecFiles(projectPath) {
+    const tracked = await listTrackedFiles(projectPath, 'planu/specs');
+    return tracked.filter((relPath) => !isCanonicalSpecFile(relPath.split('/').pop() ?? ''));
+}
 async function walkSpecDirectory(projectPath, specDir, result) {
     const entries = await readDirectory(specDir);
     for (const entry of entries) {
         const full = join(specDir, entry);
         if (mustMergeBeforeDeleteSpecFile(entry)) {
-            await mergeLegacySpecFile(projectPath, specDir, entry);
-            result.merged.push(relative(projectPath, full));
+            await classifyPendingLegacySpecFile(specDir, entry);
+            result.proposed.push(relative(projectPath, full));
             continue;
         }
         const isDir = await pathIsDirectory(full);
@@ -251,5 +262,5 @@ export async function validateStrictPlanuLayout(projectPath, options = {}) {
     }
     return { ok: offenders.length === 0, offenders, contract: canonicalContractText() };
 }
-export { PLANU_CANONICAL_POLICY };
+export { PLANU_CANONICAL_POLICY, classifyPendingLegacySpecFile };
 //# sourceMappingURL=strict-planu-cleanup.js.map

package/dist/storage/spec-store.js

@@ -50,6 +50,12 @@ function normalizeSpec(raw) {
     }
     // SPEC-601: Lazy UUID migration — generate if missing
     spec.uuid ??= crypto.randomUUID();
+    if (!Array.isArray(raw.dependencies)) {
+        spec.dependencies = [];
+    }
+    if (!Array.isArray(raw.blockedBy)) {
+        spec.blockedBy = [];
+    }
     if (spec.uuidAliases !== undefined) {
         spec.uuidAliases = [
             ...new Set(spec.uuidAliases.filter((alias) => typeof alias === 'string' && alias)),

package/dist/tools/export-spec.js

@@ -1,11 +1,12 @@
 // tools/export-spec.ts — MCP tool handler for export_spec (SPEC-097, SPEC-318)
 import { readFile, mkdir, writeFile } from 'node:fs/promises';
-import { join, resolve, relative } from 'node:path';
+import { join } from 'node:path';
 import { specStore, knowledgeStore } from '../storage/index.js';
 import { hashProjectPath } from '../storage/base-store.js';
 import { exportToSpecKit } from '../engine/spec-kit-exporter.js';
 import { stripFrontmatter } from '../engine/frontmatter-parser.js';
 import { specToAgentReady, serializeAgentReady } from '../engine/agent-ready-exporter.js';
+import { assertPathWithinBase } from '../engine/safety/assert-within-project.js';
 import { compactResult, formatKeyValue } from './output-formatter.js';
 async function readFileContent(filePath) {
     try {
@@ -65,15 +66,16 @@ export async function handleExportSpec(params) {
         const content = serializeAgentReady(agentSpec, target);
         let filePath;
         if (params.outputDir) {
-            const resolvedOutput = resolve(params.outputDir);
-            const resolvedProject = resolve(params.projectPath);
-            const rel = relative(resolvedProject, resolvedOutput);
-            if (rel.startsWith('..') || rel.startsWith('/')) {
+            let resolvedOutput;
+            try {
+                resolvedOutput = assertPathWithinBase(params.projectPath, params.outputDir);
+            }
+            catch (error) {
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: `Invalid outputDir: path escapes the project directory. Resolved to "${resolvedOutput}".`,
+                            text: `Invalid outputDir: ${error instanceof Error ? error.message : String(error)}`,
                         },
                     ],
                     isError: true,
@@ -121,24 +123,25 @@ export async function handleExportSpec(params) {
     // Write to output directory
     const slug = toSlug(spec.title);
     const outputDir = params.outputDir ?? join(params.projectPath, 'planu', 'exports', slug);
-    const resolvedOutput = resolve(outputDir);
-    const resolvedProject = resolve(params.projectPath);
-    const rel = relative(resolvedProject, resolvedOutput);
-    if (rel.startsWith('..') || rel.startsWith('/')) {
+    let resolvedOutput;
+    try {
+        resolvedOutput = assertPathWithinBase(params.projectPath, outputDir);
+    }
+    catch (error) {
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Invalid outputDir: path escapes the project directory. Resolved to "${resolvedOutput}".`,
+                    text: `Invalid outputDir: ${error instanceof Error ? error.message : String(error)}`,
                 },
             ],
             isError: true,
         };
     }
-    await mkdir(outputDir, { recursive: true });
-    const specMdPath = join(outputDir, 'spec.md');
-    const planMdPath = join(outputDir, 'plan.md');
-    const tasksMdPath = join(outputDir, 'tasks.md');
+    await mkdir(resolvedOutput, { recursive: true });
+    const specMdPath = join(resolvedOutput, 'spec.md');
+    const planMdPath = join(resolvedOutput, 'plan.md');
+    const tasksMdPath = join(resolvedOutput, 'tasks.md');
     await Promise.all([
         writeFile(specMdPath, result.specMd, 'utf-8'),
         writeFile(planMdPath, result.planMd, 'utf-8'),

package/dist/tools/heal-spec-docs.js

@@ -11,6 +11,7 @@ import { extractFilesFromSpecBody } from '../engine/spec-format/technical-md-pop
 import { jaccard } from '../engine/spec-format/jaccard.js';
 import { replaceSectionInSpec } from '../engine/spec-format/replace-section.js';
 import { executionRemove } from '../engine/execution/deadline-io.js';
+import { buildMigrationDirective, scanLegacyArtifacts, } from '../engine/spec-migrator/legacy-classifier.js';
 const SPANISH_INDICATORS = [
     'de',
     'del',
@@ -350,8 +351,8 @@ export async function handleHealSpecDocs(params) {
     // (so any regenerated technical.md files are also merged and cleaned up).
     // Migrations are git-aware via safeUnlink; previously they ran in list_specs (read-only).
     let leanMigratedCount = 0;
-    let unifiedMigratedCount = 0;
     let rootCleanedCount = 0;
+    const migrationDirectives = [];
     // Only run full migrations when no specific specId is requested (mass healing)
     if (!specId && !dryRun) {
         try {
@@ -362,14 +363,6 @@ export async function handleHealSpecDocs(params) {
         catch {
             // best-effort
         }
-        try {
-            const { migrateAllSpecsToUnified } = await import('../engine/spec-migrator/unified-migration.js');
-            const unifiedResult = await migrateAllSpecsToUnified(projectPath);
-            unifiedMigratedCount = unifiedResult.mergedCount;
-        }
-        catch {
-            // best-effort
-        }
         try {
             const { cleanPlanuRoot } = await import('../engine/spec-migrator/planu-root-cleaner.js');
             const planuDir = join(projectPath, 'planu');
@@ -380,6 +373,15 @@ export async function handleHealSpecDocs(params) {
             // best-effort
         }
     }
+    if (!dryRun) {
+        for (const spec of specs) {
+            const hits = await scanLegacyArtifacts(spec.dir);
+            const directive = await buildMigrationDirective(spec.specId, spec.dir, hits);
+            if (directive !== null) {
+                migrationDirectives.push(directive);
+            }
+        }
+    }
     const parts = [];
     parts.push(`status.json repaired: ${statusJsonRepaired ? 'yes' : 'no'}`);
     parts.push(`technical.md healed: ${String(healed)}`);
@@ -392,12 +394,12 @@ export async function handleHealSpecDocs(params) {
     if (leanMigratedCount > 0) {
         parts.push(`lean migrations: ${String(leanMigratedCount)}`);
     }
-    if (unifiedMigratedCount > 0) {
-        parts.push(`unified migrations (technical.md merged+deleted): ${String(unifiedMigratedCount)}`);
-    }
     if (rootCleanedCount > 0) {
         parts.push(`planu/ root cleaned: ${String(rootCleanedCount)} file(s)`);
     }
+    if (migrationDirectives.length > 0) {
+        parts.push(`legacy artifacts pending host-LLM migration: ${String(migrationDirectives.length)} spec(s) — call migrate_legacy_spec`);
+    }
     if (titlesNonEnglish > 0) {
         parts.push(`non-English titles detected (not modified): ${String(titlesNonEnglish)}`);
     }
@@ -410,6 +412,7 @@ export async function handleHealSpecDocs(params) {
             dryRunDiff,
             backupPath,
             warnings,
+            migrationDirectives,
         },
     };
 }

package/dist/tools/init-project/git-setup.js

@@ -78,65 +78,69 @@ async function untrackHtmlFiles(projectPath) {
 export async function configureGitignoreForPlanu(projectPath) {
     return configureGitignore(projectPath);
 }
+const PLANU_GITIGNORE_BLOCK_START = '# Planu (auto-configured)';
 async function configureGitignore(projectPath) {
     const targetPath = join(projectPath, '.gitignore');
     try {
-        let gitignoreContent = '';
+        let original = '';
         try {
-            gitignoreContent = await readFile(targetPath, 'utf-8');
+            original = await readFile(targetPath, 'utf-8');
         }
         catch {
             /* file doesn't exist */
         }
         // Remove planu/ from .gitignore if present — specs MUST be tracked in git
         const protectedPaths = ['planu/', 'planu.json', 'planu/*'];
-        const lines = gitignoreContent.split('\n');
-        const cleaned = lines.filter((line) => !protectedPaths.some((p) => line.trim() === p));
-        let updated = cleaned.length !== lines.length;
-        if (updated) {
-            gitignoreContent = cleaned.join('\n');
-        }
-        // Add data/ if missing — runtime data should NOT be tracked
+        const cleaned = removePlanuGitignoreBlock(original.split('\n')).filter((line) => !protectedPaths.some((p) => line.trim() === p));
+        let gitignoreContent = cleaned.join('\n');
         const linesToAdd = [];
         if (!gitignoreContent.includes('data/')) {
             linesToAdd.push('data/');
         }
-        // SPEC-466: Gitignore regenerable planu/ files to prevent merge conflicts
-        // SPEC-724: Gitignore heal_spec_docs backup files (.bak.<ts>)
-        const planuIgnores = [
-            'planu/*.html',
-            'planu/status.json',
-            'planu/CHANGELOG.md',
-            'planu/.housekeeping-history.jsonl',
-            'planu/audits/',
-            'planu/handoffs/',
-            'planu/data/',
-            'planu/state/',
-            'planu/.locks/',
-            'planu/specs/data/',
-            'planu/specs/**/.analysis.json',
-            'planu/specs/**/technical-report.html',
-            'planu/specs/**/reference/',
-            'planu/specs/**/*.bak.*',
-        ];
-        for (const entry of planuIgnores) {
-            if (!gitignoreContent.includes(entry)) {
-                linesToAdd.push(entry);
-            }
-        }
-        if (linesToAdd.length > 0 || updated) {
-            const separator = gitignoreContent.endsWith('\n') || gitignoreContent === '' ? '' : '\n';
-            const addition = linesToAdd.length > 0
-                ? `${separator}# Planu (auto-configured)\n${linesToAdd.join('\n')}\n`
-                : '';
-            await writeFile(targetPath, gitignoreContent + addition, 'utf-8');
-            updated = true;
+        linesToAdd.push(...buildPlanuIgnoreBlock());
+        const separator = gitignoreContent.endsWith('\n') || gitignoreContent === '' ? '' : '\n';
+        gitignoreContent += `${separator}${PLANU_GITIGNORE_BLOCK_START}\n${linesToAdd.join('\n')}\n`;
+        if (gitignoreContent === original) {
+            return false;
         }
-        return updated;
+        await writeFile(targetPath, gitignoreContent, 'utf-8');
+        return true;
     }
     catch {
         /* best-effort */
         return false;
     }
 }
+function buildPlanuIgnoreBlock() {
+    return [
+        'planu/*.html',
+        'planu/status.json',
+        'planu/CHANGELOG.md',
+        'planu/.housekeeping-history.jsonl',
+        'planu/audits/',
+        'planu/handoffs/',
+        'planu/data/',
+        'planu/state/',
+        'planu/.locks/',
+        'planu/specs/**',
+        '!planu/specs/**/',
+        '!planu/specs/**/spec.md',
+    ];
+}
+function removePlanuGitignoreBlock(lines) {
+    let result = lines;
+    let startIndex = result.findIndex((line) => line.trim() === PLANU_GITIGNORE_BLOCK_START);
+    while (startIndex !== -1) {
+        let endIndex = result.length;
+        for (let i = startIndex + 1; i < result.length; i++) {
+            if (result[i]?.trim() === '') {
+                endIndex = i;
+                break;
+            }
+        }
+        result = [...result.slice(0, startIndex), ...result.slice(endIndex)];
+        startIndex = result.findIndex((line) => line.trim() === PLANU_GITIGNORE_BLOCK_START);
+    }
+    return result;
+}
 //# sourceMappingURL=git-setup.js.map