@planu/cli 3.9.1 → 3.9.3

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [3.9.3] - 2026-05-15
+
+**Tarball SHA-256:** `cc411a544962db6b38087b081ea847f73042f280d2ee9600c971cb1f2778db73`
+
+### Bug Fixes
+- fix(tests): update release smoke mocks for pnpm dlx
+- fix(release): smoke test scoped cli with pnpm dlx
+
+
+## [3.9.2] - 2026-05-15
+
+**Tarball SHA-256:** `3768f401213d28afacbca964d7318d079e92d5f4d454b78705f9995c272034ac`
+
+### Bug Fixes
+- fix(release): allow own native core packages in license audit
+- fix(tests): stabilize release preflight checks
+- fix(release): support lock fallback without flock
+- fix(specs): enforce English structured spec generation
+- fix: stabilize mcp slim test suite
+
+
 ## [3.9.0] — 2026-05-12 — Single official SDD MCP surface
 
 ### Changed — Planu now exposes one focused MCP surface
@@ -3721,4 +3742,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/ai-cost-estimator/token-estimator.js

@@ -62,19 +62,24 @@ export async function detectProjectLanguage(projectPath) {
 // Codebase scanning
 // ---------------------------------------------------------------------------
 const MAX_SCAN_DEPTH = 5;
+const MAX_SCANNED_SOURCE_FILES = 200;
 const EXCLUDED_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '__pycache__', '.next']);
 /** Recursively counts total characters in source files up to a given depth. */
