@planu/cli 3.9.14 → 4.1.0

package/dist/tools/tool-registry/group-misc.js

@@ -1182,11 +1182,11 @@ export function registerMiscGroupTools(s) {
     registerRepairFrontmatterDriftTool(s);
     // ── Generate dashboard ─────────────────────────────────────────────────────
     s.registerTool('generate_spec_dashboard', {
-        description: 'Regenerate planu/index.html dashboard with all specs, metrics, and pagination. Call after bulk changes or to fix a stale dashboard.',
+        description: 'Deprecated compatibility tool. Planu no longer writes generated dashboard HTML into planu/.',
         inputSchema: {
             projectPath: z.string().describe('Absolute path to the project root directory'),
         },
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: true },
     }, async (args) => {
         const projectId = hashProjectPath(args.projectPath);
         const specs = await specStore.listSpecs(projectId);
@@ -1196,7 +1196,7 @@ export function registerMiscGroupTools(s) {
             content: [
                 {
                     type: 'text',
-                    text: `Dashboard regenerated: ${String(specs.length)} specs (${String(doneCount)} done). File: planu/index.html`,
+                    text: `Dashboard generation is deprecated; no project files were written. Current specs: ${String(specs.length)} (${String(doneCount)} done).`,
                 },
             ],
         };
@@ -1331,7 +1331,7 @@ export function registerMiscGroupTools(s) {
     // ── SPEC-739: flag_spec_gap ─────────────────────────────────────────────────
     s.registerTool('flag_spec_gap', {
         description: 'Record a spec implementation gap discovered mid-implementation. ' +
-            'Persists a hash-chained entry to planu/research/gaps.jsonl with severity ' +
+            'Persists a hash-chained entry to external Planu project data with severity ' +
             "classification ('low' | 'medium' | 'high') and affected spec links. " +
             'Existing callers without severity or affectedSpecs continue to work (defaults applied).',
         inputSchema: {

package/dist/tools/update-status/batch.d.ts

@@ -0,0 +1,3 @@
+import type { ToolResult, UpdateStatusBatchInput } from '../../types/index.js';
+export declare function handleUpdateStatusBatch(input: UpdateStatusBatchInput): Promise<ToolResult>;
+//# sourceMappingURL=batch.d.ts.map

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

@@ -0,0 +1,96 @@
+// tools/update-status/batch.ts — SPEC-1017 batch status transitions
+import { handleUpdateStatus } from './index.js';
+import { resolveProjectIdOrAutoDetect } from '../resolve-project-id.js';
+function firstText(result) {
+    const first = result.content[0];
+    return first?.type === 'text' ? first.text : JSON.stringify(result.structuredContent ?? {});
+}
+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 };
+    }
+    const resolved = await resolveProjectIdOrAutoDetect({
+        projectId: input.projectId,
+        projectPath: input.projectPath,
+    });
+    if (!resolved.ok) {
+        return resolved.errorResult;
+    }
+    if (input.dryRun) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Batch status dry run: ${uniqueSpecIds.length} spec(s) would transition to ${input.status}.\n` +
+                        uniqueSpecIds.map((id) => `- ${id}`).join('\n'),
+                },
+            ],
+            structuredContent: {
+                dryRun: true,
+                status: input.status,
+                specIds: uniqueSpecIds,
+            },
+        };
+    }
+    const updated = [];
+    const skipped = [];
+    const failed = [];
+    const previousSuppress = process.env.PLANU_SUPPRESS_AUTOCOMMIT;
+    process.env.PLANU_SUPPRESS_AUTOCOMMIT = 'true';
+    try {
+        for (const specId of uniqueSpecIds) {
+            const result = await handleUpdateStatus({
+                specId,
+                status: input.status,
+                projectId: resolved.projectId,
+                projectPath: resolved.projectPath,
+                reviewNotes: input.reviewNotes,
+            });
+            const message = firstText(result);
+            if (result.isError === true) {
+                if (/already|idempotent|same status/i.test(message)) {
+                    skipped.push({ specId, message });
+                }
+                else {
+                    failed.push({ specId, message });
+                }
+            }
+            else {
+                updated.push({ specId, message });
+            }
+        }
+    }
+    finally {
+        if (previousSuppress === undefined) {
+            delete process.env.PLANU_SUPPRESS_AUTOCOMMIT;
+        }
+        else {
+            process.env.PLANU_SUPPRESS_AUTOCOMMIT = previousSuppress;
+        }
+    }
+    try {
+        const { runStrictPlanuCleanup } = await import('../../engine/spec-migrator/index.js');
+        await runStrictPlanuCleanup(resolved.projectPath);
+    }
+    catch {
+        /* best-effort final pass */
+    }
+    const text = [
+        `Batch status transition complete: ${input.status}`,
+        `Updated: ${updated.length}`,
+        `Skipped: ${skipped.length}`,
+        `Failed: ${failed.length}`,
+    ].join('\n');
+    return {
+        content: [{ type: 'text', text }],
+        isError: failed.length > 0,
+        structuredContent: {
+            updated,
+            skipped,
+            failed,
+            sideEffectsFlushed: ['strict-planu-cleanup'],
+        },
+    };
+}
+//# sourceMappingURL=batch.js.map

package/dist/tools/update-status/dod-gates.js

@@ -264,7 +264,7 @@ export async function checkValidationReportGate(specId, projectId, force) {
             return null;
         }
         if (!result.payload.passed) {
-            const artifactPath = `planu/data/projects/${projectId}/handoffs/${specId}/validation-report.json`;
+            const artifactPath = `external Planu project data: handoffs/${specId}/validation-report.json`;
             return {
                 content: [
                     {

package/dist/tools/update-status/file-sync.js

@@ -86,7 +86,9 @@ export async function syncSpecFiles(updatedSpec, currentStatus, newStatus, proje
             // Commit message must reflect the actual transition — 'mark-done' is only
             // correct when newStatus === 'done'; any other transition uses 'status-update'
             // to avoid misleading "mark as done" messages on approved/implementing/etc.
-            if (projectPath) {
+            if (projectPath &&
+                process.env.PLANU_ENABLE_AUTOCOMMIT === 'true' &&
+                process.env.PLANU_SUPPRESS_AUTOCOMMIT !== 'true') {
                 try {
                     const { git: gitCmd } = await import('../git/git-helpers.js');
                     await gitCmd(projectPath, ['add', '--', updatedSpec.specPath]);

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

@@ -240,6 +240,16 @@ export async function handleUpdateStatus(params, server) {
             return resolved.errorResult;
         }
         const projectId = resolved.projectId;
+        const effectiveProjectPath = resolved.projectPath;
+        if (effectiveProjectPath) {
+            try {
+                const { runStrictPlanuCleanup } = await import('../../engine/spec-migrator/index.js');
+                await runStrictPlanuCleanup(effectiveProjectPath);
+            }
+            catch {
+                /* strict cleanup is best-effort here; validate fails closed if artifacts remain */
+            }
+        }
         try {
             // Get the current spec
             const spec = await specStore.getSpec(projectId, specId);
@@ -271,7 +281,7 @@ export async function handleUpdateStatus(params, server) {
                         content: [
                             {
                                 type: 'text',
-                                text: `Spec ${specId} is locked by another process (cross-process lock). Retry later or inspect planu/.locks/${specId}.lock`,
+                                text: `Spec ${specId} is locked by another process (cross-process lock). Retry later or inspect data/.locks/planu/${specId}.lock`,
                             },
                         ],
                         isError: true,
@@ -864,7 +874,10 @@ export async function handleUpdateStatus(params, server) {
                 }
                 // SPEC-544: Final git add after all writes complete (covers auto-advance multi-step transitions)
                 // SPEC-575: Auto-commit staged planu/ docs (idempotent, safe-fail)
-                if (effectiveGatePath && updatedSpec.specPath) {
+                if (effectiveGatePath &&
+                    updatedSpec.specPath &&
+                    process.env.PLANU_ENABLE_AUTOCOMMIT === 'true' &&
+                    process.env.PLANU_SUPPRESS_AUTOCOMMIT !== 'true') {
                     try {
                         const { git: gitCmd } = await import('../git/git-helpers.js');
                         await gitCmd(effectiveGatePath, ['add', 'planu/']);

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

@@ -162,22 +162,18 @@ export async function runDoneActions(projectId, specId, gitBranch) {
             }
             return null;
         })(),
-        // SPEC-544: Auto-stage planu/ files, then warn only if non-planu changes remain
-        // SPEC-575: Auto-commit staged planu/ docs (idempotent, safe-fail)
+        // Warn if non-planu changes remain. Planu autocommit/staging is opt-in only.
         (async () => {
             try {
                 const { resolveProjectPath, git: gitCmd } = await import('./git/git-helpers.js');
                 const projectPath = await resolveProjectPath(projectId);
-                try {
+                if (process.env.PLANU_ENABLE_AUTOCOMMIT === 'true') {
                     await gitCmd(projectPath, ['add', 'planu/']);
                     const { planuAutoCommit } = await import('../engine/git/planu-autocommit.js');
                     void planuAutoCommit({ projectPath, specId, reason: 'mark-done' }).catch((err) => {
                         console.error('[update-status] planuAutoCommit failed:', err instanceof Error ? err.message : String(err));
                     });
                 }
-                catch {
-                    // git add failed (nothing to stage, or not a git repo) — continue to status check
-                }
                 const { stdout } = await gitCmd(projectPath, ['status', '--porcelain']);
                 const nonPlanuLines = stdout
                     .trim()

package/dist/tools/validate.js

@@ -68,6 +68,33 @@ 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);
+        if (!layout.ok) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Strict Planu layout validation failed for ${specId}.\n\n` +
+                            `Non-canonical paths:\n${layout.offenders.map((p) => `- ${p}`).join('\n')}\n\n` +
+                            `Canonical contract:\n${layout.contract}`,
+                    },
+                ],
+                isError: true,
+                structuredContent: {
+                    error: 'strict_planu_layout_violation',
+                    offenders: layout.offenders,
+                    contract: layout.contract,
+                },
+            };
+        }
+    }
+    catch {
+        /* best-effort — implementation validation still runs if layout check is unavailable */
+    }
     // 3. Run validation engine
     const result = await validateSpec(spec, projectPath);
     // 4. Generate DoR and DoD checklists

