@planu/cli 4.13.0 → 5.0.0

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

@@ -10,7 +10,7 @@ export interface FrontmatterSyncWarning {
     specPath: string | null;
     reason: string;
 }
-export declare function syncSpecFiles(updatedSpec: Spec, _currentStatus: SpecStatus, newStatus: SpecStatus, projectPath?: string): Promise<{
+export declare function syncSpecFiles(updatedSpec: Spec, _currentStatus: SpecStatus, newStatus: SpecStatus, projectPath?: string, qualityWarnings?: readonly string[]): Promise<{
     warning?: FrontmatterSyncWarning;
 }>;
 export declare function tryReconcile(newStatus: string, specId: string, projectId: string): Promise<string | null>;
@@ -32,5 +32,6 @@ export declare function recordTerminalTransitionEvent(args: {
     modelId?: string;
     gateResults?: Record<string, 'pass' | 'fail' | 'skip' | 'forced'>;
     meta?: Record<string, unknown>;
+    projectPath?: string;
 }): Promise<void>;
 //# sourceMappingURL=file-sync.d.ts.map

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

@@ -3,11 +3,13 @@ import { metricsStore } from '../../storage/index.js';
 import { addLesson, getLessons } from '../../storage/lessons-store.js';
 import { dispatchFeedbackEvent } from '../learn.js';
 import { autoReconcileOnDone } from '../update-status-reconcile.js';
-import { readFile } from 'node:fs/promises';
+import { lstat, readFile, realpath } from 'node:fs/promises';
 import { parseFrontmatter } from '../../engine/frontmatter-parser.js';
 import { computeFrontmatterSha } from '../../engine/frontmatter-sha/index.js';
 import { appendTransitionEvent } from '../../storage/transition-log.js';
 import { atomicWriteFile } from '../../engine/safety/atomic-write-file.js';
+import { isAbsolute, normalize, relative, resolve, sep } from 'node:path';
+import { redactFailureMessage, reportClassifiedDegradation, } from '../../errors/classified-degradation.js';
 export async function recordDoneMetrics(projectId, specId, spec, actuals, projectPath) {
     if (actuals.devHours + actuals.reviewHours === 0) {
         return;
@@ -34,7 +36,8 @@ export async function recordDoneMetrics(projectId, specId, spec, actuals, projec
             delta: { accuracyDrift: Math.abs(100 - accuracyScore) },
             timestamp: new Date().toISOString(),
         }).catch((err) => {
-            console.error('[planu] dispatchFeedbackEvent failed:', err);
+            /* reliability-optional: ACCURACY_FEEDBACK_EVENT — metric remains persisted locally */
+            reportClassifiedDegradation('ACCURACY_FEEDBACK_EVENT', err);
         });
     }
     if (accuracyScore < 70 && projectPath) {
@@ -65,12 +68,53 @@ async function autoCaptureLessonEstimation(spec, actuals, accuracy, projectId, p
             tags: [...spec.tags, 'auto-captured', 'estimation'],
         });
     }
-    catch {
-        /* best-effort — never throw */
+    catch (error) {
+        /* reliability-optional: ESTIMATION_GAP_CAPTURE — never block the committed transition */
+        reportClassifiedDegradation('ESTIMATION_GAP_CAPTURE', error);
     }
 }
 const SPEC_BODY_SHRINK_ABSOLUTE_THRESHOLD = 200;
 const SPEC_BODY_SHRINK_RATIO_THRESHOLD = 0.05;
