@planu/cli 4.1.4 → 4.2.1

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [4.2.1] - 2026-05-21
+
+**Tarball SHA-256:** `9ff8a396e25eba3e4941bbef80ee19cc41bae46eaafa703cd32092c7ffbfdf2e`
+
+### Bug Fixes
+- fix(release): add windows native core packages
+
+
+## [4.2.0] - 2026-05-21
+
+**Tarball SHA-256:** `d036f3d5f73279fc0a12935995f899950fdf06afe454bba49da748183e07f477`
+
+### Features
+- feat(onboarding): add new project technology contract
+
+### Bug Fixes
+- fix(release): sync native package versions
+
+
 ## [4.1.4] - 2026-05-21
 
 ### Bug Fixes
@@ -3845,4 +3864,4 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 - Mermaid diagram generation (architecture, sequence, state machine, ER, data flow)
 - Multi-language i18n (EN/ES/PT) for generated specs
 - Clean Architecture (hexagonal) — engine, tools, storage, types layers
-- 10,857 tests with ≥95% coverage
+- 10,857 tests with ≥95% coverage

package/dist/engine/onboarding/new-project-resolver.d.ts

@@ -0,0 +1,7 @@
+import type { InteractiveQuestion, NewProjectOnboardingInput, NewProjectQuestionState, NewProjectResolution } from '../../types/index.js';
+export declare function slugifyAppName(input: string): string;
+export declare function validateAppSlug(slug: string): string | null;
+export declare function resolveNewProjectPath(parentWorkspacePath: string, appSlug: string): string;
+export declare function buildNewProjectQuestions(input: NewProjectOnboardingInput, resolved: NewProjectQuestionState): InteractiveQuestion[];
+export declare function resolveNewProjectOnboarding(input: NewProjectOnboardingInput): Promise<NewProjectResolution>;
+//# sourceMappingURL=new-project-resolver.d.ts.map

package/dist/engine/onboarding/new-project-resolver.js

