@planu/cli 4.3.10 → 4.3.12

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [4.3.12] - 2026-05-25
+
+### Bug Fixes
+- fix(release): avoid self-referential tarball sha
+
+
+## [4.3.11] - 2026-05-25
+
+### Bug Fixes
+- fix: close critical Planu delivery specs
+
+
 ## [4.3.9] - 2026-05-25
 
 **Tarball SHA-256:** `a47146af1f2f8e695247fb6ee92cc8da8de00b2ab7967734a7faade7f3659aeb`

package/dist/cli/commands/status.js

@@ -8,67 +8,100 @@ import { red, green } from '../colors.js';
 export const statusCommand = {
     name: 'status',
     description: 'Update the status of a spec',
-    usage: 'planu status <specId> --set <status> [--project-id ID] | planu status batch --set <status> SPEC-001 SPEC-002',
+    usage: 'planu status <specId> --set <status> [--project-id ID] [--model-tier-used TIER --model-id ID --context-hash HASH --handoff-path PATH --reviewed-by ID --arbitrated-by ID] | planu status batch --set <status> SPEC-001 SPEC-002',
     async run(args, flags) {
-        const { values, positionals } = parseArgs({
-            args,
-            options: {
-                set: { type: 'string', short: 's' },
-                'project-id': { type: 'string' },
-                notes: { type: 'string', short: 'n' },
-            },
-            strict: false,
-            allowPositionals: true,
-        });
+        const { values, positionals } = parseStatusArgs(args);
         const isBatch = positionals[0] === 'batch';
         const specId = positionals[0];
         if (!specId) {
-            process.stderr.write(`${red('Error:')} Spec ID is required.\nUsage: ${statusCommand.usage}\n`);
+            writeUsageError('Spec ID is required.');
             process.exitCode = 1;
             return;
         }
         const status = values.set;
         if (!status) {
-            process.stderr.write(`${red('Error:')} --set <status> is required.\nUsage: ${statusCommand.usage}\n`);
+            writeUsageError('--set <status> is required.');
             process.exitCode = 1;
             return;
         }
-        const projectId = values['project-id'] ?? detectProjectId();
         if (isBatch) {
-            const result = await handleUpdateStatusBatch({
-                specIds: positionals.slice(1),
-                projectId,
-                status: status,
-                reviewNotes: values.notes ?? undefined,
-            });
-            if (result.isError) {
-                process.stderr.write(`${red(formatToolResult(result, flags))}\n`);
-                process.exitCode = 1;
-                return;
-            }
-            process.stdout.write(formatToolResult(result, flags) + '\n');
+            await runBatchStatus(positionals.slice(1), values, status, flags);
             return;
         }
-        const result = await handleUpdateStatus({
-            specId,
-            projectId,
-            status: status,
-            reviewNotes: values.notes ?? undefined,
-        });
-        if (result.isError) {
-            process.stderr.write(`${red(formatToolResult(result, flags))}\n`);
-            process.exitCode = 1;
-            return;
-        }
-        const output = formatToolResult(result, flags);
-        if (flags?.quiet) {
-            if (output) {
-                process.stdout.write(output + '\n');
-            }
-        }
-        else {
-            process.stdout.write(`${green('Status updated!')} ${output}\n`);
-        }
+        await runSingleStatus(specId, values, status, flags);
     },
 };
