@planu/cli 4.4.0 → 4.4.2

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [4.4.2] - 2026-06-05
+
+### Bug Fixes
+- fix: keep spec folders spec.md-only and store evidence externally
+
+
+## [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
@@ -4019,4 +4035,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/evidence-gates/artifact-reader.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join } from 'node:path';
+import { join } from 'node:path';
 import { z } from 'zod';
 import { projectDataDir } from '../../storage/base-store.js';
 const DiscoverySchema = z.object({
@@ -49,15 +49,6 @@ const ContractValidationSchema = z.object({
     reportPath: z.string().optional(),
     summary: z.string().optional(),
 });
-function resolveSpecPath(spec, projectPath) {
-    if (isAbsolute(spec.specPath) || !projectPath) {
-        return spec.specPath;
-    }
-    return join(projectPath, spec.specPath);
-}
-function specEvidencePath(spec, filename, projectPath) {
-    return join(dirname(resolveSpecPath(spec, projectPath)), 'evidence', filename);
-}
 function handoffEvidencePath(projectId, specId, filename) {
     return join(projectDataDir(projectId), 'handoffs', specId, filename);
 }
@@ -81,7 +72,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;
         }
@@ -103,28 +94,19 @@ export async function readEvidenceArtifacts(args) {
         label: 'Discovery evidence',
         invalidArtifacts,
         schema: DiscoverySchema,
-        paths: [
-            specEvidencePath(args.spec, 'discovery.json', args.projectPath),
-            handoffEvidencePath(args.projectId, args.specId, 'discovery.json'),
-        ],
+        paths: [handoffEvidencePath(args.projectId, args.specId, 'discovery.json')],
     });
     const taskPlan = await readOptional({
         label: 'Task plan evidence',
         invalidArtifacts,
         schema: TaskPlanSchema,
-        paths: [
-            specEvidencePath(args.spec, 'task-plan.json', args.projectPath),
-            handoffEvidencePath(args.projectId, args.specId, 'task-plan.json'),
-        ],
+        paths: [handoffEvidencePath(args.projectId, args.specId, 'task-plan.json')],
     });
     const traceabilityMatrix = await readOptional({
         label: 'Traceability matrix evidence',
         invalidArtifacts,
         schema: TraceabilityMatrixSchema,
-        paths: [
-            specEvidencePath(args.spec, 'traceability-matrix.json', args.projectPath),
-            handoffEvidencePath(args.projectId, args.specId, 'traceability-matrix.json'),
-        ],
+        paths: [handoffEvidencePath(args.projectId, args.specId, 'traceability-matrix.json')],
     });
     const contractValidations = [];
     for (const filename of [
@@ -138,10 +120,7 @@ export async function readEvidenceArtifacts(args) {
             label: filename,
             invalidArtifacts,
             schema: ContractValidationSchema,
-            paths: [
-                specEvidencePath(args.spec, filename, args.projectPath),
-                handoffEvidencePath(args.projectId, args.specId, filename),
-            ],
+            paths: [handoffEvidencePath(args.projectId, args.specId, filename)],
         });
         if (evidence) {
             contractValidations.push(evidence);

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: [],
     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);
 }
