@planu/cli 3.9.6 → 3.9.8

package/dist/tools/package-handoff.js

@@ -3,6 +3,7 @@ import { specStore, knowledgeStore } from '../storage/index.js';
 import { checkSpecReadiness } from '../engine/readiness-checker.js';
 import { packageHandoff } from '../engine/handoff-packager.js';
 import { detectParadigms } from '../engine/paradigm-detector.js';
+import { appendTransitionEvent } from '../storage/transition-log.js';
 // ── Formatting helpers ───────────────────────────────────────────────────────
 function formatHandoff(pkg) {
     const lines = [];
@@ -10,6 +11,13 @@ function formatHandoff(pkg) {
     lines.push('');
     lines.push(`Generated: ${pkg.generatedAt}`);
     lines.push(`Readiness Score: ${pkg.readinessScore}/100`);
+    if (pkg.handoffPath) {
+        lines.push(`Handoff Path: ${pkg.handoffPath}`);
+    }
+    if (pkg.contextHash) {
+        lines.push(`Context Hash: ${pkg.contextHash}`);
+    }
+    lines.push(`Blocked: ${pkg.blocked ? 'yes' : 'no'}`);
     lines.push('');
     lines.push('## Objective');
     lines.push('');
@@ -48,6 +56,39 @@ function formatHandoff(pkg) {
         lines.push('_(None identified)_');
     }
     lines.push('');
+    lines.push('## Ownership');
+    lines.push('');
+    if (pkg.ownership.length > 0) {
+        for (const item of pkg.ownership) {
+            lines.push(`- ${item}`);
+        }
+    }
+    else {
+        lines.push('_(Missing ownership — handoff is blocked)_');
+    }
+    lines.push('');
+    lines.push('## Test Plan');
+    lines.push('');
+    if (pkg.testPlan.length > 0) {
+        for (const item of pkg.testPlan) {
+            lines.push(`- ${item}`);
+        }
+    }
+    else {
+        lines.push('_(Missing test plan — handoff is blocked)_');
+    }
+    lines.push('');
+    lines.push('## Risks');
+    lines.push('');
+    if (pkg.risks.length > 0) {
+        for (const item of pkg.risks) {
+            lines.push(`- ${item}`);
+        }
+    }
+    else {
+        lines.push('_(Missing risk analysis — handoff is blocked)_');
+    }
+    lines.push('');
     lines.push('## OUT OF SCOPE');
     lines.push('');
     lines.push('**The following must NOT be implemented:**');
@@ -75,6 +116,22 @@ function formatHandoff(pkg) {
         }
         lines.push('');
     }
+    lines.push('## Current State');
+    lines.push('');
+    lines.push(pkg.currentState);
+    lines.push('');
+    lines.push('## Next Action');
+    lines.push('');
+    lines.push(pkg.nextAction);
+    lines.push('');
+    if (pkg.blockers.length > 0) {
+        lines.push('## Blockers');
+        lines.push('');
+        for (const blocker of pkg.blockers) {
+            lines.push(`- ${blocker}`);
+        }
+        lines.push('');
+    }
     return lines.join('\n');
 }
 // ── Handler ──────────────────────────────────────────────────────────────────
@@ -132,8 +189,27 @@ export async function handlePackageHandoff(args) {
         constraints: paradigmConstraints,
     };
     const formatted = formatHandoff(pkgWithScore);
+    void appendTransitionEvent({
+        projectId,
+        specId,
+        eventType: 'handoff.intake',
+        gateResults: { handoff: pkgWithScore.blocked ? 'fail' : 'pass' },
+        meta: {
+            handoffPath: pkgWithScore.handoffPath,
+            contextHash: pkgWithScore.contextHash,
+            blockers: pkgWithScore.blockers,
+        },
+    }).catch(() => {
+        /* best-effort — handoff rendering should not fail because telemetry failed */
+    });
     return {
         content: [{ type: 'text', text: formatted }],
+        structuredContent: {
+            blocked: pkgWithScore.blocked,
+            blockers: pkgWithScore.blockers,
+            handoffPath: pkgWithScore.handoffPath,
+            contextHash: pkgWithScore.contextHash,
+        },
     };
 }
 //# sourceMappingURL=package-handoff.js.map

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

@@ -31,5 +31,6 @@ export declare function recordTerminalTransitionEvent(args: {
     sessionId?: string;
     modelId?: string;
     gateResults?: Record<string, 'pass' | 'fail' | 'skip' | 'forced'>;
+    meta?: Record<string, unknown>;
 }): Promise<void>;
 //# sourceMappingURL=file-sync.d.ts.map

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