-async function countCodebaseChars(dirPath, depth) {
+async function countCodebaseChars(dirPath, depth, filesScanned = 0) {
     if (depth > MAX_SCAN_DEPTH) {
-        return 0;
+        return { chars: 0, files: filesScanned };
+    }
+    if (filesScanned >= MAX_SCANNED_SOURCE_FILES) {
+        return { chars: 0, files: filesScanned };
     }
     let totalChars = 0;
+    let totalFiles = filesScanned;
     let entries;
     try {
         entries = await readdir(dirPath, { withFileTypes: true, encoding: 'utf-8' });
     }
     catch {
-        return 0;
+        return { chars: 0, files: totalFiles };
     }
     for (const entry of entries) {
         const entryName = entry.name;
@@ -83,19 +88,25 @@ async function countCodebaseChars(dirPath, depth) {
         }
         const fullPath = join(dirPath, entryName);
         if (entry.isDirectory()) {
-            totalChars += await countCodebaseChars(fullPath, depth + 1);
+            const nested = await countCodebaseChars(fullPath, depth + 1, totalFiles);
+            totalChars += nested.chars;
+            totalFiles = nested.files;
         }
         else if (entry.isFile() && isSourceFile(entryName)) {
+            if (totalFiles >= MAX_SCANNED_SOURCE_FILES) {
+                break;
+            }
             try {
                 const content = await readFile(fullPath, 'utf-8');
                 totalChars += content.length;
+                totalFiles++;
             }
             catch {
                 // Skip unreadable files
             }
         }
     }
-    return totalChars;
+    return { chars: totalChars, files: totalFiles };
 }
 /** Returns true if the file extension is a known source file type. */
 function isSourceFile(filename) {
@@ -120,7 +131,7 @@ export async function estimateInputTokens(specContent, projectPath, config) {
     // 2. Codebase context tokens (optional)
     let codebaseContextTokens = 0;
     if (projectPath) {
-        const codebaseChars = await countCodebaseChars(projectPath, 0);
+        const { chars: codebaseChars } = await countCodebaseChars(projectPath, 0);
         codebaseContextTokens = Math.ceil(codebaseChars / charsPerToken);
     }
     const inputTokens = specContentTokens + codebaseContextTokens + toolDefinitionsTokens;

package/dist/engine/autopilot/crash-shield-rate-limiter.js

@@ -1,11 +1,11 @@
 // engine/autopilot/crash-shield-rate-limiter.ts — SPEC-628: Rate-limit crash scans to max once per 6h per project
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { hashProjectPath } from '../../storage/base-store.js';
+import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
 const SIX_HOURS_MS = 6 * 60 * 60 * 1000;
 function stateFilePath(projectPath) {
     const projectId = hashProjectPath(projectPath);
-    return join('data', 'projects', projectId, 'crash-shield-state.json');
+    return join(projectDataDir(projectId), 'crash-shield-state.json');
 }
 /**
  * Returns { skip: true, reason } if a crash scan was recorded within maxAgeMs.

package/dist/engine/session-safeguard/learnings-buffer.js

@@ -1,14 +1,14 @@
 // engine/session-safeguard/learnings-buffer.ts — SPEC-585: Append/flush learnings buffer
-import { open, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { open, readFile, writeFile, mkdir, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
-import { hashProjectPath } from '../../storage/base-store.js';
+import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
 const BUFFER_VERSION = 1;
 const MEMORY_MD_PATH = '/Users/kevin/.claude/projects/-Users-kevin-Documents-desarrollo-sdd-mcp-server/memory/MEMORY.md';
-const MAX_RETRIES = 3;
+const MAX_RETRIES = 50;
 const JITTER_MS = 100;
 function bufferPath(projectPath) {
     const hash = hashProjectPath(projectPath);
-    return join('data', 'projects', hash, 'learnings-buffer.json');
+    return join(projectDataDir(hash), 'learnings-buffer.json');
 }
 function emptyBuffer() {
     return { version: BUFFER_VERSION, entries: [] };
@@ -40,7 +40,6 @@ export async function appendToBuffer(projectPath, entry) {
     for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
         try {
             const fh = await open(lockFile, 'wx');
-            await fh.close();
             try {
                 const buffer = await readBuffer(projectPath);
                 buffer.entries.push(entry);
@@ -48,7 +47,12 @@ export async function appendToBuffer(projectPath, entry) {
             }
             finally {
                 try {
-                    const { unlink } = await import('node:fs/promises');
+                    await fh.close();
+                }
+                catch {
+                    /* best-effort */
+                }
+                try {
                     await unlink(lockFile);
                 }
                 catch {
@@ -68,15 +72,9 @@ export async function appendToBuffer(projectPath, entry) {
             await new Promise((resolve) => setTimeout(resolve, JITTER_MS + Math.random() * JITTER_MS));
         }
     }
-    // Fallback: direct write without lock
-    try {
-        const buffer = await readBuffer(projectPath);
-        buffer.entries.push(entry);
-        await writeBuffer(projectPath, buffer);
-    }
-    catch {
-        throw lastError;
-    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error('Unable to acquire learnings buffer lock');
 }
 /** Build the markdown bullet for an entry to append to MEMORY.md. */
 function entryToMarkdown(entry) {

package/dist/engine/spec-format/lean-spec-generator.js

@@ -42,6 +42,11 @@ export function generateLeanSpecContent(input) {
         `  model: ${estimation.recommendedModel}`,
         `model: ${model}`,
         `budget: ${String(budget)}`,
+        ...(spec.generatedWithModel ? [`generatedWithModel: ${spec.generatedWithModel}`] : []),
+        ...(spec.generatedAt ? [`generatedAt: ${spec.generatedAt}`] : []),
+        ...(spec.qualityWarnings && spec.qualityWarnings.length > 0
+            ? [`qualityWarnings: ${JSON.stringify(spec.qualityWarnings)}`]
+            : []),
     ];
     let acLines;
     if (acFormat === 'bdd') {

package/dist/engine/spec-generator/fallback-generator.d.ts

@@ -0,0 +1,5 @@
+import type { SpecContentGenerator, SpecGenerationRequest, SpecGenerationResult } from '../../types/index.js';
+export declare class FallbackGenerator implements SpecContentGenerator {
+    generate(request: SpecGenerationRequest): Promise<SpecGenerationResult>;
+}
+//# sourceMappingURL=fallback-generator.d.ts.map

package/dist/engine/spec-generator/fallback-generator.js

@@ -0,0 +1,120 @@
+const MAX_SUMMARY_LENGTH = 700;
+export class FallbackGenerator {
+    generate(request) {
+        const slug = slugify(request.title);
+        const pascalName = toPascalCase(request.title);
+        const sourceSummary = normalizeSummary(request.description, request.title);
+        const contextLine = buildContextLine(request);
+        const technicalSection = buildTechnicalSection(slug, pascalName, contextLine);
+        const specBody = [
+            '## Problem',
+            sourceSummary,
+            '',
+            '## Solution',
+            `Implement ${request.title} with explicit behavior, project-scoped file ownership, and verification gates. ${contextLine}`,
+            '',
+            '## Acceptance Criteria',
+            '',
+            `Scenario: ${request.title} happy path`,
+            'GIVEN the relevant user or system context exists',
+            `WHEN the requested ${request.title} behavior is executed`,
+            'THEN the expected outcome from the request is observable',
+            '',
+            `Scenario: ${request.title} failure handling`,
+            'GIVEN invalid input or an unavailable dependency',
+            `WHEN the requested ${request.title} behavior runs`,
+            'THEN the system returns a clear failure state without corrupting data',
+            '',
+            `Scenario: ${request.title} verification`,
+            'GIVEN the implementation is complete',
+            'WHEN the configured verification commands run',
+            'THEN tests and lint pass without regressions',
+            '',
+            technicalSection,
+        ].join('\n');
+        return Promise.resolve({
+            specBody,
+            technicalSection,
+            generatedWithModel: 'deterministic-fallback',
+            generatedAt: new Date().toISOString(),
+            qualityWarnings: [
+                'Fallback generator used. Review candidate file paths and replace placeholders with exact code owners before approval.',
+            ],
+            fallbackReason: 'No external model generator is configured for create_spec.',
+        });
+    }
+}
+function normalizeSummary(description, title) {
+    const compact = description
+        .replace(/\r\n/g, '\n')
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith('- [ ]'))
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const summary = compact.length > 0
+        ? compact.slice(0, MAX_SUMMARY_LENGTH)
+        : `The project needs ${title} defined with enough implementation detail to proceed safely.`;
+    return summary.endsWith('.') ? summary : `${summary}.`;
+}
+function buildContextLine(request) {
+    const parts = [
+        request.projectContext?.language,
+        request.projectContext?.framework,
+        request.projectContext?.architecture,
+    ].filter((part) => part !== undefined && part.trim().length > 0);
+    if (parts.length === 0) {
+        return 'Use the existing project architecture and conventions.';
+    }
+    return `Use the existing ${parts.join(' / ')} project conventions.`;
+}
+function buildTechnicalSection(slug, pascalName, contextLine) {
+    return [
+        '## Technical',
+        '',
+        '### Implementation Notes',
+        `- ${contextLine}`,
+        '- Replace candidate paths with exact files before moving the spec to approved.',
+        '',
+        '## Files',
+        '',
+        '### Create',
+        `- src/${slug}.ts (candidate path; replace with exact owner during planning)`,
+        '### Modify',
+        '- src/index.ts (candidate integration point; replace with exact owner during planning)',
+        '### Test',
+        `- tests/${slug}.test.ts (focused coverage for the behavior and failure path)`,
+        '',
+        '## Type Signatures',
+        '```typescript',
+        `interface ${pascalName}Input {`,
+        '  readonly requestId?: string;',
+        '}',
+        '',
+        `interface ${pascalName}Result {`,
+        '  readonly ok: boolean;',
+        '  readonly reason?: string;',
+        '}',
+        '```',
+        '',
+        '## Verification',
+        '- pnpm typecheck',
+        '- pnpm lint',
+        '- pnpm test',
+    ].join('\n');
+}
+function slugify(input) {
+    const slug = input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug.length > 0 ? slug : 'generated-spec';
+}
+function toPascalCase(input) {
+    const words = input.match(/[a-zA-Z0-9]+/g) ?? ['Generated', 'Spec'];
+    return words
+        .map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1).toLowerCase()}`)
+        .join('');
+}
+//# sourceMappingURL=fallback-generator.js.map

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

@@ -0,0 +1,2 @@
+export { FallbackGenerator } from './fallback-generator.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,2 @@
+export { FallbackGenerator } from './fallback-generator.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/spec-language/english-only.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Validate that persisted spec documentation is authored in English.
+ *
+ * The detector is intentionally conservative: it ignores code fences, inline code,
+ * file paths, markdown headings, and BDD keywords before looking for common
+ * Spanish/Portuguese function words. It should block obvious non-English prose
+ * without punishing short technical descriptions.
+ */
+export declare function validateEnglishOnlySpecText(text: string): {
+    ok: boolean;
+    detectedLanguage: 'en' | 'es' | 'pt' | 'unknown';
+    reason?: string;
+    signals: string[];
+};
+//# sourceMappingURL=english-only.d.ts.map

package/dist/engine/spec-language/english-only.js

@@ -0,0 +1,142 @@
+// engine/spec-language/english-only.ts — deterministic guard for English-only spec docs.
+const MIN_PROSE_TOKENS = 8;
+const MIN_LANGUAGE_HITS = 2;
+const MIN_LANGUAGE_RATIO = 0.08;
+const NON_ENGLISH_SIGNATURES = {
+    es: new Set([
+        'abajo',
+        'acepta',
+        'actual',
+        'actualiza',
+        'cada',
+        'como',
+        'con',
+        'cuando',
+        'debajo',
+        'de',
+        'del',
+        'dentro',
+        'devuelve',
+        'diseñan',
+        'el',
+        'en',
+        'entre',
+        'fija',
+        'hacia',
+        'hay',
+        'la',
+        'las',
+        'lista',
+        'los',
+        'mismo',
+        'muestra',
+        'no',
+        'oculta',
+        'para',
+        'por',
+        'queda',
+        'que',
+        'renderiza',
+        'reporta',
+        'se',
+        'sin',
+        'usuario',
+        'usa',
+    ]),
+    pt: new Set([
+        'abaixo',
+        'aceita',
+        'atualiza',
+        'cada',
+        'com',
+        'como',
+        'quando',
+        'da',
+        'das',
+        'de',
+        'dentro',
+        'devolve',
+        'do',
+        'dos',
+        'em',
+        'entre',
+        'fica',
+        'há',
+        'lista',
+        'mesmo',
+        'mostra',
+        'não',
+        'oculta',
+        'o',
+        'os',
+        'para',
+        'por',
+        'que',
+        'renderiza',
+        'sem',
+        'usuário',
+        'usa',
+    ]),
+};
+/**
+ * Validate that persisted spec documentation is authored in English.
+ *
+ * The detector is intentionally conservative: it ignores code fences, inline code,
+ * file paths, markdown headings, and BDD keywords before looking for common
+ * Spanish/Portuguese function words. It should block obvious non-English prose
+ * without punishing short technical descriptions.
+ */
+export function validateEnglishOnlySpecText(text) {
+    const tokens = tokenizeProse(text);
+    if (tokens.length < MIN_PROSE_TOKENS) {
+        return { ok: true, detectedLanguage: 'unknown', signals: [] };
+    }
+    const scored = Object.keys(NON_ENGLISH_SIGNATURES).map((lang) => {
+        const signature = NON_ENGLISH_SIGNATURES[lang];
+        const hits = tokens.filter((token) => signature.has(token));
+        return {
+            lang,
+            hits,
+            ratio: hits.length / tokens.length,
+        };
+    });
+    const best = scored.sort((a, b) => b.hits.length - a.hits.length || b.ratio - a.ratio)[0];
+    if (!best || best.hits.length < MIN_LANGUAGE_HITS || best.ratio < MIN_LANGUAGE_RATIO) {
+        return { ok: true, detectedLanguage: 'en', signals: [] };
+    }
+    const signals = [...new Set(best.hits)].slice(0, 8);
+    return {
+        ok: false,
+        detectedLanguage: best.lang,
+        signals,
+        reason: `Spec documents must be written in English. Detected ${languageName(best.lang)} prose ` +
+            `signals: ${signals.join(', ')}.`,
+    };
+}
+function tokenizeProse(text) {
+    const withoutCode = text
+        .replace(/```[\s\S]*?```/g, ' ')
+        .replace(/~~~[\s\S]*?~~~/g, ' ')
+        .replace(/`[^`]*`/g, ' ')
+        .replace(/\b[a-zA-Z][\w.-]*(?:\/[\w.-]+)+\b/g, ' ')
+        .replace(/^---[\s\S]*?---/m, ' ');
+    return withoutCode
+        .toLowerCase()
+        .normalize('NFC')
+        .split(/[^\p{L}]+/u)
+        .filter((token) => token.length > 1)
+        .filter((token) => !isIgnoredToken(token));
+}
+function isIgnoredToken(token) {
+    return (token === 'given' ||
+        token === 'when' ||
+        token === 'then' ||
+        token === 'and' ||
+        token === 'or' ||
+        token === 'ac' ||
+        token === 'bdd');
+}
+function languageName(lang) {
+    return lang === 'es' ? 'Spanish' : 'Portuguese';
+}
+//# sourceMappingURL=english-only.js.map

package/dist/engine/spec-migrator/unified-migration.js

@@ -28,6 +28,20 @@ export async function migrateToUnified(specDir, projectPath) {
     try {
         const specContent = await readFile(specPath, 'utf-8');
         if (/\n## Technical(\n|$)/.test(specContent)) {
+            try {
+                await readFile(techPath, 'utf-8');
+                if (projectPath) {
+                    await safeUnlink(projectPath, techPath);
+                }
+                else {
+                    const { unlink } = await import('node:fs/promises');
+                    await unlink(techPath);
+                }
+                return { specDir, merged: true, reason: 'already-unified' };
+            }
+            catch {
+                /* no residual technical.md */
+            }
             return { specDir, merged: false, reason: 'already-unified' };
         }
         let techContent;

package/dist/engine/status-reconciler/index.js

@@ -125,7 +125,7 @@ export async function reconcileStatusFromDisk(projectPath, projectId) {
         reconcileReason: `count mismatch: status.json had ${String(current.totalSpecs)}, disk has ${String(diskTotal)}`,
     };
     try {
-        await writeJsonSafe(statusPath, updated);
+        await writeJsonSafe(statusPath, updated, { verify: false });
     }
     catch {
         // Best-effort — if write fails, return result without throwing

package/dist/index.js

@@ -63,6 +63,7 @@ const server = createMcpServer();
 async function setupPostHandshake(handshakeGate) {
     // Wait for initialize + notifications/initialized before firing any notifications.
     await handshakeGate;
+    const envKey = process.env.SDD_LICENSE_KEY;
     const [{ bootstrapAutopilotHandlers }, { registerAgentSquadHandlers }, { startupSync }, { checkForUpdates }, { setConnectedClient }, { handleActivateLicense }, { GroupManager }, { setGroupManager }, { registerSddTools, OFFICIAL_SDD_TOOL_NAMES },] = await Promise.all([
         import('./engine/autopilot/bootstrap.js'),
         import('./tools/register-agent-squad-tools.js'),
@@ -109,7 +110,6 @@ async function setupPostHandshake(handshakeGate) {
         console.error('[Planu] Startup spec state sync failed:', err);
     });
     // Auto-activate license from environment variable if present.
-    const envKey = process.env.SDD_LICENSE_KEY;
     if (envKey) {
         const { licenseStore: ls } = await import('./storage/index.js');
         const existingState = await ls.getLicenseState().catch(() => null);

package/dist/tools/create-spec.js

@@ -17,6 +17,8 @@ import { runAutoPostCreatePipeline, formatPipelineLines } from './create-spec/au
 import { generateLeanSpecContent } from '../engine/spec-format/lean-spec-generator.js';
 import { generateLeanTechnicalContent } from '../engine/spec-format/lean-technical-generator.js';
 import { buildUnifiedSpecContent } from '../engine/spec-format/unified-spec-builder.js';
+import { validateEnglishOnlySpecText } from '../engine/spec-language/english-only.js';
+import { FallbackGenerator } from '../engine/spec-generator/index.js';
 import { analyzeProjectForSpec, getEmptyAutopilotResult, } from './create-spec/autopilot-analyzer.js';
 import { AutopilotSummaryCollector } from '../engine/autopilot/summary-collector.js';
 import { trackCost } from '../engine/cost-tracking/operation-tracker.js';
@@ -327,6 +329,28 @@ async function findRecentlyWrittenSpecs(projectPath, windowMs) {
 }
 const DESCRIPTION_MAX_CHARS = 10_000;
 const DESCRIPTION_EXCEED_MSG = 'Description exceeds 10000 chars. Create with a summary (<3k) and use reconcile_spec to add the rest.';
+function checkEnglishOnlyInput(params) {
+    const validation = validateEnglishOnlySpecText(`${params.title}\n\n${params.description}`);
+    if (validation.ok) {
+        return null;
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `English-only spec gate blocked create_spec.\n\n${validation.reason ?? 'Non-English prose detected.'}\n\n` +
+                    'Rewrite the title and description in English, then call create_spec again. User-facing responses may be localized, but spec.md must be English.',
+            },
+        ],
+        isError: true,
+        structuredContent: {
+            error: 'SPEC_LANGUAGE_GATE_BLOCKED',
+            detectedLanguage: validation.detectedLanguage,
+            signals: validation.signals,
+            fixHint: 'Rewrite title and description in English before creating the spec.',
+        },
+    };
+}
 // eslint-disable-next-line max-lines-per-function
 export async function handleCreateSpec(inputParams, server) {
     // SPEC-781: Friendly error for description exceeding 10000 chars (replaces cryptic Zod error)
@@ -363,6 +387,10 @@ export async function handleCreateSpec(inputParams, server) {
         inputParams.specId) {
         return handleAgentTeamSynthesis(inputParams.specId, resolvedPath, inputParams.agentTeamFindings);
     }
+    const languageGate = checkEnglishOnlyInput(resolvedInputParams);
+    if (languageGate) {
+        return languageGate;
+    }
     // SPEC-665: Fire-and-forget TTL refresh for conventions.json (never blocks create_spec)
     void import('../engine/conventions-ttl.js').then(({ triggerConventionsTtlRefresh }) => {
         void triggerConventionsTtlRefresh(resolvedPath).catch(() => {
@@ -463,9 +491,26 @@ 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 specGenerator = new FallbackGenerator();
+                const generatedSpec = await measureStep('generateSpecBody', () => specGenerator.generate({
+                    title: spec.title,
+                    description,
+                    type: spec.type,
+                    scope: spec.scope,
+                    target: spec.target,
+                    acFormat: params.acFormat,
+                    projectContext: {
+                        language: knowledge?.language ?? undefined,
+                        framework: knowledge?.framework ?? undefined,
+                        architecture: knowledge?.architecture.primary ?? undefined,
+                    },
+                }));
+                spec.generatedWithModel = generatedSpec.generatedWithModel;
+                spec.generatedAt = generatedSpec.generatedAt;
+                spec.qualityWarnings = generatedSpec.qualityWarnings;
                 const leanSpec = generateLeanSpecContent({
                     spec,
-                    description,
+                    description: generatedSpec.specBody,
                     estimation,
                     extraCriteria: filteredCriteria,
                     acFormat: params.acFormat,

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

@@ -339,14 +339,16 @@ export async function handleInitProject(params, server) {
             void withAudit(projectPath, 'init_project', 'configurePlanuHooks', () => configurePlanuHooks(projectPath)).catch(() => {
                 /* best-effort */
             });
-            // SPEC-779: Install universal rules catalog (fire-and-forget)
-            void (async () => {
+            // SPEC-779: Install universal rules catalog before returning so init_project
+            // has no delayed project mutations after the tool result is delivered.
+            try {
                 const hostHint = detectHost();
                 const host = hostHint === 'codex' ? 'codex' : hostHint === 'gemini' ? 'gemini' : 'claude-code';
                 await installUniversalRules(projectPath, host);
-            })().catch(() => {
+            }
+            catch {
                 /* best-effort */
-            });
+            }
             // SPEC-566: Auto-configure Claude Code keybindings (shift+enter → submit) — fire-and-forget
             void configureClaudeKeybindings()
                 .then((configured) => configured ? globalStore.updateGlobalConfig({ keybindingsConfigured: true }) : undefined)

package/dist/tools/list-specs.js

@@ -3,7 +3,6 @@ import { specStore, knowledgeStore } from '../storage/index.js';
 import { buildListSpecsSummary } from '../engine/human-summary.js';
 import { dirname } from 'node:path';
 import { checkBundledVersionGap } from '../engine/version-detector/bundled-version-checker.js';
-import { checkAndFixBundledVersion } from '../engine/mcp-config/mcp-config-writer.js';
 import { readLastModifiedTimestamp, formatRelativeDate } from '../engine/spec-changelog/index.js';
 import { discoverAndFlattenSpecs, filterUnprefixedSpecs, importFilesystemSpecs, migrateSpecFolderNames, reconcileSpecPaths, scanForAmbiguousCriteria, } from '../engine/spec-migrator.js';
 import { detectDrift, formatDriftMessage } from '../engine/spec-migrator/drift-detector.js';
@@ -109,15 +108,8 @@ export async function handleListSpecs(params) {
         const collector = new AutopilotSummaryCollector();
         // SPEC-756: lazy version check — fire-and-forget, non-blocking
         if (params.projectPath) {
-            const lazyPath = params.projectPath;
             checkBundledVersionGap(2000)
-                .then((gap) => {
-                if (gap.gap) {
-                    checkAndFixBundledVersion(lazyPath, gap.current, gap.latest).catch(() => {
-                        /* best-effort — never block list_specs */
-                    });
-                }
-            })
+                .then(() => undefined)
                 .catch(() => {
                 /* best-effort */
             });
@@ -151,21 +143,6 @@ export async function handleListSpecs(params) {
             if (knowledge.projectPath) {
                 await autoDiscoverProject(projectId, knowledge.projectPath, collector);
             }
-            // SPEC-768: Auto-migrate legacy technical.md into unified spec.md (non-blocking)
-            if (knowledge.projectPath) {
-                try {
-                    const { runSsrBackMigration } = await import('../engine/spec-migrator/ssr-back-migration.js');
-                    await runSsrBackMigration({
-                        projectPath: knowledge.projectPath,
-                        dryRun: false,
-                        foldProgressMd: true,
-                        allowDoneSpecs: false,
-                    });
-                }
-                catch {
-                    /* best-effort — never block list_specs */
-                }
-            }
             // Get all specs
             let specs = await specStore.listSpecs(projectId);
             // Apply filters

package/dist/tools/update-status/transition-guard.d.ts

@@ -59,12 +59,15 @@ export declare function checkDorGate(spec: Spec, specId: string, projectId: stri
  */
 export declare function checkAmbiguityGate(spec: Spec, newStatus: SpecStatus): Promise<ToolResult | null>;
 /**
- * SPEC-769: Readiness gate — block 'approved' when spec quality is too low.
+ * SPEC-769/SPEC-492: Readiness gate — block 'review'/'approved' when spec
+ * quality is too low or the persisted spec document is not English.
  * Best-effort: if spec.md cannot be read, the gate is skipped (returns no block).
  *
  * - 0 criteria → InteractiveQuestion (hard block, no force path)
- * - score < 70 && !forceApprove → InteractiveQuestion with 3 options
- * - score < 70 && forceApprove → proceed, qualityWarnings populated
+ * - score < 70 on approved && !forceApprove → InteractiveQuestion with 3 options
+ * - score < 70 on approved && forceApprove → proceed, qualityWarnings populated
+ * - score < 70 on review → block and keep draft
+ * - non-English prose → hard block
  * - score >= 70 → proceed, no warnings
  */
 export declare function checkReadinessGate(spec: Spec, newStatus: SpecStatus, forceApprove: boolean | undefined): Promise<ReadinessGateOutput>;

package/dist/tools/update-status/transition-guard.js

@@ -5,6 +5,7 @@ import { validateDoR } from '../../engine/dor-dod.js';
 import { dispatchFeedbackEvent } from '../learn.js';
 import { scoreAmbiguityFromPath } from '../../engine/ambiguity-scorer.js';
 import { checkReadinessInternal } from '../../engine/readiness-checker.js';
+import { validateEnglishOnlySpecText } from '../../engine/spec-language/english-only.js';
 /**
  * Valid state transitions for spec lifecycle.
  * draft -> review -> approved -> implementing -> done
@@ -173,16 +174,19 @@ export async function checkAmbiguityGate(spec, newStatus) {
     };
 }
 /**
- * SPEC-769: Readiness gate — block 'approved' when spec quality is too low.
+ * SPEC-769/SPEC-492: Readiness gate — block 'review'/'approved' when spec
+ * quality is too low or the persisted spec document is not English.
  * Best-effort: if spec.md cannot be read, the gate is skipped (returns no block).
  *
  * - 0 criteria → InteractiveQuestion (hard block, no force path)
- * - score < 70 && !forceApprove → InteractiveQuestion with 3 options
- * - score < 70 && forceApprove → proceed, qualityWarnings populated
+ * - score < 70 on approved && !forceApprove → InteractiveQuestion with 3 options
+ * - score < 70 on approved && forceApprove → proceed, qualityWarnings populated
+ * - score < 70 on review → block and keep draft
+ * - non-English prose → hard block
  * - score >= 70 → proceed, no warnings
  */
 export async function checkReadinessGate(spec, newStatus, forceApprove) {
-    if (newStatus !== 'approved' || !spec.specPath) {
+    if ((newStatus !== 'review' && newStatus !== 'approved') || !spec.specPath) {
         return { blockResult: null, qualityWarnings: [] };
     }
     let body;
@@ -197,6 +201,29 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
     if (typeof body !== 'string') {
         return { blockResult: null, qualityWarnings: [] };
     }
+    const languageValidation = validateEnglishOnlySpecText(body);
+    if (!languageValidation.ok) {
+        return {
+            blockResult: {
+                content: [
+                    {
+                        type: 'text',
+                        text: `English-only spec gate blocked transition to ${newStatus}.\n\n` +
+                            `${languageValidation.reason ?? 'Non-English prose detected.'}\n\n` +
+                            'Rewrite spec.md in English before moving it forward.',
+                    },
+                ],
+                isError: true,
+                structuredContent: {
+                    error: 'SPEC_LANGUAGE_GATE_BLOCKED',
+                    detectedLanguage: languageValidation.detectedLanguage,
+                    signals: languageValidation.signals,
+                    fixHint: 'Rewrite spec.md in English before review or approval.',
+                },
+            },
+            qualityWarnings: [],
+        };
+    }
     let score;
     let warnings;
     let criteriaCount;
@@ -207,6 +234,27 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
         return { blockResult: null, qualityWarnings: [] };
     }
     if (criteriaCount === 0) {
+        if (newStatus === 'review') {
+            return {
+                blockResult: {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Readiness gate blocked transition to review: spec has 0 acceptance criteria.',
+                        },
+                    ],
+                    isError: true,
+                    structuredContent: {
+                        error: 'READINESS_GATE_BLOCKED',
+                        score,
+                        threshold: 70,
+                        warnings,
+                        fixHint: 'Add at least 3 testable acceptance criteria before moving to review.',
+                    },
+                },
+                qualityWarnings: [],
+            };
+        }
         const question = {
             header: 'Spec incomplete',
             question: 'This spec has 0 acceptance criteria. Add criteria before approving — transition blocked.',
@@ -244,6 +292,29 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
     if (score >= 70) {
         return { blockResult: null, qualityWarnings: [] };
     }
+    if (newStatus === 'review') {
+        const warningsSummary = warnings.slice(0, 3).join('; ');
+        return {
+            blockResult: {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Readiness gate blocked transition to review: score ${String(score)}/100 — below 70 threshold. ` +
+                            `Warnings: ${warningsSummary}`,
+                    },
+                ],
+                isError: true,
+                structuredContent: {
+                    error: 'READINESS_GATE_BLOCKED',
+                    score,
+                    threshold: 70,
+                    warnings,
+                    fixHint: 'Complete the spec before moving from draft to review.',
+                },
+            },
+            qualityWarnings: [],
+        };
+    }
     // Score < 70
     if (forceApprove) {
         // Caller wants to force through — proceed with warnings attached

package/dist/types/index.d.ts

@@ -59,6 +59,7 @@ export * from './hooks.js';
 export * from './webhook.js';
 export * from './ci.js';
 export * from './spec-templates.js';
+export * from './spec-generator.js';
 export * from './registry.js';
 export * from './tool-groups.js';
 export * from './code-transforms.js';

package/dist/types/index.js

@@ -60,6 +60,7 @@ export * from './hooks.js';
 export * from './webhook.js';
 export * from './ci.js';
 export * from './spec-templates.js';
+export * from './spec-generator.js';
 export * from './registry.js';
 export * from './tool-groups.js';
 export * from './code-transforms.js';

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

@@ -57,6 +57,12 @@ export interface Spec {
     model?: 'haiku' | 'sonnet' | 'opus';
     /** SPEC-630: token budget derived from devHours. */
     budget?: 800 | 2000 | 4000;
+    /** SPEC-766: Generator that produced the initial spec body. */
+    generatedWithModel?: string;
+    /** SPEC-766: ISO timestamp for initial spec body generation. */
+    generatedAt?: string;
+    /** SPEC-766: Non-blocking quality warnings emitted by the generator. */
+    qualityWarnings?: string[];
     /** SPEC-686: Implementation priority for ROI scoring. Defaults to 'medium'. */
     priority?: 'high' | 'medium' | 'low';
     /**

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

@@ -0,0 +1,26 @@
+import type { SpecScope, SpecTarget, SpecType } from './common/index.js';
+export interface SpecGenerationRequest {
+    title: string;
+    description: string;
+    type: SpecType;
+    scope: SpecScope;
+    target: SpecTarget;
+    acFormat?: 'checkbox' | 'bdd';
+    projectContext?: {
+        language?: string;
+        framework?: string;
+        architecture?: string;
+    };
+}
+export interface SpecGenerationResult {
+    specBody: string;
+    technicalSection: string;
+    generatedWithModel: string;
+    generatedAt: string;
+    qualityWarnings: string[];
+    fallbackReason?: string;
+}
+export interface SpecContentGenerator {
+    generate(request: SpecGenerationRequest): Promise<SpecGenerationResult>;
+}
+//# sourceMappingURL=spec-generator.d.ts.map

package/dist/types/spec-generator.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=spec-generator.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "3.9.1",
+  "version": "3.9.3",
   "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",