@planu/cli 5.3.52 → 5.3.55

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

@@ -17,7 +17,7 @@ import { formatKeyValue } from '../output-formatter.js';
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { verifyCurrentDoneReceipt } from './done-receipt-verifier.js';
 import { projectDataDir } from '../../storage/base-store.js';
-import { readTransitionLog } from '../../storage/transition-log.js';
+import { readTransitionLog, transitionLogPath } from '../../storage/transition-log.js';
 import { ImplementationReviewV1Schema, ReviewFeedbackV1Schema, ValidationReportV1Schema, } from '../../engine/handoff-artifacts/schemas.js';
 import { renderSchemaSkeleton } from '../../engine/handoff-artifacts/schema-skeleton.js';
 export { completedJobPublishesReceipt } from './done-receipt-verifier.js';
@@ -30,6 +30,11 @@ function lazyTemplate(render) {
         return cached;
     };
 }
+function schemaBlockers(errors) {
+    return errors
+        .filter((issue) => issue.code !== 'ARTIFACT_NOT_FOUND' && issue.code !== 'INVALID_JSON')
+        .map((issue) => `${issue.path}: ${issue.message}`);
+}
 export const reviewFeedbackTemplate = lazyTemplate(() => renderSchemaSkeleton(ReviewFeedbackV1Schema, {
     overrides: {
         schema_version: HANDOFF_ARTIFACT_TEMPLATE_SCHEMA_VERSION,
@@ -525,6 +530,7 @@ export async function readApprovedValidationReportGate(specId, projectId, force)
                     error: 'validation_report_invalid',
                     message: 'The validation-report artifact is malformed or uses an obsolete schema. Re-run validate so Planu can generate reviewer evidence.',
                     gates: [],
+                    blockers: schemaBlockers(result.errors),
                     fixHint: 'Re-run validate for this spec. The report must include reviewer evidence and passing gates.',
                     template: validationReportTemplate(),
                 }),
@@ -602,7 +608,7 @@ export async function checkSpecReviewGate(specId, projectId, _forceApprove) {
                 message: firstErr?.code === 'ARTIFACT_NOT_FOUND'
                     ? 'No spec review feedback exists for this spec. An independent planu-spec-reviewer must review the spec and write its evidence before approval.'
                     : 'Spec review feedback is malformed or uses an obsolete schema.',
-                blockers: [],
+                blockers: schemaBlockers(result.errors),
                 fixHint: firstErr?.code === 'ARTIFACT_NOT_FOUND'
                     ? 'Have planu-spec-reviewer write review_feedback.md (ReviewFeedbackV1) into the handoff store, then retry update_status(approved).'
                     : 'Have planu-spec-reviewer rewrite review_feedback.md as valid ReviewFeedbackV1 evidence, then retry approval.',
@@ -666,7 +672,7 @@ export async function checkImplementationReviewGate(specId, projectId, _force) {
                 message: firstErr?.code === 'ARTIFACT_NOT_FOUND'
                     ? 'No implementation review exists for this spec. An independent planu-implementation-reviewer must review the implementation and write its own evidence before done.'
                     : 'Implementation review evidence is malformed or uses an obsolete schema.',
-                blockers: [],
+                blockers: schemaBlockers(result.errors),
                 fixHint: firstErr?.code === 'ARTIFACT_NOT_FOUND'
                     ? 'Have planu-implementation-reviewer write implementation_review.json (ImplementationReviewV1) into the handoff store, then retry update_status(done).'
                     : 'Have planu-implementation-reviewer rewrite implementation_review.json as valid ImplementationReviewV1 evidence, then retry done.',
@@ -704,7 +710,22 @@ export async function checkImplementationReviewGate(specId, projectId, _force) {
                 fixHint: 'Have planu-implementation-reviewer (with the recognized identity) write the review artifact, then retry done.',
             });
         }
-        const implementerActor = await findImplementingActor(specId, projectId);
+        let implementerActor;
+        try {
+            implementerActor = await findImplementingActor(specId, projectId);
+        }
+        catch (err) {
+            /* reliability-optional: TRANSITION_LOG_GATE_READ — typed gate error blocks done */
+            reportClassifiedDegradation('TRANSITION_LOG_GATE_READ', err);
+            return implementationReviewGateError({
+                specId,
+                error: 'implementing_actor_unreadable',
+                message: `Could not read the transition log to find the implementing actor: ${err instanceof Error ? err.message : String(err)}`,
+                blockers: [],
+                fixHint: 'Fix the transition log so it can be read, then retry update_status(done).',
+                artifactPath: transitionLogPath(projectId),
+            });
+        }
         if (implementerActor !== undefined && implementerActor === review.reviewer.agent) {
             return implementationReviewGateError({
                 specId,
@@ -739,7 +760,8 @@ async function findImplementingActor(specId, projectId) {
     return undefined;
 }
 function implementationReviewGateError(args) {
-    const artifactPath = `external Planu project data: handoffs/${args.specId}/implementation_review.json`;
+    const artifactPath = args.artifactPath ??
+        `external Planu project data: handoffs/${args.specId}/implementation_review.json`;
     return {
         content: [
             {
@@ -766,6 +788,7 @@ function implementationReviewGateError(args) {
 }
 function validationReportGateError(args) {
     const artifactPath = `external Planu project data: handoffs/${args.specId}/validation-report.json`;
+    const blockerCount = args.blockers && args.blockers.length > 0 ? args.blockers.length : undefined;
     return {
         content: [
             {
@@ -776,6 +799,8 @@ function validationReportGateError(args) {
                     artifactPath,
                     failedGates: args.gates.filter((gate) => !gate.passed).length,
                     totalGates: args.gates.length,
+                    blockers: blockerCount,
+                    firstBlocker: args.blockers?.[0],
                     fixHint: args.fixHint,
                 }, 'Validation report gate failed'),
             },
@@ -784,7 +809,12 @@ function validationReportGateError(args) {
         structuredContent: {
             error: args.error,
             code: 422,
-            context: { specId: args.specId, artifactPath, gates: args.gates },
+            context: {
+                specId: args.specId,
+                artifactPath,
+                gates: args.gates,
+                ...(args.blockers ? { blockers: args.blockers } : {}),
+            },
             fixHint: args.fixHint,
             ...(args.template ? { template: args.template } : {}),
         },

package/dist/tools/update-status/file-sync.d.ts

@@ -12,6 +12,7 @@ export interface FrontmatterSyncWarning {
 }
 export declare function syncSpecFiles(updatedSpec: Spec, _currentStatus: SpecStatus, newStatus: SpecStatus, projectPath?: string, qualityWarnings?: readonly string[]): Promise<{
     warning?: FrontmatterSyncWarning;
+    title?: string;
 }>;
 export declare function tryReconcile(newStatus: string, specId: string, projectId: string): Promise<string | null>;
 /**

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

@@ -75,6 +75,24 @@ async function autoCaptureLessonEstimation(spec, actuals, accuracy, projectId, p
 }
 const SPEC_BODY_SHRINK_ABSOLUTE_THRESHOLD = 200;
 const SPEC_BODY_SHRINK_RATIO_THRESHOLD = 0.05;
+const SPEC_ARTIFACT_ABSENT_CODE = 'SPEC_ARTIFACT_ABSENT';
+function specArtifactAbsentError() {
+    const error = new Error('Spec artifact is absent');
+    error.code = SPEC_ARTIFACT_ABSENT_CODE;
+    return error;
+}
+function isAbsentSpecArtifactFailure(err, resolvedArtifactPath) {
+    if (!(err instanceof Error)) {
+        return false;
+    }
+    const code = err.code;
+    if (code === SPEC_ARTIFACT_ABSENT_CODE) {
+        return true;
+    }
+    return (code === 'ENOENT' &&
+        resolvedArtifactPath !== undefined &&
+        err.path === resolvedArtifactPath);
+}
 async function resolveSpecPathForTransition(spec, projectPath) {
     if (!projectPath) {
         return spec.specPath;
@@ -100,11 +118,16 @@ async function resolveSpecPathForTransition(spec, projectPath) {
         isAbsolute(relativeCandidate)) {
         throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath escapes the selected root');
     }
-    const [rootRealpath, candidateRealpath, candidateStat] = await Promise.all([
-        realpath(selectedRoot),
+    const rootRealpath = await realpath(selectedRoot);
+    const [candidateRealpath, candidateStat] = await Promise.all([
         realpath(candidate),
         lstat(candidate),
-    ]);
+    ]).catch((err) => {
+        if (err instanceof Error && err.code === 'ENOENT') {
+            throw specArtifactAbsentError();
+        }
+        throw err;
+    });
     const realRelative = relative(rootRealpath, candidateRealpath);
     if (candidateStat.isSymbolicLink() ||
         !candidateStat.isFile() ||
@@ -138,15 +161,20 @@ function assertSpecBodyIntegrity(args) {
 }
 export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, projectPath, qualityWarnings = []) {
     let warning;
+    let refreshedTitle;
+    let transitionSpecPath;
     if (updatedSpec.specPath) {
         try {
-            const transitionSpecPath = await resolveSpecPathForTransition(updatedSpec, projectPath);
+            transitionSpecPath = await resolveSpecPathForTransition(updatedSpec, projectPath);
             const specContent = await readFile(transitionSpecPath, 'utf-8');
-            if (projectPath) {
-                const parsedId = parseFrontmatter(specContent).metadata.id;
-                if (parsedId !== updatedSpec.id) {
-                    throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: spec frontmatter ID does not match');
-                }
+            const parsedMetadata = parseFrontmatter(specContent).metadata;
+            if (projectPath && parsedMetadata.id !== updatedSpec.id) {
+                throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: spec frontmatter ID does not match');
+            }
+            if (typeof parsedMetadata.title === 'string' &&
+                parsedMetadata.title.trim() !== '' &&
+                parsedMetadata.title !== updatedSpec.title) {
+                refreshedTitle = parsedMetadata.title;
             }
             const { updateFrontmatterField } = await import('../../engine/frontmatter-parser.js');
             let updatedContent = updateFrontmatterField(specContent, 'status', newStatus);
@@ -191,19 +219,23 @@ export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, proj
             }
         }
         catch (err) {
-            /* reliability-optional: SPEC_FRONTMATTER_SYNC — warning is returned to the caller */
+            if (newStatus === 'discarded' && isAbsentSpecArtifactFailure(err, transitionSpecPath)) {
+                return {};
+            }
             const msg = redactFailureMessage(err);
-            // SPEC-698: log AND surface the warning so the user sees it in the tool response
             reportClassifiedDegradation('SPEC_FRONTMATTER_SYNC', err);
             warning = { specId: updatedSpec.id, specPath: updatedSpec.specPath, reason: msg };
         }
     }
-    else {
+    else if (newStatus !== 'discarded') {
         const reason = 'specPath not set on spec — spec.md not updated on disk. Run reconcile_spec to re-link this spec to its file.';
         console.warn(`[Planu] update_status: ${reason} (${updatedSpec.id})`);
         warning = { specId: updatedSpec.id, specPath: null, reason };
     }
-    return warning ? { warning } : {};
+    if (warning) {
+        return { warning };
+    }
+    return refreshedTitle ? { title: refreshedTitle } : {};
 }
 /** Flip all `    done: false` lines to `    done: true` in spec content.
  * Safe: in lean YAML spec, `done: false` only appears inside criteria items. */

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

@@ -9,7 +9,7 @@ import { cascadeCheck } from '../../engine/spec-versioner.js';
 import { runComplianceGates } from '../update-status-convention-gate.js';
 import { runDoneActions, runDoneSideEffects, runImplementingActions, runImplementingSideEffects, } from '../update-status-actions.js';
 import { compactObj } from '../../engine/compact-obj.js';
-import { checkTransition, checkDorGate, checkAmbiguityGate, checkReadinessGate, checkChallengeGate, checkImplementationDependencyGate, resolveAutoAdvanceSteps, isReverseTransition, validateReverseTransition, } from './transition-guard.js';
+import { checkTransition, checkDorGate, checkAmbiguityGate, checkReadinessGate, checkChallengeGate, checkImplementationDependencyGate, checkSpecArtifactCommittedGate, resolveAutoAdvanceSteps, isReverseTransition, validateReverseTransition, } from './transition-guard.js';
 import { checkApprovedDepGate } from '../../engine/dep-guard/index.js';
 import { checkApprovalGate } from '../../engine/approval-workflow.js';
 import * as approvalStore from '../../storage/approval-store.js';
@@ -667,6 +667,10 @@ async function commitTransitionWithNarrowLock(args) {
             const updatedSpec = transitionRecord.spec;
             const syncResult = await syncSpecFiles(updatedSpec, args.originalStatus, args.newStatus, args.projectPath, args.qualityWarnings);
             if (!syncResult.warning) {
+                if (syncResult.title) {
+                    updatedSpec.title = syncResult.title;
+                    await specStore.updateSpec(args.projectId, args.specId, { title: syncResult.title });
+                }
                 return { ok: true, transitionRecord, updatedSpec };
             }
             try {
@@ -959,6 +963,10 @@ export async function handleUpdateStatus(params, server) {
                         if (dependencyGate) {
                             return dependencyGate;
                         }
+                        const specArtifactGate = await checkSpecArtifactCommittedGate(spec, 'implementing', transitionProjectPath);
+                        if (specArtifactGate) {
+                            return specArtifactGate;
+                        }
                     }
                     // SPEC-964: Challenge gate — block 'review' if challenge_spec was never run
                     const challengeGateStatus = plannedStatuses.includes('review') ? 'review' : newStatus;
@@ -1344,6 +1352,9 @@ export async function handleUpdateStatus(params, server) {
                         return persistence.error;
                     }
                     const { transitionRecord, updatedSpec } = persistence;
+                    if (updatedSpec.title && updatedSpec.title !== spec.title) {
+                        spec.title = updatedSpec.title;
+                    }
                     const frontmatterSyncWarnings = [];
                     const transitionId = transitionRecord.transitionId;
                     const committedAt = transitionRecord.timestamp;

package/dist/tools/update-status/transition-guard.d.ts

@@ -60,6 +60,7 @@ export declare function checkImplementationDependencyGate(spec: Spec, allSpecs:
  * Fails closed when the spec cannot be scored.
  */
 export declare function checkAmbiguityGate(spec: Spec, newStatus: SpecStatus): Promise<ToolResult | null>;
+export declare function checkSpecArtifactCommittedGate(spec: Spec, newStatus: SpecStatus, projectPath: string | undefined): Promise<ToolResult | null>;
 /**
  * SPEC-769/SPEC-492: Readiness gate — block 'review'/'approved' when spec
  * quality is too low or the persisted spec document is not English.

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

@@ -1,5 +1,6 @@
 // tools/update-status/transition-guard.ts — Valid state transitions and DoR gate
 import { readFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
 import { ti } from '../../i18n/index.js';
 import { validateDoR } from '../../engine/dor-dod.js';
 import { dispatchFeedbackEvent } from '../learn.js';
@@ -232,6 +233,47 @@ export async function checkAmbiguityGate(spec, newStatus) {
         },
     };
 }
+export async function checkSpecArtifactCommittedGate(spec, newStatus, projectPath) {
+    if (newStatus !== 'implementing' || !projectPath || !spec.specPath) {
+        return null;
+    }
+    const absoluteSpecPath = isAbsolute(spec.specPath)
+        ? spec.specPath
+        : join(projectPath, spec.specPath);
+    try {
+        const { git } = await import('../git/git-helpers.js');
+        const { stdout } = await git(projectPath, ['status', '--porcelain', '--', absoluteSpecPath]);
+        if (stdout.trim().length === 0) {
+            return null;
+        }
+    }
+    catch (error) {
+        reportClassifiedDegradation('SPEC_ARTIFACT_GIT_STATUS_UNAVAILABLE', error);
+        return null;
+    }
+    const fixHint = `Commit ${absoluteSpecPath} (git add "${absoluteSpecPath}" && git commit) then retry update_status(specId: "${spec.id}", status: "implementing").`;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: formatKeyValue({
+                    error: 'SPEC_ARTIFACT_UNCOMMITTED',
+                    message: `spec.md for ${spec.id} has uncommitted changes. The approved contract on disk must match what git holds before an implementer is dispatched.`,
+                    specId: spec.id,
+                    specPath: absoluteSpecPath,
+                    fixHint,
+                }),
+            },
+        ],
+        isError: true,
+        structuredContent: {
+            error: 'SPEC_ARTIFACT_UNCOMMITTED',
+            specId: spec.id,
+            specPath: absoluteSpecPath,
+            fixHint,
+        },
+    };
+}
 /**
  * SPEC-769/SPEC-492: Readiness gate — block 'review'/'approved' when spec
  * quality is too low or the persisted spec document is not English.
@@ -511,6 +553,7 @@ function gateUnavailableResult(code, message) {
 function readinessUnavailable(code, message, qualityWarnings = []) {
     return { blockResult: gateUnavailableResult(code, message), qualityWarnings };
 }
+const CHALLENGE_RESOLUTION_INSTRUCTIONS = 'Add a "### Challenge Resolution" subsection to the spec\'s spec.md with one "- " bullet per unresolved finding, each bullet containing that finding\'s exact scenario text plus your mitigation, then re-run challenge_spec to re-derive the report.';
 /**
  * SPEC-964: Challenge gate — block 'review' if challenge_spec was never run
  * or does not contain enough explicit resolution evidence.
@@ -584,7 +627,7 @@ export function checkChallengeGate(spec, newStatus) {
             content: [
                 {
                     type: 'text',
-                    text: `Challenge gate blocked: ${String(unresolvedCriticalCount)} unresolved critical finding(s) remain (addressed ${String(addressedCount)}/${String(requiredCount)} required). Record mitigation or accepted-risk evidence for every critical finding before retrying.`,
+                    text: `Challenge gate blocked: ${String(unresolvedCriticalCount)} unresolved critical finding(s) remain (addressed ${String(addressedCount)}/${String(requiredCount)} required). Record resolution evidence for every critical finding before retrying.`,
                 },
             ],
             isError: true,
@@ -595,7 +638,8 @@ export function checkChallengeGate(spec, newStatus) {
                 requiredCount,
                 unresolvedCount,
                 unresolvedCriticalCount,
-                fixHint: `Resolve every critical challenge_spec finding with concrete evidence, then retry update_status(specId="${spec.id}", status="review").`,
+                unresolvedCriticalIdentities: gateState.unresolvedCriticalIdentities,
+                fixHint: `${CHALLENGE_RESOLUTION_INSTRUCTIONS} Then retry update_status(specId="${spec.id}", status="review").`,
             },
         };
     }
@@ -604,7 +648,7 @@ export function checkChallengeGate(spec, newStatus) {
             content: [
                 {
                     type: 'text',
-                    text: `Challenge gate blocked: only ${String(addressedCount)} scenario(s) have explicit resolution evidence (minimum ${String(requiredCount)} required). Record mitigation or accepted-risk evidence for discovered findings before retrying.`,
+                    text: `Challenge gate blocked: only ${String(addressedCount)} scenario(s) have explicit resolution evidence (minimum ${String(requiredCount)} required). Record resolution evidence for discovered findings before retrying.`,
                 },
             ],
             isError: true,
@@ -613,7 +657,9 @@ export function checkChallengeGate(spec, newStatus) {
                 code: 'INSUFFICIENT_CHALLENGES',
                 addressedCount,
                 requiredCount,
-                fixHint: `Resolve challenge_spec findings with concrete evidence, then retry update_status(specId="${spec.id}", status="review").`,
+                unresolvedCount,
+                unresolvedIdentities: gateState.unresolvedIdentities,
+                fixHint: `${CHALLENGE_RESOLUTION_INSTRUCTIONS} Then retry update_status(specId="${spec.id}", status="review").`,
             },
         };
     }

package/dist/tools/validate.js

@@ -688,8 +688,11 @@ function buildExecutableCoverage(specCompliance) {
     const matches = specCompliance.scenarios
         .filter((scenario) => scenario.verdict === 'pass')
         .map((scenario) => scenario.title);
+    const indeterminate = specCompliance.scenarios
+        .filter((scenario) => scenario.verdict !== 'pass' && scenario.unverifiable)
+        .map((scenario) => scenario.title);
     const missing = specCompliance.scenarios
-        .filter((scenario) => scenario.verdict !== 'pass')
+        .filter((scenario) => scenario.verdict !== 'pass' && !scenario.unverifiable)
         .map((scenario) => scenario.title);
     return {
         score: specCompliance.score,
@@ -697,7 +700,7 @@ function buildExecutableCoverage(specCompliance) {
         fieldsTotal: specCompliance.scenarios.length,
         matches,
         missing,
-        indeterminate: [],
+        indeterminate,
     };
 }
 function buildEffectiveValidationResult(result, specCompliance) {

package/dist/types/handoff-artifacts.d.ts

@@ -86,6 +86,7 @@ export interface ValidationReportV1 {
             title: string;
             verdict: 'pass' | 'fail' | 'missing';
             evidence: string[];
+            unverifiable?: true;
         }[];
     };
     minimalityReport?: MinimalImplementationReport;
@@ -133,6 +134,7 @@ export type ReconciliationSpecSync = (spec: Spec, currentStatus: 'implementing'
     warning?: {
         reason: string;
     };
+    title?: string;
 }>;
 export interface ArtifactPayloadMap {
     intake: IntakeV1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.52",
+  "version": "5.3.55",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",

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": "5.3.52",
+  "version": "5.3.55",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",