@planu/cli 5.7.3 → 5.7.5

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [5.7.5] - 2026-08-31
+
+### Bug Fixes
+- fix(init-project): address implementation review blockers for SPEC-1716
+- fix(init-project): neutralize stale legacy guidance and fold divergent technical.md residuals
+
+### Chores
+- chore(planu): discard 29 triaged drafts and record SPEC-1716 cycle state
+
+
+## [5.7.4] - 2026-08-31
+
+### Bug Fixes
+- fix(cleanup): run runtime hygiene in report mode and exempt .runtime from offender scans
+- fix(cleanup): ignore planu/.runtime and untrack leaked runtime files in strict cleanup
+
+### Chores
+- chore(runtime): untrack leaked planu runtime state and pin repo-local ignores
+
+
 ## [5.7.3] - 2026-08-31
 
 ### Bug Fixes

package/dist/.planu-build.json

@@ -1 +1 @@
-{"schemaVersion":1,"commit":"c4bce4cb95bcc9bf608918ec18bf3dd47c6b3f91"}
+{"schemaVersion":1,"commit":"858730d3bc7c59966cbff5c34cae03fa636843eb"}

package/dist/config/registries/legacy-guidance.json

@@ -0,0 +1,26 @@
+{
+  "hostSurfaceFiles": [
+    "CLAUDE.md",
+    "AGENTS.md",
+    ".cursorrules",
+    ".windsurfrules",
+    ".github/copilot-instructions.md",
+    ".clinerules",
+    ".cursor/rules/planu.mdc",
+    ".agents/skills/planu-sdd.md"
+  ],
+  "hostSurfaceDirectories": [{ "dir": ".claude/rules", "extension": ".md" }],
+  "legacyFilenameAllowlist": [
+    ".claude/rules/sdd-planu.md",
+    ".claude/rules/planu-workflow.md",
+    ".cursor/rules/planu.mdc",
+    ".agents/skills/planu-sdd.md"
+  ],
+  "managedByMarkers": ["Auto-generated by Planu", "Auto-generated by `init_project`", "managed-by: planu"],
+  "contradictoryPhrases": [
+    "spec.md + technical.md + progress.md",
+    "technical.md — architecture",
+    "keep technical.md and progress.md"
+  ],
+  "replacementGuidance": "Specs live in `planu/specs/SPEC-XXX-slug/spec.md`. Technical planning, file ownership, and progress live inline in `## Technical`, `## Files`, and `## Progress` sections. Do not create standalone technical.md or progress.md files."
+}

package/dist/engine/spec-migrator/drift-detector.js

@@ -3,7 +3,7 @@ import { readdir, stat, access, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isOldFormat } from './lean-migration.js';
 import { fastScanSpecsAsync } from '../core-bridge.js';
