@planu/cli 4.4.0 → 4.4.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [4.4.1] - 2026-06-04
+
+### Bug Fixes
+- fix: make validate spec-scoped and non-mutating
+
+### Chores
+- chore(deps): sync lockfile
+- chore(deps): update patch and minor dependencies
+
+
 ## [4.4.0] - 2026-06-03
 
 ### Features

package/dist/engine/evidence-gates/artifact-reader.js

@@ -50,13 +50,18 @@ const ContractValidationSchema = z.object({
     summary: z.string().optional(),
 });
 function resolveSpecPath(spec, projectPath) {
-    if (isAbsolute(spec.specPath) || !projectPath) {
-        return spec.specPath;
+    const specPath = spec.specPath;
+    if (!specPath?.trim()) {
+        return null;
     }
-    return join(projectPath, spec.specPath);
+    if (isAbsolute(specPath) || !projectPath) {
+        return specPath;
+    }
+    return join(projectPath, specPath);
 }
 function specEvidencePath(spec, filename, projectPath) {
-    return join(dirname(resolveSpecPath(spec, projectPath)), 'evidence', filename);
+    const specPath = resolveSpecPath(spec, projectPath);
+    return specPath ? join(dirname(specPath), 'evidence', filename) : null;
 }
 function handoffEvidencePath(projectId, specId, filename) {
     return join(projectDataDir(projectId), 'handoffs', specId, filename);
@@ -81,7 +86,7 @@ async function readUnknown(paths) {
 }
 async function readOptional(args) {
     try {
-        const found = await readUnknown(args.paths);
+        const found = await readUnknown(args.paths.filter((path) => Boolean(path)));
         if (!found) {
             return undefined;
         }

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

@@ -3,6 +3,7 @@ export declare const PLANU_CANONICAL_POLICY: PlanuCanonicalPathPolicy;
 export declare function isCanonicalPlanuRootFile(name: string): boolean;
 export declare function isCanonicalPlanuRootDir(name: string): boolean;
 export declare function isCanonicalSpecFile(name: string): boolean;
+export declare function isCanonicalSpecDir(name: string): boolean;
 export declare function mustMergeBeforeDeleteSpecFile(name: string): boolean;
 export declare function isCanonicalReleaseFile(relativeToPlanu: string): boolean;
 export declare function canonicalContractText(): string;

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

@@ -4,6 +4,7 @@ export const PLANU_CANONICAL_POLICY = {
     canonicalRootFiles: ['conventions.json', 'context.md', 'session-context.md', 'session.json'],
     canonicalRootDirs: ['releases', 'specs'],
     canonicalSpecFiles: ['spec.md'],
+    canonicalSpecDirs: ['evidence'],
     forbiddenHostAssetRootDirs: ['agents', 'skills', 'rules', 'hooks'],
     generatedRuntimePatterns: [
         'planu/index.html',
@@ -38,6 +39,7 @@ export const PLANU_CANONICAL_POLICY = {
 const ROOT_FILE_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootFiles);
 const ROOT_DIR_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootDirs);
 const SPEC_FILE_SET = new Set(PLANU_CANONICAL_POLICY.canonicalSpecFiles);
+const SPEC_DIR_SET = new Set(PLANU_CANONICAL_POLICY.canonicalSpecDirs);
 const LEGACY_MERGE_SET = new Set(PLANU_CANONICAL_POLICY.legacyMergeBeforeDeleteFiles);
 export function isCanonicalPlanuRootFile(name) {
     return ROOT_FILE_SET.has(name);
@@ -48,6 +50,9 @@ export function isCanonicalPlanuRootDir(name) {
 export function isCanonicalSpecFile(name) {
     return SPEC_FILE_SET.has(name);
 }
+export function isCanonicalSpecDir(name) {
+    return SPEC_DIR_SET.has(name);
+}
 export function mustMergeBeforeDeleteSpecFile(name) {
     return LEGACY_MERGE_SET.has(name);
 }
@@ -66,6 +71,8 @@ export function canonicalContractText() {
         '  specs/',
         '    SPEC-XXX-slug/',
         '      spec.md',
+        '      evidence/',
+        '        *.json',
         '',
         'Host adapters are written outside planu/:',
         '  Claude Code: .claude/agents, .claude/skills, .claude/rules',

package/dist/engine/spec-migrator/strict-planu-cleanup.d.ts

@@ -1,6 +1,6 @@
-import type { StrictPlanuCleanupResult, StrictPlanuValidationResult } from '../../types/index.js';
+import type { StrictPlanuCleanupResult, StrictPlanuValidationOptions, StrictPlanuValidationResult } from '../../types/index.js';
 import { PLANU_CANONICAL_POLICY } from './planu-canonical-policy.js';
 export declare function runStrictPlanuCleanup(projectPath: string): Promise<StrictPlanuCleanupResult>;
-export declare function validateStrictPlanuLayout(projectPath: string): Promise<StrictPlanuValidationResult>;
+export declare function validateStrictPlanuLayout(projectPath: string, options?: StrictPlanuValidationOptions): Promise<StrictPlanuValidationResult>;
 export { PLANU_CANONICAL_POLICY };
 //# sourceMappingURL=strict-planu-cleanup.d.ts.map

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

@@ -4,10 +4,10 @@ import { readdir, readFile, rm, stat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { join, relative } from 'node:path';
+import { dirname, isAbsolute, join, relative } from 'node:path';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
 import { safeUnlink } from './git-aware-fs.js';
-import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalReleaseFile, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
+import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalReleaseFile, isCanonicalSpecDir, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
 const execFileAsync = promisify(execFile);
 async function pathIsDirectory(path) {
     try {
@@ -125,7 +125,9 @@ async function walkSpecDirectory(projectPath, specDir, result) {
             }
             continue;
         }
-        if (entry === 'reference' || !isCanonicalSpecFile(entry)) {
+        const isDir = await pathIsDirectory(full);
+        if (entry === 'reference' ||
+            (isDir ? !isCanonicalSpecDir(entry) : !isCanonicalSpecFile(entry))) {
             await removePath(projectPath, full);
             result.deleted.push(relative(projectPath, full));
         }
@@ -173,33 +175,46 @@ export async function runStrictPlanuCleanup(projectPath) {
     result.gitignoreUpdated = await updateGitignore(projectPath);
     return result;
 }
-export async function validateStrictPlanuLayout(projectPath) {
+function resolveSpecDirsForValidation(projectPath, specPath) {
+    if (!specPath?.trim()) {
+        return null;
+    }
+    const resolved = isAbsolute(specPath) ? specPath : join(projectPath, specPath);
+    return [dirname(resolved)];
+}
+export async function validateStrictPlanuLayout(projectPath, options = {}) {
     const offenders = [];
     const planuDir = join(projectPath, 'planu');
-    const entries = await readdir(planuDir).catch(() => []);
-    for (const entry of entries) {
-        const full = join(planuDir, entry);
-        const isDir = await pathIsDirectory(full);
-        if ((isDir && !isCanonicalPlanuRootDir(entry)) ||
-            (!isDir && !isCanonicalPlanuRootFile(entry))) {
-            offenders.push(relative(projectPath, full));
+    if (options.includeRoot !== false) {
+        const entries = await readdir(planuDir).catch(() => []);
+        for (const entry of entries) {
+            const full = join(planuDir, entry);
+            const isDir = await pathIsDirectory(full);
+            if ((isDir && !isCanonicalPlanuRootDir(entry)) ||
+                (!isDir && !isCanonicalPlanuRootFile(entry))) {
+                offenders.push(relative(projectPath, full));
+            }
         }
-    }
-    for (const entry of await readdir(join(planuDir, 'releases')).catch(() => [])) {
-        const rel = `releases/${entry}`;
-        if (!isCanonicalReleaseFile(rel)) {
-            offenders.push(`planu/${rel}`);
+        for (const entry of await readdir(join(planuDir, 'releases')).catch(() => [])) {
+            const rel = `releases/${entry}`;
+            if (!isCanonicalReleaseFile(rel)) {
+                offenders.push(`planu/${rel}`);
+            }
         }
     }
-    for (const specDir of await readdir(join(planuDir, 'specs')).catch(() => [])) {
-        const full = join(planuDir, 'specs', specDir);
+    const scopedSpecDirs = resolveSpecDirsForValidation(projectPath, options.specPath) ??
+        (await readdir(join(planuDir, 'specs')).catch(() => [])).map((specDir) => join(planuDir, 'specs', specDir));
+    for (const full of scopedSpecDirs) {
+        const specDir = relative(join(planuDir, 'specs'), full);
         if (!(await pathIsDirectory(full)) || specDir === 'data') {
             offenders.push(relative(projectPath, full));
             continue;
         }
         for (const entry of await readdir(full).catch(() => [])) {
-            if (!isCanonicalSpecFile(entry)) {
-                offenders.push(relative(projectPath, join(full, entry)));
+            const entryPath = join(full, entry);
+            const isDir = await pathIsDirectory(entryPath);
+            if (isDir ? !isCanonicalSpecDir(entry) : !isCanonicalSpecFile(entry)) {
+                offenders.push(relative(projectPath, entryPath));
             }
         }
     }

package/dist/tools/validate.js

@@ -73,9 +73,11 @@ export async function handleValidate(args, server) {
     const projectPath = knowledge.projectPath;
     // SPEC-1017: fail closed when planu/ contains non-canonical artifacts.
     try {
-        const { runStrictPlanuCleanup, validateStrictPlanuLayout } = await import('../engine/spec-migrator/index.js');
-        await runStrictPlanuCleanup(projectPath);
-        const layout = await validateStrictPlanuLayout(projectPath);
+        const { validateStrictPlanuLayout } = await import('../engine/spec-migrator/index.js');
+        const layout = await validateStrictPlanuLayout(projectPath, {
+            specPath: spec.specPath,
+            includeRoot: false,
+        });
         if (!layout.ok) {
             return {
                 content: [

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

@@ -54,6 +54,7 @@ export interface PlanuCanonicalPathPolicy {
     readonly canonicalRootFiles: readonly string[];
     readonly canonicalRootDirs: readonly string[];
     readonly canonicalSpecFiles: readonly string[];
+    readonly canonicalSpecDirs: readonly string[];
     readonly forbiddenHostAssetRootDirs: readonly string[];
     readonly generatedRuntimePatterns: readonly string[];
     readonly legacyMergeBeforeDeleteFiles: readonly string[];
@@ -68,6 +69,10 @@ export interface StrictPlanuValidationResult {
     offenders: string[];
     contract: string;
 }
+export interface StrictPlanuValidationOptions {
+    specPath?: string;
+    includeRoot?: boolean;
+}
 export interface UpdateStatusBatchInput {
     specIds: string[];
     status: SpecStatus;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.4.0",
+  "version": "4.4.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",
@@ -34,14 +34,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.4.0",
-    "@planu/core-darwin-x64": "4.4.0",
-    "@planu/core-linux-arm64-gnu": "4.4.0",
-    "@planu/core-linux-arm64-musl": "4.4.0",
-    "@planu/core-linux-x64-gnu": "4.4.0",
-    "@planu/core-linux-x64-musl": "4.4.0",
-    "@planu/core-win32-arm64-msvc": "4.4.0",
-    "@planu/core-win32-x64-msvc": "4.4.0"
+    "@planu/core-darwin-arm64": "4.4.1",
+    "@planu/core-darwin-x64": "4.4.1",
+    "@planu/core-linux-arm64-gnu": "4.4.1",
+    "@planu/core-linux-arm64-musl": "4.4.1",
+    "@planu/core-linux-x64-gnu": "4.4.1",
+    "@planu/core-linux-x64-musl": "4.4.1",
+    "@planu/core-win32-arm64-msvc": "4.4.1",
+    "@planu/core-win32-x64-msvc": "4.4.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -185,12 +185,12 @@
     "@types/node": "^25.9.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vitest/coverage-v8": "^4.1.8",
-    "@vue/test-utils": "^2.4.10",
+    "@vue/test-utils": "^2.4.11",
     "eslint": "^10.4.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
-    "happy-dom": "^20.9.0",
+    "happy-dom": "^20.10.1",
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.4.3",
     "knip": "^6.15.0",

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.4.0",
+  "version": "4.4.1",
   "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.4.0",
+  "version": "4.4.1",
   "icon": "assets/plugin/icon.svg",
   "command": [
     "npx",