@planu/cli 4.10.9 → 4.10.10

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [4.10.10] - 2026-07-08
+
+### Bug Fixes
+- fix(create-spec): merge readiness-compliant spec generation
+- fix(create-spec): generate readiness-compliant technical details
+
+
 ## [4.10.9] - 2026-07-07
 
 ### Bug Fixes

package/dist/engine/spec-format/lean-technical-generator.d.ts

@@ -1,5 +1,5 @@
 import type { LeanFileEntry, LeanTechnicalInput } from '../../types/index.js';
 export type { LeanFileEntry, LeanTechnicalInput };
-/** Generate lean ## Technical content: YAML-like metadata + files section only. */
+/** Generate lean ## Technical content: YAML-like metadata + files and verification notes. */
 export declare function generateLeanTechnicalContent(input: LeanTechnicalInput): string;
 //# sourceMappingURL=lean-technical-generator.d.ts.map

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

@@ -1,10 +1,13 @@
 // engine/spec-format/lean-technical-generator.ts — Generates lean ## Technical content (SPEC-461)
-// Output: ~15-20 lines. Only files section with create/modify/test and pending/done status.
-/** Generate lean ## Technical content: YAML-like metadata + files section only. */
+// Output: lean files section with enough detail for readiness to evaluate concrete scope.
+/** Generate lean ## Technical content: YAML-like metadata + files and verification notes. */
 export function generateLeanTechnicalContent(input) {
-    const { specId, filesToCreate = [], filesToModify = [], filesToTest = [] } = input;
+    const { specId, filesToCreate = [], filesToModify = [], filesToTest = [], includeDecisionRequiredPlaceholder = false, } = input;
     const lines = ['---', `spec: ${specId}`, '---'];
     if (filesToCreate.length === 0 && filesToModify.length === 0 && filesToTest.length === 0) {
+        if (includeDecisionRequiredPlaceholder) {
+            lines.push('', '## Files', '', '- Decision required: identify expected source and test files before implementation.', '', '## Implementation Notes', '', '- File inference did not find grounded `src/` or `tests/` paths.', '- Do not fabricate authoritative paths; update this section during review with concrete files.');
+        }
         return lines.join('\n');
     }
     lines.push('', '## Files', '');
@@ -29,6 +32,14 @@ export function generateLeanTechnicalContent(input) {
         }
         lines.push('');
     }
+    lines.push('## Implementation Notes', '');
+    lines.push('- Keep implementation scoped to the files listed above unless review updates this spec.');
+    if (filesToTest.length > 0) {
+        lines.push(`- Verification starts with: \`pnpm vitest run ${filesToTest.map((file) => file.path).join(' ')}\`.`);
+    }
+    else {
+        lines.push('- Decision required: add at least one concrete automated test path before approval.');
+    }
     return lines.join('\n');
 }
 //# sourceMappingURL=lean-technical-generator.js.map

package/dist/engine/spec-format/technical-md-populator.js