+async function resolveSpecPathForTransition(spec, projectPath) {
+    if (!projectPath) {
+        return spec.specPath;
+    }
+    const normalizedPath = normalize(spec.specPath);
+    const segments = normalizedPath.split(sep).filter(Boolean);
+    const planuIndex = segments.lastIndexOf('planu');
+    const specDirectory = segments[planuIndex + 2];
+    const isPortableContract = planuIndex >= 0 &&
+        segments[planuIndex + 1] === 'specs' &&
+        segments[planuIndex + 3] === 'spec.md' &&
+        planuIndex + 4 === segments.length &&
+        specDirectory !== undefined &&
+        (specDirectory === spec.id || specDirectory.startsWith(`${spec.id}-`));
+    if (!isPortableContract) {
+        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath is not a portable spec contract');
+    }
+    const selectedRoot = resolve(projectPath);
+    const candidate = resolve(selectedRoot, 'planu', 'specs', specDirectory, 'spec.md');
+    const relativeCandidate = relative(selectedRoot, candidate);
+    if (relativeCandidate.startsWith(`..${sep}`) ||
+        relativeCandidate === '..' ||
+        isAbsolute(relativeCandidate)) {
+        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath escapes the selected root');
+    }
+    const [rootRealpath, candidateRealpath, candidateStat] = await Promise.all([
+        realpath(selectedRoot),
+        realpath(candidate),
+        lstat(candidate),
+    ]);
+    const realRelative = relative(rootRealpath, candidateRealpath);
+    if (candidateStat.isSymbolicLink() ||
+        !candidateStat.isFile() ||
+        realRelative.startsWith(`..${sep}`) ||
+        realRelative === '..' ||
+        isAbsolute(realRelative)) {
+        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath is not a contained regular file');
+    }
+    return candidateRealpath;
+}
 function bodyWithoutFrontmatter(content) {
     return parseFrontmatter(content).body;
 }
@@ -92,13 +136,23 @@ function assertSpecBodyIntegrity(args) {
         throw new Error(`SPEC_INTEGRITY_WRITE_FAILED: refusing to write ${args.specId} because update_status(${args.newStatus}) would shrink spec.md body by ${String(lost)} characters without an explicit migration marker.`);
     }
 }