@@ -67,6 +72,8 @@ export function canonicalContractText() {
         '    SPEC-XXX-slug/',
         '      spec.md',
         '',
+        'Evidence artifacts are Planu runtime data and are stored outside planu/specs/.',
+        '',
         'Host adapters are written outside planu/:',
         '  Claude Code: .claude/agents, .claude/skills, .claude/rules',
         '  Codex: AGENTS.md, .agents/skills, .codex/agents',

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/engine/universal-rules/rules/planu-workflow.js

@@ -28,7 +28,7 @@ For non-trivial specs, Planu blocks lifecycle transitions unless evidence is pre
 | done | Traceability matrix covering every acceptance criterion |
 | done for API/UI/event/MCP work | Passing contract validation evidence |
 
-Evidence can live under \`planu/specs/<spec>/evidence/\` or the external Planu handoff store. Trivial specs may use lightweight evidence, but \`done\` still needs at least one traceability row.
+Evidence lives in the external Planu handoff store, not under \`planu/specs/<spec>/\`. Spec folders remain \`spec.md\`-only. Trivial specs may use lightweight evidence, but \`done\` still needs at least one traceability row.
 
 ## When to use \`facilitate\`
 

package/dist/tools/update-status/evidence-gate.js

@@ -80,7 +80,7 @@ function evidenceGateError(args) {
                     transition: args.transition,
                     issues: args.issues,
                     requiredContractKinds: args.requiredContractKinds,
-                    fixHint: 'Add the missing evidence artifact under planu/specs/<spec>/evidence/ or external Planu project data handoffs/<specId>/, then retry the transition.',
+                    fixHint: 'Add the missing evidence artifact to the external Planu project data handoff store, then retry the transition. Do not create JSON files under planu/specs/<spec>/.',
                 }, null, 2),
             },
         ],
@@ -95,7 +95,7 @@ function evidenceGateError(args) {
                 issues: args.issues,
                 requiredContractKinds: args.requiredContractKinds,
             },
-            fixHint: 'Add discovery.json, task-plan.json, traceability-matrix.json, and contract-validation-*.json as required for this transition.',
+            fixHint: 'Add discovery.json, task-plan.json, traceability-matrix.json, and contract-validation-*.json to the external Planu handoff store as required for this transition. Spec folders remain spec.md-only.',
         },
     };
 }

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.2",
   "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.2",
+    "@planu/core-darwin-x64": "4.4.2",
+    "@planu/core-linux-arm64-gnu": "4.4.2",
+    "@planu/core-linux-arm64-musl": "4.4.2",
+    "@planu/core-linux-x64-gnu": "4.4.2",
+    "@planu/core-linux-x64-musl": "4.4.2",
+    "@planu/core-win32-arm64-msvc": "4.4.2",
+    "@planu/core-win32-x64-msvc": "4.4.2"
   },
   "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,26 +1,20 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.4.0",
+  "version": "4.4.2",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {
       "requiresMcp": false,
       "requiresDaemon": false,
-      "hosts": [
-        "codex",
-        "claude-code"
-      ],
+      "hosts": ["codex", "claude-code"],
       "commands": [
         {
           "id": "planu.status",
           "title": "Project status",
           "description": "Show the compact Planu project snapshot without loading the MCP tool graph.",
           "invocation": "planu status",
-          "hosts": [
-            "codex",
-            "claude-code"
-          ],
+          "hosts": ["codex", "claude-code"],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handlePlanStatus"
@@ -30,10 +24,7 @@
           "title": "Create spec",
           "description": "Create a new spec through the CLI-backed SDD contract.",
           "invocation": "planu spec create \"<title>\"",
-          "hosts": [
-            "codex",
-            "claude-code"
-          ],
+          "hosts": ["codex", "claude-code"],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleCreateSpec"
@@ -43,10 +34,7 @@
           "title": "List specs",
           "description": "List specs in the current project with optional status/type filters.",
           "invocation": "planu spec list",
-          "hosts": [
-            "codex",
-            "claude-code"
-          ],
+          "hosts": ["codex", "claude-code"],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleListSpecs"
@@ -56,10 +44,7 @@
           "title": "Validate spec",
           "description": "Validate a spec against the current codebase from the native CLI surface.",
           "invocation": "planu spec validate SPEC-001",
-          "hosts": [
-            "codex",
-            "claude-code"
-          ],
+          "hosts": ["codex", "claude-code"],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleValidate"
@@ -69,10 +54,7 @@
           "title": "Audit technical debt",
           "description": "Run the read-only project audit path for lightweight debt checks.",
           "invocation": "planu audit debt",
-          "hosts": [
-            "codex",
-            "claude-code"
-          ],
+          "hosts": ["codex", "claude-code"],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleAudit"
@@ -82,10 +64,7 @@
           "title": "Check release readiness",
           "description": "Check local branch cleanliness and main/develop/release sync readiness.",
           "invocation": "planu release check",
-          "hosts": [
-            "codex",
-            "claude-code"
-          ],
+          "hosts": ["codex", "claude-code"],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "releaseCommand"

package/planu-plugin.json

@@ -2,12 +2,9 @@
   "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.2",
   "icon": "assets/plugin/icon.svg",
-  "command": [
-    "npx",
-    "@planu/cli@latest"
-  ],
+  "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",
   "capabilities": {
     "tools": [
@@ -26,42 +23,17 @@
       "create_skill",
       "skill_search"
     ],
-    "resources": [
-      "planu://specs/list",
-      "planu://specs/{id}",
-      "planu://project/status",
-      "planu://roadmap"
-    ],
-    "prompts": [
-      "create-spec-from-idea",
-      "review-spec-readiness",
-      "generate-implementation-plan"
-    ],
-    "subagents": [
-      "sdd-orchestrator",
-      "spec-challenger",
-      "test-generator"
-    ]
+    "resources": ["planu://specs/list", "planu://specs/{id}", "planu://project/status", "planu://roadmap"],
+    "prompts": ["create-spec-from-idea", "review-spec-readiness", "generate-implementation-plan"],
+    "subagents": ["sdd-orchestrator", "spec-challenger", "test-generator"]
   },
   "compatibility": {
     "minimumHostVersion": "1.0.0",
-    "requiredFeatures": [
-      "mcp-tools",
-      "file-editing"
-    ]
+    "requiredFeatures": ["mcp-tools", "file-editing"]
   },
   "repository": "https://github.com/planu-dev/planu",
   "author": "Planu",
   "license": "MIT",
   "homepage": "https://planu.dev",
-  "keywords": [
-    "sdd",
-    "spec-driven-development",
-    "mcp",
-    "specs",
-    "planning",
-    "ai",
-    "bdd",
-    "tdd"
-  ]
+  "keywords": ["sdd", "spec-driven-development", "mcp", "specs", "planning", "ai", "bdd", "tdd"]
 }