@planu/cli 3.9.8 → 3.9.10

package/dist/engine/handoff-packager.js

@@ -175,7 +175,7 @@ function extractOutOfScope(huContent, spec) {
         return [
             `Changes beyond the ${spec.target} target layer`,
             'Refactors not explicitly requested in acceptance criteria',
-            'New dependencies not listed in FICHA-TECNICA.md',
+            'New dependencies not listed in spec.md ## Technical',
         ];
     }
     return outOfScopeItems;
@@ -203,12 +203,9 @@ function buildConstraints(knowledge) {
 export async function packageHandoff(spec, knowledge) {
     const warnings = [];
     const huContent = await safeReadFile(spec.specPath);
-    const fichaContent = await safeReadFile(spec.technicalPath);
+    const fichaContent = huContent;
     if (!huContent) {
-        warnings.push('HU.md not found — using minimal package. Run create_spec_hu to generate it.');
-    }
-    if (!fichaContent) {
-        warnings.push('FICHA-TECNICA.md not found — file lists may be incomplete. Run create_spec_tech to generate it.');
+        warnings.push('spec.md not found — using minimal package. Run create_spec to generate it.');
     }
     const objective = extractObjective(huContent, spec);
     const criteria = extractCriteria(huContent);

package/dist/engine/host-rules-templates/templates.js

@@ -64,7 +64,7 @@ function buildSharedRules() {
         '- Every tool result ends with what was DONE, not what SHOULD be done',
         '',
         '### Spec docs — mandatory format',
-        "- **Language**: `spec.md` and `technical.md` must always be in **English**, no exceptions. Tool response narratives adapt to the user's locale; spec docs do not.",
+        "- **Language**: `spec.md` must always be in **English**, no exceptions. Tool response narratives adapt to the user's locale; spec docs do not.",
         '- **Clean title**: never include the spec ID in the title — it is already in the `id` field.',
         '',
         '### Output quality',

package/dist/tools/init-project/conventions-writer.js

@@ -26,7 +26,7 @@ function buildConventionsContent(knowledge) {
     if (knowledge.projectPath) {
         lines.push(`- Project root: \`${knowledge.projectPath}\``);
     }
-    lines.push('- Source: `src/`', '- Tests: `tests/` (mirrors `src/` structure)', '- Specs: `planu/specs/`', '', '## Code Style', '', '- Prefer explicit return types on all functions', '- No magic numbers — use named constants', '- Error handling: return `ToolResult` with `isError: true`, never throw from handlers', '', '## Spec Conventions', '', '- One spec per feature/bugfix', '- ACs must be testable: GIVEN/WHEN/THEN or measurable condition', '- spec.md and technical.md always in English');
+    lines.push('- Source: `src/`', '- Tests: `tests/` (mirrors `src/` structure)', '- Specs: `planu/specs/`', '', '## Code Style', '', '- Prefer explicit return types on all functions', '- No magic numbers — use named constants', '- Error handling: return `ToolResult` with `isError: true`, never throw from handlers', '', '## Spec Conventions', '', '- One spec per feature/bugfix', '- ACs must be testable: GIVEN/WHEN/THEN or measurable condition', '- spec.md always in English', '- Technical planning belongs in `spec.md` under `## Technical`; do not create `technical.md`');
     return lines.join('\n') + '\n';
 }
 /**

package/dist/tools/init-project/helpers.js

@@ -206,7 +206,7 @@ This project uses **Spec-Driven Development** managed by [Planu](https://planu.d
 
 **Key commands:** \`init_project\` → \`create_spec\` → (user approves) → implement → \`validate\`
 
-Specs live in \`planu/specs/SPEC-XXX-name/\` with \`spec.md\`, \`technical.md\`, and \`progress.md\`.
+Specs live in \`planu/specs/SPEC-XXX-name/spec.md\`. Technical planning, file ownership, and progress live inline in \`## Technical\`, \`## Files\`, and \`## Progress\` sections.
 ${SDD_MARKER}
 `.trimStart();
 /**

package/dist/tools/package-handoff.js

@@ -31,7 +31,7 @@ function formatHandoff(pkg) {
         }
     }
     else {
-        lines.push('_(No criteria found — check HU.md)_');
+        lines.push('_(No criteria found — check spec.md acceptance criteria)_');
     }
     lines.push('');
     lines.push('## Files to Modify');
@@ -42,7 +42,7 @@ function formatHandoff(pkg) {
         }
     }
     else {
-        lines.push('_(No files identified — check FICHA-TECNICA.md)_');
+        lines.push('_(No files identified — check spec.md ## Technical / ## Files)_');
     }
     lines.push('');
     lines.push('## Files to Create');

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

@@ -0,0 +1,147 @@
+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

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

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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,6 @@
+// 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

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

@@ -0,0 +1,168 @@
+import type { SpecScope, SpecType } from '../common/primitives.js';
+/**
+ * A single week's throughput data point.
+ * weekLabel: ISO week string, e.g. "2026-W12"
+ */
+export interface ThroughputPoint {
+    weekLabel: string;
+    weekStart: string;
+    weekEnd: string;
+    specsCompleted: number;
+    specIds: string[];
+}
+/**
+ * Lead time statistics grouped by scope.
+ * Lead time = done timestamp - created timestamp (in hours).
+ */
+export interface LeadTimeStats {
+    avgHours: number;
+    medianHours: number;
+    minHours: number;
+    maxHours: number;
+    /** Number of specs used to compute these stats */
+    sampleSize: number;
+    /** Breakdown by scope */
+    byScope: Record<SpecScope, LeadTimeScopeStats>;
+}
+export interface LeadTimeScopeStats {
+    avgHours: number;
+    sampleSize: number;
+}
+/**
+ * Cycle time statistics.
+ * Cycle time = done timestamp - implementing timestamp (in hours).
+ */
+export interface CycleTimeStats {
+    avgHours: number;
+    medianHours: number;
+    sampleSize: number;
+}
+/**
+ * A single burndown data point for one week.
+ */
+export interface BurndownPoint {
+    weekLabel: string;
+    weekStart: string;
+    weekEnd: string;
+    /** Specs completed (done) up to and including this week */
+    completedCumulative: number;
+    /** Specs completed in this specific week */
+    completedThisWeek: number;
+    /** Specs created up to and including this week */
+    createdCumulative: number;
+    /** Backlog: total created - total completed */
+    backlog: number;
+}
+/**
+ * Flow efficiency: time spent in active states vs total lead time.
+ */
+export interface FlowEfficiencyStats {
+    /** 0.0-1.0 ratio of active time to total time */
+    efficiency: number;
+    /** Average hours spent in active states (implementing, review) */
+    avgActiveHours: number;
+    /** Average total lead time hours */
+    avgTotalHours: number;
+    sampleSize: number;
+}
+/**
+ * WIP (Work In Progress) snapshot.
+ */
+export interface WipSnapshot {
+    current: number;
+    specIds: string[];
+    avgAgeHours: number;
+}
+/**
+ * Full velocity report for a project.
+ */
+export interface VelocityReport {
+    projectId: string;
+    projectPath: string;
+    generatedAt: string;
+    /** Number of weeks analyzed */
+    weeks: number;
+    /** Applied filters */
+    filters: VelocityFilters;
+    /** Average specs completed per week */
+    avgThroughputPerWeek: number;
+    throughput: ThroughputPoint[];
+    leadTime: LeadTimeStats | null;
+    cycleTime: CycleTimeStats | null;
+    wip: WipSnapshot;
+    flowEfficiency: FlowEfficiencyStats | null;
+    burndown: BurndownPoint[];
+    /** Human-readable summary line */
+    summary: string;
+    /** Total specs done in the period */
+    totalDone: number;
+    /** Total specs in the project */
+    totalSpecs: number;
+}
+/**
+ * Trend comparison: last N weeks vs previous N weeks.
+ */
+export interface VelocityTrend {
+    projectId: string;
+    projectPath: string;
+    generatedAt: string;
+    compareWeeks: number;
+    recent: VelocityPeriodStats;
+    previous: VelocityPeriodStats;
+    throughputDelta: number;
+    leadTimeDelta: number | null;
+    trend: 'improving' | 'stable' | 'declining';
+    summary: string;
+}
+export interface VelocityPeriodStats {
+    label: string;
+    fromDate: string;
+    toDate: string;
+    avgThroughputPerWeek: number;
+    avgLeadTimeHours: number | null;
+    totalDone: number;
+}
+/**
+ * Input filters for velocity tools.
+ */
+export interface VelocityFilters {
+    weeks: number;
+    scope?: SpecScope;
+    type?: SpecType;
+}
+/** Input args for velocity_report tool */
+export interface VelocityReportInput {
+    projectPath: string;
+    weeks?: number;
+    scope?: SpecScope;
+    type?: SpecType;
+}
+/** Input args for velocity_trend tool */
+export interface VelocityTrendInput {
+    projectPath: string;
+    compareWeeks?: number;
+    scope?: SpecScope;
+    type?: SpecType;
+}
+/**
+ * Velocity profile derived from recent spec actuals.
+ * Used to convert devHours estimates into real calendar days.
+ * SPEC-555
+ */
+export interface VelocityProfile {
+    /** SPECs completed per calendar day (in the window) */
+    specsPerDay: number;
+    /** Productive dev hours per calendar day */
+    hoursPerDay: number;
+    /** Average actual devHours by difficulty (1-5) */
+    avgHoursByDifficulty: Record<1 | 2 | 3 | 4 | 5, number>;
+    /** ISO date of last calculation */
+    calibrationDate: string;
+    /** Window used to calculate (default 30 days) */
+    windowDays: number;
+    /** Number of done specs used for calibration */
+    sampleSize: number;
+    /** Confidence based on sample size: high >20, medium 5-20, low <5 */
+    confidence: 'high' | 'medium' | 'low';
+}
+//# sourceMappingURL=velocity.d.ts.map

package/dist/types/data/velocity.js

@@ -0,0 +1,4 @@
+// types/velocity.ts — Velocity metrics domain types (SPEC-288)
+// Lead Time, Throughput, Burndown, Cycle Time, WIP, Flow Efficiency
+export {};
+//# sourceMappingURL=velocity.js.map

package/package.json

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