-import { isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalSpecFile, } from './planu-canonical-policy.js';
+import { isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalSpecFile, isRuntimeHomeRootDir, } from './planu-canonical-policy.js';
 async function scanPlanuRoot(projectPath) {
     const rootFiles = [];
     const planuDir = join(projectPath, 'planu');
@@ -14,7 +14,7 @@ async function scanPlanuRoot(projectPath) {
             try {
                 const info = await stat(fullPath);
                 if (info.isDirectory()) {
-                    if (!isCanonicalPlanuRootDir(entry)) {
+                    if (!isCanonicalPlanuRootDir(entry) && !isRuntimeHomeRootDir(entry)) {
                         rootFiles.push(entry);
                     }
                 }

package/dist/engine/spec-migrator/fold-technical.js

@@ -1,10 +1,47 @@
 // engine/spec-migrator/fold-technical.ts — SPEC-752
 // Folds legacy technical.md body into spec.md's ## Technical section, then deletes technical.md.
 // Uses the same pattern as unified-migration.ts (SPEC-630).
-import { readFile } from 'node:fs/promises';
+import { readFile, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
 import { safeUnlink } from './git-aware-fs.js';
+import { isPlaceholderTechnical } from './placeholder-technical.js';
+const FOLDED_HEADING = '### Folded from legacy technical.md';
+/**
+ * Insert `techBody` under a `### Folded from legacy technical.md` subsection,
+ * placed right after the existing `## Technical` section (before the next
+ * top-level `## ` heading, or at the end of the document when none follows).
+ */
+function foldIntoTechnicalSection(specContent, techBody) {
+    const headingMatch = /\n## Technical(\n|$)/.exec(specContent);
+    const insertion = `\n${FOLDED_HEADING}\n\n${techBody}\n`;
+    if (!headingMatch) {
+        return `${specContent.trimEnd()}\n\n## Technical\n${insertion}`;
+    }
+    const afterHeading = headingMatch.index + headingMatch[0].length;
+    const nextHeadingMatch = /\n## /.exec(specContent.slice(afterHeading));
+    if (!nextHeadingMatch) {
+        return `${specContent.trimEnd()}\n${insertion}`;
+    }
+    const insertAt = afterHeading + nextHeadingMatch.index;
+    return specContent.slice(0, insertAt) + insertion + specContent.slice(insertAt);
+}
+async function removeResidualTechnicalMd(techPath, projectPath) {
+    if (projectPath) {
+        // safeUnlink is already idempotent for a missing file (git rm --ignore-unmatch,
+        // unlink swallows ENOENT) and rethrows every other failure.
+        await safeUnlink(projectPath, techPath);
+        return;
+    }
+    try {
+        await unlink(techPath);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+}
 /**
  * Fold technical.md content into spec.md under a `## Technical` section.
  * Idempotent: returns already_unified if spec.md already has `## Technical`.
@@ -20,22 +57,32 @@ export async function foldTechnicalIntoSpec(specDir, projectPath) {
         const specContent = await readFile(specPath, 'utf-8');
         // Idempotency check: already has ## Technical section.
         // SPEC-1008: also delete any residual technical.md so the spec dir ends
-        // up in the canonical single-file layout. Previously the early-return
-        // left the legacy file behind forever.
+        // up in the canonical single-file layout.
+        // SPEC-1716: before deleting, read the residual — divergent content is
+        // folded under a "Folded from legacy technical.md" subsection instead of
+        // silently dropped.
         if (/\n## Technical(\n|$)/.test(specContent)) {
+            let residualContent;
             try {
-                if (projectPath) {
-                    await safeUnlink(projectPath, techPath);
-                }
-                else {
-                    const { unlink } = await import('node:fs/promises');
-                    await unlink(techPath);
-                }
+                residualContent = await readFile(techPath, 'utf-8');
             }
             catch {
-                /* technical.md already absent — nothing to clean up */
+                return { ok: true, reason: 'already_unified' };
             }
-            return { ok: true, reason: 'already_unified' };
+            const residualBody = residualContent.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
+            const alreadyContained = residualBody.length === 0 ||
+                specContent.includes(residualBody) ||
+                isPlaceholderTechnical(residualBody);
+            if (alreadyContained) {
+                await removeResidualTechnicalMd(techPath, projectPath);
+                return { ok: true, reason: 'already_unified' };
+            }
+            const unified = foldIntoTechnicalSection(specContent, residualBody);
+            const before = Buffer.byteLength(specContent, 'utf-8');
+            const after = Buffer.byteLength(unified, 'utf-8');
+            await atomicWriteFile(specPath, unified);
+            await removeResidualTechnicalMd(techPath, projectPath);
+            return { ok: true, reason: 'folded_residual', byteDelta: after - before };
         }
         // Try reading technical.md
         let techContent;
@@ -51,13 +98,7 @@ export async function foldTechnicalIntoSpec(specDir, projectPath) {
         const before = Buffer.byteLength(specContent, 'utf-8');
         const after = Buffer.byteLength(unified, 'utf-8');
         await atomicWriteFile(specPath, unified);
-        if (projectPath) {
-            await safeUnlink(projectPath, techPath);
-        }
-        else {
-            const { unlink } = await import('node:fs/promises');
-            await unlink(techPath);
-        }
+        await removeResidualTechnicalMd(techPath, projectPath);
         return { ok: true, reason: 'ok', byteDelta: after - before };
     }
     catch (err) {

package/dist/engine/spec-migrator/placeholder-technical.d.ts

@@ -0,0 +1,2 @@
+export declare function isPlaceholderTechnical(content: string): boolean;
+//# sourceMappingURL=placeholder-technical.d.ts.map

package/dist/engine/spec-migrator/placeholder-technical.js

@@ -0,0 +1,18 @@
+// engine/spec-migrator/placeholder-technical.ts — SPEC-1716
+// Shared placeholder-stub detector for technical.md bodies. Lives in engine/ so
+// both engine (fold-technical.ts) and tools (heal-spec-docs.ts) can import it —
+// engine/ must never import from tools/.
+export function isPlaceholderTechnical(content) {
+    if (content.includes('(pending)')) {
+        return true;
+    }
+    if (/--[a-z]/.test(content)) {
+        return true;
+    }
+    if (content.includes('(to be determined)') &&
+        !/\.(ts|tsx|js|jsx|py|rb|go|java|cs)/.test(content)) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=placeholder-technical.js.map

package/dist/engine/spec-migrator/planu-canonical-policy.d.ts

@@ -2,6 +2,7 @@ import type { PlanuCanonicalPathPolicy } from '../../types/index.js';
 export declare const PLANU_CANONICAL_POLICY: PlanuCanonicalPathPolicy;
 export declare function isCanonicalPlanuRootFile(name: string): boolean;
 export declare function isCanonicalPlanuRootDir(name: string): boolean;
+export declare function isRuntimeHomeRootDir(name: string): boolean;
 export declare function isCanonicalSpecFile(name: string): boolean;
 export declare function isCanonicalSpecDir(name: string): boolean;
 export declare function mustMergeBeforeDeleteSpecFile(name: string): boolean;

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

@@ -48,12 +48,18 @@ const ROOT_DIR_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootDirs);
 const SPEC_FILE_SET = new Set(PLANU_CANONICAL_POLICY.canonicalSpecFiles);
 const SPEC_DIR_SET = new Set(PLANU_CANONICAL_POLICY.canonicalSpecDirs);
 const LEGACY_MERGE_SET = new Set(PLANU_CANONICAL_POLICY.legacyMergeBeforeDeleteFiles);
+const RUNTIME_HOME_TOP_DIR = PLANU_CANONICAL_POLICY.runtimeHomeDir
+    .replace(/^planu\//, '')
+    .replace(/\/$/, '');
 export function isCanonicalPlanuRootFile(name) {
     return ROOT_FILE_SET.has(name);
 }
 export function isCanonicalPlanuRootDir(name) {
     return ROOT_DIR_SET.has(name);
 }
+export function isRuntimeHomeRootDir(name) {
+    return name === RUNTIME_HOME_TOP_DIR;
+}
 export function isCanonicalSpecFile(name) {
     return SPEC_FILE_SET.has(name);
 }

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

@@ -8,7 +8,7 @@ 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, isLegacyReleasePendingFile, isCanonicalSpecDir, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
+import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isLegacyReleasePendingFile, isCanonicalSpecDir, isCanonicalSpecFile, isRuntimeHomeRootDir, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
 const execFileAsync = promisify(execFile);
 // SPEC-1699: legacy planu/ root files folded into project.json by init_project's
 // migration. Destructive cleanup must never delete them outright — only the
@@ -44,7 +44,6 @@ async function gitRmCached(projectPath, relPath) {
         return;
     }
     try {
-        // This helper is only called for directories from removePath.
         const args = ['rm', '--cached', '--quiet', '--ignore-unmatch', '-r', relPath];
         await execFileAsync('git', args, {
             cwd: projectPath,
@@ -82,6 +81,7 @@ function buildPlanuIgnoreBlock() {
         'planu/data/',
         'planu/state/',
         'planu/.locks/',
+        'planu/.runtime/',
         'planu/specs/**',
         '!planu/specs/**/',
         '!planu/specs/**/spec.md',
@@ -163,16 +163,23 @@ async function shouldDeleteOrphanSpecDir(specDir) {
     // Keeping them without spec.md leaves a permanently non-canonical orphan behind.
     return !entries.includes('spec.md');
 }
+async function runReportModeCleanup(projectPath) {
+    const validation = await validateStrictPlanuLayout(projectPath);
+    const planuExists = existsSync(join(projectPath, 'planu'));
+    const gitignoreUpdated = planuExists ? await updateGitignore(projectPath) : false;
+    const untracked = planuExists ? await untrackRuntimeFiles(projectPath) : [];
+    return {
+        mode: 'report',
+        deleted: [],
+        merged: [],
+        proposed: validation.offenders,
+        gitignoreUpdated,
+        untracked,
+    };
+}
 export async function runStrictPlanuCleanup(projectPath, authority = { mode: 'report' }) {
     if (authority.mode === 'report') {
-        const validation = await validateStrictPlanuLayout(projectPath);
-        return {
-            mode: 'report',
-            deleted: [],
-            merged: [],
-            proposed: validation.offenders,
-            gitignoreUpdated: false,
-        };
+        return runReportModeCleanup(projectPath);
     }
     const result = {
         mode: 'execute',
@@ -180,6 +187,7 @@ export async function runStrictPlanuCleanup(projectPath, authority = { mode: 're
         merged: [],
         proposed: [],
         gitignoreUpdated: false,
+        untracked: [],
     };
     const planuDir = join(projectPath, 'planu');
     if (!existsSync(planuDir)) {
@@ -189,10 +197,7 @@ export async function runStrictPlanuCleanup(projectPath, authority = { mode: 're
     for (const entry of entries) {
         const full = join(planuDir, entry);
         const isDir = await pathIsDirectory(full);
-        if (isDir && entry === 'releases') {
-            // SPEC-1699: 'releases' is no longer a canonical root dir, but its
-            // pending.json still needs the dedicated fold-into-project.json
-            // migration below before its directory can be removed.
+        if (isDir && (entry === 'releases' || isRuntimeHomeRootDir(entry))) {
             continue;
         }
         if (isDir && !isCanonicalPlanuRootDir(entry)) {
@@ -236,8 +241,20 @@ export async function runStrictPlanuCleanup(projectPath, authority = { mode: 're
         await walkSpecDirectory(projectPath, full, result);
     }
     result.gitignoreUpdated = await updateGitignore(projectPath);
+    result.untracked = await untrackRuntimeFiles(projectPath);
     return result;
 }
+async function untrackRuntimeFiles(projectPath) {
+    const trackedRuntimeFiles = await listTrackedFiles(projectPath, 'planu/.runtime');
+    if (trackedRuntimeFiles.length === 0) {
+        return trackedRuntimeFiles;
+    }
+    for (const relPath of trackedRuntimeFiles) {
+        await gitRmCached(projectPath, relPath);
+    }
+    const stillTracked = new Set(await listTrackedFiles(projectPath, 'planu/.runtime'));
+    return trackedRuntimeFiles.filter((relPath) => !stillTracked.has(relPath));
+}
 function resolveSpecDirsForValidation(projectPath, specPath) {
     if (!specPath?.trim()) {
         return null;
@@ -253,6 +270,9 @@ export async function validateStrictPlanuLayout(projectPath, options = {}) {
         for (const entry of entries) {
             const full = join(planuDir, entry);
             const isDir = await pathIsDirectory(full);
+            if (isDir && isRuntimeHomeRootDir(entry)) {
+                continue;
+            }
             if ((isDir && !isCanonicalPlanuRootDir(entry)) ||
                 (!isDir && !isCanonicalPlanuRootFile(entry))) {
                 offenders.push(relative(projectPath, full));

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

@@ -13,6 +13,7 @@ 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';
 import { escapeRegex } from '../core/shared/strings.js';
+import { isPlaceholderTechnical } from '../engine/spec-migrator/placeholder-technical.js';
 const SPANISH_INDICATORS = [
     'de',
     'del',
@@ -36,19 +37,6 @@ const SPANISH_INDICATORS = [
 // ---------------------------------------------------------------------------
 // Placeholder detection
 // ---------------------------------------------------------------------------
-function isPlaceholderTechnical(content) {
-    if (content.includes('(pending)')) {
-        return true;
-    }
-    if (/--[a-z]/.test(content)) {
-        return true;
-    }
-    if (content.includes('(to be determined)') &&
-        !/\.(ts|tsx|js|jsx|py|rb|go|java|cs)/.test(content)) {
-        return true;
-    }
-    return false;
-}
 function hasInlineTechnicalFilesPlaceholder(content) {
     return /^##\s+Technical\b[\s\S]*?^##\s+Files\b[\s\S]*?(?:\(pending\)|\(to be determined\)|\bTBD\b|--[a-z])/im.test(content);
 }

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

@@ -21,8 +21,9 @@ import { regeneratePages } from '../../engine/doc-generator/portal/index.js';
 import { detectStackPatterns } from './stack-detector.js';
 import { buildProjectConfig } from './config-builder.js';
 import { runSpecMigrations, listProjectSpecs } from './migration-runner.js';
-import { reconcilePortableSpecIndex, describeReconciliationOutcome, } from './portable-index-reconciler.js';
+import { reconcilePortableSpecIndex, buildAlreadyInitializedResult, buildAuthorizedMigrationResult, } from './portable-index-reconciler.js';
 import { refreshCoreHostAssets } from './host-assets-writer.js';
+import { scanLegacyGuidance, summarizeLegacyGuidanceScan } from './legacy-guidance-scanner.js';
 import { runScaffoldWriter } from './scaffold-writer.js';
 import { readAutoInstallFlag, orchestrateSkillInstalls, runHealthCheckWithBaseline, runConventionScanSafe, fireTelemetry, } from './lifecycle-helpers.js';
 import { injectProactiveRules } from '../../engine/claude-md-injector/index.js';
@@ -223,28 +224,12 @@ export async function handleInitProject(params, server) {
             const authorizedMigrations = params.authorizedMigrations ?? [];
             if (isUpdate && authorizedMigrations.length === 0) {
                 const reconciliation = await reconcilePortableSpecIndex(projectPath, projectId);
-                const repositoryFilesChanged = reconciliation.failures.length === 0 ? await refreshCoreHostAssets(projectPath) : [];
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: describeReconciliationOutcome(reconciliation, repositoryFilesChanged),
-                        },
-                    ],
-                    structuredContent: {
-                        projectId,
-                        ...(reconciliation.failures.length === 0 ? { projectPath } : {}),
-                        isUpdate: true,
-                        repositoryFilesChanged,
-                        authorizedMigrations: [],
-                        importedSpecIds: reconciliation.importedSpecIds,
-                        failures: reconciliation.failures,
-                        skippedLegacy: reconciliation.skippedLegacy,
-                        strayRepoRemovals: reconciliation.strayRepoRemovals,
-                        migratedLegacyPaths: legacyMigration.migrated,
-                    },
-                    ...(reconciliation.failures.length > 0 ? { isError: true } : {}),
-                };
+                const canRefresh = reconciliation.failures.length === 0;
+                const legacyGuidanceScan = canRefresh
+                    ? await scanLegacyGuidance(projectPath)
+                    : { healed: [], warnings: [] };
+                const refreshedAssets = canRefresh ? await refreshCoreHostAssets(projectPath) : [];
+                return buildAlreadyInitializedResult(projectId, reconciliation, legacyMigration.migrated, refreshedAssets, legacyGuidanceScan, projectPath);
             }
             if (isUpdate) {
                 if (existing === null) {
@@ -261,26 +246,8 @@ export async function handleInitProject(params, server) {
                 const migrationResult = await runSpecMigrations(projectPath, projectId, existing, {
                     repositoryMigration: 'planu-spec-format-v1',
                 });
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: migrationResult.criticalMigrationFailures.length === 0
-                                ? 'Authorized planu-spec-format-v1 migration completed.'
-                                : `Authorized migration completed with ${String(migrationResult.criticalMigrationFailures.length)} blocking issue(s).`,
-                        },
-                    ],
-                    structuredContent: {
-                        projectId,
-                        projectPath,
-                        isUpdate: true,
-                        authorizedMigrations,
-                        repositoryFilesChanged: migrationResult.changedPaths ?? [],
-                        migrationReportPath: migrationResult.migrationReportPath,
-                        criticalMigrationFailures: migrationResult.criticalMigrationFailures,
-                    },
-                    ...(migrationResult.criticalMigrationFailures.length > 0 ? { isError: true } : {}),
-                };
+                const legacyGuidanceScan = await scanLegacyGuidance(projectPath).catch(() => ({ healed: [], warnings: [] }));
+                return buildAuthorizedMigrationResult(projectId, projectPath, authorizedMigrations, migrationResult, legacyGuidanceScan);
             }
             // Get global config for defaults
             const globalConfig = await globalStore.getGlobalConfig();
@@ -439,6 +406,7 @@ export async function handleInitProject(params, server) {
             // Write scaffold files: rules, git setup, constitution, CLAUDE.md, lint, architecture rules
             const scaffoldResult = await runScaffoldWriter(projectPath, projectId, knowledge, recommendedSkills, params.permissionsMode, params.pluginsMode, autoInstallFromConfig);
             const { platform, generatedRules, rulesWritten, additionalFilesWritten, hooksInstalled, gitFlowType, gitignoreUpdated, gitRepoDetected, layoutOffenders, constitutionInitialized, claudeMdUpdated, eslintCreated, prettierCreated, lintSuggestions, architectureRulesWritten, architectureRulesSkipped, planuWorkflowInjected, planuHooksConfigured, planuRulesWritten, gitAutoStageInjected, } = scaffoldResult;
+            const legacyGuidanceScan = await scanLegacyGuidance(projectPath).catch(() => ({ healed: [], warnings: [] }));
             // SPEC-444: Inject proactive behavior rules into project CLAUDE.md
             const proactiveRulesInjected = await injectProactiveRules(join(projectPath, 'CLAUDE.md'), '1.22.0')
                 .then(() => true)
@@ -561,6 +529,7 @@ export async function handleInitProject(params, server) {
             if (skillsAutoInstalled.length > 0) {
                 collector.pushOk('skills-installed', `Auto-installed skills: ${skillsAutoInstalled.join(', ')}`);
             }
+            summarizeLegacyGuidanceScan(collector, legacyGuidanceScan);
             const toolResult = buildInitProjectResult({
                 projectId,
                 projectPath,
@@ -620,8 +589,12 @@ export async function handleInitProject(params, server) {
                 branchInfo,
             });
             if (toolResult.structuredContent) {
-                toolResult.structuredContent.repositoryFilesChanged = migrationChangedPaths;
-                toolResult.structuredContent.authorizedMigrations = authorizedMigrations;
+                Object.assign(toolResult.structuredContent, {
+                    repositoryFilesChanged: [...migrationChangedPaths, ...legacyGuidanceScan.healed],
+                    authorizedMigrations,
+                    legacyGuidanceHealed: legacyGuidanceScan.healed,
+                    legacyGuidanceWarnings: legacyGuidanceScan.warnings,
+                });
             }
             // Inject autopilotSummary into structuredContent
             if (collector.hasEntries() && toolResult.structuredContent) {

package/dist/tools/init-project/legacy-guidance-scanner.d.ts

@@ -0,0 +1,12 @@
+import type { AutopilotSummaryCollector } from '../../engine/autopilot/summary-collector.js';
+import type { LegacyGuidanceScanResult } from '../../types/index.js';
+/**
+ * Scan the bounded set of Planu-installed host guidance surfaces for stale
+ * directives that contradict the current spec.md-only contract, and
+ * neutralize what can be neutralized fail-closed. Never touches files
+ * outside the inventoried scan surface (no repo-wide walk).
+ */
+export declare function scanLegacyGuidance(projectPath: string): Promise<LegacyGuidanceScanResult>;
+/** Records a legacy-guidance scan outcome onto an init_project autopilot summary. */
+export declare function summarizeLegacyGuidanceScan(collector: AutopilotSummaryCollector, scan: LegacyGuidanceScanResult): void;
+//# sourceMappingURL=legacy-guidance-scanner.d.ts.map

package/dist/tools/init-project/legacy-guidance-scanner.js

@@ -0,0 +1,176 @@
+// tools/init-project/legacy-guidance-scanner.ts — SPEC-1716
+// Neutralizes stale Planu-installed guidance that instructs agents to create
+// legacy standalone technical.md/progress.md files. Fail-closed by tiers:
+//   Tier 1 — delimited Planu block markers: rewrite only the block content.
+//   Tier 2 — composite fingerprint (allowlisted legacy filename + managed-by
+//            header): replace the whole file, backing up the prior content.
+//   Tier 3 — contradictory phrase alone: warning only, zero mutation.
+// Malformed markers (opening without closing) also fail closed: warning only.
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { atomicWriteFile } from '../../engine/safety/atomic-write-file.js';
+import { resolveContainedProjectFile } from '../../engine/safety/contained-project-file.js';
+import legacyGuidanceRegistry from '../../config/registries/legacy-guidance.json' with { type: 'json' };
+const REGISTRY = legacyGuidanceRegistry;
+async function resolveScanSurface(projectPath) {
+    const files = [...REGISTRY.hostSurfaceFiles];
+    for (const { dir, extension } of REGISTRY.hostSurfaceDirectories) {
+        let entries;
+        try {
+            entries = await readdir(join(projectPath, dir), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith(extension)) {
+                files.push(`${dir}/${entry.name}`);
+            }
+        }
+    }
+    return files;
+}
+function containsContradictoryPhrase(text) {
+    return REGISTRY.contradictoryPhrases.find((phrase) => text.includes(phrase));
+}
+const OPEN_MARKER_RE = /<!--\s*(planu[\w:-]*)\s*-->/g;
+/**
+ * Locate delimited `<!-- planu... --> ... <!-- /planu... -->` (or repeated-tag,
+ * as emitted by claude-md-generator.ts wrap()) blocks. Returns `null` when an
+ * opening marker has no matching close — the malformed-marker fail-closed case.
+ *
+ * Uses its own cursor (a fresh RegExp with `re.lastIndex` advanced past each
+ * close marker) instead of `matchAll` over the whole string — a repeated-tag
+ * close is itself a valid open-marker match, so scanning the string without
+ * skipping past it would misread that close as the next block's opener.
+ */
+function findPlanuBlocks(content) {
+    const blocks = [];
+    const re = new RegExp(OPEN_MARKER_RE.source, 'g');
+    let match;
+    while ((match = re.exec(content)) !== null) {
+        const id = match[1];
+        if (id === undefined) {
+            continue;
+        }
+        const openEnd = match.index + match[0].length;
+        const closeTag = `<!-- /${id} -->`;
+        const repeatTag = match[0];
+        const closeTagStart = content.indexOf(closeTag, openEnd);
+        const repeatTagStart = content.indexOf(repeatTag, openEnd);
+        const closeStart = [closeTagStart, repeatTagStart]
+            .filter((idx) => idx !== -1)
+            .sort((a, b) => a - b)[0];
+        if (closeStart === undefined) {
+            return null;
+        }
+        const closeLength = closeStart === closeTagStart ? closeTag.length : repeatTag.length;
+        blocks.push({ id, openEnd, closeStart });
+        re.lastIndex = closeStart + closeLength;
+    }
+    return blocks;
+}
+async function scanTier1(absPath, relPath, content) {
+    const blocks = findPlanuBlocks(content);
+    if (blocks === null) {
+        return {
+            kind: 'warning',
+            file: relPath,
+            reason: 'malformed Planu block marker: an opening marker has no matching closing marker',
+        };
+    }
+    const dirty = blocks.some(({ openEnd, closeStart }) => containsContradictoryPhrase(content.slice(openEnd, closeStart)));
+    if (!dirty) {
+        return { kind: 'clean' };
+    }
+    let rewritten = '';
+    let cursor = 0;
+    for (const { openEnd, closeStart } of blocks) {
+        const body = content.slice(openEnd, closeStart);
+        rewritten += content.slice(cursor, openEnd);
+        rewritten += containsContradictoryPhrase(body) ? `\n${REGISTRY.replacementGuidance}\n` : body;
+        cursor = closeStart;
+    }
+    rewritten += content.slice(cursor);
+    await atomicWriteFile(absPath, rewritten);
+    return { kind: 'healed', file: relPath };
+}
+async function scanTier2Or3(absPath, relPath, content) {
+    const phrase = containsContradictoryPhrase(content);
+    if (!phrase) {
+        return { kind: 'clean' };
+    }
+    const strongFingerprint = REGISTRY.legacyFilenameAllowlist.includes(relPath) &&
+        REGISTRY.managedByMarkers.some((marker) => content.includes(marker));
+    if (!strongFingerprint) {
+        return {
+            kind: 'warning',
+            file: relPath,
+            reason: `contains contradictory legacy guidance phrase: "${phrase}"`,
+        };
+    }
+    await atomicWriteFile(`${absPath}.planu-backup`, content);
+    await atomicWriteFile(absPath, `${REGISTRY.replacementGuidance}\n`);
+    return { kind: 'healed', file: relPath };
+}
+async function scanFile(projectPath, relPath) {
+    const absPath = join(projectPath, relPath);
+    let content;
+    try {
+        content = await readFile(absPath, 'utf-8');
+    }
+    catch {
+        return { kind: 'clean' };
+    }
+    // Fail closed if the surface entry (or an ancestor directory, e.g. a
+    // symlinked .claude/rules) resolves outside the project root — never let a
+    // mutation follow a symlink off the repo.
+    try {
+        await resolveContainedProjectFile(projectPath, absPath);
+    }
+    catch {
+        return {
+            kind: 'warning',
+            file: relPath,
+            reason: 'path escapes the project directory (symlink containment check failed)',
+        };
+    }
+    const hasMarkers = OPEN_MARKER_RE.test(content);
+    OPEN_MARKER_RE.lastIndex = 0;
+    return hasMarkers
+        ? scanTier1(absPath, relPath, content)
+        : scanTier2Or3(absPath, relPath, content);
+}
+/**
+ * Scan the bounded set of Planu-installed host guidance surfaces for stale
+ * directives that contradict the current spec.md-only contract, and
+ * neutralize what can be neutralized fail-closed. Never touches files
+ * outside the inventoried scan surface (no repo-wide walk).
+ */
+export async function scanLegacyGuidance(projectPath) {
+    const files = await resolveScanSurface(projectPath);
+    const healed = [];
+    const warnings = [];
+    for (const relPath of files) {
+        const outcome = await scanFile(projectPath, relPath);
+        if (outcome.kind === 'healed') {
+            healed.push(outcome.file);
+        }
+        else if (outcome.kind === 'warning') {
+            warnings.push({ file: outcome.file, reason: outcome.reason });
+        }
+    }
+    return { healed, warnings };
+}
+/** Records a legacy-guidance scan outcome onto an init_project autopilot summary. */
+export function summarizeLegacyGuidanceScan(collector, scan) {
+    if (scan.healed.length > 0) {
+        collector.pushOk('legacy-guidance-healed', `Neutralized stale Planu guidance in: ${scan.healed.join(', ')}`);
+    }
+    if (scan.warnings.length > 0) {
+        collector.pushSkipped('legacy-guidance-warnings', `Left untouched (weak fingerprint, needs manual review): ${scan.warnings
+            .map((w) => w.file)
+            .join(', ')}`);
+    }
+}
+//# sourceMappingURL=legacy-guidance-scanner.js.map

package/dist/tools/init-project/portable-index-reconciler.d.ts

@@ -1,10 +1,29 @@
-import type { FilesystemImportDeps, FilesystemImportFailure, PortableIndexReconciliationResult, SkippedLegacyContract } from '../../types/index.js';
+import type { FilesystemImportDeps, FilesystemImportFailure, LegacyGuidanceScanResult, PortableIndexReconciliationResult, SkippedLegacyContract } from '../../types/index.js';
+import type { ToolResult } from '../../types/common/primitives.js';
 /** Autopilot-first summary of fatal reconciliation failures: what failed, why, and the next action. */
 export declare function describeReconciliationFailures(failures: FilesystemImportFailure[]): string;
 /** Autopilot-first summary of a successful reconciliation, including any legacy skips. */
 export declare function describeReconciliationSuccess(repositoryFilesChanged: string[], skippedLegacy: SkippedLegacyContract[], strayRepoRemovals?: string[]): string;
 /** Autopilot-first message for a reconciliation outcome, success or fatal-failure. */
 export declare function describeReconciliationOutcome(reconciliation: PortableIndexReconciliationResult, repositoryFilesChanged: string[]): string;
+/**
+ * SPEC-1716: Build the already-initialized `init_project` result, folding the
+ * legacy-guidance scan's healed paths into the reported repository file changes.
+ */
+export declare function buildAlreadyInitializedResult(projectId: string, reconciliation: PortableIndexReconciliationResult, legacyMigratedPaths: readonly string[], refreshedAssets: readonly string[], legacyGuidanceScan: LegacyGuidanceScanResult, projectPath: string): ToolResult;
+/** The subset of `MigrationRunResult` (migration-runner.ts) needed to report an authorized migration. */
+interface AuthorizedMigrationSummary {
+    criticalMigrationFailures: unknown[];
+    changedPaths?: string[];
+    migrationReportPath: string | null;
+}
+/**
+ * SPEC-1716: Build the authorized-migration `init_project` result, folding the
+ * legacy-guidance scan's healed paths into the reported repository file changes
+ * the same way the already-initialized fast path does.
+ */
+export declare function buildAuthorizedMigrationResult(projectId: string, projectPath: string, authorizedMigrations: readonly string[], migrationResult: AuthorizedMigrationSummary, legacyGuidanceScan: LegacyGuidanceScanResult): ToolResult;
 /** Rebuild the mutable external index from the repository-owned portable contracts. */
 export declare function reconcilePortableSpecIndex(projectPath: string, projectId: string, deps?: FilesystemImportDeps): Promise<PortableIndexReconciliationResult>;
+export {};
 //# sourceMappingURL=portable-index-reconciler.d.ts.map

package/dist/tools/init-project/portable-index-reconciler.js

@@ -156,6 +156,67 @@ export function describeReconciliationOutcome(reconciliation, repositoryFilesCha
         ? describeReconciliationSuccess(repositoryFilesChanged, reconciliation.skippedLegacy, reconciliation.strayRepoRemovals)
         : describeReconciliationFailures(reconciliation.failures);
 }
+/**
+ * SPEC-1716: Build the already-initialized `init_project` result, folding the
+ * legacy-guidance scan's healed paths into the reported repository file changes.
+ */
+export function buildAlreadyInitializedResult(projectId, reconciliation, legacyMigratedPaths, refreshedAssets, legacyGuidanceScan, projectPath) {
+    const repositoryFilesChanged = [...refreshedAssets, ...legacyGuidanceScan.healed];
+    const baseText = describeReconciliationOutcome(reconciliation, [...refreshedAssets]);
+    const healedGuidanceSuffix = legacyGuidanceScan.healed.length === 0
+        ? ''
+        : ` Healed stale legacy guidance in: ${legacyGuidanceScan.healed.join(', ')}.`;
+    return {
+        content: [{ type: 'text', text: baseText + healedGuidanceSuffix }],
+        structuredContent: {
+            projectId,
+            ...(reconciliation.failures.length === 0 ? { projectPath } : {}),
+            isUpdate: true,
+            repositoryFilesChanged,
+            authorizedMigrations: [],
+            importedSpecIds: reconciliation.importedSpecIds,
+            failures: reconciliation.failures,
+            skippedLegacy: reconciliation.skippedLegacy,
+            strayRepoRemovals: reconciliation.strayRepoRemovals,
+            migratedLegacyPaths: legacyMigratedPaths,
+            legacyGuidanceHealed: legacyGuidanceScan.healed,
+            legacyGuidanceWarnings: legacyGuidanceScan.warnings,
+        },
+        ...(reconciliation.failures.length > 0 ? { isError: true } : {}),
+    };
+}
+/**
+ * SPEC-1716: Build the authorized-migration `init_project` result, folding the
+ * legacy-guidance scan's healed paths into the reported repository file changes
+ * the same way the already-initialized fast path does.
+ */
+export function buildAuthorizedMigrationResult(projectId, projectPath, authorizedMigrations, migrationResult, legacyGuidanceScan) {
+    const hasCriticalFailures = migrationResult.criticalMigrationFailures.length > 0;
+    const healedGuidanceSuffix = legacyGuidanceScan.healed.length === 0
+        ? ''
+        : ` Healed stale legacy guidance in: ${legacyGuidanceScan.healed.join(', ')}.`;
+    const baseText = hasCriticalFailures
+        ? `Authorized migration completed with ${String(migrationResult.criticalMigrationFailures.length)} blocking issue(s).`
+        : 'Authorized planu-spec-format-v1 migration completed.';
+    return {
+        content: [{ type: 'text', text: baseText + healedGuidanceSuffix }],
+        structuredContent: {
+            projectId,
+            projectPath,
+            isUpdate: true,
+            authorizedMigrations,
+            repositoryFilesChanged: [
+                ...(migrationResult.changedPaths ?? []),
+                ...legacyGuidanceScan.healed,
+            ],
+            migrationReportPath: migrationResult.migrationReportPath,
+            criticalMigrationFailures: migrationResult.criticalMigrationFailures,
+            legacyGuidanceHealed: legacyGuidanceScan.healed,
+            legacyGuidanceWarnings: legacyGuidanceScan.warnings,
+        },
+        ...(hasCriticalFailures ? { isError: true } : {}),
+    };
+}
 /** Rebuild the mutable external index from the repository-owned portable contracts. */
 export async function reconcilePortableSpecIndex(projectPath, projectId, deps = {
     listSpecs: specStore.listSpecs,

package/dist/types/index.d.ts

@@ -278,6 +278,7 @@ export * from './reviewer-tokens.js';
 export * from './coach.js';
 export * from './tdd-strict.js';
 export * from './ssr-migration.js';
+export * from './legacy-guidance.js';
 export * from './workspace-overview.js';
 export * from './mcp-config.js';
 export * from './security/index.js';

package/dist/types/index.js

@@ -275,6 +275,7 @@ export * from './reviewer-tokens.js';
 export * from './coach.js';
 export * from './tdd-strict.js';
 export * from './ssr-migration.js';
+export * from './legacy-guidance.js';
 // SPEC-753: workspace_overview + reconcile_status_json types
 export * from './workspace-overview.js';
 // SPEC-756: MCP config auto-update types

package/dist/types/legacy-guidance.d.ts

@@ -0,0 +1,20 @@
+export interface LegacyGuidanceWarning {
+    file: string;
+    reason: string;
+}
+export interface LegacyGuidanceScanResult {
+    healed: string[];
+    warnings: LegacyGuidanceWarning[];
+}
+export interface LegacyGuidanceRegistry {
+    hostSurfaceFiles: string[];
+    hostSurfaceDirectories: {
+        dir: string;
+        extension: string;
+    }[];
+    legacyFilenameAllowlist: string[];
+    managedByMarkers: string[];
+    contradictoryPhrases: string[];
+    replacementGuidance: string;
+}
+//# sourceMappingURL=legacy-guidance.d.ts.map

package/dist/types/legacy-guidance.js

@@ -0,0 +1,3 @@
+// types/legacy-guidance.ts — SPEC-1716: stale Planu-installed guidance scanner
+export {};
+//# sourceMappingURL=legacy-guidance.js.map

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

@@ -82,6 +82,7 @@ export interface StrictPlanuCleanupResult {
     merged: string[];
     proposed: string[];
     gitignoreUpdated: boolean;
+    untracked: string[];
 }
 export interface StrictPlanuValidationResult {
     ok: boolean;

package/dist/types/ssr-migration.d.ts

@@ -1,7 +1,7 @@
 /** Result of folding technical.md into spec.md ## Technical section. */
 export interface FoldTechnicalResult {
     ok: boolean;
-    reason: 'already_unified' | 'no_technical_md' | 'ok' | 'error';
+    reason: 'already_unified' | 'no_technical_md' | 'ok' | 'error' | 'folded_residual';
     byteDelta?: number;
     error?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.7.3",
+  "version": "5.7.5",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "5.7.3",
+  "version": "5.7.5",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",