@@ -1,7 +1,7 @@
 // engine/spec-format/technical-md-populator.ts — SPEC-586: Parse spec body to populate ## Technical
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
-const FILE_PATH_RE = /\b(src|tests)\/[\w/-]+\.[a-z]+\b/g;
+const FILE_PATH_RE = /\b(?:src|tests)\/[a-zA-Z0-9/_.-]+\.[a-z]+\b/g;
 function extractPathsFromSection(sectionText) {
     const paths = [];
     const listRe = /^-\s+`?(src\/[\w./-]+|tests\/[\w./-]+)`?/gm;
@@ -18,10 +18,12 @@ function extractPathsFromSection(sectionText) {
     return paths;
 }
 function parseSectionedFileLists(body) {
-    const filesSection = /##\s+Files\s+likely\s+to\s+change[\s\S]*?(?=^##\s|$)/m.exec(body);
-    const createSection = /###\s+Create[\s\S]*?(?=###|^##\s|$)/m.exec(filesSection?.[0] ?? body);
-    const modifySection = /###\s+Modify[\s\S]*?(?=###|^##\s|$)/m.exec(filesSection?.[0] ?? body);
-    if (!createSection && !modifySection) {
+    const filesSection = /##\s+Files\s+likely\s+to\s+change[\s\S]*?(?=\n##\s|$)/.exec(body);
+    const scopedBody = filesSection?.[0] ?? body;
+    const createSection = /###\s+Create[\s\S]*?(?=\n###|\n##\s|$)/.exec(scopedBody);
+    const modifySection = /###\s+Modify[\s\S]*?(?=\n###|\n##\s|$)/.exec(scopedBody);
+    const testSection = /###\s+Test[\s\S]*?(?=\n###|\n##\s|$)/.exec(scopedBody);
+    if (!createSection && !modifySection && !testSection) {
         return null;
     }
     return {
@@ -33,13 +35,21 @@ function parseSectionedFileLists(body) {
             path: p,
             status: 'pending',
         })),
-        test: [],
+        test: extractPathsFromSection(testSection?.[0] ?? '').map((p) => ({
+            path: p,
+            status: 'pending',
+        })),
     };
 }
 async function categorizeByExistence(paths, projectPath) {
     const create = [];
     const modify = [];
+    const test = [];
     for (const p of paths) {
+        if (p.startsWith('tests/')) {
+            test.push({ path: p, status: 'pending' });
+            continue;
+        }
         const full = join(projectPath, p);
         try {
             await stat(full);
@@ -49,7 +59,7 @@ async function categorizeByExistence(paths, projectPath) {
             create.push({ path: p, status: 'pending' });
         }
     }
-    return { create, modify, test: [] };
+    return { create, modify, test };
 }
 /**
  * Attempt to extract file paths from spec body for auto-populating ## Technical.

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

@@ -27,6 +27,7 @@ export function buildUnifiedSpecContent(leanSpecBody, leanTechnicalBody) {
     // Split the generated technical body into its constituent sections so we can
     // inject only the ones the user did not provide.
     const generatedFiles = extractSection(technicalBodyRaw, 'Files');
+    const generatedImplementationNotes = extractSection(technicalBodyRaw, 'Implementation Notes');
     // Generated technical body always starts with `## Files`. If the user already
     // authored both, return the spec body untouched.
     if (userHasTechnical && userHasFiles) {
@@ -37,13 +38,21 @@ export function buildUnifiedSpecContent(leanSpecBody, leanTechnicalBody) {
         sectionsToAppend.push('## Technical', '');
     }
     if (!userHasFiles && generatedFiles !== null) {
-        sectionsToAppend.push(generatedFiles);
+        sectionsToAppend.push(demoteTopLevelHeadings(generatedFiles));
+    }
+    if (!userHasTechnical && generatedImplementationNotes !== null) {
+        sectionsToAppend.push('', demoteTopLevelHeadings(generatedImplementationNotes));
     }
     if (sectionsToAppend.length === 0) {
         return leanSpecBody.endsWith('\n') ? leanSpecBody : `${leanSpecBody}\n`;
     }
     return `${leanSpecBody.trimEnd()}\n\n${sectionsToAppend.join('\n').trimEnd()}\n`;
 }
+function demoteTopLevelHeadings(section) {
+    return section.replace(/^(#{2,6})(\s+\S.*)$/gm, (_match, hashes, rest) => {
+        return `${hashes}#${rest}`;
+    });
+}
 function stripFencedCodeBlocks(body) {
     return body.replace(/```[\s\S]*?```/g, '').replace(/~~~[\s\S]*?~~~/g, '');
 }

package/dist/tools/create-spec.js

@@ -113,13 +113,29 @@ function handleClarification(_server, description, knowledge, autopilot, params)
 function hasFileEntries(files) {
     return files.create.length + files.modify.length + files.test.length > 0;
 }
+function mergeTechnicalFiles(primary, fallback) {
+    return {
+        create: mergeFileEntries(primary.create, fallback.create),
+        modify: mergeFileEntries(primary.modify, fallback.modify),
+        test: mergeFileEntries(primary.test, fallback.test),
+    };
+}
+function mergeFileEntries(primary, fallback) {
+    const byPath = new Map();
+    for (const file of [...primary, ...fallback]) {
+        if (!byPath.has(file.path)) {
+            byPath.set(file.path, file);
+        }
+    }
+    return [...byPath.values()];
+}
 async function resolveTechnicalFiles(input) {
     const generatedSource = [input.generatedTechnicalSection, input.generatedSpecBody]
         .filter((part) => part.trim().length > 0)
         .join('\n\n');
     const extracted = await extractFilesFromSpecBody(generatedSource, input.projectPath);
     if (extracted !== null && hasFileEntries(extracted)) {
-        return extracted;
+        return mergeTechnicalFiles(extracted, input.autopilot.suggestedFiles);
     }
     if (input.fallbackReason !== undefined && hasFileEntries(input.autopilot.suggestedFiles)) {
         return input.autopilot.suggestedFiles;
@@ -687,6 +703,7 @@ export async function handleCreateSpec(inputParams, server) {
                     filesToCreate: groundedTechnical.files.create,
                     filesToModify: groundedTechnical.files.modify,
                     filesToTest: groundedTechnical.files.test,
+                    includeDecisionRequiredPlaceholder: spec.scope !== 'trivial',
                 });
                 // SPEC-709: write unified spec.md from origin — no separate technical.md.
                 // The legacy two-file output is preserved by appending the technical body

package/dist/tools/validate-structured-compat.d.ts

@@ -0,0 +1,19 @@
+interface ValidateStructuredCompatInput {
+    structured: Record<string, unknown>;
+    fieldsImplemented: number;
+    fieldsTotal: number;
+    matches: string[];
+    missing: string[];
+    extra: string[];
+    qualityIssues: unknown[];
+    conventionViolations: {
+        category: string;
+        file: string;
+        line?: number;
+        message: string;
+        severity: string;
+    }[];
+}
+export declare function applyValidateStructuredCompat(input: ValidateStructuredCompatInput): void;
+export {};
+//# sourceMappingURL=validate-structured-compat.d.ts.map

package/dist/tools/validate-structured-compat.js

@@ -0,0 +1,14 @@
+export function applyValidateStructuredCompat(input) {
+    const structured = input.structured;
+    structured.fieldsImplemented = input.fieldsImplemented;
+    structured.fieldsTotal = input.fieldsTotal;
+    structured.matches = input.matches;
+    structured.missing = input.missing;
+    structured.extra = input.extra;
+    structured.qualityIssues = input.qualityIssues;
+    const conventionCompliance = structured.conventionCompliance;
+    if (conventionCompliance !== undefined) {
+        conventionCompliance.violations = input.conventionViolations;
+    }
+}
+//# sourceMappingURL=validate-structured-compat.js.map

package/dist/tools/validate.js

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- validate coordinates multiple legacy gate payloads in one tool. */
 // tools/validate.ts — Compare spec vs implementation (SPEC-595: elicitation on failures)
 // Uses the validator engine to check coverage, missing items, quality issues.
 import { elicitOrFallback, buildEnumSchema } from '../engine/elicitation/elicit-helper.js';
@@ -19,6 +20,7 @@ import { buildMinimalityReport } from './validate-minimality.js';
 import { buildValidateFailureFallback, validateStrictLayoutOrError } from './validate-helpers.js';
 import { runLintCheck } from './validate-lint.js';
 import { checkPlanuUncommittedChanges, runAssuranceGates } from './validate-assurance.js';
+import { applyValidateStructuredCompat } from './validate-structured-compat.js';
 // Re-export for external use (SPEC-018)
 export { validateContractCompliance };
 // SPEC-595: server? param enables elicitation on failures
@@ -487,6 +489,7 @@ function buildValidateStructuredContent(args) {
         conventionCompliance: {
             totalViolations: args.conventionCompliance.totalViolations,
             regressionDetected: args.conventionCompliance.regressionDetected,
+            violations: args.conventionCompliance.violations,
             violationsTop5: args.conventionCompliance.violations.slice(0, 5),
         },
         lintCheck: {
@@ -522,6 +525,16 @@ function buildValidateStructuredContent(args) {
     });
     const lintCheck = structured.lintCheck;
     lintCheck.output = args.lintCheck.output ?? '';
+    applyValidateStructuredCompat({
+        structured,
+        fieldsImplemented: args.compactSummary.passed,
+        fieldsTotal: args.compactSummary.total,
+        matches: args.result.matches,
+        missing: args.result.missing,
+        extra: args.result.extra,
+        qualityIssues: args.qualityIssues,
+        conventionViolations: args.conventionCompliance.violations,
+    });
     return structured;
 }
 function buildCompactValidateText(args) {

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

@@ -132,6 +132,7 @@ export interface LeanTechnicalInput {
     filesToCreate?: LeanFileEntry[];
     filesToModify?: LeanFileEntry[];
     filesToTest?: LeanFileEntry[];
+    includeDecisionRequiredPlaceholder?: boolean;
 }
 export interface ImplementationContractInput {
     description: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.10.9",
+  "version": "4.10.10",
   "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",
@@ -34,14 +34,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.10.9",
-    "@planu/core-darwin-x64": "4.10.9",
-    "@planu/core-linux-arm64-gnu": "4.10.9",
-    "@planu/core-linux-arm64-musl": "4.10.9",
-    "@planu/core-linux-x64-gnu": "4.10.9",
-    "@planu/core-linux-x64-musl": "4.10.9",
-    "@planu/core-win32-arm64-msvc": "4.10.9",
-    "@planu/core-win32-x64-msvc": "4.10.9"
+    "@planu/core-darwin-arm64": "4.10.10",
+    "@planu/core-darwin-x64": "4.10.10",
+    "@planu/core-linux-arm64-gnu": "4.10.10",
+    "@planu/core-linux-arm64-musl": "4.10.10",
+    "@planu/core-linux-x64-gnu": "4.10.10",
+    "@planu/core-linux-x64-musl": "4.10.10",
+    "@planu/core-win32-arm64-msvc": "4.10.10",
+    "@planu/core-win32-x64-msvc": "4.10.10"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -144,7 +144,7 @@
     "@secretlint/secretlint-rule-preset-recommend": "^13.0.2",
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
-    "@supabase/supabase-js": "^2.110.0",
+    "@supabase/supabase-js": "^2.110.1",
     "@types/node": "^26.1.0",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vitest/coverage-v8": "^4.1.10",
@@ -156,7 +156,7 @@
     "happy-dom": "^20.10.6",
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.4.3",
-    "knip": "^6.24.0",
+    "knip": "^6.25.0",
     "lint-staged": "^17.0.8",
     "madge": "^8.0.0",
     "prettier": "^3.9.4",

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.10.9",
+  "version": "4.10.10",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {

package/planu-plugin.json

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