+function parseStatusArgs(args) {
+    const parsed = parseArgs({
+        args,
+        options: {
+            set: { type: 'string', short: 's' },
+            'project-id': { type: 'string' },
+            'project-path': { type: 'string' },
+            notes: { type: 'string', short: 'n' },
+            'model-id': { type: 'string' },
+            'model-tier-used': { type: 'string' },
+            'context-hash': { type: 'string' },
+            'handoff-path': { type: 'string' },
+            'handoff-artifact-id': { type: 'string' },
+            'reviewed-by': { type: 'string' },
+            'arbitrated-by': { type: 'string' },
+            reason: { type: 'string' },
+            force: { type: 'boolean' },
+            'force-status': { type: 'boolean' },
+            'force-status-reason': { type: 'string' },
+        },
+        strict: false,
+        allowPositionals: true,
+    });
+    return { values: parsed.values, positionals: parsed.positionals };
+}
+function writeUsageError(message) {
+    process.stderr.write(`${red('Error:')} ${message}\nUsage: ${statusCommand.usage}\n`);
+}
+async function runBatchStatus(specIds, values, status, flags) {
+    const result = await handleUpdateStatusBatch({
+        specIds,
+        projectId: values['project-id'] ?? detectProjectId(),
+        status: status,
+        reviewNotes: values.notes,
+    });
+    writeToolResult(result, flags, false);
+}
+async function runSingleStatus(specId, values, status, flags) {
+    const result = await handleUpdateStatus({
+        specId,
+        projectId: values['project-id'] ?? detectProjectId(),
+        projectPath: values['project-path'],
+        status: status,
+        reviewNotes: values.notes,
+        modelId: values['model-id'],
+        modelTierUsed: values['model-tier-used'],
+        contextHash: values['context-hash'],
+        handoffPath: values['handoff-path'],
+        handoffArtifactId: values['handoff-artifact-id'],
+        reviewedBy: values['reviewed-by'],
+        arbitratedBy: values['arbitrated-by'],
+        reason: values.reason,
+        force: values.force === true ? true : undefined,
+        forceStatus: values['force-status'] === true ? true : undefined,
+        forceStatusReason: values['force-status-reason'],
+    });
+    writeToolResult(result, flags, true);
+}
+function writeToolResult(result, flags, includeSuccessPrefix) {
+    if (result.isError) {
+        process.stderr.write(`${red(formatToolResult(result, flags))}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const output = formatToolResult(result, flags);
+    if (flags?.quiet) {
+        if (output) {
+            process.stdout.write(`${output}\n`);
+        }
+        return;
+    }
+    process.stdout.write(includeSuccessPrefix ? `${green('Status updated!')} ${output}\n` : `${output}\n`);
+}
 //# sourceMappingURL=status.js.map

package/dist/engine/spec-generator/api-key-resolver.d.ts

@@ -0,0 +1,4 @@
+export declare class ApiKeyResolver {
+    resolveAnthropicKey(projectPath: string): Promise<string | undefined>;
+}
+//# sourceMappingURL=api-key-resolver.d.ts.map

package/dist/engine/spec-generator/api-key-resolver.js

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export class ApiKeyResolver {
+    async resolveAnthropicKey(projectPath) {
+        const envKey = process.env.PLANU_ANTHROPIC_API_KEY ?? process.env.ANTHROPIC_API_KEY;
+        if (envKey?.trim()) {
+            return envKey.trim();
+        }
+        for (const file of [
+            join(projectPath, 'src/config/api-keys.json'),
+            join(projectPath, '.planu/api-keys.json'),
+        ]) {
+            const key = await readKeyFile(file);
+            if (key) {
+                return key;
+            }
+        }
+        return undefined;
+    }
+}
+async function readKeyFile(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf-8'));
+        const key = parsed.anthropic?.apiKey;
+        return key?.trim() ? key.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=api-key-resolver.js.map

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

@@ -1,2 +1,5 @@
 export { FallbackGenerator } from './fallback-generator.js';
+export { ApiKeyResolver } from './api-key-resolver.js';
+export { OpusGenerator } from './opus-generator.js';
+export { QualityValidator } from './quality-validator.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,2 +1,5 @@
 export { FallbackGenerator } from './fallback-generator.js';
+export { ApiKeyResolver } from './api-key-resolver.js';
+export { OpusGenerator } from './opus-generator.js';
+export { QualityValidator } from './quality-validator.js';
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,12 @@
+import type { OpusGeneratorDeps, SpecContentGenerator, SpecGenerationRequest, SpecGenerationResult } from '../../types/index.js';
+export declare class OpusGenerator implements SpecContentGenerator {
+    private readonly model;
+    private readonly timeoutMs;
+    private readonly client;
+    private readonly fallback;
+    private readonly validator;
+    constructor(deps: OpusGeneratorDeps);
+    generate(request: SpecGenerationRequest): Promise<SpecGenerationResult>;
+    private fallbackWithReason;
+}
+//# sourceMappingURL=opus-generator.d.ts.map

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

@@ -0,0 +1,97 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { FallbackGenerator } from './fallback-generator.js';
+import { QualityValidator } from './quality-validator.js';
+export class OpusGenerator {
+    model;
+    timeoutMs;
+    client;
+    fallback;
+    validator;
+    constructor(deps) {
+        this.model = deps.model ?? 'claude-opus-4-5';
+        this.timeoutMs = deps.timeoutMs ?? 60_000;
+        this.client = deps.client ?? new Anthropic({ apiKey: deps.apiKey }).messages;
+        this.fallback = deps.fallback ?? new FallbackGenerator();
+        this.validator = deps.validator ?? new QualityValidator();
+    }
+    async generate(request) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => {
+            controller.abort();
+        }, this.timeoutMs);
+        try {
+            const response = await this.client.create({
+                model: this.model,
+                max_tokens: 6000,
+                temperature: 0.2,
+                system: buildSystemPrompt(),
+                messages: [{ role: 'user', content: buildUserPrompt(request) }],
+            }, { signal: controller.signal });
+            const text = response.content
+                .filter((block) => block.type === 'text' && typeof block.text === 'string')
+                .map((block) => block.text)
+                .join('\n')
+                .trim();
+            if (response.content.some((block) => block.type === 'tool_use') || text.length === 0) {
+                return await this.fallbackWithReason(request, 'tool-use-leak');
+            }
+            const result = parseGeneratedText(text, this.model);
+            const validation = this.validator.validate(result);
+            if (validation.passed) {
+                return result;
+            }
+            return { ...result, qualityWarnings: validation.warnings };
+        }
+        catch {
+            return await this.fallbackWithReason(request, 'timeout-or-http-error');
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async fallbackWithReason(request, reason) {
+        const fallback = await this.fallback.generate(request);
+        return {
+            ...fallback,
+            qualityWarnings: [
+                ...fallback.qualityWarnings,
+                `Opus generator fallback used: ${reason}. Configure PLANU_ANTHROPIC_API_KEY for Opus-quality create_spec generation.`,
+            ],
+            fallbackReason: reason,
+        };
+    }
+}
+function buildSystemPrompt() {
+    return [
+        'You generate Planu unified spec.md content.',
+        'Do not invoke any tools. Do not request tool use. Return markdown only.',
+        'Include ## Problem, ## Acceptance Criteria, ## Technical, ## Files, and ## Verification.',
+        'Acceptance criteria must include at least 3 GIVEN/WHEN/THEN items.',
+        'Technical must include at least 2 TypeScript signatures relevant to the requested change.',
+    ].join('\n');
+}
+function buildUserPrompt(request) {
+    return [
+        `Title: ${request.title}`,
+        `Type: ${request.type}`,
+        `Scope: ${request.scope}`,
+        `Target: ${request.target}`,
+        request.projectContext?.language ? `Language: ${request.projectContext.language}` : '',
+        request.projectContext?.framework ? `Framework: ${request.projectContext.framework}` : '',
+        '',
+        request.description,
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+function parseGeneratedText(text, model) {
+    const technicalMatch = /\n## Technical\n([\s\S]*?)(?=\n## |\s*$)/.exec(`\n${text}`);
+    return {
+        specBody: text,
+        technicalSection: technicalMatch?.[1]?.trim() ?? '',
+        generatedWithModel: model,
+        generatedAt: new Date().toISOString(),
+        qualityWarnings: [],
+    };
+}
+//# sourceMappingURL=opus-generator.js.map

package/dist/engine/spec-generator/quality-validator.d.ts

@@ -0,0 +1,5 @@
+import type { SpecGenerationResult, SpecQualityValidation } from '../../types/index.js';
+export declare class QualityValidator {
+    validate(result: SpecGenerationResult): SpecQualityValidation;
+}
+//# sourceMappingURL=quality-validator.d.ts.map

package/dist/engine/spec-generator/quality-validator.js

@@ -0,0 +1,22 @@
+export class QualityValidator {
+    validate(result) {
+        const text = `${result.specBody}\n${result.technicalSection}`;
+        const warnings = [];
+        for (const heading of ['## Problem', '## Acceptance Criteria', '## Technical']) {
+            if (!text.includes(heading)) {
+                warnings.push(`Missing required generated section: ${heading}`);
+            }
+        }
+        const bddCount = (text.match(/\bGIVEN\b[\s\S]*?\bWHEN\b[\s\S]*?\bTHEN\b/gi) ?? []).length;
+        if (bddCount < 3) {
+            warnings.push('Generated spec should include at least 3 GIVEN/WHEN/THEN criteria.');
+        }
+        const signatureCount = (result.technicalSection.match(/\b(?:export\s+)?(?:interface|type|class|function)\s+\w+/g) ??
+            []).length;
+        if (signatureCount < 2) {
+            warnings.push('Generated technical section should include at least 2 TypeScript signatures.');
+        }
+        return { passed: warnings.length === 0, warnings };
+    }
+}
+//# sourceMappingURL=quality-validator.js.map

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

@@ -25,7 +25,15 @@ export const PLANU_CANONICAL_POLICY = {
         'planu/specs/*/implementation-brief.md',
         'planu/specs/*/risk-register.md',
     ],
-    legacyMergeBeforeDeleteFiles: ['technical.md', 'plan.md', 'PLAN.md', 'progress.md'],
+    legacyMergeBeforeDeleteFiles: [
+        'technical.md',
+        'plan.md',
+        'PLAN.md',
+        'progress.md',
+        'HU.md',
+        'FICHA-TECNICA.md',
+        'PROGRESS.md',
+    ],
 };
 const ROOT_FILE_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootFiles);
 const ROOT_DIR_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootDirs);

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

@@ -22,7 +22,12 @@ async function gitRmCached(projectPath, relPath) {
         return;
     }
     try {
-        await execFileAsync('git', ['rm', '--cached', '--quiet', '--ignore-unmatch', relPath], {
+        const args = ['rm', '--cached', '--quiet', '--ignore-unmatch'];
+        if (await pathIsDirectory(join(projectPath, relPath))) {
+            args.push('-r');
+        }
+        args.push(relPath);
+        await execFileAsync('git', args, {
             cwd: projectPath,
             timeout: 5_000,
         });
@@ -51,7 +56,11 @@ async function mergeLegacySpecFile(projectPath, specDir, fileName) {
         readFile(legacyPath, 'utf-8'),
     ]);
     const body = stripFrontmatter(legacyContent);
-    const section = fileName === 'progress.md' ? 'Progress' : fileName === 'technical.md' ? 'Technical' : 'Files';
+    const section = fileName === 'progress.md' || fileName === 'PROGRESS.md'
+        ? 'Progress'
+        : fileName === 'technical.md' || fileName === 'FICHA-TECNICA.md'
+            ? 'Technical'
+            : 'Files';
     const merged = appendSectionIfMissing(specContent, section, body);
     if (merged !== specContent) {
         await atomicWriteFile(specPath, merged, {

package/dist/tools/create-spec.js

@@ -19,7 +19,7 @@ import { generateLeanSpecContent } from '../engine/spec-format/lean-spec-generat
 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 { ApiKeyResolver, FallbackGenerator, OpusGenerator, } 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';
@@ -535,7 +535,10 @@ export async function handleCreateSpec(inputParams, server) {
                         .filter(Boolean)
                         .join('\n')
                     : '';
-                const specGenerator = new FallbackGenerator();
+                const anthropicKey = await new ApiKeyResolver().resolveAnthropicKey(params.projectPath ?? '');
+                const specGenerator = anthropicKey !== undefined
+                    ? new OpusGenerator({ apiKey: anthropicKey })
+                    : new FallbackGenerator();
                 const generatedSpec = await measureStep('generateSpecBody', () => specGenerator.generate({
                     title: spec.title,
                     description: `${description}${contractNote}`,

package/dist/types/cli.d.ts

@@ -17,4 +17,21 @@ export interface CliCommand {
     /** Execute the command with parsed args */
     run(args: string[], flags?: GlobalFlags): Promise<void>;
 }
+export interface StatusCommandValues {
+    set?: string;
+    'project-id'?: string;
+    'project-path'?: string;
+    notes?: string;
+    'model-id'?: string;
+    'model-tier-used'?: string;
+    'context-hash'?: string;
+    'handoff-path'?: string;
+    'handoff-artifact-id'?: string;
+    'reviewed-by'?: string;
+    'arbitrated-by'?: string;
+    reason?: string;
+    force?: boolean;
+    'force-status'?: boolean;
+    'force-status-reason'?: string;
+}
 //# sourceMappingURL=cli.d.ts.map

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

@@ -23,4 +23,42 @@ export interface SpecGenerationResult {
 export interface SpecContentGenerator {
     generate(request: SpecGenerationRequest): Promise<SpecGenerationResult>;
 }
+export interface SpecQualityValidation {
+    passed: boolean;
+    warnings: string[];
+}
+export interface SpecGeneratorMessagesClient {
+    create(body: {
+        model: string;
+        max_tokens: number;
+        temperature: number;
+        system: string;
+        messages: {
+            role: 'user';
+            content: string;
+        }[];
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        content: {
+            type: string;
+            text?: string;
+        }[];
+    }>;
+}
+export interface OpusGeneratorDeps {
+    apiKey: string;
+    model?: string;
+    timeoutMs?: number;
+    client?: SpecGeneratorMessagesClient;
+    fallback?: SpecContentGenerator;
+    validator?: {
+        validate(result: SpecGenerationResult): SpecQualityValidation;
+    };
+}
+export interface ApiKeyConfig {
+    anthropic?: {
+        apiKey?: string;
+    };
+}
 //# sourceMappingURL=spec-generator.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.3.10",
+  "version": "4.3.12",
   "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,14 +32,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.3.10",
-    "@planu/core-darwin-x64": "4.3.10",
-    "@planu/core-linux-arm64-gnu": "4.3.10",
-    "@planu/core-linux-arm64-musl": "4.3.10",
-    "@planu/core-linux-x64-gnu": "4.3.10",
-    "@planu/core-linux-x64-musl": "4.3.10",
-    "@planu/core-win32-arm64-msvc": "4.3.10",
-    "@planu/core-win32-x64-msvc": "4.3.10"
+    "@planu/core-darwin-arm64": "4.3.12",
+    "@planu/core-darwin-x64": "4.3.12",
+    "@planu/core-linux-arm64-gnu": "4.3.12",
+    "@planu/core-linux-arm64-musl": "4.3.12",
+    "@planu/core-linux-x64-gnu": "4.3.12",
+    "@planu/core-linux-x64-musl": "4.3.12",
+    "@planu/core-win32-arm64-msvc": "4.3.12",
+    "@planu/core-win32-x64-msvc": "4.3.12"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -127,6 +127,7 @@
   ],
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.98.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "glob": "^13.0.6",
     "yaml": "^2.9.0",
@@ -178,7 +179,7 @@
     "@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.106.1",
+    "@supabase/supabase-js": "^2.106.2",
     "@types/node": "^25.9.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vitest/coverage-v8": "^4.1.7",