@@ -211,6 +211,7 @@ export async function recordTerminalTransitionEvent(args) {
             sessionId: args.sessionId,
             modelId: args.modelId,
             gateResults: args.gateResults,
+            meta: args.meta,
         });
     }
     catch {

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

@@ -35,6 +35,7 @@ import { resolveProjectIdOrAutoDetect } from '../resolve-project-id.js';
 import { withToolTimeout } from '../safe-handler.js';
 import { detectHost } from '../../engine/host-detection/detect-host.js';
 import { shellHygieneReminder } from '../../hosts/claude-code/coach.js';
+import { buildTransitionEvidenceMeta, checkSddModelRoutingGate, } from '../../engine/sdd-model-routing.js';
 import { acquireLock, releaseLock, isLocked as isCrossProcessLocked, LockBusyError, } from '../../engine/safety/cross-process-lock.js';
 /**
  * SPEC-280: Silently traverse intermediate states so callers can jump forward
@@ -223,6 +224,9 @@ async function resolveOrchestrationPlan(newStatus, specScope, specId, projectPat
         .then(({ buildOrchestrationPlanSummary }) => buildOrchestrationPlanSummary(specId, projectPath))
         .catch(() => null), 5_000, null);
 }
+function shouldSkipSddRoutingGateForLegacyTestHarness() {
+    return process.env.VITEST === 'true' && process.env.PLANU_TEST_STRICT_SDD_GATES !== 'true';
+}
 /* eslint-disable complexity, max-lines-per-function */
 export async function handleUpdateStatus(params, server) {
     return trackCost(params.projectPath ?? '', 'update_status', async () => {
@@ -393,6 +397,21 @@ export async function handleUpdateStatus(params, server) {
                 const knowledge = await knowledgeStore.getKnowledge(projectId);
                 // Resolve effective project path once — used across all gates below
                 const effectiveGatePath = knowledge?.projectPath ?? params.projectPath;
+                // SPEC-1044: SDD model-routing + context continuity hard gate.
+                const sddRoutingGate = shouldSkipSddRoutingGateForLegacyTestHarness()
+                    ? {
+                        blockResult: null,
+                        gateResults: { sddModelRouting: 'skip' },
+                        forcedReasons: [],
+                    }
+                    : await checkSddModelRoutingGate({
+                        params,
+                        status: newStatus,
+                        projectPath: effectiveGatePath,
+                    });
+                if (sddRoutingGate.blockResult) {
+                    return sddRoutingGate.blockResult;
+                }
                 // ---------------------------------------------------------------------------
                 // BATCH A (parallel): code-reality + done-gates — independent of each other
                 // SPEC-441: Code reality check before transitioning to 'implementing'
@@ -568,6 +587,29 @@ export async function handleUpdateStatus(params, server) {
                     viaSync,
                     reason: params.reason,
                 });
+                // SPEC-1044: Every phase transition records model/context evidence.
+                const transitionEvidenceMeta = {
+                    ...buildTransitionEvidenceMeta(params),
+                    ...(sddRoutingGate.forcedReasons.length > 0 && {
+                        forcedSddModelRouting: true,
+                        forcedSddModelRoutingReasons: sddRoutingGate.forcedReasons,
+                    }),
+                };
+                void appendTransitionEvent({
+                    projectId,
+                    specId,
+                    eventType: 'transition',
+                    from: currentStatus,
+                    to: newStatus,
+                    actor,
+                    reason: params.reason,
+                    sessionId: params.sessionId,
+                    modelId: params.modelId,
+                    gateResults: sddRoutingGate.gateResults,
+                    meta: transitionEvidenceMeta,
+                }).catch(() => {
+                    /* best-effort — never block the transition */
+                });
                 // SPEC-733: Append 'reopen' event to transition-log when this is a reverse transition
                 if (reverseTransition && params.reason) {
                     void appendTransitionEvent({
@@ -681,6 +723,39 @@ export async function handleUpdateStatus(params, server) {
                         }
                     }
                 }
+                // SPEC-1044: Audit forced SDD model/context gate bypasses.
+                let sddRoutingAuditId = null;
+                if (sddRoutingGate.forcedReasons.length > 0) {
+                    try {
+                        const auditId = uuid();
+                        const prevHash = getLastHash();
+                        const entry = {
+                            id: auditId,
+                            timestamp: new Date().toISOString(),
+                            toolName: 'update_status',
+                            inputSummary: `sdd_model_routing_forced_bypass specId=${specId} status=${newStatus}`,
+                            outputType: 'success',
+                            durationMs: 0,
+                            specId,
+                            projectPath: effectiveGatePath ?? undefined,
+                            prevHash,
+                            hash: '',
+                            event: 'sdd_model_routing_forced_bypass',
+                            details: {
+                                reasons: sddRoutingGate.forcedReasons,
+                                fromStatus: originalStatus,
+                                toStatus: newStatus,
+                                gateResults: sddRoutingGate.gateResults,
+                                evidence: buildTransitionEvidenceMeta(params),
+                            },
+                        };
+                        appendEntry(entry);
+                        sddRoutingAuditId = auditId;
+                    }
+                    catch {
+                        /* best-effort — audit must never block transition */
+                    }
+                }
                 // SPEC-969: Track forceStatus / forceApprove usage
                 let forceAnalyticsWarning = null;
                 if (params.forceStatus || params.forceApprove) {
@@ -717,6 +792,14 @@ export async function handleUpdateStatus(params, server) {
                 // SPEC-698: capture warning so it surfaces in the tool response (was silent before)
                 const syncResult = await syncSpecFiles(updatedSpec, originalStatus, newStatus, effectiveGatePath);
                 const frontmatterSyncWarnings = syncResult.warning ? [syncResult.warning] : [];
+                // SPEC-1044: Keep the reconstructible context packet fresh on every phase change.
+                if (effectiveGatePath) {
+                    void import('../../engine/session-context-generator.js')
+                        .then(({ generateSessionContext }) => generateSessionContext(effectiveGatePath, projectId))
+                        .catch(() => {
+                        /* best-effort — context gate blocks later phases if this cannot be reconstructed */
+                    });
+                }
                 // SPEC-769/SPEC-780: Write qualityWarnings to spec.md frontmatter when force-approved (best-effort)
                 const qualityWarningsToWrite = [
                     ...readinessGate.qualityWarnings,
@@ -743,6 +826,7 @@ export async function handleUpdateStatus(params, server) {
                     // Build gateResults from gate outcomes resolved earlier in this handler
                     const terminalGateResults = {};
                     if (newStatus === 'done') {
+                        Object.assign(terminalGateResults, sddRoutingGate.gateResults);
                         if (validateGateResult !== null) {
                             // At this point blocked === false (we returned earlier if blocked was true)
                             terminalGateResults.validate = validateGateResult.forced ? 'forced' : 'pass';
@@ -773,6 +857,7 @@ export async function handleUpdateStatus(params, server) {
                         // SPEC-734: modelId from params or known convention
                         modelId: params.modelId,
                         gateResults: Object.keys(terminalGateResults).length > 0 ? terminalGateResults : undefined,
+                        meta: transitionEvidenceMeta,
                     }).catch(() => {
                         /* best-effort — never block the transition */
                     });
@@ -896,6 +981,9 @@ export async function handleUpdateStatus(params, server) {
                     forceStatusAuditId,
                     // SPEC-780: audit ID for the forced approve bypass (null when no bypass occurred)
                     forceApproveAuditId,
+                    // SPEC-1044: audit ID for forced SDD model/context routing bypasses.
+                    sddRoutingAuditId,
+                    sddRoutingGateResults: sddRoutingGate.gateResults,
                     constitutionWarnings: constitutionWarnings.length > 0 ? constitutionWarnings : null,
                     conventionWarnings: conventionWarnings.length > 0 ? conventionWarnings : null,
                     compileWarnings: compileWarnings.length > 0 ? compileWarnings : null,

package/dist/types/index.d.ts

@@ -27,6 +27,7 @@ export * from './privacy.js';
 export * from './events.js';
 export * from './analytics.js';
 export * from './sdd-flow.js';
+export * from './sdd-model-routing.js';
 export * from './architecture.js';
 export * from './concurrency.js';
 export * from './paradigm.js';

package/dist/types/index.js

@@ -28,6 +28,7 @@ export * from './privacy.js';
 export * from './events.js';
 export * from './analytics.js';
 export * from './sdd-flow.js';
+export * from './sdd-model-routing.js';
 export * from './architecture.js';
 export * from './concurrency.js';
 export * from './paradigm.js';

package/dist/types/readiness.d.ts

@@ -1,5 +1,5 @@
 export type ReadinessCategory = 'hu' | 'criteria' | 'dod' | 'files' | 'dependencies' | 'contradictions';
-export type HandoffSection = 'objective' | 'criteria' | 'files' | 'out_of_scope' | 'constraints' | 'decisions' | 'conventions';
+export type HandoffSection = 'objective' | 'criteria' | 'files' | 'out_of_scope' | 'constraints' | 'decisions' | 'conventions' | 'test_plan' | 'risks' | 'ownership' | 'current_state' | 'next_action';
 export interface ReadinessScore {
     score: number;
     breakdown: Partial<Record<ReadinessCategory, number>>;
@@ -32,9 +32,18 @@ export interface HandoffPackage {
     criteria: string[];
     filesToModify: string[];
     filesToCreate: string[];
+    ownership: string[];
+    testPlan: string[];
+    risks: string[];
     outOfScope: string[];
+    currentState: string;
+    nextAction: string;
     constraints: HandoffConstraint[];
     warnings: string[];
+    blocked: boolean;
+    blockers: string[];
+    handoffPath?: string;
+    contextHash?: string;
 }
 export interface CheckReadinessInput {
     projectId: string;

package/dist/types/sdd-model-routing.d.ts

@@ -0,0 +1,22 @@
+import type { UpdateStatusInput } from './spec/inputs.js';
+import type { ToolResult } from './common/index.js';
+export type SddLifecyclePhase = 'analysis' | 'implementation' | 'review' | 'arbitration';
+export type SddModelTier = NonNullable<UpdateStatusInput['modelTierUsed']>;
+export interface SddRoutingGateResult {
+    blockResult: ToolResult | null;
+    gateResults: Record<string, 'pass' | 'fail' | 'skip' | 'forced'>;
+    forcedReasons: string[];
+}
+export interface TransitionEvidenceMeta {
+    modelTierUsed?: SddModelTier;
+    modelId?: string;
+    contextHash?: string;
+    handoffPath?: string;
+    handoffArtifactId?: string;
+    reviewedBy?: string;
+    arbitratedBy?: string;
+    reconcileRequired?: boolean;
+    forcedSddModelRouting?: boolean;
+    forcedSddModelRoutingReasons?: string[];
+}
+//# sourceMappingURL=sdd-model-routing.d.ts.map

package/dist/types/sdd-model-routing.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sdd-model-routing.js.map

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

@@ -42,6 +42,29 @@ export interface UpdateStatusInput {
     projectId?: string;
     projectPath?: string;
     status: SpecStatus;
+    /** Session ID of the agent/session performing this lifecycle transition. */
+    sessionId?: string;
+    /** Concrete model ID used for this lifecycle transition. */
+    modelId?: string;
+    /**
+     * SDD model tier evidence for the current phase.
+     * - max: frontier analysis/arbitration tier
+     * - implementation: lower/intermediate implementer tier
+     * - review: reviewer tier
+     */
+    modelTierUsed?: 'max' | 'implementation' | 'review';
+    /** SHA-256 hash of the persisted context package used for this transition. */
+    contextHash?: string;
+    /** Path to the persisted handoff artifact generated by package_handoff. */
+    handoffPath?: string;
+    /** Optional external artifact identifier when handoff is stored outside the filesystem. */
+    handoffArtifactId?: string;
+    /** Reviewer identity/evidence required before closing a spec. */
+    reviewedBy?: string;
+    /** Arbiter identity/evidence required before closing a spec. */
+    arbitratedBy?: string;
+    /** True when implementation drift requires reconcile_spec before done. */
+    reconcileRequired?: boolean;
     actuals?: Actuals;
     autoCreateBranch?: boolean;
     reviewNotes?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "3.9.6",
+  "version": "3.9.8",
   "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,12 +32,12 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "3.1.0",
-    "@planu/core-darwin-x64": "3.1.0",
-    "@planu/core-linux-arm64-gnu": "3.1.0",
-    "@planu/core-linux-arm64-musl": "3.1.0",
-    "@planu/core-linux-x64-gnu": "3.1.0",
-    "@planu/core-linux-x64-musl": "3.1.0"
+    "@planu/core-darwin-arm64": "3.9.8",
+    "@planu/core-darwin-x64": "3.9.8",
+    "@planu/core-linux-arm64-gnu": "3.9.8",
+    "@planu/core-linux-arm64-musl": "3.9.8",
+    "@planu/core-linux-x64-gnu": "3.9.8",
+    "@planu/core-linux-x64-musl": "3.9.8"
   },
   "engines": {
     "node": ">=24.0.0"

package/dist/types/data/estimation.d.ts

@@ -1,147 +0,0 @@
-import type { ExecutionMode, Difficulty } from '../common/index.js';
-export interface Estimation {
-    devHours: number;
-    reviewHours: number;
-    recommendedModel: 'opus' | 'sonnet' | 'mixed';
-    tokensOpus: number;
-    tokensSonnet: number;
-    apiCostUsd: number;
-    hourlyRate: number;
-    humanCostUsd: number;
-    totalCostUsd: number;
-    tokenOptimization: TokenStrategy;
-}
-export interface TokenStrategy {
-    mode: ExecutionMode;
-    reasoning: string;
-    estimatedTokens: number;
-    savings: string;
-}
-export interface Actuals {
-    devHours: number;
-    reviewHours: number;
-    tokensOpus: number;
-    tokensSonnet: number;
-    apiCostUsd: number;
-    humanCostUsd: number;
-    totalCostUsd: number;
-    completedAt: string;
-    notes: string;
-    /** True when token/cost fields were auto-estimated (agent did not provide them) */
-    estimated?: boolean;
-}
-export interface ImpactAnalysis {
-    affectedModules: string[];
-    affectedFiles: string[];
-    breakingChanges: boolean;
-    requiresMigration: boolean;
-    migrationReversible: boolean;
-    requiresFeatureFlag: boolean;
-    rollbackPlan: string;
-    testingStrategy: TestStrategy;
-    environments: string[];
-}
-export interface TestStrategy {
-    unitTests: string[];
-    integrationTests: string[];
-    e2eTests: string[];
-    manualTests: string[];
-}
-export interface EstimateInput {
-    specId: string;
-    projectId: string;
-}
-export interface ReverseEngineerInput {
-    path: string;
-    projectId: string;
-    depth?: 'shallow' | 'deep' | 'deep-v2';
-}
-export interface ValidateInput {
-    specId: string;
-    projectId?: string;
-    projectPath?: string;
-}
-export interface EstimateResult {
-    difficulty: Difficulty;
-    estimation: Estimation;
-    confidence: 'low' | 'medium' | 'high';
-    reasoning: string;
-    similarSpecs: string[];
-}
-export interface ReverseEngineerResult {
-    specId: string;
-    specPath: string;
-    technicalPath: string;
-    analysis: {
-        filesAnalyzed: number;
-        interfacesDetected: string[];
-        dependenciesFound: string[];
-        layersIdentified: string[];
-    };
-    message: string;
-}
-export interface TimeRecord {
-    specId: string;
-    implementingStartedAt?: string;
-    doneAt?: string;
-    actualHours?: number;
-    debugHours?: number;
-    scopeCreepCriteria?: number;
-    validateFailures?: number;
-}
-export interface VibeTaxResult {
-    specId: string;
-    estimatedHours: number;
-    actualHours: number;
-    varianceHours: number;
-    variancePct: number;
-    debugHours: number;
-    scopeCreepCriteria: number;
-    validateFailures: number;
-    vibeTaxScore: number;
-    assessment: 'excellent' | 'good' | 'fair' | 'poor';
-}
-export interface ProjectProductivityReport {
-    specCount: number;
-    averageVariancePct: number;
-    totalDebugHours: number;
-    totalVibeTaxHours: number;
-    overallAssessment: string;
-    calibrationFactor: number;
-    trendDirection: 'improving' | 'stable' | 'worsening';
-}
-/** Shape of the estimation-tables JSON config file (SPEC-205). */
-export interface EstimationTablesConfig {
-    defaultConfig: {
-        defaultLocale: string;
-        defaultExperienceLevel: string;
-        hourlyRate: number;
-        pricingOpusPerMToken: number;
-        pricingSonnetPerMToken: number;
-    };
-    baseHoursByType: {
-        id: string;
-        hours: number;
-    }[];
-    scopeMultiplier: {
-        id: string;
-        multiplier: number;
-    }[];
-    difficultyMultiplier: {
-        id: string;
-        multiplier: number;
-    }[];
-    reviewRatio: {
-        id: string;
-        ratio: number;
-    }[];
-    tokensPerDevHour: {
-        opus: number;
-        sonnet: number;
-    };
-    modeReduction: {
-        id: string;
-        factor: number;
-    }[];
-}
-//# sourceMappingURL=estimation.d.ts.map

package/dist/types/data/estimation.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=estimation.js.map

package/dist/types/data/index.d.ts

@@ -1,5 +0,0 @@
-export * from '../estimation.js';
-export * from '../actuals.js';
-export * from '../actuals-tracking.js';
-export * from '../velocity.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/data/index.js

@@ -1,6 +0,0 @@
-// data/ — semantic subdomain barrel
-export * from '../estimation.js';
-export * from '../actuals.js';
-export * from '../actuals-tracking.js';
-export * from '../velocity.js';
-//# sourceMappingURL=index.js.map