@planu/cli 5.7.4 → 5.7.6

package/dist/tools/validate.js

@@ -162,10 +162,15 @@ export async function handleValidate(args) {
             },
         };
     }
-    const [spec, knowledge] = await Promise.all([
-        specStore.getSpec(projectId, args.specId),
-        knowledgeStore.getKnowledge(projectId),
-    ]);
+    const knowledge = await knowledgeStore.getKnowledge(projectId);
+    if (!knowledge) {
+        return {
+            content: [{ type: 'text', text: t('project.notFound') }],
+            isError: true,
+            structuredContent: { error: 'project_not_found', code: 404, context: { projectId } },
+        };
+    }
+    const spec = await specStore.getSpec(projectId, args.specId, knowledge.projectPath);
     if (!spec) {
         return {
             content: [{ type: 'text', text: ti('spec.notFound', { id: args.specId }) }],
@@ -177,13 +182,6 @@ export async function handleValidate(args) {
             },
         };
     }
-    if (!knowledge) {
-        return {
-            content: [{ type: 'text', text: t('project.notFound') }],
-            isError: true,
-            structuredContent: { error: 'project_not_found', code: 404, context: { projectId } },
-        };
-    }
     let validationWorktree;
     try {
         validationWorktree = await resolveValidationWorktree({
@@ -259,6 +257,11 @@ function validationWorktreeErrorResult(error, specId) {
                 specId: failure.specId,
                 ...(failure.relativeSpecPath ? { path: failure.relativeSpecPath } : {}),
             },
+            ...(failure.code === 'VALIDATION_STALE_SPEC_PATH'
+                ? {
+                    fixHint: `The spec registry still points at a stale checkout for ${failure.relativeSpecPath ?? 'this spec'}. Re-run validate from the canonical checkout (or call list_specs against the canonical projectPath) to self-heal the registry entry, then retry.`,
+                }
+                : {}),
         },
     };
 }
@@ -281,27 +284,30 @@ async function acquireValidationSubmissionLock(projectId, specId) {
 }
 function validationAcceptedResult(job, projectId, runtime, { justCreated }) {
     const observation = runtime.observe(job);
+    const reused = !justCreated;
     const accepted = {
         schemaVersion: 1,
         operationId: job.id,
         projectId,
         workspaceId: job.workspaceId,
         state: job.state,
-        submittedAt: job.createdAt,
-        attachedAt: justCreated ? job.createdAt : new Date().toISOString(),
+        submittedAt: justCreated ? job.updatedAt : job.createdAt,
+        attachedAt: justCreated ? job.updatedAt : new Date().toISOString(),
+        reused,
         cursor: publicJobCursor(observation),
         queue: observation.queue,
         terminalStates: ['completed', 'failed', 'cancelled', 'dead-letter'],
         resultSchema: 'validate-completion/v1',
         observation: {
             get: 'get_job',
-            watch: 'watch_job',
-            cancel: 'cancel_job',
             restart: 'restart_job',
         },
     };
+    const text = reused
+        ? `Attached to already-running validation job ${job.id}; no new work was scheduled. Follow it with get_job. To force re-execution after it reaches a terminal state, run validate again.`
+        : `Validation accepted as durable job ${job.id}.`;
     return {
-        content: [{ type: 'text', text: `Validation accepted as durable job ${job.id}.` }],
+        content: [{ type: 'text', text }],
         structuredContent: accepted,
     };
 }
