brainclaw 1.7.5 → 1.9.0

package/dist/commands/estimation-report.js

@@ -1,5 +1,47 @@
 import { loadState } from '../core/state.js';
 import { memoryExists } from '../core/io.js';
+/** Default wall-clock outlier cutoff: a single plan's "actual" over 24h is almost certainly idle, not work. */
+export const DEFAULT_OUTLIER_THRESHOLD_MINUTES = 1440;
+/**
+ * Sum of per-step estimates — only when EVERY step carries one. A mixed plan
+ * (some steps estimated, some not) returns undefined so the caller falls back
+ * to the plan-level estimate rather than mixing half-measured data (pln#495).
+ */
+function sumStepEstimates(plan) {
+    const steps = plan.steps ?? [];
+    if (steps.length === 0)
+        return undefined;
+    if (!steps.every((s) => typeof s.estimated_effort === 'number'))
+        return undefined;
+    return steps.reduce((acc, s) => acc + s.estimated_effort, 0);
+}
+/**
+ * Sum of per-step actual durations — only when EVERY step is measurable, via an
+ * explicit `actual_effort` string OR both `started_at`+`completed_at`. Returns
+ * undefined otherwise (→ fall back to plan-level). This is the key win: summing
+ * per-step durations excludes the idle time BETWEEN steps that plan-level
+ * wall-clock wrongly counts as work (pln#495, the pln#494 step-6 bias).
+ */
+function sumStepActuals(plan) {
+    const steps = plan.steps ?? [];
+    if (steps.length === 0)
+        return undefined;
+    let total = 0;
+    for (const s of steps) {
+        let dur;
+        if (s.actual_effort) {
+            dur = parseEffortMinutes(s.actual_effort);
+        }
+        else if (s.started_at && s.completed_at) {
+            const d = (new Date(s.completed_at).getTime() - new Date(s.started_at).getTime()) / 60000;
+            dur = d > 0 ? d : undefined;
+        }
+        if (dur === undefined)
+            return undefined; // any unmeasurable step → no step-level actual
+        total += dur;
+    }
+    return total > 0 ? total : undefined;
+}
 /** Parse legacy actual_effort strings ("30min", "2h", "1h30m", "1d", "45m") → minutes.
  *  Still needed for actual_effort which remains a free string. */
 export function parseEffortMinutes(effort) {
@@ -23,7 +65,7 @@ export function parseEffortMinutes(effort) {
     }
     if (!matched) {
         const bare = parseFloat(s);
-        if (!isNaN(bare))
+        if (!isNaN(bare) && /^\d+(?:\.\d+)?$/.test(s))
             return bare;
         return undefined;
     }
@@ -65,37 +107,78 @@ export function buildEstimationReport(options = {}) {
     const state = loadState(options.cwd);
     const done = state.plan_items.filter((p) => p.status === 'done' && (!options.agent || p.author === options.agent));
     const entries = done.map((p) => {
+        // Estimate: prefer the sum of per-step estimates when ALL steps carry one,
+        // else the plan-level estimate (pln#495).
+        const stepEstimate = sumStepEstimates(p);
         const entry = {
             id: p.id,
             text: p.text,
             author: p.author,
-            estimated_minutes: p.estimated_effort, // already a number after schema coercion
+            estimated_minutes: stepEstimate ?? p.estimated_effort,
             actual_effort: p.actual_effort,
             completed_at: p.completed_at,
         };
-        // Compute elapsed from wall-clock timestamps
-        const endTime = p.completed_at ?? p.updated_at;
-        const startTime = p.started_at ?? p.created_at;
-        if (endTime && startTime) {
-            const elapsed = (new Date(endTime).getTime() - new Date(startTime).getTime()) / 60000;
-            if (elapsed > 0)
-                entry.elapsed_minutes = Math.round(elapsed);
+        // Actual + source, in fallback order (pln#495):
+        //   step durations (idle-gap-free) > plan.actual_effort string > plan wall-clock.
+        let actualMinutes;
+        let source;
+        const stepActual = sumStepActuals(p);
+        if (stepActual !== undefined) {
+            actualMinutes = stepActual;
+            source = 'step';
         }
-        // Resolve actual minutes: explicit actual_effort string > elapsed wall-clock
-        const actualMinutes = p.actual_effort
-            ? parseEffortMinutes(p.actual_effort)
-            : entry.elapsed_minutes;
-        if (actualMinutes !== undefined)
+        else if (p.actual_effort) {
+            actualMinutes = parseEffortMinutes(p.actual_effort);
+            source = 'plan_string';
+        }
+        else {
+            const endTime = p.completed_at ?? p.updated_at;
+            const startTime = p.started_at ?? p.created_at;
+            if (endTime && startTime) {
+                const elapsed = (new Date(endTime).getTime() - new Date(startTime).getTime()) / 60000;
+                if (elapsed > 0)
+                    actualMinutes = elapsed;
+            }
+            source = 'plan_wallclock';
+        }
+        if (actualMinutes !== undefined) {
             entry.elapsed_minutes = Math.round(actualMinutes);
+            entry.source = source;
+        }
         if (entry.estimated_minutes !== undefined && actualMinutes !== undefined && actualMinutes > 0) {
             entry.ratio = parseFloat((entry.estimated_minutes / actualMinutes).toFixed(2));
         }
         return entry;
     });
+    // Wall-clock outlier filter (pln#495 step 7): a plan whose actual is plan-level
+    // wall-clock AND exceeds the threshold is flagged and dropped from the summary
+    // stats — it would otherwise drag the median/mean (the post-restoration +9900%
+    // accident). Step- and string-derived actuals are trusted at any size. A
+    // threshold of 0 disables the filter. Outliers keep their ratio and stay in
+    // `entries` so the chart still shows them, just marked.
+    const threshold = options.outlierThresholdMinutes ?? DEFAULT_OUTLIER_THRESHOLD_MINUTES;
+    if (threshold > 0) {
+        for (const e of entries) {
+            if (e.source === 'plan_wallclock' && e.elapsed_minutes !== undefined && e.elapsed_minutes > threshold) {
+                e.excluded_from_stats = true;
+            }
+        }
+    }
     const withBoth = entries.filter((e) => e.ratio !== undefined);
-    const ratios = withBoth.map((e) => e.ratio);
+    const included = withBoth.filter((e) => !e.excluded_from_stats);
+    const ratios = included.map((e) => e.ratio);
     const medianRatio = ratios.length > 0 ? parseFloat(median(ratios).toFixed(2)) : undefined;
     const meanRatio = ratios.length > 0 ? parseFloat(mean(ratios).toFixed(2)) : undefined;
+    // Per-source median (pln#495): exposes how much calibration noise is wall-clock
+    // contamination vs idle-gap-free step measurement. Excludes flagged outliers.
+    const bySource = {};
+    for (const src of ['step', 'plan_string', 'plan_wallclock']) {
+        const srcRatios = included.filter((e) => e.source === src).map((e) => e.ratio);
+        if (srcRatios.length > 0) {
+            bySource[src] = { count: srcRatios.length, median_ratio: parseFloat(median(srcRatios).toFixed(2)) };
+        }
+    }
+    const outliersExcluded = withBoth.filter((e) => e.excluded_from_stats).length;
     return {
         entries,
         summary: {
@@ -105,6 +188,8 @@ export function buildEstimationReport(options = {}) {
             median_ratio: medianRatio,
             mean_ratio: meanRatio,
             calibration_hint: medianRatio !== undefined ? buildCalibrationHint(medianRatio) : undefined,
+            by_source: Object.keys(bySource).length > 0 ? bySource : undefined,
+            outliers_excluded: outliersExcluded > 0 ? outliersExcluded : undefined,
         },
     };
 }
@@ -129,6 +214,19 @@ export function runEstimationReport(options = {}) {
         console.log(`\nMedian ratio (estimated÷actual): ${summary.median_ratio}x · Mean: ${summary.mean_ratio}x`);
         console.log(`→ ${summary.calibration_hint}`);
     }
+    if (summary.outliers_excluded) {
+        console.log(`(${summary.outliers_excluded} wall-clock outlier(s) >24h excluded from the stats above — shown ⚠ in the chart)`);
+    }
+    if (summary.by_source) {
+        const labels = {
+            step: 'step-derived', plan_string: 'plan-string', plan_wallclock: 'plan-wallclock',
+        };
+        const parts = ['step', 'plan_string', 'plan_wallclock']
+            .filter((s) => summary.by_source[s])
+            .map((s) => `${labels[s]}: ${summary.by_source[s].median_ratio}x (n=${summary.by_source[s].count})`);
+        console.log(`By measurement quality — ${parts.join(' · ')}`);
+        console.log('  (step-derived excludes inter-step idle; plan-wallclock is the noisiest)');
+    }
     // Chart — only plans with ratio data
     const chartable = entries.filter((e) => e.ratio !== undefined);
     if (chartable.length > 0) {
@@ -149,7 +247,8 @@ export function runEstimationReport(options = {}) {
                 : ` OVER  +${Math.round((1 / e.ratio - 1) * 100)}%`;
             const est = e.estimated_minutes !== undefined ? `${e.estimated_minutes}min` : '?';
             const act = e.elapsed_minutes !== undefined ? `${e.elapsed_minutes}min` : '?';
-            console.log(`  ${label} ${bar} ${e.ratio}x  ${est}→${act}${pct}`);
+            const srcTag = e.excluded_from_stats ? ' ⚠outlier' : e.source === 'step' ? ' ✓step' : e.source === 'plan_wallclock' ? ' ~wall' : '';
+            console.log(`  ${label} ${bar} ${e.ratio}x  ${est}→${act}${pct}${srcTag}`);
         }
         console.log('');
     }