package/dist/tools/workspace-dashboard-handler.js

@@ -10,6 +10,7 @@ import { readRecentAutopilotAlerts } from '../storage/autopilot-log-store.js';
 import { verifyStateFiles } from '../engine/cascade-hooks/state-drift-detector.js';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { getAsyncAnalysisPath } from './create-spec/post-creation.js';
 export async function handleWorkspaceOverview(args) {
     const result = await buildWorkspaceOverview(args.healthThreshold);
     if (result.projectCount === 0) {
@@ -126,10 +127,10 @@ export async function handleWorkspaceSearch(args) {
     }
     return { content: [{ type: 'text', text: lines.join('\n') }] };
 }
-/** SPEC-781: Check if a spec has a pending async analysis (no .analysis.json yet). */
-async function hasPendingAnalysis(projectPath, specDir) {
+/** SPEC-781: Check if a spec has pending async analysis in external project data. */
+async function hasPendingAnalysis(projectPath, specId) {
     try {
-        await readFile(join(projectPath, specDir, '.analysis.json'), 'utf-8');
+        await readFile(getAsyncAnalysisPath(projectPath, specId), 'utf-8');
         return false;
     }
     catch {
@@ -144,7 +145,6 @@ async function collectPendingAnalysisAlerts(projectPath) {
         const results = [];
         const PENDING_RE = /^pendingAnalysis:\s*true/m;
         const ID_RE = /^id:\s*(SPEC-\d+)/m;
-        const SPEC_DIR_RE = /planu\/specs\/([^/]+)\/spec\.md$/;
         for (const specFile of specFiles) {
             const content = await readFile(specFile, 'utf-8').catch(() => '');
             if (!PENDING_RE.test(content)) {
@@ -155,11 +155,8 @@ async function collectPendingAnalysisAlerts(projectPath) {
             if (specId === undefined) {
                 continue;
             }
-            const dirMatch = SPEC_DIR_RE.exec(specFile);
-            const dirName = dirMatch?.[1];
-            const specDir = dirName !== undefined ? join('planu/specs', dirName) : null;
-            if (specDir !== null && !(await hasPendingAnalysis(projectPath, specDir))) {
-                continue; // .analysis.json exists — analysis done
+            if (!(await hasPendingAnalysis(projectPath, specId))) {
+                continue;
             }
             results.push({ specId, message: `Spec ${specId} analysis still running` });
         }

package/dist/types/git.d.ts

@@ -310,7 +310,7 @@ export interface ListSpecPrsInput {
     projectPath: string;
     specId?: string;
 }
-export type PlanuAutocommitSkipReason = 'no-staged-changes' | 'mid-merge' | 'detached-head';
+export type PlanuAutocommitSkipReason = 'disabled' | 'no-staged-changes' | 'mid-merge' | 'detached-head';
 export type PlanuAutocommitReason = 'mark-done' | 'sync-release' | 'status-update' | 'session-checkpoint';
 export interface PlanuAutocommitResult {
     committed: boolean;

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

@@ -1,5 +1,6 @@
 import type { Spec } from './spec/core.js';
 import type { Estimation } from './estimation.js';
+import type { SpecStatus } from './common/index.js';
 /** A criterion in the lean spec frontmatter. */
 export interface LeanCriterion {
     text: string;
@@ -42,6 +43,31 @@ export interface CleanupResult {
     deletedSpecFiles: string[];
     totalDeleted: number;
 }
+export interface PlanuCanonicalPathPolicy {
+    readonly canonicalRootFiles: readonly string[];
+    readonly canonicalRootDirs: readonly string[];
+    readonly canonicalSpecFiles: readonly string[];
+    readonly generatedRuntimePatterns: readonly string[];
+    readonly legacyMergeBeforeDeleteFiles: readonly string[];
+}
+export interface StrictPlanuCleanupResult {
+    deleted: string[];
+    merged: string[];
+    gitignoreUpdated: boolean;
+}
+export interface StrictPlanuValidationResult {
+    ok: boolean;
+    offenders: string[];
+    contract: string;
+}
+export interface UpdateStatusBatchInput {
+    specIds: string[];
+    status: SpecStatus;
+    projectId?: string;
+    projectPath?: string;
+    dryRun?: boolean;
+    reviewNotes?: string;
+}
 /** Report of detected migration drift (SPEC-715). Read-only — no FS mutations. */
 export interface MigrationDriftReport {
     /** Count of specs that still have a stray technical.md (need unified migration). */

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

@@ -0,0 +1,8 @@
+export type EnglishOnlyArtifactKind = 'spec' | 'skill' | 'agent' | 'rule';
+export interface EnglishOnlyValidationResult {
+    ok: boolean;
+    detectedLanguage: 'en' | 'es' | 'pt' | 'unknown';
+    reason?: string;
+    signals: string[];
+}
+//# sourceMappingURL=spec-language.d.ts.map

package/dist/types/spec-language.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "3.9.14",
+  "version": "4.1.0",
   "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,12 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "3.9.14",
-    "@planu/core-darwin-x64": "3.9.14",
-    "@planu/core-linux-arm64-gnu": "3.9.14",
-    "@planu/core-linux-arm64-musl": "3.9.14",
-    "@planu/core-linux-x64-gnu": "3.9.14",
-    "@planu/core-linux-x64-musl": "3.9.14"
+    "@planu/core-darwin-arm64": "4.1.0",
+    "@planu/core-darwin-x64": "4.1.0",
+    "@planu/core-linux-arm64-gnu": "4.1.0",
+    "@planu/core-linux-arm64-musl": "4.1.0",
+    "@planu/core-linux-x64-gnu": "4.1.0",
+    "@planu/core-linux-x64-musl": "4.1.0"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -149,8 +149,8 @@
     "@commitlint/config-conventional": "^21.0.1",
     "@eslint/js": "^10.0.1",
     "@napi-rs/cli": "^3.6.2",
-    "@secretlint/secretlint-rule-no-homedir": "^13.0.0",
-    "@secretlint/secretlint-rule-preset-recommend": "^13.0.0",
+    "@secretlint/secretlint-rule-no-homedir": "^13.0.2",
+    "@secretlint/secretlint-rule-preset-recommend": "^13.0.2",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
@@ -159,30 +159,30 @@
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
-    "@supabase/supabase-js": "^2.105.4",
-    "@types/node": "^25.7.0",
-    "@vitejs/plugin-vue": "^6.0.6",
-    "@vitest/coverage-v8": "^4.1.6",
+    "@supabase/supabase-js": "^2.106.1",
+    "@types/node": "^25.9.1",
+    "@vitejs/plugin-vue": "^6.0.7",
+    "@vitest/coverage-v8": "^4.1.7",
     "@vue/test-utils": "^2.4.10",
-    "eslint": "^10.3.0",
+    "eslint": "^10.4.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
     "happy-dom": "^20.9.0",
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.4.2",
-    "knip": "^6.13.1",
-    "lint-staged": "^17.0.4",
+    "knip": "^6.14.1",
+    "lint-staged": "^17.0.5",
     "madge": "^8.0.0",
     "prettier": "^3.8.3",
-    "secretlint": "^13.0.0",
+    "secretlint": "^13.0.2",
     "semantic-release": "^25.0.3",
     "tsc-alias": "^1.8.17",
     "type-coverage": "^2.29.7",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.3",
-    "vite": "^8.0.12",
-    "vitest": "^4.1.6",
+    "typescript-eslint": "^8.59.4",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7",
     "vue": "^3.5.34"
   }
 }