@@ -313,29 +319,29 @@ export async function executeValidate(args, server, onProgress) {
     if (!projectId) {
         return missingProjectIdError;
     }
-    const spec = await specStore.getSpec(projectId, specId);
-    if (!spec) {
+    const knowledge = await knowledgeStore.getKnowledge(projectId);
+    if (!knowledge) {
         return {
-            content: [{ type: 'text', text: ti('spec.notFound', { id: specId }) }],
+            content: [{ type: 'text', text: t('project.notFound') }],
             isError: true,
             structuredContent: {
-                error: 'spec_not_found',
+                error: 'project_not_found',
                 code: 404,
-                context: { specId, projectId },
-                fixHint: `Verify the specId is correct and the spec exists in project ${projectId}.`,
+                context: { projectId },
+                fixHint: 'Run init_project first to initialize the project knowledge.',
             },
         };
     }
-    const knowledge = await knowledgeStore.getKnowledge(projectId);
-    if (!knowledge) {
+    const spec = await specStore.getSpec(projectId, specId, knowledge.projectPath);
+    if (!spec) {
         return {
-            content: [{ type: 'text', text: t('project.notFound') }],
+            content: [{ type: 'text', text: ti('spec.notFound', { id: specId }) }],
             isError: true,
             structuredContent: {
-                error: 'project_not_found',
+                error: 'spec_not_found',
                 code: 404,
-                context: { projectId },
-                fixHint: 'Run init_project first to initialize the project knowledge.',
+                context: { specId, projectId },
+                fixHint: `Verify the specId is correct and the spec exists in project ${projectId}.`,
             },
         };
     }

package/dist/transports/oauth-validator.js

@@ -3,6 +3,7 @@
 //   1. API key (SDD_OAUTH_API_KEY) — simplest: token must match env var
 //   2. HMAC-signed JWT (SDD_OAUTH_JWT_SECRET) — validates HS256 JWT signature
 // Configure via environment variables — no accounts or external services needed.
+import { timingSafeEqual } from 'node:crypto';
 export function loadOAuthConfig() {
     const apiKey = process.env.SDD_OAUTH_API_KEY;
     const jwtSecret = process.env.SDD_OAUTH_JWT_SECRET;
@@ -32,13 +33,23 @@ export async function validateToken(token, config) {
         return { valid: true };
     }
     if (config.mode === 'api-key') {
-        return token === config.apiKey ? { valid: true } : { valid: false, reason: 'Invalid API key' };
+        return isMatchingApiKey(token, config.apiKey ?? '')
+            ? { valid: true }
+            : { valid: false, reason: 'Invalid API key' };
     }
     if (config.mode === 'jwt-hmac') {
         return validateHmacJwt(token, config);
     }
     return { valid: false, reason: 'Unknown auth mode' };
 }
+function isMatchingApiKey(token, apiKey) {
+    const tokenBuffer = Buffer.from(token);
+    const apiKeyBuffer = Buffer.from(apiKey);
+    if (tokenBuffer.byteLength !== apiKeyBuffer.byteLength) {
+        return false;
+    }
+    return timingSafeEqual(tokenBuffer, apiKeyBuffer);
+}
 // Validate HS256 JWT using Node.js built-in crypto (no external deps).
 async function validateHmacJwt(token, config) {
     const parts = token.split('.');

package/dist/transports/transport-factory.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { TransportConfig } from '../types/index.js';
+import type { TransportConfig, OAuthConfig } from '../types/index.js';
 export declare function parseTransportConfig(args: string[]): TransportConfig;
+export declare function assertHttpExposureAllowed(config: TransportConfig, oauth: OAuthConfig): void;
 export declare function selectTransport(server: McpServer, args: string[], serverFactory?: () => McpServer): Promise<void>;
 //# sourceMappingURL=transport-factory.d.ts.map

package/dist/transports/transport-factory.js

@@ -2,6 +2,7 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { execFileSync } from 'node:child_process';
 import { createHttpTransport } from './http-transport.js';
+import { loadOAuthConfig } from './oauth-validator.js';
 import { compactToolsListMessage, isToolsListResponse, } from '../engine/compact/tool-list-compactor.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 const VALID_TRANSPORTS = ['stdio', 'http'];
@@ -84,8 +85,25 @@ export function parseTransportConfig(args) {
         port,
         host: getFlag(args, 'host') ?? process.env.HOST ?? DEFAULT_HOST,
         corsOrigin: getFlag(args, 'cors-origin') ?? process.env.CORS_ORIGIN,
+        insecure: args.includes('--insecure'),
     };
 }
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
+function isLoopbackHost(host) {
+    return LOOPBACK_HOSTS.has(host);
+}
+export function assertHttpExposureAllowed(config, oauth) {
+    if (config.transport !== 'http' || isLoopbackHost(config.host) || oauth.enabled) {
+        return;
+    }
+    if (config.insecure) {
+        console.error(`[Planu] WARNING: running UNAUTHENTICATED on non-loopback host "${config.host}" because --insecure was passed.`);
+        return;
+    }
+    console.error(`[Planu] Refusing to start: HTTP transport on non-loopback host "${config.host}" has no authentication configured. ` +
+        'Set SDD_OAUTH_API_KEY or SDD_OAUTH_JWT_SECRET, or pass --insecure to bypass this at your own risk.');
+    process.exit(1);
+}
 export async function selectTransport(server, args, serverFactory) {
     const config = parseTransportConfig(args);
     if (config.transport === 'stdio') {
@@ -102,6 +120,7 @@ export async function selectTransport(server, args, serverFactory) {
         return;
     }
     // HTTP mode: each session needs its own McpServer instance
+    assertHttpExposureAllowed(config, loadOAuthConfig());
     const factory = serverFactory ?? (() => server);
     await createHttpTransport(factory, config);
 }

package/dist/types/common/primitives.d.ts

@@ -3,6 +3,8 @@ export type Difficulty = 1 | 2 | 3 | 4 | 5;
 export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
 export type SupportedLocale = 'en' | 'es' | 'pt';
 export type ExperienceLevel = 'beginner' | 'intermediate' | 'expert';
+/** SDD model tier evidence for lifecycle transitions. */
+export type ModelTierUsed = 'max' | 'implementation' | 'review';
 /** SPEC-313: Preferred interaction style with Planu (stored in planu.json) */
 export type WorkMode = 'guided' | 'standard' | 'expert';
 export type SpecType = 'feature' | 'refactor' | 'bugfix' | 'infra' | 'docs' | 'project' | 'agent' | 'tech-debt';

package/dist/types/durable-job.d.ts

@@ -1,4 +1,5 @@
 import type { ValidationArtifactDigests, ValidationFreshnessLease } from './validation-receipt.js';
+import type { HandoffPackage } from './readiness.js';
 export interface DurableJobIdentity {
     readonly operationId: string;
     readonly projectId: string;
@@ -35,6 +36,50 @@ export interface ValidateDurableJobPayload {
     readonly freshnessLease?: ValidationFreshnessLease;
     readonly specPath: string;
 }
+export interface PackageHandoffDurableJobPayload {
+    readonly kind: 'package-handoff';
+    readonly schemaVersion: 1;
+    readonly projectId: string;
+    readonly specId: string;
+    readonly specVersion: string;
+}
+/** Outcome of one deadline-bounded package-handoff stage execution. */
+export interface PackageHandoffStageOutcome<T> {
+    readonly ok: boolean;
+    readonly value?: T;
+    readonly timedOut: boolean;
+    readonly error?: unknown;
+}
+export interface PackageHandoffStageResult<T> {
+    readonly stage: string;
+    readonly durationMs: number;
+    readonly outcome: PackageHandoffStageOutcome<T>;
+}
+export interface PackageHandoffDegradation {
+    readonly stage: string;
+    readonly code: 'HANDOFF_ENRICHMENT_TIMEOUT' | 'HANDOFF_ENRICHMENT_FAILURE' | 'HANDOFF_STALE_VERSION_SKIPPED';
+    readonly remediation: string;
+}
+export interface PackageHandoffCoreStageOutput {
+    readonly readinessScore: number;
+    readonly pkg: HandoffPackage & {
+        readonly staleVersionSkipped?: boolean;
+    };
+    readonly stageTimings: Record<string, number>;
+}
+export interface PackageHandoffEnrichmentOutput {
+    readonly pkgWithConstraints: HandoffPackage;
+    readonly graphContext: {
+        text: string;
+        structured: unknown;
+    } | null;
+    readonly minimalityBlocked: boolean | null;
+    readonly minimalitySummary: Record<string, unknown> | undefined;
+    readonly tokenWasteRiskCount: number | null;
+    readonly tokenWasteSummary: Record<string, unknown> | undefined;
+    readonly stageTimings: Record<string, number>;
+    readonly degradations: readonly PackageHandoffDegradation[];
+}
 export declare const DURABLE_JOB_STATES: readonly ['accepted', 'running', 'checkpointed', 'cancelled', 'failed', 'dead-letter', 'completed'];
 export type DurableJobState = (typeof DURABLE_JOB_STATES)[number];
 export interface DurableJobRecord {

package/dist/types/durable-validation.d.ts

@@ -9,7 +9,7 @@ export interface DurableValidationBindings {
     readonly policyHash: string;
     readonly toolchainHash: string;
 }
-export type ValidationWorktreeErrorCode = 'VALIDATION_PAYLOAD_VERSION_UNSUPPORTED' | 'VALIDATION_ROOT_ID_MALFORMED' | 'VALIDATION_ROOT_ID_MISMATCH' | 'VALIDATION_ROOT_BUSY' | 'VALIDATION_ROOT_NOT_GIT_WORKTREE' | 'VALIDATION_COMMON_DIR_MISMATCH' | 'VALIDATION_SPEC_PATH_TRAVERSAL' | 'VALIDATION_SPEC_PATH_SYMLINK' | 'VALIDATION_SPEC_NOT_FOUND' | 'VALIDATION_SPEC_ID_MISMATCH';
+export type ValidationWorktreeErrorCode = 'VALIDATION_PAYLOAD_VERSION_UNSUPPORTED' | 'VALIDATION_ROOT_ID_MALFORMED' | 'VALIDATION_ROOT_ID_MISMATCH' | 'VALIDATION_ROOT_BUSY' | 'VALIDATION_ROOT_NOT_GIT_WORKTREE' | 'VALIDATION_COMMON_DIR_MISMATCH' | 'VALIDATION_SPEC_PATH_TRAVERSAL' | 'VALIDATION_STALE_SPEC_PATH' | 'VALIDATION_SPEC_PATH_SYMLINK' | 'VALIDATION_SPEC_NOT_FOUND' | 'VALIDATION_SPEC_ID_MISMATCH';
 export interface ResolvedValidationWorktree {
     readonly projectPath: string;
     readonly gitCommonDir: string;

package/dist/types/evidence-autofill.d.ts

@@ -28,9 +28,21 @@ export type AutofillTraceabilityMatrixResult = {
     written: true;
     path: string;
     rowCount: number;
+    reason?: 'regenerated-stale';
 } | {
     written: false;
-    reason: 'already-exists' | 'no-criteria' | 'write-failed';
+    reason: 'already-exists-manual' | 'already-exists-current' | 'no-criteria' | 'write-failed';
     error?: string;
 };
+/** Classification of an on-disk traceability-matrix.json relative to the
+ * generator's own prose templates: absent, hand-written/mixed/unparseable
+ * ("manual" — never touched), or autofill-shaped and safe to regenerate. */
+export type ExistingMatrixLookup = {
+    kind: 'absent';
+} | {
+    kind: 'manual';
+} | {
+    kind: 'autofill-shaped';
+    raw: string;
+};
 //# sourceMappingURL=evidence-autofill.d.ts.map

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

@@ -48,6 +48,7 @@ export interface ImplementationReviewV1 {
         kind: 'implementation-review-agent' | 'human';
         agent: string;
         verdict: 'approved' | 'changes-requested';
+        sessionId?: string;
     };
     blockers: string[];
     suggestions: string[];
@@ -147,7 +148,7 @@ export interface ArtifactPayloadMap {
 }
 export type ArtifactPayload<K extends ArtifactKind> = ArtifactPayloadMap[K];
 import type { MinimalImplementationReport } from './minimal-implementation-gate.js';
-export type ImplementationReviewRejectionReason = 'missing' | 'unreadable' | 'schema_invalid' | 'stub_body' | 'wrong_agent_or_kind' | 'not_approved' | 'self_review' | 'actor_unreadable' | 'wrong_spec';
+export type ImplementationReviewRejectionReason = 'missing' | 'unreadable' | 'schema_invalid' | 'stub_body' | 'wrong_agent_or_kind' | 'not_approved' | 'self_review' | 'actor_unreadable' | 'wrong_spec' | 'identity_unverifiable';
 export interface VerifiedImplementationReviewOk {
     ok: true;
     review: ImplementationReviewV1;

package/dist/types/index.d.ts

@@ -278,6 +278,7 @@ export * from './reviewer-tokens.js';
 export * from './coach.js';
 export * from './tdd-strict.js';
 export * from './ssr-migration.js';
+export * from './legacy-guidance.js';
 export * from './workspace-overview.js';
 export * from './mcp-config.js';
 export * from './security/index.js';

package/dist/types/index.js

@@ -275,6 +275,7 @@ export * from './reviewer-tokens.js';
 export * from './coach.js';
 export * from './tdd-strict.js';
 export * from './ssr-migration.js';
+export * from './legacy-guidance.js';
 // SPEC-753: workspace_overview + reconcile_status_json types
 export * from './workspace-overview.js';
 // SPEC-756: MCP config auto-update types

package/dist/types/legacy-guidance.d.ts

@@ -0,0 +1,20 @@
+export interface LegacyGuidanceWarning {
+    file: string;
+    reason: string;
+}
+export interface LegacyGuidanceScanResult {
+    healed: string[];
+    warnings: LegacyGuidanceWarning[];
+}
+export interface LegacyGuidanceRegistry {
+    hostSurfaceFiles: string[];
+    hostSurfaceDirectories: {
+        dir: string;
+        extension: string;
+    }[];
+    legacyFilenameAllowlist: string[];
+    managedByMarkers: string[];
+    contradictoryPhrases: string[];
+    replacementGuidance: string;
+}
+//# sourceMappingURL=legacy-guidance.d.ts.map

package/dist/types/legacy-guidance.js

@@ -0,0 +1,3 @@
+// types/legacy-guidance.ts — SPEC-1716: stale Planu-installed guidance scanner
+export {};
+//# sourceMappingURL=legacy-guidance.js.map

package/dist/types/readiness.d.ts

@@ -63,8 +63,15 @@ export interface AmbiguityReport {
     violations: AmbiguityViolation[];
     blockers: string[];
 }
+/** Version fence for the durable executor: skip publishing a stale-version artifact. */
+export interface HandoffVersionFence {
+    readonly specVersion: string;
+    readonly getCurrentSpecVersion: () => Promise<string | undefined>;
+    readonly signal?: AbortSignal;
+}
 export interface PackageHandoffInput {
-    projectId: string;
+    projectId?: string;
+    projectPath?: string;
     specId: string;
 }
 /**

package/dist/types/reconcile.d.ts

@@ -26,6 +26,12 @@ export interface SectionBounds {
     start: number;
     end: number;
 }
+export type AppliedSections = ReadonlySet<string>;
+export interface ParsedFilesSection {
+    create: string[];
+    modify: string[];
+    test: string[];
+}
 export interface CurrentStatus {
     totalSpecs: number;
     content: Record<string, unknown>;

package/dist/types/skill-registry.d.ts

@@ -398,9 +398,34 @@ export interface WorkflowSkillGenerationOptions {
 export interface WorkflowSkillGenerationResult {
     /** Skill names that were written (new or updated). */
     written: string[];
-    /** Skill names that were skipped (conventions unchanged). */
+    /** Skill names that were skipped (content unchanged). */
     skipped: string[];
+    /** Skill names left untouched because the on-disk file was user-authored or user-edited. */
+    userModified: string[];
     /** Any non-fatal errors (skill name → error message). */
     errors: Record<string, string>;
 }
+/** Fail-closed result of reading the hash marker from an on-disk skill file. */
+export type MarkerReadResult = {
+    kind: 'absent';
+} | {
+    kind: 'invalid';
+} | {
+    kind: 'legacy';
+} | {
+    kind: 'current';
+    hash: string;
+    lineIndex: number;
+};
+/** Per-file write decision made by generateWorkflowSkills for one skill definition. */
+export type SkillFileDecision = {
+    action: 'write';
+} | {
+    action: 'skip-unchanged';
+} | {
+    action: 'skip-user-modified';
+} | {
+    action: 'skip-error';
+    message: string;
+};
 //# sourceMappingURL=skill-registry.d.ts.map

package/dist/types/spec/core.d.ts

@@ -435,6 +435,11 @@ export interface SyncDivergence {
     yamlStatus: string;
     dataStatus: string;
 }
+/** Options controlling how syncSpecState reconciles divergences. */
+export interface SyncSpecStateOptions {
+    /** When false, non-terminal drift is reported read-only instead of applied via handleUpdateStatus. */
+    applyTransitions?: boolean;
+}
 /** Report produced by spec state synchronisation. */
 export interface SyncReport {
     synced: number;

package/dist/types/spec/inputs.d.ts

@@ -1,4 +1,4 @@
-import type { SpecStatus, SpecType, SpecScope, SpecTarget, ToolResult } from '../common/index.js';
+import type { ModelTierUsed, SpecStatus, SpecType, SpecScope, SpecTarget, ToolResult } from '../common/index.js';
 import type { Actuals } from '../estimation.js';
 import type { GlobalConfig } from '../project/config-metrics.js';
 import type { ProjectKnowledge } from '../project.js';
@@ -58,7 +58,7 @@ export interface UpdateStatusInput {
      * - implementation: lower/intermediate implementer tier
      * - review: reviewer tier
      */
-    modelTierUsed?: 'max' | 'implementation' | 'review';
+    modelTierUsed?: ModelTierUsed;
     /** SHA-256 hash of the persisted context package used for this transition. */
     contextHash?: string;
     /** Path to the persisted handoff artifact generated by package_handoff. */

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

@@ -1,6 +1,6 @@
 import type { Spec } from './spec/core.js';
 import type { Estimation } from './estimation.js';
-import type { SpecStatus } from './common/index.js';
+import type { ModelTierUsed, SpecStatus } from './common/index.js';
 import type { CriterionGroundingRecord, TechnicalReferenceGroundingRecord } from './spec-grounding.js';
 /** A criterion in the lean spec frontmatter. */
 export interface LeanCriterion {
@@ -110,6 +110,15 @@ export interface LegacyMigrationDirective {
     legacyFiles: LegacyArtifactHit[];
     directive: 'migrate_legacy_spec';
 }
+export interface UpdateStatusBatchEvidence {
+    modelTierUsed?: ModelTierUsed;
+    modelId?: string;
+    contextHash?: string;
+    handoffPath?: string;
+    handoffArtifactId?: string;
+    reviewedBy?: string;
+    arbitratedBy?: string;
+}
 export interface UpdateStatusBatchInput {
     specIds: string[];
     status: Exclude<SpecStatus, 'done'>;
@@ -117,6 +126,7 @@ export interface UpdateStatusBatchInput {
     projectPath?: string;
     dryRun?: boolean;
     reviewNotes?: string;
+    evidence?: Record<string, UpdateStatusBatchEvidence>;
 }
 /** Report of detected migration drift (SPEC-715). Read-only — no FS mutations. */
 export interface MigrationDriftReport {

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

@@ -19,4 +19,16 @@ export interface GroundingGateResult {
     issues: string[];
     records: CriterionGroundingRecord[];
 }
+export interface RawGroundingFrontmatter {
+    grounding?: {
+        criteria?: unknown;
+        technicalReferences?: unknown;
+    };
+}
+export type FrontmatterYamlOutcome = {
+    parsed: true;
+    document: Record<string, unknown> | undefined;
+} | {
+    parsed: false;
+};
 //# sourceMappingURL=spec-grounding.d.ts.map

package/dist/types/ssr-migration.d.ts

@@ -1,7 +1,7 @@
 /** Result of folding technical.md into spec.md ## Technical section. */
 export interface FoldTechnicalResult {
     ok: boolean;
-    reason: 'already_unified' | 'no_technical_md' | 'ok' | 'error';
+    reason: 'already_unified' | 'no_technical_md' | 'ok' | 'error' | 'folded_residual';
     byteDelta?: number;
     error?: string;
 }

package/dist/types/transport.d.ts

@@ -10,5 +10,6 @@ export interface TransportConfig {
     port: number;
     host: string;
     corsOrigin?: string;
+    insecure?: boolean;
 }
 //# sourceMappingURL=transport.d.ts.map

package/dist/types/validation-receipt.d.ts

@@ -15,6 +15,16 @@ export interface ValidationArtifactDigests {
     readonly traceability: string;
     readonly contractValidation: string;
 }
+export interface ValidationArtifactProvenanceWriteResult {
+    readonly writtenPaths: readonly string[];
+    readonly absentArtifacts: readonly string[];
+}
+export interface PerFileArtifactSentinel {
+    readonly name: string;
+    readonly digestValue: string;
+    readonly sentinel: string;
+    readonly payloadFile?: string;
+}
 export interface ValidationArtifactProvenance {
     readonly receiptId: string;
     /** Digest of canonical artifact content excluding this provenance envelope. */
@@ -28,6 +38,23 @@ export interface ValidationFreshnessLease {
     readonly epoch: string;
     readonly generation: number;
 }
+export type ValidationFreshnessBarrierReason = 'lease-superseded' | 'invalidation-drain-failed' | 'evidence-check-failed' | 'evidence-changed' | 'source-changed' | 'source-check-failed' | 'state-lost' | 'lease-expired' | 'bindings-mismatch';
+export type ValidationFreshnessBarrierResult = {
+    readonly fresh: true;
+} | {
+    readonly fresh: false;
+    readonly reason: ValidationFreshnessBarrierReason;
+    readonly changedInput?: string;
+};
+export type ValidationFreshnessRebaselineReason = 'lease-expired' | 'recompute-failed' | 'bindings-mismatch' | 'lease-unstable';
+export type ValidationFreshnessRebaselineResult = {
+    readonly lease: ValidationFreshnessLease;
+} | {
+    readonly rejection: {
+        readonly reason: ValidationFreshnessRebaselineReason;
+        readonly changedInput?: string;
+    };
+};
 /**
  * Classification of one raw filesystem watcher event feeding the freshness
  * barrier: a direct relevant/ignored child path, a synthetic root event (the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.7.4",
+  "version": "5.7.6",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=22.13.0"
   },
   "packageManager": "pnpm@11.9.0+sha512.bd682d5d03fe525ef7c9fd6780c6884d1e756ac4c9c9fe00c538782824310dcf90e3ddc4f53835f06dfaebd5085e41855e0bcbb3b60de2ac5bbab89e5036f03b",
   "scripts": {
@@ -48,6 +48,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage --testTimeout=60000 --maxWorkers=4",
     "test:release-gate": "vitest run --exclude 'tests/integration/**'",
+    "test:pre-push-scripts": "PLANU_PRE_PUSH_SCRIPTS_LANE=1 vitest run tests/scripts --reporter=dot",
     "test:integration": "vitest run tests/integration",
     "test:website:unit": "vitest run tests/website tests/scripts/generate-website-proof.test.ts tests/scripts/website-tool-counts.test.ts",
     "test:website:browser": "playwright test --config playwright.website.config.ts",