@planu/cli 4.13.0 → 4.14.1

package/dist/tools/init-project/claude-md-generator.js

@@ -1,7 +1,14 @@
+import { technologyValue } from '../../engine/technology-registry.js';
 function wrap(name, content) {
     return `<!-- planu:${name} -->\n${content}\n<!-- planu:${name} -->`;
 }
-const SERVERLESS_PLATFORMS = ['vercel', 'netlify', 'lambda', 'cloudflare-workers', 'deno-deploy'];
+const SERVERLESS_PLATFORMS = [
+    technologyValue('technology-vercel-9d3508'),
+    technologyValue('technology-netlify-58465a'),
+    'lambda',
+    'cloudflare-workers',
+    'deno-deploy',
+];
 function isServerlessPlatform(knowledge) {
     const services = knowledge.externalServices.map((s) => s.toLowerCase());
     const deployPlatform = (knowledge.conventions['deploy-platform'] ?? '').toLowerCase();
@@ -110,14 +117,14 @@ function buildArchitecture(knowledge) {
     return wrap('architecture', `## Architecture\n${items.join('\n')}`);
 }
 function detectTestFramework(testCommand) {
-    if (testCommand.includes('vitest')) {
-        return 'Vitest';
+    if (testCommand.includes(technologyValue('technology-vitest-a9127f'))) {
+        return technologyValue('technology-vitest-7fc39e');
     }
-    if (testCommand.includes('jest')) {
-        return 'Jest';
+    if (testCommand.includes(technologyValue('technology-jest-35e99f'))) {
+        return technologyValue('technology-jest-1f30f0');
     }
-    if (testCommand.includes('pytest')) {
-        return 'pytest';
+    if (testCommand.includes(technologyValue('technology-pytest-2b0121'))) {
+        return technologyValue('technology-pytest-2b0121');
     }
     if (testCommand.includes('go test')) {
         return 'go test';
@@ -165,9 +172,9 @@ function buildCiCd(knowledge) {
     return wrap('cicd', `## CI/CD\n- **Platform**: ${label}`);
 }
 const DEPLOY_PLATFORM_MAP = {
-    vercel: 'Vercel',
-    netlify: 'Netlify',
-    railway: 'Railway',
+    vercel: technologyValue('technology-vercel-68edc7'),
+    netlify: technologyValue('technology-netlify-55c13c'),
+    railway: technologyValue('technology-railway-3e12c4'),
     heroku: 'Heroku',
     'aws-lambda': 'AWS Lambda',
     'aws-ecs': 'AWS ECS',
@@ -176,8 +183,8 @@ const DEPLOY_PLATFORM_MAP = {
     fly: 'Fly.io',
     render: 'Render',
     cloudflare: 'Cloudflare Pages/Workers',
-    docker: 'Docker',
-    kubernetes: 'Kubernetes',
+    docker: technologyValue('technology-docker-e6169e'),
+    kubernetes: technologyValue('technology-kubernetes-a37d07'),
 };
 function buildDeployment(knowledge) {
     const fromConventions = knowledge.conventions['deploy-platform'] ?? null;

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

@@ -1,7 +1,11 @@
+import { technologyValue } from '../../engine/technology-registry.js';
 import { elicitOrFallback, questionsToFormSchema } from '../../engine/elicitation/elicit-helper.js';
 import { ti } from '../../i18n/index.js';
 import { AutopilotSummaryCollector } from '../../engine/autopilot/summary-collector.js';
-import { hashProjectPath, knowledgeStore, globalStore, licenseStore, technologySelectionStore, } from '../../storage/index.js';
+import { knowledgeStore, globalStore, licenseStore, technologySelectionStore, projectDataDir, } from '../../storage/index.js';
+import { migrateCanonicalStorage } from '../../storage/migrations/canonical-storage.js';
+import { deriveWorkspaceKey, ensureProjectIdentity } from '../../storage/project-identity.js';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
 import { addProject } from '../../storage/global-projects-store.js';
 import { getCurrentTier } from '../license-gate.js';
 import { checkLimits } from '../../engine/license-validator.js';
@@ -19,11 +23,12 @@ import { detectStackPatterns } from './stack-detector.js';
 import { buildProjectConfig } from './config-builder.js';
 import { runSpecMigrations, listProjectSpecs } from './migration-runner.js';
 import { runScaffoldWriter } from './scaffold-writer.js';
-import { detectAncestorDataDirs, buildAncestorDataWarning } from './ancestor-data-detector.js';
 import { readAutoInstallFlag, orchestrateSkillInstalls, runHealthCheckWithBaseline, runConventionScanSafe, fireTelemetry, } from './lifecycle-helpers.js';
 import { injectProactiveRules } from '../../engine/claude-md-injector/index.js';
 import { discoverSkillsForInit } from '../../engine/skill-bootstrap/registry-fetcher.js';
 import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
 import { mkdir, stat } from 'node:fs/promises';
 import { generateAgentTeamsRulesIfMissing, generateWorkflowRulesIfMissing, } from './rules-generator.js';
 import { installUniversalRules } from '../../engine/universal-rules/installer.js';
@@ -37,14 +42,27 @@ import { applyStackBasedGroupActivations } from './tool-group-activator.js';
 import { checkGate } from '../../engine/clarification-gate/gate.js';
 import { upsertToken, hashQuestions } from '../../engine/clarification-gate/token-store.js';
 import { reconcileInteractiveQuestionHooks } from '../reconcile-interactive-question-hooks.js';
+import { installSessionSafeguardHook } from '../reconcile-session-safeguard-hook.js';
 import { resolveNewProjectOnboarding } from '../../engine/onboarding/new-project-resolver.js';
 import { interactiveResult } from '../response-helpers.js';
 /** Frontend framework groups — mutually exclusive. Two or more detected → multi-stack conflict. */
 const FRONTEND_FRAMEWORK_GROUPS = [
-    ['react', 'next', 'next.js', 'nextjs', 'remix', 'preact'],
-    ['vue', 'nuxt', 'nuxt.js', 'nuxtjs'],
-    ['angular', 'angularjs'],
-    ['svelte', 'sveltekit'],
+    [
+        technologyValue('technology-react-275976'),
+        'next',
+        technologyValue('technology-next-js-0d857f'),
+        technologyValue('technology-nextjs-c93379'),
+        technologyValue('technology-remix-0c5d96'),
+        'preact',
+    ],
+    [
+        technologyValue('technology-vue-564382'),
+        technologyValue('technology-nuxt-22c407'),
+        'nuxt.js',
+        'nuxtjs',
+    ],
+    [technologyValue('technology-angular-a39f89'), 'angularjs'],
+    [technologyValue('technology-svelte-c190ac'), technologyValue('technology-sveltekit-eefb03')],
     ['solid', 'solidstart'],
     ['qwik'],
     ['ember'],
@@ -71,16 +89,6 @@ function detectMultipleFrameworks(stack) {
 }
 // eslint-disable-next-line max-lines-per-function
 export async function handleInitProject(params, server) {
-    // SPEC-584: Gate check — block if pending clarification token exists and no answers provided
-    const gateProjectId = hashProjectPath(params.projectPath);
-    const gateResult = await checkGate({
-        projectId: gateProjectId,
-        toolName: 'init_project',
-        clarificationAnswers: params.clarificationAnswers,
-    });
-    if (!gateResult.allow) {
-        return gateResult.error;
-    }
     // eslint-disable-next-line max-lines-per-function, complexity
     return trackCost(params.projectPath, 'init_project', async () => {
         const { projectPath, mode, locale, hourlyRate, experienceLevel, userProfile, autoInstallSkills, workMode, } = params;
@@ -137,42 +145,119 @@ export async function handleInitProject(params, server) {
                     };
                 }
             }
-            const projectId = hashProjectPath(projectPath);
-            // SPEC-1007: migrate legacy <cwd>/data/projects/{id} into ~/.planu/data/
-            // before any storage call so the rest of init_project sees a single
-            // canonical location. Best-effort — errors here are surfaced via the
-            // ancestor warning below rather than aborting the whole init.
-            try {
-                const { migrateLegacyDataDir } = await import('../../storage/migrations/cwd-to-absolute.js');
-                await migrateLegacyDataDir(projectId, projectPath);
-            }
-            catch {
-                // ignore — fall through to detectAncestorDataDirs which will warn.
+            // Legacy identities were the first 16 chars (and, briefly, all 64 chars)
+            // of the raw path hash. Derive them independently of project.json so a
+            // second init can still discover pre-cutover storage.
+            const legacyFullProjectId = createHash('sha256').update(projectPath).digest('hex');
+            const legacyProjectId = legacyFullProjectId.slice(0, 16);
+            const hadProjectIdentity = await stat(join(projectPath, 'planu', 'project.json'))
+                .then((identityStat) => identityStat.isFile())
+                .catch(() => false);
+            const identity = await ensureProjectIdentity(projectPath, {
+                workspaceKey: await deriveWorkspaceKey(projectPath),
+            });
+            const logicalProjectId = identity.project.logicalProjectId;
+            const projectId = /^[0-9a-f-]{36}$/i.test(logicalProjectId)
+                ? logicalProjectId.replaceAll('-', '').toLowerCase()
+                : logicalProjectId;
+            // The clarification gate is keyed by the portable identity. Creating the
+            // identity must happen first so init never falls back to a path-derived ID.
+            const gateResult = await checkGate({
+                projectId,
+                toolName: 'init_project',
+                clarificationAnswers: params.clarificationAnswers,
+            });
+            if (!gateResult.allow) {
+                return gateResult.error;
             }
-            // Detect divergent ancestor data dirs that would otherwise corrupt state
-            // silently (e.g. user ran init_project from /repo/ then from /repo/sub/).
-            // Read-only — we surface the finding but never touch existing data.
-            const ancestorReport = await detectAncestorDataDirs(projectPath, projectId);
-            const ancestorWarning = buildAncestorDataWarning(ancestorReport);
-            if (ancestorWarning !== null) {
-                console.warn(`[Planu] init_project: ${ancestorWarning}`);
+            // The only accepted legacy source is derived from the explicit projectPath.
+            // There is no CWD/ancestor discovery, so launching MCP elsewhere cannot
+            // select a different state tree.
+            const destinationRoot = projectDataDir(projectId);
+            const legacyRoots = [
+                join(projectPath, 'data', 'projects', legacyProjectId),
+                join(resolveStorageLayout().projects, legacyProjectId),
+                join(resolveStorageLayout().projects, legacyFullProjectId),
+                join(homedir(), '.planu', 'data', 'projects', legacyProjectId),
+                join(homedir(), '.planu', 'data', 'projects', legacyFullProjectId),
+            ].filter((root) => root !== destinationRoot);
+            const migration = await migrateCanonicalStorage({ legacyRoots, destinationRoot });
+            if (migration.status === 'error' || migration.status === 'rolled-back') {
+                return {
+                    content: [
+                        { type: 'text', text: migration.reason ?? 'Canonical storage migration failed.' },
+                    ],
+                    isError: true,
+                };
             }
             // Check if project is already initialized
             const existing = await knowledgeStore.getKnowledge(projectId);
-            const isUpdate = existing !== null;
-            // License: check project limit only for new projects
-            if (!isUpdate) {
-                const tier = await getCurrentTier();
-                const projectCount = await licenseStore.countActiveProjects();
-                const limitCheck = checkLimits(tier, projectCount, 'maxProjects');
-                if (!limitCheck.allowed) {
-                    return { content: [{ type: 'text', text: limitCheck.message }], isError: true };
+            const isUpdate = hadProjectIdentity || existing !== null;
+            const authorizedMigrations = params.authorizedMigrations ?? [];
+            if (isUpdate && authorizedMigrations.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Project already initialized. Safe update completed without changing repository files.',
+                        },
+                    ],
+                    structuredContent: {
+                        projectId,
+                        projectPath,
+                        isUpdate: true,
+                        repositoryFilesChanged: [],
+                        authorizedMigrations: [],
+                    },
+                };
+            }
+            if (isUpdate) {
+                if (existing === null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Repository migration requires recovered canonical project knowledge.',
+                            },
+                        ],
+                        isError: true,
+                    };
                 }
+                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 } : {}),
+                };
+            }
+            // The update branches returned above; only new projects reach the limit gate.
+            const tier = await getCurrentTier();
+            const projectCount = await licenseStore.countActiveProjects();
+            const limitCheck = checkLimits(tier, projectCount, 'maxProjects');
+            if (!limitCheck.allowed) {
+                return { content: [{ type: 'text', text: limitCheck.message }], isError: true };
             }
             // Get global config for defaults
             const globalConfig = await globalStore.getGlobalConfig();
-            const effectiveLocale = locale ?? existing?.locale ?? globalConfig.defaultLocale;
-            const effectiveExperience = experienceLevel ?? existing?.experienceLevel ?? globalConfig.defaultExperienceLevel;
+            const effectiveLocale = locale ?? globalConfig.defaultLocale;
+            const effectiveExperience = experienceLevel ?? globalConfig.defaultExperienceLevel;
             // Run full project analysis
             const knowledge = await analyzeProject(projectPath, projectId, effectiveLocale, effectiveExperience);
             if (approvedTechnologyContract !== null) {
@@ -219,15 +304,18 @@ export async function handleInitProject(params, server) {
                         interactiveQuestions: questions,
                     },
                 };
-                upsertToken({
-                    toolName: 'init_project',
-                    projectId,
-                    questionsHash: hashQuestions(questions),
-                    emittedAt: new Date().toISOString(),
-                    questions,
-                }).catch(() => {
+                try {
+                    await upsertToken({
+                        toolName: 'init_project',
+                        projectId,
+                        questionsHash: hashQuestions(questions),
+                        emittedAt: new Date().toISOString(),
+                        questions,
+                    });
+                }
+                catch {
                     /* best-effort */
-                });
+                }
                 return earlyReturn;
             }
             // SPEC-026a: Compute project completeness score
@@ -271,14 +359,16 @@ export async function handleInitProject(params, server) {
             const configResult = await buildProjectConfig(projectPath, projectId, knowledge, workMode);
             const { planuConfigPath, planuConfigGenerated, whatsNew } = configResult;
             // Run spec migrations (v0.30 -> v0.40, legacy paths, prefix normalization)
-            const { discoveryResult, migrationResult, folderMigrationResult, criticalMigrationFailures, nonCriticalWarnings: nonCriticalMigrationWarnings, migrationReportPath, } = await runSpecMigrations(projectPath, projectId, knowledge);
+            const { discoveryResult, migrationResult, folderMigrationResult, criticalMigrationFailures, nonCriticalWarnings: nonCriticalMigrationWarnings, migrationReportPath, changedPaths: migrationChangedPaths = [], } = await runSpecMigrations(projectPath, projectId, knowledge, {
+                repositoryMigration: 'initialization',
+            });
             // Auto-fetch recommended skills based on detected stack
             const recommendedSkills = await fetchRecommendedSkills(knowledge);
             // 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);
             // Write scaffold files: rules, git setup, constitution, CLAUDE.md, lint, architecture rules
-            const scaffoldResult = await runScaffoldWriter(projectPath, projectId, knowledge, recommendedSkills, params.permissionsMode, params.pluginsMode);
+            const scaffoldResult = await runScaffoldWriter(projectPath, projectId, knowledge, recommendedSkills, params.permissionsMode, params.pluginsMode, autoInstallFromConfig);
             const { platform, generatedRules, rulesWritten, additionalFilesWritten, hooksInstalled, gitFlowType, gitignoreUpdated, gitRepoDetected, constitutionInitialized, claudeMdUpdated, eslintCreated, prettierCreated, lintSuggestions, architectureRulesWritten, architectureRulesSkipped, planuWorkflowInjected, planuHooksConfigured, planuRulesWritten, gitAutoStageInjected, } = scaffoldResult;
             // SPEC-444: Inject proactive behavior rules into project CLAUDE.md
             const proactiveRulesInjected = await injectProactiveRules(join(projectPath, 'CLAUDE.md'), '1.22.0')
@@ -464,20 +554,19 @@ export async function handleInitProject(params, server) {
                 discoveredRegistrySkills,
                 branchInfo,
             });
+            if (toolResult.structuredContent) {
+                toolResult.structuredContent.repositoryFilesChanged = migrationChangedPaths;
+                toolResult.structuredContent.authorizedMigrations = authorizedMigrations;
+            }
             // Inject autopilotSummary into structuredContent
             if (collector.hasEntries() && toolResult.structuredContent) {
                 toolResult.structuredContent.autopilotSummary = collector.getMessages();
             }
-            // SPEC-584: Auto-install PostToolUse hook in the client project (fire-and-forget)
-            reconcileInteractiveQuestionHooks(projectPath).catch(() => {
-                /* best-effort — never block init_project */
-            });
-            // SPEC-585: Install PreCompaction session-safeguard hook (fire-and-forget)
-            import('../reconcile-session-safeguard-hook.js')
-                .then(({ installSessionSafeguardHook }) => installSessionSafeguardHook(projectPath))
-                .catch(() => {
-                /* best-effort — never block init_project */
-            });
+            // SPEC-584/585: These installers both mutate .claude/settings.json. Await them
+            // sequentially so init_project never returns while repository writes are pending.
+            // Failures remain best-effort and must not prevent project initialization.
+            await reconcileInteractiveQuestionHooks(projectPath).catch(() => undefined);
+            await installSessionSafeguardHook(projectPath).catch(() => undefined);
             // SPEC-595: If interactiveQuestions are present and client supports elicitation, use native UI
             const rawEmitted = toolResult.structuredContent?.interactiveQuestions;
             if (server !== undefined && Array.isArray(rawEmitted) && rawEmitted.length > 0) {
@@ -500,15 +589,18 @@ export async function handleInitProject(params, server) {
             // SPEC-584: Persist token when emitting interactiveQuestions so gate blocks retries
             if (Array.isArray(rawEmitted) && rawEmitted.length > 0) {
                 const emittedQuestions = rawEmitted;
-                upsertToken({
-                    toolName: 'init_project',
-                    projectId,
-                    questionsHash: hashQuestions(emittedQuestions),
-                    emittedAt: new Date().toISOString(),
-                    questions: emittedQuestions,
-                }).catch(() => {
-                    /* best-effort — token persistence should not block the response */
-                });
+                try {
+                    await upsertToken({
+                        toolName: 'init_project',
+                        projectId,
+                        questionsHash: hashQuestions(emittedQuestions),
+                        emittedAt: new Date().toISOString(),
+                        questions: emittedQuestions,
+                    });
+                }
+                catch {
+                    /* best-effort — token persistence should not fail the response */
+                }
             }
             // SPEC-756: lazy version check — fire-and-forget, non-blocking
             checkBundledVersionGap(2000)

package/dist/tools/init-project/host-assets-writer.d.ts

@@ -17,5 +17,5 @@ export interface InitHostAssetsResult {
  * host configs that should stay in sync too.
  */
 export declare function detectInitAssetHosts(projectPath: string): Promise<InitAssetHost[]>;
-export declare function installInitHostAssets(projectPath: string, _knowledge: ProjectKnowledge): Promise<InitHostAssetsResult>;
+export declare function installInitHostAssets(projectPath: string, _knowledge: ProjectKnowledge, installSkills?: boolean): Promise<InitHostAssetsResult>;
 //# sourceMappingURL=host-assets-writer.d.ts.map

package/dist/tools/init-project/host-assets-writer.js

@@ -153,7 +153,7 @@ async function scaffoldHostConfig(projectPath, host) {
     }
     return false;
 }
-export async function installInitHostAssets(projectPath, _knowledge) {
+export async function installInitHostAssets(projectPath, _knowledge, installSkills = true) {
     const detectedHosts = await detectInitAssetHosts(projectPath);
     const rulesInstalled = [];
     const skillsInstalled = [];
@@ -165,7 +165,9 @@ export async function installInitHostAssets(projectPath, _knowledge) {
             continue;
         }
         rulesInstalled.push(...(await installRulesForHost(projectPath, host)));
-        skillsInstalled.push(...(await installCoreSkillsForHost(projectPath, host)));
+        if (installSkills) {
+            skillsInstalled.push(...(await installCoreSkillsForHost(projectPath, host)));
+        }
     }
     return { detectedHosts, rulesInstalled, skillsInstalled, opencodeConfigured };
 }

package/dist/tools/init-project/lifecycle-helpers.js

@@ -3,7 +3,7 @@ import { autoInstallRecommendedSkills } from './skill-auto-installer.js';
 import { checkProjectHealth, } from '../../engine/project-health-checker.js';
 import { saveBaseline } from '../../storage/convention-baseline.js';
 import { scanProject } from '../../engine/project-scanner/index.js';
-import { isTelemetryEnabled, hasNeverBeenPrompted, markAsPrompted, getOrCreateInstallationId, sendTelemetryEvent, } from '../../engine/telemetry/index.js';
+import { isTelemetryEnabled, hasNeverBeenPrompted, markAsPrompted, sendTelemetryEvent, } from '../../engine/telemetry/index.js';
 import { generateProjectRules, writeRules } from '../../engine/rules-generator/index.js';
 import { getWhatsNew } from '../../engine/whats-new.js';
 import { PLANU_VERSION } from '../../config/version.js';
@@ -102,12 +102,11 @@ export function generateAndWriteRules(projectPath) {
     }
 }
 export async function fireTelemetry(knowledge) {
-    const [enabled, neverPrompted, installationId] = await Promise.all([
+    const [enabled, neverPrompted] = await Promise.all([
         isTelemetryEnabled().catch(() => false),
         hasNeverBeenPrompted().catch(() => false),
-        getOrCreateInstallationId().catch(() => ''),
     ]);
-    if (enabled && installationId) {
+    if (enabled) {
         sendTelemetryEvent({
             event: 'init_project',
             properties: {
@@ -118,7 +117,6 @@ export async function fireTelemetry(knowledge) {
                 nodeVersion: process.version,
                 specCount: knowledge.specCount ?? 0,
             },
-            installationId,
         });
     }
     if (neverPrompted) {

package/dist/tools/init-project/lint-scaffolder.js

@@ -1,3 +1,4 @@
+import { technologyValue } from '../../engine/technology-registry.js';
 import { readFile, writeFile, access } from 'node:fs/promises';
 import { join } from 'node:path';
 const ESLINT_CONFIG_FILES = [
@@ -72,7 +73,8 @@ function hasDevDep(packageJson, dep) {
 }
 function buildEslintConfig(framework) {
     const isNext = framework?.toLowerCase().includes('next') ?? false;
-    const isReact = !isNext && (framework?.toLowerCase().includes('react') ?? false);
+    const isReact = !isNext &&
+        (framework?.toLowerCase().includes(technologyValue('technology-react-275976')) ?? false);
     if (isNext) {
         return `import nextPlugin from '@next/eslint-plugin-next';
 import tseslint from 'typescript-eslint';
@@ -143,7 +145,9 @@ export async function scaffoldLintConfig(projectPath, knowledge) {
         suggestions: [],
     };
     const lang = knowledge.language.toLowerCase();
-    const isJsTs = lang === 'typescript' || lang === 'javascript' || lang === 'unknown';
+    const isJsTs = lang === technologyValue('technology-typescript-969545') ||
+        lang === 'javascript' ||
+        lang === 'unknown';
     if (!isJsTs) {
         // Python/Go/Rust — suggest language-specific linters, skip file generation
         if (lang === 'python') {

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

@@ -11,6 +11,10 @@ export interface MigrationRunResult {
         renamedCount: number;
         errors: string[];
     } | null;
+    filesystemImportResult: {
+        importedCount: number;
+        errors: string[];
+    } | null;
     migrationResult: {
         migratedCount: number;
         errors: string[];
@@ -22,6 +26,10 @@ export interface MigrationRunResult {
     criticalMigrationFailures: MigrationRunIssue[];
     nonCriticalWarnings: MigrationRunIssue[];
     migrationReportPath: string | null;
+    changedPaths?: string[];
+}
+interface SpecMigrationOptions {
+    repositoryMigration?: 'initialization' | 'planu-spec-format-v1';
 }
 /**
  * Run all spec migration passes during init_project:
@@ -30,7 +38,8 @@ export interface MigrationRunResult {
  * 3. Reconcile stale paths in specs.json
  * 4. Migrate spec folders without SPEC-XXX- prefix
  */
-export declare function runSpecMigrations(projectPath: string, projectId: string, knowledge: ProjectKnowledge): Promise<MigrationRunResult>;
+export declare function runSpecMigrations(projectPath: string, projectId: string, knowledge: ProjectKnowledge, options?: SpecMigrationOptions): Promise<MigrationRunResult>;
 /** Return all specs for the project (needed by caller for health check refs). */
 export declare function listProjectSpecs(projectId: string): Promise<Spec[]>;
+export {};
 //# sourceMappingURL=migration-runner.d.ts.map

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

@@ -1,7 +1,48 @@
 // tools/init-project/migration-runner.ts — Spec migration orchestration during init_project
 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 { filterLegacySpecs, migrateSpecs, filterUnprefixedSpecs, migrateSpecFolderNames, discoverAndFlattenSpecs, reconcileSpecPaths, migrateAllSpecsToLean, importFilesystemSpecs, } from '../../engine/spec-migrator.js';
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readdir, readlink } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+async function snapshotPlanuTree(projectPath) {
+    const root = join(projectPath, 'planu');
+    const snapshot = new Map();
+    const pending = [root];
+    try {
+        while (pending.length > 0) {
+            const directory = pending.pop();
+            if (directory === undefined) {
+                continue;
+            }
+            const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+            for (const entry of entries) {
+                const absolute = join(directory, entry.name);
+                const path = relative(projectPath, absolute).replaceAll('\\', '/');
+                if (entry.isDirectory()) {
+                    pending.push(absolute);
+                }
+                else if (entry.isSymbolicLink()) {
+                    snapshot.set(path, `link:${await readlink(absolute)}`);
+                }
+                else if ((await lstat(absolute)).isFile()) {
+                    snapshot.set(path, createHash('sha256')
+                        .update(await readFile(absolute))
+                        .digest('hex'));
+                }
+            }
+        }
+    }
+    catch {
+        // Test doubles and unreadable files degrade reporting, never migration safety.
+    }
+    return snapshot;
+}
+function changedPaths(before, after) {
+    return [...new Set([...before.keys(), ...after.keys()])]
+        .filter((path) => before.get(path) !== after.get(path))
+        .sort();
+}
 function issueFromError(phase, severity, err) {
     return {
         phase,
@@ -19,7 +60,9 @@ function issuesFromMessages(phase, severity, messages) {
  * 3. Reconcile stale paths in specs.json
  * 4. Migrate spec folders without SPEC-XXX- prefix
  */
-export async function runSpecMigrations(projectPath, projectId, knowledge) {
+export async function runSpecMigrations(projectPath, projectId, knowledge, options = {}) {
+    const before = await snapshotPlanuTree(projectPath);
+    const authorizedUpdate = options.repositoryMigration === 'planu-spec-format-v1';
     // Auto-discover and flatten specs in subcategory folders (v0.30 → v0.40 migration)
     let discoveryResult = null;
     const criticalMigrationFailures = [];
@@ -31,6 +74,16 @@ export async function runSpecMigrations(projectPath, projectId, knowledge) {
     catch (err) {
         criticalMigrationFailures.push(issueFromError('discover-and-flatten-specs', 'critical', err));
     }
+    // Rebuild missing mutable index records from the portable Git contract.
+    // This is required after a storage-root migration or a clean-machine import.
+    let filesystemImportResult = null;
+    try {
+        filesystemImportResult = await importFilesystemSpecs(projectPath, { listSpecs: specStore.listSpecs, createSpec: specStore.createSpec }, projectId);
+        criticalMigrationFailures.push(...issuesFromMessages('filesystem-spec-import', 'critical', filesystemImportResult.errors));
+    }
+    catch (err) {
+        criticalMigrationFailures.push(issueFromError('filesystem-spec-import', 'critical', err));
+    }
     // Auto-migrate legacy specs if detected (docs/sdd/specs/ → planu/specs/)
     let allSpecs = [];
     try {
@@ -41,7 +94,14 @@ export async function runSpecMigrations(projectPath, projectId, knowledge) {
     }
     const legacySpecs = filterLegacySpecs(allSpecs);
     let migrationResult = null;
-    if (legacySpecs.length > 0) {
+    if (legacySpecs.length > 0 && authorizedUpdate) {
+        criticalMigrationFailures.push({
+            phase: 'legacy-spec-migration',
+            severity: 'critical',
+            message: 'planu-spec-format-v1 is confined to planu/ and cannot migrate legacy docs/sdd paths.',
+        });
+    }
+    else if (legacySpecs.length > 0) {
         try {
             migrationResult = await migrateSpecs(projectPath, legacySpecs, {
                 listSpecs: specStore.listSpecs,
@@ -110,6 +170,7 @@ export async function runSpecMigrations(projectPath, projectId, knowledge) {
     catch (err) {
         criticalMigrationFailures.push(issueFromError('strict-planu-cleanup', 'critical', err));
     }
+    const repositoryFilesChanged = changedPaths(before, await snapshotPlanuTree(projectPath));
     let migrationReportPath = null;
     try {
         const reportPath = `${projectDataDir(projectId)}/reports/init-migrations/latest.json`;
@@ -118,10 +179,12 @@ export async function runSpecMigrations(projectPath, projectId, knowledge) {
             projectId,
             generatedAt: new Date().toISOString(),
             discoveryResult,
+            filesystemImportResult,
             migrationResult,
             folderMigrationResult,
             criticalMigrationFailures,
             nonCriticalWarnings,
+            changedPaths: repositoryFilesChanged,
         });
         migrationReportPath = reportPath;
     }
@@ -130,11 +193,13 @@ export async function runSpecMigrations(projectPath, projectId, knowledge) {
     }
     return {
         discoveryResult,
+        filesystemImportResult,
         migrationResult,
         folderMigrationResult,
         criticalMigrationFailures,
         nonCriticalWarnings,
         migrationReportPath,
+        changedPaths: repositoryFilesChanged,
     };
 }
 /** Return all specs for the project (needed by caller for health check refs). */