-export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, projectPath) {
+export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, projectPath, qualityWarnings = []) {
     let warning;
     if (updatedSpec.specPath) {
         try {
-            const specContent = await readFile(updatedSpec.specPath, 'utf-8');
+            const 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 { updateFrontmatterField } = await import('../../engine/frontmatter-parser.js');
             let updatedContent = updateFrontmatterField(specContent, 'status', newStatus);
+            if (qualityWarnings.length > 0) {
+                updatedContent = updateFrontmatterField(updatedContent, 'qualityWarnings', JSON.stringify(qualityWarnings));
+            }
             if (newStatus === 'done') {
                 updatedContent = markAllCriteriaDone(updatedContent);
                 if (isLeanSpecContent(updatedContent)) {
@@ -111,7 +165,7 @@ export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, proj
                 newStatus,
                 specId: updatedSpec.id,
             });
-            await atomicWriteFile(updatedSpec.specPath, updatedContent);
+            await atomicWriteFile(transitionSpecPath, updatedContent);
             // SPEC-544: Auto-stage spec.md after writing so it's included in the user's next commit
             // SPEC-575: Auto-commit staged planu/ docs (idempotent, safe-fail)
             // Commit message must reflect the actual transition — 'mark-done' is only
@@ -122,7 +176,7 @@ export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, proj
                 process.env.PLANU_SUPPRESS_AUTOCOMMIT !== 'true') {
                 try {
                     const { git: gitCmd } = await import('../git/git-helpers.js');
-                    await gitCmd(projectPath, ['add', '--', updatedSpec.specPath]);
+                    await gitCmd(projectPath, ['add', '--', transitionSpecPath]);
                     const { planuAutoCommit } = await import('../../engine/git/planu-autocommit.js');
                     void planuAutoCommit({
                         projectPath,
@@ -130,15 +184,17 @@ export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, proj
                         reason: newStatus === 'done' ? 'mark-done' : 'status-update',
                     });
                 }
-                catch {
-                    // best-effort — never blocks the transition
+                catch (error) {
+                    // reliability-cleanup: MIGRATED_STATUS_CLEANUP — never blocks the transition
+                    reportClassifiedDegradation('MIGRATED_STATUS_CLEANUP', error);
                 }
             }
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
+            /* reliability-optional: SPEC_FRONTMATTER_SYNC — warning is returned to the caller */
+            const msg = redactFailureMessage(err);
             // SPEC-698: log AND surface the warning so the user sees it in the tool response
-            console.warn(`[Planu] update_status: failed to sync spec.md for ${updatedSpec.id} at ${updatedSpec.specPath}: ${msg}`);
+            reportClassifiedDegradation('SPEC_FRONTMATTER_SYNC', err);
             warning = { specId: updatedSpec.id, specPath: updatedSpec.specPath, reason: msg };
         }
     }
@@ -174,7 +230,11 @@ export async function tryReconcile(newStatus, specId, projectId) {
     if (newStatus !== 'done') {
         return null;
     }
-    return autoReconcileOnDone(specId, projectId).catch(() => null);
+    return autoReconcileOnDone(specId, projectId).catch((error) => {
+        // reliability-optional: DONE_AUTO_RECONCILE — explicit null reports unavailable enrichment
+        reportClassifiedDegradation('DONE_AUTO_RECONCILE', error);
+        return null;
+    });
 }
 /**
  * SPEC-723: Record a terminal transition event in the hash-chained log.
@@ -188,12 +248,13 @@ export async function recordTerminalTransitionEvent(args) {
         let frontmatterSha;
         if (args.specPath) {
             try {
-                const content = await readFile(args.specPath, 'utf-8');
+                const content = await readFile(await resolveSpecPathForTransition({ id: args.specId, specPath: args.specPath }, args.projectPath), 'utf-8');
                 const { metadata } = parseFrontmatter(content);
                 frontmatterSha = computeFrontmatterSha(metadata);
             }
-            catch {
-                // If we can't read the spec.md, compute from minimal metadata
+            catch (error) {
+                // reliability-compat: FRONTMATTER_SHA_READ — compute from minimal metadata
+                reportClassifiedDegradation('FRONTMATTER_SHA_READ', error);
                 frontmatterSha = undefined;
             }
         }
@@ -211,8 +272,9 @@ export async function recordTerminalTransitionEvent(args) {
             meta: args.meta,
         });
     }
-    catch {
-        // Best-effort — never throw from file-sync
+    catch (error) {
+        // reliability-optional: VALIDATION_REPORT_SYNC — committed lifecycle state remains authoritative
+        reportClassifiedDegradation('VALIDATION_REPORT_SYNC', error);
     }
 }
 //# sourceMappingURL=file-sync.js.map

package/dist/tools/update-status/gate-harness.d.ts

@@ -0,0 +1,7 @@
+export type UpdateStatusGate = 'evidence' | 'routing' | 'strict-layout';
+/**
+ * Production gates are never disabled by process environment. Legacy tests that
+ * need isolation must replace this module through their test runner.
+ */
+export declare function shouldSkipGateForExplicitLegacyHarness(_gate: UpdateStatusGate): boolean;
+//# sourceMappingURL=gate-harness.d.ts.map

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

@@ -0,0 +1,8 @@
+/**
+ * Production gates are never disabled by process environment. Legacy tests that
+ * need isolation must replace this module through their test runner.
+ */
+export function shouldSkipGateForExplicitLegacyHarness(_gate) {
+    return false;
+}
+//# sourceMappingURL=gate-harness.js.map

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

@@ -1,5 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { UpdateStatusInput, ToolResult } from '../../types/index.js';
+/** Bind deferred lifecycle work to one normalized absolute root without persisting that path. */
+export declare function computeTransitionRootBinding(projectPath: string): string;
 /** Recover durable post-commit work for every registered project after server startup. */
 export declare function recoverPendingPostCommitTasksAtStartup(): Promise<void>;
 export declare function handleUpdateStatus(params: UpdateStatusInput, server?: McpServer): Promise<ToolResult>;