@@ -0,0 +1,265 @@
+// engine/onboarding/new-project-resolver.ts — SPEC-1021 safe new-project onboarding
+import { mkdir } from 'node:fs/promises';
+import path, { resolve } from 'node:path';
+import { findDocsEntry, loadDocsRegistry } from '../web-fetcher/registry-loader.js';
+const NONE_LABELS = new Set(['none', 'no framework', 'ninguno', 'sin framework', 'n/a']);
+const UNSURE_LABELS = new Set(['not sure', 'unsure', 'no estoy seguro', 'not-sure']);
+function answer(input, key) {
+    const value = input.clarificationAnswers?.[key] ?? input.clarificationAnswers?.[key.toLowerCase()];
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function valueOrAnswer(explicit, input, key) {
+    if (typeof explicit === 'string' && explicit.trim().length > 0) {
+        return explicit.trim();
+    }
+    return answer(input, key);
+}
+function normalizeNullableTech(value) {
+    if (value === null) {
+        return null;
+    }
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const lower = trimmed.toLowerCase();
+    if (NONE_LABELS.has(lower)) {
+        return null;
+    }
+    if (UNSURE_LABELS.has(lower)) {
+        return undefined;
+    }
+    return trimmed;
+}
+export function slugifyAppName(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/[-.]{2,}/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '');
+}
+export function validateAppSlug(slug) {
+    if (!slug) {
+        return 'App folder is required.';
+    }
+    if (slug === '.' || slug === '..' || slug.includes('/') || slug.includes('\\')) {
+        return 'App folder must be a simple folder name, not a path.';
+    }
+    if (slug.includes('..')) {
+        return 'App folder cannot contain path traversal.';
+    }
+    return null;
+}
+function isWinPath(value) {
+    return /^[a-zA-Z]:[\\/]/.test(value) || value.startsWith('\\\\');
+}
+export function resolveNewProjectPath(parentWorkspacePath, appSlug) {
+    const slugError = validateAppSlug(appSlug);
+    if (slugError) {
+        throw new Error(slugError);
+    }
+    if (isWinPath(parentWorkspacePath)) {
+        return path.win32.normalize(path.win32.join(parentWorkspacePath, appSlug));
+    }
+    return resolve(parentWorkspacePath, appSlug);
+}
+function buildQuestion(header, question, recommended, alternate, fallback) {
+    return {
+        header,
+        question,
+        multiSelect: false,
+        options: [
+            { label: `${recommended} (Recommended)`, description: `Use "${recommended}".` },
+            { label: alternate, description: `Use "${alternate}".` },
+            { label: fallback, description: `Use "${fallback}" or provide another value.` },
+        ],
+    };
+}
+function buildRequiredQuestions(input, resolved) {
+    const suggestedSlug = slugifyAppName(input.appName ?? input.description).slice(0, 48) || 'new-app';
+    const specs = [
+        [
+            !resolved.parentWorkspacePath,
+            buildQuestion('Parent', 'Which parent workspace should contain the new app folder?', process.cwd(), input.projectPath ?? './', 'Custom path'),
+        ],
+        [
+            !resolved.appSlug,
+            buildQuestion('App Folder', 'What should the new app folder be called?', suggestedSlug, 'api', 'Custom folder'),
+        ],
+        [
+            !resolved.projectType,
+            buildQuestion('Project Type', 'What type of project are you creating?', 'api', 'web app', 'Custom type'),
+        ],
+        [
+            !resolved.platform,
+            buildQuestion('Platform', 'Where will this project run?', 'server', 'web', 'Custom platform'),
+        ],
+        [
+            !resolved.languageAnswered,
+            buildQuestion('Language', 'Which programming language should this project use?', 'Not sure', 'Use project/team default', 'Custom language'),
+        ],
+        [
+            !resolved.frameworkAnswered,
+            buildQuestion('Framework', 'Which framework should this project use?', 'Not sure', 'No framework', 'Custom framework'),
+        ],
+    ];
+    return specs.filter(([missing]) => missing).map(([, question]) => question);
+}
+function buildCreateDirectoryQuestion() {
+    return {
+        header: 'Create Dir',
+        question: 'May Planu create the project folder if it does not exist?',
+        multiSelect: false,
+        options: [
+            { label: 'yes (Recommended)', description: 'Create only the resolved app folder.' },
+            { label: 'no', description: 'Do not create folders; I will create it myself.' },
+            { label: 'already exists', description: 'The project folder already exists.' },
+        ],
+    };
+}
+export function buildNewProjectQuestions(input, resolved) {
+    const questions = buildRequiredQuestions(input, resolved);
+    if (!resolved.createDirectoryAnswered) {
+        questions.push(buildCreateDirectoryQuestion());
+    }
+    return questions;
+}
+async function verifyDocs(names) {
+    const registry = await loadDocsRegistry();
+    return names
+        .filter((name) => name.trim().length > 0)
+        .map((name) => {
+        const entry = findDocsEntry(name, registry);
+        if (entry) {
+            return { name, url: entry.base, status: 'verified' };
+        }
+        return {
+            name,
+            url: '',
+            status: 'unverified',
+            reason: 'No official docs registry entry found.',
+        };
+    });
+}
+function collectResolvedFields(input) {
+    const parentWorkspacePath = valueOrAnswer(input.parentWorkspacePath, input, 'Parent') ??
+        valueOrAnswer(input.projectPath, input, 'Parent');
+    const appName = valueOrAnswer(input.appName, input, 'App Folder');
+    const appSlug = valueOrAnswer(input.appSlug, input, 'App Folder') ??
+        (appName ? slugifyAppName(appName) : undefined);
+    const projectType = valueOrAnswer(input.projectType, input, 'Project Type');
+    const platform = valueOrAnswer(input.platform, input, 'Platform');
+    const rawLanguage = valueOrAnswer(input.language, input, 'Language');
+    const rawFramework = input.framework === null ? null : valueOrAnswer(input.framework, input, 'Framework');
+    const rawDatabase = input.database === null ? null : valueOrAnswer(input.database, input, 'Database');
+    const language = normalizeNullableTech(rawLanguage);
+    const framework = normalizeNullableTech(rawFramework);
+    const database = normalizeNullableTech(rawDatabase);
+    const createDirAnswer = answer(input, 'Create Dir')?.toLowerCase();
+    const languageAnswered = rawLanguage !== undefined;
+    const frameworkAnswered = rawFramework !== undefined;
+    const createDirectoryAnswered = input.createDirectory !== undefined || createDirAnswer !== undefined;
+    const createDirectory = input.createDirectory === true ||
+        createDirAnswer === 'yes' ||
+        createDirAnswer === 'yes (recommended)' ||
+        createDirAnswer === 'already exists';
+    const errors = appSlug ? [validateAppSlug(appSlug)].filter((e) => Boolean(e)) : [];
+    const resolvedProjectPath = parentWorkspacePath && appSlug && errors.length === 0
+        ? resolveNewProjectPath(parentWorkspacePath, appSlug)
+        : undefined;
+    return {
+        parentWorkspacePath,
+        appName,
+        appSlug,
+        projectType,
+        platform,
+        language: language ?? undefined,
+        framework,
+        database,
+        languageAnswered,
+        frameworkAnswered,
+        createDirectoryAnswered,
+        createDirectory,
+        resolvedProjectPath,
+        errors,
+    };
+}
+function isReady(fields) {
+    return Boolean(fields.parentWorkspacePath &&
+        fields.appSlug &&
+        fields.projectType &&
+        fields.platform &&
+        fields.languageAnswered &&
+        fields.frameworkAnswered &&
+        fields.createDirectoryAnswered &&
+        fields.createDirectory &&
+        fields.resolvedProjectPath &&
+        fields.errors.length === 0);
+}
+async function buildTechnologyContract(input, fields) {
+    const resolvedProjectPath = fields.resolvedProjectPath;
+    if (!resolvedProjectPath) {
+        throw new Error('Resolved project path is required to build a technology contract.');
+    }
+    const docNames = [fields.language, fields.framework, fields.database].filter((name) => typeof name === 'string' && name.length > 0);
+    const officialDocs = await verifyDocs(docNames);
+    return {
+        mode: 'new_project',
+        projectPath: resolvedProjectPath,
+        parentWorkspacePath: fields.parentWorkspacePath,
+        appName: fields.appName,
+        appSlug: fields.appSlug,
+        projectType: fields.projectType,
+        platform: fields.platform,
+        language: fields.language,
+        framework: fields.framework ?? null,
+        database: fields.database ?? null,
+        source: 'user-confirmed',
+        evidence: [
+            `User requested a new project: ${input.description}`,
+            `Resolved project folder: ${resolvedProjectPath}`,
+        ],
+        officialDocs,
+        verifiedAt: new Date().toISOString(),
+    };
+}
+export async function resolveNewProjectOnboarding(input) {
+    const fields = collectResolvedFields(input);
+    if (!isReady(fields)) {
+        return {
+            ready: false,
+            parentWorkspacePath: fields.parentWorkspacePath,
+            resolvedProjectPath: fields.resolvedProjectPath,
+            appSlug: fields.appSlug,
+            questions: buildNewProjectQuestions(input, {
+                parentWorkspacePath: fields.parentWorkspacePath,
+                appSlug: fields.appSlug,
+                projectType: fields.projectType,
+                platform: fields.platform,
+                language: fields.language,
+                framework: fields.framework,
+                languageAnswered: fields.languageAnswered,
+                frameworkAnswered: fields.frameworkAnswered,
+                createDirectoryAnswered: fields.createDirectoryAnswered,
+            }),
+            errors: fields.errors,
+        };
+    }
+    const resolvedProjectPath = fields.resolvedProjectPath;
+    if (!resolvedProjectPath) {
+        throw new Error('Resolved project path is required before directory creation.');
+    }
+    await mkdir(resolvedProjectPath, { recursive: true });
+    const contract = await buildTechnologyContract(input, fields);
+    return {
+        ready: true,
+        parentWorkspacePath: fields.parentWorkspacePath,
+        resolvedProjectPath: fields.resolvedProjectPath,
+        appSlug: fields.appSlug,
+        questions: [],
+        contract,
+        errors: fields.errors,
+    };
+}
+//# sourceMappingURL=new-project-resolver.js.map

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

