@planu/cli 4.14.1 → 5.1.1

package/dist/tools/update-status/response-builder.js

@@ -84,7 +84,7 @@ export function buildStatusResponse(result, specId, currentStatus, newStatus, re
     const toEmoji = STATUS_EMOJIS[newStatus];
     const r = result;
     const lines = [
-        `**SPEC-${specId}** moved: ${fromEmoji} \`${currentStatus}\` → ${toEmoji} \`${newStatus}\``,
+        `**${specId}** moved: ${fromEmoji} \`${currentStatus}\` → ${toEmoji} \`${newStatus}\``,
     ];
     if (r.committed && r.transitionId) {
         lines.push(`\nTransition committed: \`${r.transitionId}\``);
@@ -125,7 +125,7 @@ export function buildStatusResponse(result, specId, currentStatus, newStatus, re
         lines.push(`\n✅ Validate score: ${String(r.validateScore)}/100${sourceSuffix}`);
     }
     if (r.cascade.affectedSpecs.length > 0) {
-        lines.push(`\n🔗 Downstream specs affected: ${r.cascade.affectedSpecs.map((s) => `SPEC-${s}`).join(', ')}`);
+        lines.push(`\n🔗 Downstream specs affected: ${r.cascade.affectedSpecs.join(', ')}`);
     }
     if (r.codeRealityWarning) {
         lines.push(`\n${r.codeRealityWarning}`);
@@ -200,7 +200,7 @@ export function buildStatusResponse(result, specId, currentStatus, newStatus, re
     const markdownText = reconciliationMarkdown
         ? `${withNextSteps}\n\n${reconciliationMarkdown}`
         : withNextSteps;
-    const displayTitle = specTitle ?? `SPEC-${specId}`;
+    const displayTitle = specTitle ?? specId;
     const humanSummary = buildUpdateStatusSummary(displayTitle, newStatus);
     const warningItems = [
         r.protectedBranchWarning,

package/dist/tools/update-status/side-effects.d.ts

@@ -35,6 +35,7 @@ export declare function fireAndForgetSideEffects(params: {
     projectId: string;
     spec: Spec;
     currentStatus: SpecStatus;
+    projectPath?: string;
 }): void;
 /**
  * SPEC-772: Run cascade and await fast hooks (fast: true) within a 2s window.
@@ -50,5 +51,6 @@ export declare function runCascadeForResponse(params: {
     projectId: string;
     spec: Spec;
     currentStatus: SpecStatus;
+    projectPath?: string;
 }): Promise<RunCascadeResult | null>;
 //# sourceMappingURL=side-effects.d.ts.map

package/dist/tools/update-status/side-effects.js

@@ -193,7 +193,7 @@ function readDisabledByEnv() {
 /** Fire-and-forget side effects after a successful status transition. */
 export function fireAndForgetSideEffects(params) {
     const { knowledge, allSpecs, specId, newStatus, validateScore, projectId, spec, currentStatus } = params;
-    const projectPath = knowledge?.projectPath;
+    const projectPath = params.projectPath ?? knowledge?.projectPath;
     const ctx = {
         specId,
         spec,
@@ -223,7 +223,7 @@ export function fireAndForgetSideEffects(params) {
  */
 export async function runCascadeForResponse(params) {
     const { knowledge, allSpecs, specId, newStatus, validateScore, projectId, spec, currentStatus } = params;
-    const projectPath = knowledge?.projectPath;
+    const projectPath = params.projectPath ?? knowledge?.projectPath;
     const ctx = {
         specId,
         spec,

package/dist/tools/update-status/transition-guard.js

@@ -4,7 +4,7 @@ import { ti } from '../../i18n/index.js';
 import { validateDoR } from '../../engine/dor-dod.js';
 import { dispatchFeedbackEvent } from '../learn.js';
 import { scoreAmbiguityFromPath } from '../../engine/ambiguity-scorer.js';
-import { checkReadinessInternal } from '../../engine/readiness-checker.js';
+import { checkSpecReadiness } from '../../engine/readiness-checker.js';
 import { validateEnglishOnlySpecText } from '../../engine/spec-language/english-only.js';
 import { checkGroundedSpecContract } from '../../engine/spec-grounding/contract.js';
 import { checkGenericSpecOutput } from '../../engine/spec-quality/generic-output-gate.js';
@@ -255,7 +255,19 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
     catch (error) {
         /* reliability-optional: READINESS_SPEC_UNREADABLE — transition fails closed below */
         reportClassifiedDegradation('READINESS_SPEC_UNREADABLE', error);
-        return readinessUnavailable('READINESS_SPEC_UNREADABLE', error instanceof Error ? error.message : 'spec.md could not be read');
+        // SPEC-1351 (AC4): a missing spec.md (ENOENT) is a distinct, recoverable
+        // situation — surface an actionable message instead of the raw fs error
+        // ("ENOENT: no such file or directory, open '<path>'") that update_status
+        // was previously appending "Transition blocked..." to verbatim.
+        const isMissingFile = typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT';
+        return readinessUnavailable('READINESS_SPEC_UNREADABLE', isMissingFile
+            ? `spec.md is missing at ${spec.specPath}. Recreate the spec via create_spec or restore spec.md from git/backup before retrying this transition.`
+            : error instanceof Error
+                ? error.message
+                : 'spec.md could not be read');
     }
     // Guard: mock environments return undefined; unreadable files return non-string
     if (typeof body !== 'string') {
@@ -331,18 +343,21 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
             qualityWarnings: [],
         };
     }
-    let score;
-    let warnings;
-    let criteriaCount;
+    let readiness;
     try {
-        ({ score, warnings, criteriaCount } = checkReadinessInternal(body));
+        readiness = await checkSpecReadiness(spec, 'strict');
     }
     catch (error) {
         /* reliability-optional: READINESS_EVALUATION_FAILED — transition fails closed below */
         reportClassifiedDegradation('READINESS_EVALUATION_FAILED', error);
         return readinessUnavailable('READINESS_EVALUATION_FAILED', error instanceof Error ? error.message : 'readiness evaluation failed');
     }
-    if (criteriaCount === 0) {
+    const { score } = readiness;
+    const blockers = [...readiness.issues.blockers];
+    const warnings = [...readiness.issues.warnings];
+    const issues = [...blockers, ...warnings];
+    const hasNoCriteria = readiness.issues.breakdown.criteria === 0;
+    if (hasNoCriteria) {
         if (newStatus === 'review') {
             return {
                 blockResult: {
@@ -357,6 +372,7 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
                         error: 'READINESS_GATE_BLOCKED',
                         score,
                         threshold: 70,
+                        blockers,
                         warnings,
                         fixHint: 'Add at least 3 testable acceptance criteria before moving to review.',
                     },
@@ -388,24 +404,32 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
                     },
                 ],
                 structuredContent: {
+                    error: 'READINESS_GATE_BLOCKED',
+                    score,
+                    threshold: 70,
+                    blockers,
+                    warnings,
                     interactiveQuestions: [question],
                 },
             },
             qualityWarnings: [],
         };
     }
-    if (score >= 70) {
+    if (readiness.ready) {
         return { blockResult: null, qualityWarnings: [] };
     }
+    const diagnostic = score < 70
+        ? `score ${String(score)}/100 is below the 70 threshold`
+        : `score ${String(score)}/100 meets the threshold, but ${String(blockers.length)} canonical blocker(s) remain`;
+    const issuesSummary = issues.slice(0, 3).join('; ');
     if (newStatus === 'review') {
-        const warningsSummary = warnings.slice(0, 3).join('; ');
         return {
             blockResult: {
                 content: [
                     {
                         type: 'text',
-                        text: `Readiness gate blocked transition to review: score ${String(score)}/100 — below 70 threshold. ` +
-                            `Warnings: ${warningsSummary}`,
+                        text: `Readiness gate blocked transition to review: ${diagnostic}. ` +
+                            `Issues: ${issuesSummary}`,
                     },
                 ],
                 isError: true,
@@ -413,6 +437,7 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
                     error: 'READINESS_GATE_BLOCKED',
                     score,
                     threshold: 70,
+                    blockers,
                     warnings,
                     fixHint: 'Complete the spec before moving from draft to review.',
                 },
@@ -423,12 +448,11 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
     // Score < 70
     if (forceApprove) {
         // Caller wants to force through — proceed with warnings attached
-        return { blockResult: null, qualityWarnings: warnings };
+        return { blockResult: null, qualityWarnings: issues };
     }
-    const warningsSummary = warnings.slice(0, 3).join('; ');
     const question = {
         header: 'Readiness gate',
-        question: `Spec readiness score ${String(score)}/100 (threshold: 70). How to proceed?`,
+        question: `Spec readiness ${diagnostic}. How to proceed?`,
         multiSelect: false,
         options: [
             {
@@ -437,7 +461,7 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
             },
             {
                 label: 'view_missing',
-                description: `View missing items: ${warningsSummary}`,
+                description: `View missing items: ${issuesSummary}`,
             },
             {
                 label: 'force_approve',
@@ -450,10 +474,15 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
             content: [
                 {
                     type: 'text',
-                    text: `Readiness gate: score ${String(score)}/100 — below 70 threshold. Warnings: ${warningsSummary}`,
+                    text: `Readiness gate: ${diagnostic}. Issues: ${issuesSummary}`,
                 },
             ],
             structuredContent: {
+                error: 'READINESS_GATE_BLOCKED',
+                score,
+                threshold: 70,
+                blockers,
+                warnings,
                 interactiveQuestions: [question],
             },
         },

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

@@ -1,6 +1,7 @@
 import type { ConstitutionViolation } from '../types/index.js';
 export declare function runImplementingActions(projectId: string, specId: string, options?: {
     deferSideEffects?: boolean;
+    projectPath?: string;
 }): Promise<{
     autoBranch: string | undefined;
     protectedBranchWarning: string | null;
@@ -8,9 +9,10 @@ export declare function runImplementingActions(projectId: string, specId: string
     autopilotSummary: string[];
 }>;
 /** Create the implementation branch and refresh derived context after commit. */
-export declare function runImplementingSideEffects(projectId: string, specId: string): Promise<string | undefined>;
+export declare function runImplementingSideEffects(projectId: string, specId: string, transitionProjectPath?: string): Promise<string | undefined>;
 export declare function runDoneActions(projectId: string, specId: string, gitBranch: string | undefined, options?: {
     deferSideEffects?: boolean;
+    projectPath?: string;
 }): Promise<{
     mergeWarning: string | null;
     prSuggestion: {
@@ -22,7 +24,7 @@ export declare function runDoneActions(projectId: string, specId: string, gitBra
     autopilotSummary: string[];
 }>;
 /** Run cleanup and state refreshes only after the done transition is durable. */
-export declare function runDoneSideEffects(projectId: string, specId: string, gitBranch: string | undefined): Promise<void>;
+export declare function runDoneSideEffects(projectId: string, specId: string, gitBranch: string | undefined, transitionProjectPath?: string): Promise<void>;
 /**
  * Best-effort constitution compliance check for status transitions.
  * Returns warnings (never blocks the transition).

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

@@ -8,13 +8,17 @@ function normalizeRejectedReasons(results) {
         return reason instanceof Error ? reason : new Error(String(reason));
     });
 }
+function suppliedProjectPath(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
 export async function runImplementingActions(projectId, specId, options = {}) {
     let autoBranch;
     let protectedBranchWarning = null;
     // Check if on a protected branch
     try {
         const { resolveProjectPath, git: gitCmd } = await import('./git/git-helpers.js');
-        const projectPath = await resolveProjectPath(projectId);
+        const projectPath = suppliedProjectPath(options.projectPath) ?? (await resolveProjectPath(projectId));
         const { stdout } = await gitCmd(projectPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
         const currentBranch = stdout.trim();
         const protectedBranches = ['main', 'master', 'develop', 'production'];
@@ -27,7 +31,7 @@ export async function runImplementingActions(projectId, specId, options = {}) {
     }
     if (!options.deferSideEffects) {
         try {
-            autoBranch = await runImplementingSideEffects(projectId, specId);
+            autoBranch = await runImplementingSideEffects(projectId, specId, options.projectPath);
         }
         catch {
             // Legacy direct callers keep best-effort behavior.
@@ -41,20 +45,20 @@ export async function runImplementingActions(projectId, specId, options = {}) {
     };
 }
 /** Create the implementation branch and refresh derived context after commit. */
-export async function runImplementingSideEffects(projectId, specId) {
+export async function runImplementingSideEffects(projectId, specId, transitionProjectPath) {
+    const { resolveProjectPath } = await import('./git/git-helpers.js');
+    const projectPath = suppliedProjectPath(transitionProjectPath) ?? (await resolveProjectPath(projectId));
     let autoBranch;
     const foundSpec = await specStore.getSpec(projectId, specId);
     if (foundSpec && !foundSpec.gitBranch) {
         let branchResult;
         try {
-            const { resolveProjectPath: resolveBranchPath } = await import('./git/git-helpers.js');
             const { handleCreateBranch } = await import('./git/branch-ops.js');
-            const branchProjectPath = await resolveBranchPath(projectId);
-            branchResult = await withAudit(branchProjectPath, 'update_status(implementing)', 'handleCreateBranch', () => handleCreateBranch(projectId, specId), (r) => ({ isError: r.isError }));
+            branchResult = await withAudit(projectPath, 'update_status(implementing)', 'handleCreateBranch', () => handleCreateBranch(projectId, specId, undefined, projectPath), (r) => ({ isError: r.isError }));
         }
         catch {
             const { handleCreateBranch } = await import('./git/branch-ops.js');
-            branchResult = await handleCreateBranch(projectId, specId);
+            branchResult = await handleCreateBranch(projectId, specId, undefined, projectPath);
         }
         if (!branchResult.isError) {
             try {
@@ -70,8 +74,6 @@ export async function runImplementingSideEffects(projectId, specId) {
     // SPEC-600: Fire-and-forget cascade — recommend_model, orchestration plan, context check
     // -------------------------------------------------------------------------
     try {
-        const { resolveProjectPath: resolveCascadePath } = await import('./git/git-helpers.js');
-        const projectPath = await resolveCascadePath(projectId);
         const spec = foundSpec ?? (await specStore.getSpec(projectId, specId));
         const results = await Promise.allSettled([
             // SPEC-633: Write session state when spec moves to implementing
@@ -161,7 +163,7 @@ export async function runDoneActions(projectId, specId, gitBranch, options = {})
         (async () => {
             try {
                 const { resolveProjectPath, git: gitCmd } = await import('./git/git-helpers.js');
-                const projectPath = await resolveProjectPath(projectId);
+                const projectPath = suppliedProjectPath(options.projectPath) ?? (await resolveProjectPath(projectId));
                 if (process.env.PLANU_ENABLE_AUTOCOMMIT === 'true') {
                     await gitCmd(projectPath, ['add', 'planu/']);
                     const { planuAutoCommit } = await import('../engine/git/planu-autocommit.js');
@@ -193,7 +195,7 @@ export async function runDoneActions(projectId, specId, gitBranch, options = {})
         const mergeResult = await Promise.resolve((async () => {
             try {
                 const { resolveProjectPath, resolveBaseBranch, git: gitCmd, } = await import('./git/git-helpers.js');
-                const projectPath = await resolveProjectPath(projectId);
+                const projectPath = suppliedProjectPath(options.projectPath) ?? (await resolveProjectPath(projectId));
                 await gitCmd(projectPath, ['rev-parse', '--verify', gitBranch]);
                 const baseBranch = await resolveBaseBranch(projectPath);
                 if (!baseBranch) {
@@ -213,7 +215,7 @@ export async function runDoneActions(projectId, specId, gitBranch, options = {})
         mergeWarning = mergeResult;
     }
     if (!options.deferSideEffects) {
-        void runDoneSideEffects(projectId, specId, gitBranch).catch(() => {
+        void runDoneSideEffects(projectId, specId, gitBranch, options.projectPath).catch(() => {
             // Legacy direct callers keep best-effort behavior.
         });
     }
@@ -231,9 +233,9 @@ export async function runDoneActions(projectId, specId, gitBranch, options = {})
     };
 }
 /** Run cleanup and state refreshes only after the done transition is durable. */
-export async function runDoneSideEffects(projectId, specId, gitBranch) {
+export async function runDoneSideEffects(projectId, specId, gitBranch, transitionProjectPath) {
     const { resolveProjectPath } = await import('./git/git-helpers.js');
-    const projectPath = await resolveProjectPath(projectId);
+    const projectPath = suppliedProjectPath(transitionProjectPath) ?? (await resolveProjectPath(projectId));
     const results = await Promise.allSettled([
         (async () => {
             const { cleanupSpecOnDone } = await import('./git/cleanup-ops.js');

package/dist/tools/usage-report.js

@@ -3,28 +3,13 @@
 import { usageStore } from '../storage/index.js';
 import { filterEventsByPeriod } from '../engine/usage-tracker/core.js';
 import { calculateUsageStats, formatStatsAsMarkdown } from '../engine/usage-tracker/stats.js';
-import { calculateDaysSinceFirstRun, isTrialActive } from '../engine/usage-tracker/trial.js';
-import { getCurrentTier } from './license-gate.js';
 import { compactJson, compactResult } from './output-formatter.js';
 export async function handleUsageReport(args) {
     const format = args.format ?? 'markdown';
-    const tier = await getCurrentTier();
-    // Gather data from storage
     const usageLog = await usageStore.getUsageLog();
-    const trialState = await usageStore.ensureTrialState();
-    const today = new Date().toISOString().slice(0, 10);
-    const todayCount = await usageStore.getDailyCallCount(today);
-    // Compute context values
-    const daysSinceFirstRun = calculateDaysSinceFirstRun(trialState.firstRunAt);
-    const trialActive = isTrialActive(trialState.firstRunAt);
-    let remainingDailyCalls = -1;
-    if (tier === 'free') {
-        const dailyLimit = trialActive ? 50 : 30;
-        remainingDailyCalls = Math.max(0, dailyLimit - todayCount);
-    }
     // Full report uses all events
     const allEvents = filterEventsByPeriod(usageLog.events, 'all');
-    const stats = calculateUsageStats(allEvents, 0, 0, tier, daysSinceFirstRun, trialActive, remainingDailyCalls);
+    const stats = calculateUsageStats(allEvents, 0, 0);
     if (format === 'json') {
         return compactResult(compactJson(stats));
     }

package/dist/tools/usage-stats.js

@@ -3,32 +3,15 @@
 import { usageStore } from '../storage/index.js';
 import { filterEventsByPeriod } from '../engine/usage-tracker/core.js';
 import { calculateUsageStats, formatStatsAsMarkdown } from '../engine/usage-tracker/stats.js';
-import { calculateDaysSinceFirstRun, isTrialActive } from '../engine/usage-tracker/trial.js';
-import { getCurrentTier } from './license-gate.js';
 import { addNextSteps } from './response-helpers.js';
 import { t } from '../i18n/index.js';
 export async function handleUsageStats(args) {
     const period = args.period ?? '30d';
-    const tier = await getCurrentTier();
-    // Gather data from storage
     const usageLog = await usageStore.getUsageLog();
-    const trialState = await usageStore.ensureTrialState();
-    const today = new Date().toISOString().slice(0, 10);
-    const todayCount = await usageStore.getDailyCallCount(today);
-    // Compute context values
-    const daysSinceFirstRun = calculateDaysSinceFirstRun(trialState.firstRunAt);
-    const trialActive = isTrialActive(trialState.firstRunAt);
-    // Remaining daily calls: only relevant for Starter tier
-    let remainingDailyCalls = -1;
-    if (tier === 'free') {
-        const dailyLimit = trialActive ? 50 : 30;
-        remainingDailyCalls = Math.max(0, dailyLimit - todayCount);
-    }
     // Filter events by period and calculate stats
     const filteredEvents = filterEventsByPeriod(usageLog.events, period);
     const stats = calculateUsageStats(filteredEvents, 0, // activeSpecs — placeholder, no cross-layer access to spec store
-    0, // activeProjects — placeholder
-    tier, daysSinceFirstRun, trialActive, remainingDailyCalls);
+    0);
     const markdown = formatStatsAsMarkdown(stats);
     const header = t('tools.response.statsTitle');
     const withHeader = `${header}\n\n${markdown}`;

package/dist/tools/usage-tracking.d.ts

@@ -0,0 +1,4 @@
+import type { ToolResult } from '../types/index.js';
+/** Record local tool health without entitlement, tier, trial, or quota behavior. */
+export declare function withUsageTracking<T>(toolName: string, handler: (args: T, extra?: unknown) => Promise<ToolResult>): (args: T, extra?: unknown) => Promise<ToolResult>;
+//# sourceMappingURL=usage-tracking.d.ts.map

package/dist/tools/usage-tracking.js

@@ -0,0 +1,20 @@
+import { recordUsageEvent } from '../engine/usage-tracker/index.js';
+import * as usageStore from '../storage/usage-store.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
+/** Record local tool health without entitlement, tier, trial, or quota behavior. */
+export function withUsageTracking(toolName, handler) {
+    return async (args, extra) => {
+        const rawResult = (await handler(args, extra));
+        const result = rawResult ?? {
+            content: [{ type: 'text', text: 'Internal error: tool handler returned no result' }],
+            isError: true,
+        };
+        void usageStore
+            .appendUsageEvent(recordUsageEvent(toolName, result.isError !== true))
+            .catch((error) => {
+            reportClassifiedDegradation('USAGE_EVENT_WRITE_FAILED', error);
+        });
+        return result;
+    };
+}
+//# sourceMappingURL=usage-tracking.js.map

package/dist/tools/validate-lint.d.ts

@@ -2,6 +2,7 @@ import type { LintCheckResult } from '../types/index.js';
 interface LintCheckContext {
     projectId?: string;
     specId?: string;
+    maximumTimeoutMs?: number;
 }
 export declare function runLintCheck(projectPath: string, lintCommand: string | null, context?: LintCheckContext): Promise<LintCheckResult>;
 export {};

package/dist/tools/validate-lint.js

@@ -80,7 +80,7 @@ export async function runLintCheck(projectPath, lintCommand, context = {}) {
             };
         }
     }
-    const timeoutMs = lintCheckTimeoutMs();
+    const timeoutMs = Math.min(lintCheckTimeoutMs(), context.maximumTimeoutMs ?? Number.MAX_SAFE_INTEGER);
     try {
         const startedAt = Date.now();
         const processResult = await runProjectCommandPlan(plan, projectPath, timeoutMs, getToolExecutionSignal());

package/dist/tools/validate.d.ts

@@ -1,9 +1,10 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { validateContractCompliance } from '../engine/test-scaffold-generator.js';
 import type { ValidateInput, ToolResult, ContractSpec, ContractValidation } from '../types/index.js';
+import type { ValidateWorkerProgress } from '../types/validate-worker.js';
 export { validateContractCompliance };
 export type { ContractSpec, ContractValidation };
 /** Public MCP boundary: persist and acknowledge validation work without running it inline. */
 export declare function handleValidate(args: ValidateInput): Promise<ToolResult>;
-export declare function executeValidate(args: ValidateInput, server?: McpServer): Promise<ToolResult>;
+export declare function executeValidate(args: ValidateInput, server?: McpServer, onProgress?: (progress: ValidateWorkerProgress) => void): Promise<ToolResult>;
 //# sourceMappingURL=validate.d.ts.map