@@ -171,7 +171,8 @@ export async function validateStrictPlanuLayout(projectPath) {
     for (const entry of entries) {
         const full = join(planuDir, entry);
         const isDir = await pathIsDirectory(full);
-        if ((isDir && !isCanonicalPlanuRootDir(entry)) || (!isDir && !isCanonicalPlanuRootFile(entry))) {
+        if ((isDir && !isCanonicalPlanuRootDir(entry)) ||
+            (!isDir && !isCanonicalPlanuRootFile(entry))) {
             offenders.push(relative(projectPath, full));
         }
     }

package/dist/storage/index.d.ts

@@ -19,5 +19,6 @@ export * as conventionBaselineStore from './convention-baseline.js';
 export * as lessonsStore from './lessons-store.js';
 export * as actualsStore from './actuals-store.js';
 export * as approvalStore from './approval-store.js';
+export * as technologySelectionStore from './technology-selection-store.js';
 export * from './skill-registry-storage.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/storage/index.js

@@ -20,5 +20,6 @@ export * as conventionBaselineStore from './convention-baseline.js';
 export * as lessonsStore from './lessons-store.js';
 export * as actualsStore from './actuals-store.js';
 export * as approvalStore from './approval-store.js';
+export * as technologySelectionStore from './technology-selection-store.js';
 export * from './skill-registry-storage.js';
 //# sourceMappingURL=index.js.map

package/dist/storage/technology-selection-store.d.ts

@@ -0,0 +1,5 @@
+import type { TechnologySelectionContract } from '../types/index.js';
+export declare const TECHNOLOGY_SELECTION_RELATIVE_PATH = ".planu/technology-selection.json";
+export declare function readTechnologySelectionContract(projectPath: string): Promise<TechnologySelectionContract | null>;
+export declare function writeTechnologySelectionContract(projectPath: string, contract: TechnologySelectionContract): Promise<void>;
+//# sourceMappingURL=technology-selection-store.d.ts.map

package/dist/storage/technology-selection-store.js

@@ -0,0 +1,42 @@
+// storage/technology-selection-store.ts — SPEC-1021 project-local technology contract
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { writeJsonSafe } from '../engine/safety/atomic-writer.js';
+import { safeJsonParse } from './base-store.js';
+import { withFileLock } from './file-mutex.js';
+export const TECHNOLOGY_SELECTION_RELATIVE_PATH = '.planu/technology-selection.json';
+function contractPath(projectPath) {
+    return join(projectPath, TECHNOLOGY_SELECTION_RELATIVE_PATH);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function isTechnologySelectionContract(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const rec = value;
+    return ((rec.mode === 'existing_project' || rec.mode === 'new_project') &&
+        typeof rec.projectPath === 'string' &&
+        (rec.source === 'detected' ||
+            rec.source === 'user-confirmed' ||
+            rec.source === 'suggested-confirmed') &&
+        isStringArray(rec.evidence) &&
+        Array.isArray(rec.officialDocs));
+}
+export async function readTechnologySelectionContract(projectPath) {
+    try {
+        const raw = await readFile(contractPath(projectPath), 'utf-8');
+        const parsed = safeJsonParse(raw, null);
+        return isTechnologySelectionContract(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeTechnologySelectionContract(projectPath, contract) {
+    const filePath = contractPath(projectPath);
+    await mkdir(dirname(filePath), { recursive: true });
+    await withFileLock(filePath, () => writeJsonSafe(filePath, contract));
+}
+//# sourceMappingURL=technology-selection-store.js.map

package/dist/tools/create-spec.js

@@ -2,6 +2,7 @@ import { checkGate } from '../engine/clarification-gate/gate.js';
 import { upsertToken, hashQuestions } from '../engine/clarification-gate/token-store.js';
 import { ti } from '../i18n/index.js';
 import { knowledgeStore, specStore } from '../storage/index.js';
+import { readTechnologySelectionContract } from '../storage/technology-selection-store.js';
 import { formatSuccess, addNextSteps, toolResult, interactiveResult } from './response-helpers.js';
 import { writeFile, mkdir, rm, readFile, stat } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
@@ -515,17 +516,36 @@ export async function handleCreateSpec(inputParams, server) {
                 await measureStep('mkdir-specDir', () => mkdir(specDir, { recursive: true }));
                 // SPEC-586: Filter suggested criteria by spec tags/target/scope before injection
                 const filteredCriteria = await filterCriteriaByTags(autopilot.suggestedCriteria, spec.tags, spec.target, spec.scope).catch(() => autopilot.suggestedCriteria);
+                const technologyContract = await readTechnologySelectionContract(params.projectPath ?? '');
+                const contractNote = technologyContract
+                    ? [
+                        '',
+                        'Technology Contract:',
+                        `- Mode: ${technologyContract.mode}`,
+                        technologyContract.language ? `- Language: ${technologyContract.language}` : '',
+                        technologyContract.framework
+                            ? `- Framework: ${technologyContract.framework}`
+                            : '- Framework: none or not selected',
+                        technologyContract.platform ? `- Platform: ${technologyContract.platform}` : '',
+                        technologyContract.projectType
+                            ? `- Project type: ${technologyContract.projectType}`
+                            : '',
+                        '- Agents must not choose a different stack unless the user approves a new contract.',
+                    ]
+                        .filter(Boolean)
+                        .join('\n')
+                    : '';
                 const specGenerator = new FallbackGenerator();
                 const generatedSpec = await measureStep('generateSpecBody', () => specGenerator.generate({
                     title: spec.title,
-                    description,
+                    description: `${description}${contractNote}`,
                     type: spec.type,
                     scope: spec.scope,
                     target: spec.target,
                     acFormat: params.acFormat,
                     projectContext: {
-                        language: knowledge?.language ?? undefined,
-                        framework: knowledge?.framework ?? undefined,
+                        language: technologyContract?.language ?? knowledge?.language ?? undefined,
+                        framework: technologyContract?.framework ?? knowledge?.framework ?? undefined,
                         architecture: knowledge?.architecture.primary ?? undefined,
                     },
                 }));

package/dist/tools/facilitate.js

@@ -7,6 +7,8 @@ import { loadContext } from '../engine/facilitate/context-loader.js';
 import { route } from '../engine/facilitate/router.js';
 import { parsePlanContent } from '../engine/facilitate/plan-parser.js';
 import { compactJson, compactResult, compactError } from './output-formatter.js';
+import { interactiveResult } from './response-helpers.js';
+import { resolveNewProjectOnboarding } from '../engine/onboarding/new-project-resolver.js';
 // ---------------------------------------------------------------------------
 // Scenario detection (SPEC-037 legacy — kept for backward compatibility)
 // ---------------------------------------------------------------------------
@@ -31,29 +33,6 @@ function detectScenario(description) {
     return 'new_project';
 }
 // ---------------------------------------------------------------------------
-// Step questions for new_project scenario
-// ---------------------------------------------------------------------------
-const NEW_PROJECT_STEPS = [
-    'What is the main purpose of your app? What problem does it solve and for whom?',
-    'What platform will it run on? (web app, mobile iOS/Android, REST API, desktop app, CLI tool)',
-    'Do you have a preferred tech stack? (language, framework, database — skip if unsure)',
-];
-function buildNewProjectResponse(step, collectedInfo) {
-    if (step < NEW_PROJECT_STEPS.length) {
-        const question = NEW_PROJECT_STEPS[step] ?? NEW_PROJECT_STEPS[0];
-        const intro = step === 0
-            ? "Welcome to Planu! I'll guide you with a few questions to generate a precise spec.\n\n"
-            : `Got it! ${Object.values(collectedInfo).join(', ')}\n\n`;
-        return `${intro}Step ${step + 1}/3: ${question}`;
-    }
-    const info = Object.values(collectedInfo).join(' | ');
-    return (`Great — I have enough context to generate your spec.\n\n` +
-        `Summary: ${info}\n\n` +
-        `Next step: Call \`create_spec\` with this description:\n` +
-        `"${Object.values(collectedInfo).join('. ')}."\n\n` +
-        `Or call \`clarify_requirements\` first for deeper requirement analysis.`);
-}
-// ---------------------------------------------------------------------------
 // Existing project scenario
 // ---------------------------------------------------------------------------
 function buildExistingProjectResponse(description) {
@@ -206,7 +185,7 @@ async function runSmartOrchestrator(description, projectId, planContent) {
 // Main handler
 // ---------------------------------------------------------------------------
 export async function handleFacilitate(params, server) {
-    const { description, projectId, sessionId, scenario: explicitScenario, collectedInfo = {}, step = 0, targetTool, checkFocus = false, changeFocus, paradigmReport, planContent, } = params;
+    const { description, projectId, sessionId, scenario: explicitScenario, step = 0, targetTool, checkFocus = false, changeFocus, paradigmReport, planContent, } = params;
     const sessionKey = sessionId ?? projectId ?? 'default';
     // SPEC-264: When planContent provided OR no explicit scenario/control params given,
     // use the smart orchestrator path.
@@ -355,11 +334,42 @@ export async function handleFacilitate(params, server) {
         let guidance;
         switch (scenario) {
             case 'new_project': {
-                const updatedInfo = step === 0
-                    ? { ...collectedInfo, step0: description }
-                    : { ...collectedInfo, [`step${step}`]: description };
-                guidance = buildNewProjectResponse(step, updatedInfo);
-                break;
+                const resolution = await resolveNewProjectOnboarding({
+                    description,
+                    parentWorkspacePath: params.parentWorkspacePath,
+                    projectPath: params.projectId,
+                    appName: params.appName,
+                    appSlug: params.appSlug,
+                    projectType: params.projectType,
+                    platform: params.platform,
+                    language: params.language,
+                    framework: params.framework,
+                    database: params.database,
+                    createDirectory: params.createDirectory,
+                    clarificationAnswers: params.clarificationAnswers,
+                });
+                if (!resolution.ready) {
+                    const response = interactiveResult(resolution.questions, 'New project onboarding needs a target app folder and technology choices before Planu can initialize anything. Do not call init_project on the parent workspace yet.', 'universal');
+                    response.structuredContent = {
+                        ...response.structuredContent,
+                        mode: 'new_project',
+                        parentWorkspacePath: resolution.parentWorkspacePath,
+                        resolvedProjectPath: resolution.resolvedProjectPath,
+                        appSlug: resolution.appSlug,
+                        errors: resolution.errors,
+                        nextAction: 'Ask the user these questions, then call facilitate again with clarificationAnswers or explicit fields. Only call init_project with the resolved child projectPath.',
+                    };
+                    return response;
+                }
+                return ok({
+                    action: 'facilitate',
+                    scenario,
+                    mode: 'new_project',
+                    readyToInitialize: true,
+                    resolvedProjectPath: resolution.resolvedProjectPath,
+                    technologySelectionContract: resolution.contract,
+                    nextAction: 'Call init_project with mode="new_project", projectPath set to resolvedProjectPath, createDirectory=true, and technologySelectionContract from this response.',
+                });
             }
             case 'existing_project':
                 guidance = buildExistingProjectResponse(description);

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

@@ -1,7 +1,7 @@
 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 } from '../../storage/index.js';
+import { hashProjectPath, knowledgeStore, globalStore, licenseStore, technologySelectionStore, } from '../../storage/index.js';
 import { addProject } from '../../storage/global-projects-store.js';
 import { getCurrentTier } from '../license-gate.js';
 import { checkLimits } from '../../engine/license-validator.js';
@@ -24,7 +24,7 @@ import { readAutoInstallFlag, orchestrateSkillInstalls, runHealthCheckWithBaseli
 import { injectProactiveRules } from '../../engine/claude-md-injector/index.js';
 import { discoverSkillsForInit } from '../../engine/skill-bootstrap/registry-fetcher.js';
 import { join } from 'node:path';
-import { stat } from 'node:fs/promises';
+import { mkdir, stat } from 'node:fs/promises';
 import { generateAgentTeamsRulesIfMissing, generateWorkflowRulesIfMissing, } from './rules-generator.js';
 import { installUniversalRules } from '../../engine/universal-rules/installer.js';
 import { detectHost } from '../../engine/host-detection/detect-host.js';
@@ -37,6 +37,8 @@ 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 { 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'],
@@ -81,8 +83,29 @@ export async function handleInitProject(params, server) {
     }
     // eslint-disable-next-line max-lines-per-function, complexity
     return trackCost(params.projectPath, 'init_project', async () => {
-        const { projectPath, locale, hourlyRate, experienceLevel, userProfile, autoInstallSkills, workMode, } = params;
+        const { projectPath, mode, locale, hourlyRate, experienceLevel, userProfile, autoInstallSkills, workMode, } = params;
         try {
+            let approvedTechnologyContract = params.technologySelectionContract ?? null;
+            if (mode === 'new_project' && approvedTechnologyContract === null) {
+                const resolution = await resolveNewProjectOnboarding({
+                    description: params.appName ?? params.projectType ?? 'New project',
+                    parentWorkspacePath: params.parentWorkspacePath,
+                    projectPath,
+                    appName: params.appName,
+                    appSlug: params.appSlug,
+                    projectType: params.projectType,
+                    platform: params.platform,
+                    language: params.language,
+                    framework: params.framework,
+                    database: params.database,
+                    createDirectory: params.createDirectory,
+                    clarificationAnswers: params.clarificationAnswers,
+                });
+                if (!resolution.ready) {
+                    return interactiveResult(resolution.questions, 'init_project new_project mode needs a confirmed child app folder and technology choices before writing project files.', 'universal');
+                }
+                approvedTechnologyContract = resolution.contract ?? null;
+            }
             // Validate projectPath exists and is a directory before any I/O
             try {
                 const pathStat = await stat(projectPath);
@@ -99,15 +122,20 @@ export async function handleInitProject(params, server) {
                 }
             }
             catch {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Project directory does not exist: "${projectPath}". Create the directory first and try again.`,
-                        },
-                    ],
-                    isError: true,
-                };
+                if (mode === 'new_project' && params.createDirectory === true) {
+                    await mkdir(projectPath, { recursive: true });
+                }
+                else {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Project directory does not exist: "${projectPath}". Create the directory first and try again.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
             }
             const projectId = hashProjectPath(projectPath);
             // SPEC-1007: migrate legacy <cwd>/data/projects/{id} into ~/.planu/data/
@@ -147,6 +175,19 @@ export async function handleInitProject(params, server) {
             const effectiveExperience = experienceLevel ?? existing?.experienceLevel ?? globalConfig.defaultExperienceLevel;
             // Run full project analysis
             const knowledge = await analyzeProject(projectPath, projectId, effectiveLocale, effectiveExperience);
+            if (approvedTechnologyContract !== null) {
+                knowledge.language = approvedTechnologyContract.language ?? knowledge.language;
+                knowledge.framework =
+                    approvedTechnologyContract.framework !== undefined
+                        ? approvedTechnologyContract.framework
+                        : knowledge.framework;
+                const stackAdditions = [
+                    approvedTechnologyContract.language,
+                    approvedTechnologyContract.framework ?? undefined,
+                    approvedTechnologyContract.database ?? undefined,
+                ].filter((item) => typeof item === 'string' && item.length > 0);
+                knowledge.stack = Array.from(new Set([...knowledge.stack, ...stackAdditions]));
+            }
             // Apply overrides
             if (userProfile) {
                 knowledge.userProfile = userProfile;
@@ -214,6 +255,12 @@ export async function handleInitProject(params, server) {
             }
             // Save initial project knowledge
             await knowledgeStore.saveKnowledge(projectId, knowledge);
+            if (approvedTechnologyContract !== null) {
+                await technologySelectionStore.writeTechnologySelectionContract(projectPath, {
+                    ...approvedTechnologyContract,
+                    projectPath,
+                });
+            }
             // SPEC-789: Register project in global workspace registry so workspace_health
             // and list_registered_projects can discover it without manual registration.
             addProject(projectPath).catch(() => {

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

@@ -18,6 +18,34 @@ import { handleTypeSafetyGate } from '../type-safety-gate.js';
 /** init_project inputSchema — extracted to keep registerCoreSpecTools within line budget. */
 const INIT_PROJECT_INPUT_SCHEMA = {
     projectPath: z.string().max(4096).describe('Absolute path to the project root'),
+    mode: z
+        .enum(['existing_project', 'new_project'])
+        .optional()
+        .describe('Onboarding mode. Defaults to existing_project for backwards compatibility.'),
+    parentWorkspacePath: z
+        .string()
+        .max(4096)
+        .optional()
+        .describe('Parent workspace path for explicit new_project onboarding'),
+    appName: z.string().max(500).optional().describe('Human-readable app name for new_project'),
+    appSlug: z
+        .string()
+        .max(200)
+        .optional()
+        .describe('Safe folder slug for new_project; must not contain path separators'),
+    projectType: z.string().max(500).optional().describe('Type of project being initialized'),
+    platform: z.string().max(500).optional().describe('Runtime/deployment platform'),
+    language: z.string().max(500).optional().describe('User-confirmed language'),
+    framework: z.string().max(500).nullable().optional().describe('User-confirmed framework'),
+    database: z.string().max(500).nullable().optional().describe('User-confirmed database'),
+    createDirectory: z
+        .boolean()
+        .optional()
+        .describe('When true with mode=new_project, create only the resolved projectPath directory'),
+    technologySelectionContract: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe('Approved TechnologySelectionContract returned by facilitate new_project flow'),
     locale: SupportedLocaleEnum.optional().describe('Preferred locale for this project'),
     hourlyRate: z.number().optional().describe('Developer hourly rate in USD for cost estimation'),
     experienceLevel: ExperienceLevelEnum.optional().describe('Developer experience level: beginner, intermediate, or expert'),
@@ -317,7 +345,11 @@ export function registerCoreSpecTools(server) {
                 .describe('Absolute project root. Preferred when projectId is unknown.'),
             status: SpecStatusEnum.describe('New status for all specs'),
             dryRun: z.boolean().optional().describe('Preview the batch without mutating any spec.'),
-            reviewNotes: z.string().max(10_000).optional().describe('Optional notes for each transition.'),
+            reviewNotes: z
+                .string()
+                .max(10_000)
+                .optional()
+                .describe('Optional notes for each transition.'),
         },
     }, safeTracked('update_status_batch', async (args) => handleUpdateStatusBatch(args)));
     // 8. estimate

package/dist/tools/tool-registry/core-tools.js

@@ -456,11 +456,45 @@ const coreToolsRegistry = [
                 .record(z.string().max(500), z.string().max(10_000))
                 .optional()
                 .describe('Answers collected in previous steps'),
+            parentWorkspacePath: z
+                .string()
+                .max(4096)
+                .optional()
+                .describe('Parent workspace path that should contain a new project folder'),
+            appName: z.string().max(500).optional().describe('Human-readable new app name'),
+            appSlug: z
+                .string()
+                .max(200)
+                .optional()
+                .describe('Safe folder name for the new app; must not contain path separators'),
+            projectType: z.string().max(500).optional().describe('Kind of project to create'),
+            platform: z.string().max(500).optional().describe('Runtime or deployment platform'),
+            language: z.string().max(500).optional().describe('User-confirmed programming language'),
+            framework: z
+                .string()
+                .max(500)
+                .nullable()
+                .optional()
+                .describe('User-confirmed framework, null for no framework'),
+            database: z
+                .string()
+                .max(500)
+                .nullable()
+                .optional()
+                .describe('User-confirmed database, null for no database'),
+            createDirectory: z
+                .boolean()
+                .optional()
+                .describe('When true in new_project flow, create only the resolved child project folder'),
+            clarificationAnswers: z
+                .record(z.string().max(500), z.string().max(10_000))
+                .optional()
+                .describe('Answers to interactiveQuestions emitted by facilitate'),
             step: z
                 .number()
                 .int()
                 .min(0)
-                .max(2)
+                .max(10)
                 .optional()
                 .describe('Current step index for new_project flow (0–2)'),
             targetTool: z

package/dist/tools/update-status/batch.js

@@ -8,7 +8,10 @@ function firstText(result) {
 export async function handleUpdateStatusBatch(input) {
     const uniqueSpecIds = [...new Set(input.specIds)].sort();
     if (uniqueSpecIds.length === 0) {
-        return { content: [{ type: 'text', text: 'update_status_batch requires at least one specId.' }], isError: true };
+        return {
+            content: [{ type: 'text', text: 'update_status_batch requires at least one specId.' }],
+            isError: true,
+        };
     }
     const resolved = await resolveProjectIdOrAutoDetect({
         projectId: input.projectId,

package/dist/types/facilitator.d.ts

@@ -1,4 +1,5 @@
 import type { ParadigmReport } from './paradigm.js';
+import type { TechnologySelectionContract } from './technology-selection.js';
 /** Ambiguity level for a tool request. */
 export type AmbiguityLevel = 'none' | 'low' | 'medium' | 'critical';
 /** Dimensions evaluated during ambiguity scoring. */
@@ -68,6 +69,18 @@ export interface FacilitateInput {
     scenario?: FacilitateScenario;
     /** Cumulative answers from previous steps. */
     collectedInfo?: Record<string, string>;
+    /** Parent workspace path for new-project onboarding. */
+    parentWorkspacePath?: string;
+    appName?: string;
+    appSlug?: string;
+    projectType?: string;
+    platform?: string;
+    language?: string;
+    framework?: string | null;
+    database?: string | null;
+    createDirectory?: boolean;
+    clarificationAnswers?: Record<string, string>;
+    technologySelectionContract?: TechnologySelectionContract;
     /** Step index (0-based). Incremented by the caller. */
     step?: number;
     /** Target tool for ambiguity check (optional). */

package/dist/types/index.d.ts

@@ -212,6 +212,7 @@ export * from './steering.js';
 export * from './sentry.js';
 export * from './supabase.js';
 export * from './skill-bootstrap.js';
+export * from './technology-selection.js';
 export * from './compliance-gate.js';
 export * from './schema-parity.js';
 export * from './auto-update.js';

package/dist/types/index.js

@@ -209,6 +209,7 @@ export * from './steering.js';
 export * from './sentry.js';
 export * from './supabase.js';
 export * from './skill-bootstrap.js';
+export * from './technology-selection.js';
 export * from './compliance-gate.js';
 export * from './schema-parity.js';
 export * from './auto-update.js';

package/dist/types/project/inputs.d.ts

@@ -2,12 +2,24 @@ import type { SupportedLocale, ExperienceLevel, WorkMode } from '../common/index
 import type { ConstitutionPrinciple } from './core.js';
 import type { PermissionsMode } from '../permissions-config.js';
 import type { PluginInstallMode } from '../plugin-install.js';
+import type { ProjectOnboardingMode, TechnologySelectionContract } from '../technology-selection.js';
 export interface SetLocaleInput {
     projectId?: string;
     locale: SupportedLocale;
 }
 export interface InitProjectInput {
     projectPath: string;
+    mode?: ProjectOnboardingMode;
+    parentWorkspacePath?: string;
+    appName?: string;
+    appSlug?: string;
+    projectType?: string;
+    platform?: string;
+    language?: string;
+    framework?: string | null;
+    database?: string | null;
+    createDirectory?: boolean;
+    technologySelectionContract?: TechnologySelectionContract;
     locale?: SupportedLocale;
     hourlyRate?: number;
     experienceLevel?: ExperienceLevel;

package/dist/types/technology-selection.d.ts

@@ -0,0 +1,77 @@
+import type { InteractiveQuestion } from './clarification.js';
+export type ProjectOnboardingMode = 'existing_project' | 'new_project';
+export type TechnologyDecisionSource = 'detected' | 'user-confirmed' | 'suggested-confirmed';
+export type TechnologyVerificationStatus = 'verified' | 'unverified';
+export interface TechnologyDocsVerification {
+    name: string;
+    url: string;
+    status: TechnologyVerificationStatus;
+    reason?: string;
+}
+export interface TechnologySelectionContract {
+    mode: ProjectOnboardingMode;
+    projectPath: string;
+    parentWorkspacePath?: string;
+    appName?: string;
+    appSlug?: string;
+    projectType?: string;
+    platform?: string;
+    language?: string;
+    framework?: string | null;
+    database?: string | null;
+    source: TechnologyDecisionSource;
+    evidence: string[];
+    officialDocs: TechnologyDocsVerification[];
+    verifiedAt?: string;
+}
+export interface NewProjectOnboardingInput {
+    description: string;
+    parentWorkspacePath?: string;
+    projectPath?: string;
+    appName?: string;
+    appSlug?: string;
+    projectType?: string;
+    platform?: string;
+    language?: string;
+    framework?: string | null;
+    database?: string | null;
+    createDirectory?: boolean;
+    clarificationAnswers?: Record<string, string>;
+}
+export interface NewProjectResolution {
+    ready: boolean;
+    parentWorkspacePath?: string;
+    resolvedProjectPath?: string;
+    appSlug?: string;
+    questions: InteractiveQuestion[];
+    contract?: TechnologySelectionContract;
+    errors: string[];
+}
+export type NewProjectQuestionState = Partial<{
+    parentWorkspacePath: string;
+    appSlug: string;
+    projectType: string;
+    platform: string;
+    language: string;
+    framework: string | null;
+    languageAnswered: boolean;
+    frameworkAnswered: boolean;
+    createDirectoryAnswered: boolean;
+}>;
+export interface NewProjectResolvedFields {
+    parentWorkspacePath?: string;
+    appName?: string;
+    appSlug?: string;
+    projectType?: string;
+    platform?: string;
+    language?: string;
+    framework?: string | null;
+    database?: string | null;
+    languageAnswered: boolean;
+    frameworkAnswered: boolean;
+    createDirectoryAnswered: boolean;
+    createDirectory: boolean;
+    resolvedProjectPath?: string;
+    errors: string[];
+}
+//# sourceMappingURL=technology-selection.d.ts.map

package/dist/types/technology-selection.js

@@ -0,0 +1,3 @@
+// types/technology-selection.ts — SPEC-1021 runtime onboarding contract
+export {};
+//# sourceMappingURL=technology-selection.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.1.4",
+  "version": "4.2.1",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -32,12 +32,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.1.4",
-    "@planu/core-darwin-x64": "4.1.4",
-    "@planu/core-linux-arm64-gnu": "4.1.4",
-    "@planu/core-linux-arm64-musl": "4.1.4",
-    "@planu/core-linux-x64-gnu": "4.1.4",
-    "@planu/core-linux-x64-musl": "4.1.4"
+    "@planu/core-darwin-arm64": "4.2.1",
+    "@planu/core-darwin-x64": "4.2.1",
+    "@planu/core-linux-arm64-gnu": "4.2.1",
+    "@planu/core-linux-arm64-musl": "4.2.1",
+    "@planu/core-linux-x64-gnu": "4.2.1",
+    "@planu/core-linux-x64-musl": "4.2.1",
+    "@planu/core-win32-arm64-msvc": "4.2.1",
+    "@planu/core-win32-x64-msvc": "4.2.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -147,7 +149,8 @@
     "supportedArchitectures": {
       "os": [
         "darwin",
-        "linux"
+        "linux",
+        "win32"
       ],
       "cpu": [
         "arm64",
@@ -185,7 +188,7 @@
     "eslint-plugin-import": "^2.32.0",
     "happy-dom": "^20.9.0",
     "husky": "^9.1.7",
-    "javascript-obfuscator": "^5.4.2",
+    "javascript-obfuscator": "^5.4.3",
     "knip": "^6.14.1",
     "lint-staged": "^17.0.5",
     "madge": "^8.0.0",