@planu/cli 0.90.2 → 0.92.0

package/dist/tools/email-digest-handler.js

@@ -0,0 +1,198 @@
+import { getEmailDigestConfig, saveEmailDigestConfig, getDeliveryLog, appendDelivery, } from '../storage/email-digest-store.js';
+import { generateDigestContent } from '../engine/email-digest-generator.js';
+import { sendViaFile, sendViaSendGrid, sendViaSmtp } from '../engine/email-sender.js';
+import { hashProjectPath } from '../storage/base-store.js';
+import { listSpecs } from '../storage/spec-store.js';
+const DEFAULT_PERIOD_DAYS = 7;
+// ---------------------------------------------------------------------------
+// configure_email_digest
+// ---------------------------------------------------------------------------
+export async function handleConfigureEmailDigest(input) {
+    const config = {
+        provider: input.provider,
+        frequency: input.frequency,
+        recipients: input.recipients,
+        credentials: input.credentials ?? {},
+        updatedAt: new Date().toISOString(),
+    };
+    await saveEmailDigestConfig(input.projectPath, config);
+    const lines = [
+        'Email digest configured.',
+        '',
+        '| Field | Value |',
+        '|-------|-------|',
+        `| Provider | ${config.provider} |`,
+        `| Frequency | ${config.frequency} |`,
+        `| Recipients | ${config.recipients.join(', ')} |`,
+        `| Updated At | ${config.updatedAt.slice(0, 10)} |`,
+    ];
+    if (config.provider === 'sendgrid' && !config.credentials.apiKey) {
+        lines.push('', '> Warning: No API key set. Run again with credentials.apiKey to complete setup.');
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+}
+// ---------------------------------------------------------------------------
+// generate_digest
+// ---------------------------------------------------------------------------
+export async function handleGenerateDigest(input) {
+    const days = input.days ?? DEFAULT_PERIOD_DAYS;
+    const projectId = hashProjectPath(input.projectPath);
+    const specs = await listSpecs(projectId);
+    const digest = generateDigestContent(specs, days);
+    const lines = [
+        `Digest generated for the last **${days} day${days === 1 ? '' : 's'}**.`,
+        '',
+        '**Stats:**',
+        `- Total specs: ${digest.stats.total}`,
+        `- Completed in period: ${digest.stats.completedInPeriod}`,
+        `- In progress: ${digest.stats.wipCount}`,
+        `- Blocked: ${digest.stats.blockedCount}`,
+        `- Upcoming (approved): ${digest.stats.upcomingCount}`,
+        '',
+        '---',
+        '',
+        digest.text,
+    ];
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        structuredContent: {
+            stats: digest.stats,
+            completedSpecs: digest.completedSpecs,
+            wipSpecs: digest.wipSpecs,
+            blockedSpecs: digest.blockedSpecs,
+            upcomingSpecs: digest.upcomingSpecs,
+            generatedAt: digest.generatedAt,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// send_digest
+// ---------------------------------------------------------------------------
+export async function handleSendDigest(input) {
+    const config = await getEmailDigestConfig(input.projectPath);
+    if (config === null) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Email digest is not configured for this project. ' +
+                        'Run configure_email_digest first.',
+                },
+            ],
+            isError: true,
+        };
+    }
+    const days = input.days ?? DEFAULT_PERIOD_DAYS;
+    const projectId = hashProjectPath(input.projectPath);
+    const specs = await listSpecs(projectId);
+    const digest = generateDigestContent(specs, days);
+    const deliveryId = generateDeliveryId();
+    const delivery = {
+        id: deliveryId,
+        sentAt: new Date().toISOString(),
+        status: 'sent',
+        provider: config.provider,
+    };
+    try {
+        await dispatchDigest(digest, config, projectId);
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        delivery.status = 'failed';
+        delivery.error = errMsg;
+        await appendDelivery(input.projectPath, delivery);
+        return {
+            content: [{ type: 'text', text: `Digest delivery failed: ${errMsg}` }],
+            isError: true,
+        };
+    }
+    if (config.provider === 'file') {
+        delivery.status = 'saved';
+    }
+    await appendDelivery(input.projectPath, delivery);
+    const providerLabel = config.provider === 'file'
+        ? `saved to disk (delivery ID: ${deliveryId})`
+        : `sent via ${config.provider} (delivery ID: ${deliveryId})`;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: [
+                    `Digest ${providerLabel}.`,
+                    '',
+                    `Period: last ${days} day${days === 1 ? '' : 's'}`,
+                    `Recipients: ${config.recipients.join(', ') || '(file mode — no recipients)'}`,
+                    `Stats: ${digest.stats.completedInPeriod} completed, ${digest.stats.wipCount} in-progress, ${digest.stats.blockedCount} blocked`,
+                ].join('\n'),
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// email_digest_status
+// ---------------------------------------------------------------------------
+export async function handleEmailDigestStatus(input) {
+    const [config, log] = await Promise.all([
+        getEmailDigestConfig(input.projectPath),
+        getDeliveryLog(input.projectPath),
+    ]);
+    if (config === null) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'No email digest configuration found. ' +
+                        'Run configure_email_digest to set up digests for this project.',
+                },
+            ],
+        };
+    }
+    const lines = [
+        '**Email Digest Configuration**',
+        '',
+        '| Field | Value |',
+        '|-------|-------|',
+        `| Provider | ${config.provider} |`,
+        `| Frequency | ${config.frequency} |`,
+        `| Recipients | ${config.recipients.join(', ') || '(none)'} |`,
+        `| Updated At | ${config.updatedAt.slice(0, 10)} |`,
+        '',
+        `**Delivery Log** (last ${log.length})`,
+    ];
+    if (log.length === 0) {
+        lines.push('', 'No deliveries yet.');
+    }
+    else {
+        lines.push('', '| ID | Date | Status | Provider |', '|----|------|--------|----------|');
+        for (const d of log) {
+            const errNote = d.error ? ` — ${d.error.slice(0, 60)}` : '';
+            lines.push(`| ${d.id} | ${d.sentAt.slice(0, 10)} | ${d.status}${errNote} | ${d.provider} |`);
+        }
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        structuredContent: { config, deliveries: log },
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+let _deliveryCounter = 0;
+function generateDeliveryId() {
+    _deliveryCounter += 1;
+    return `DLV-${String(_deliveryCounter).padStart(3, '0')}`;
+}
+async function dispatchDigest(digest, config, projectHash) {
+    const provider = config.provider;
+    if (provider === 'file') {
+        await sendViaFile(digest, projectHash);
+        return;
+    }
+    if (provider === 'sendgrid') {
+        await sendViaSendGrid(digest, config);
+        return;
+    }
+    /* v8 ignore next 2 */
+    await sendViaSmtp(digest, config);
+}
+//# sourceMappingURL=email-digest-handler.js.map

package/dist/tools/email-digest-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-digest-handler.js","sourceRoot":"","sources":["../../src/tools/email-digest-handler.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,cAAc,GACf,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,KAAgC;IAEhC,MAAM,MAAM,GAAsB;QAChC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;QACpC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,MAAM,qBAAqB,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAEvD,MAAM,KAAK,GAAa;QACtB,0BAA0B;QAC1B,EAAE;QACF,mBAAmB;QACnB,mBAAmB;QACnB,gBAAgB,MAAM,CAAC,QAAQ,IAAI;QACnC,iBAAiB,MAAM,CAAC,SAAS,IAAI;QACrC,kBAAkB,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QAClD,kBAAkB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI;KACpD,CAAC;IAEF,IAAI,MAAM,CAAC,QAAQ,KAAK,UAAU,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;QACjE,KAAK,CAAC,IAAI,CACR,EAAE,EACF,iFAAiF,CAClF,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;AACjE,CAAC;AAED,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,KAA0B;IACnE,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,mBAAmB,CAAC;IAC/C,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,SAAS,CAAC,CAAC;IAEzC,MAAM,MAAM,GAAG,qBAAqB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAElD,MAAM,KAAK,GAAa;QACtB,mCAAmC,IAAI,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK;QACxE,EAAE;QACF,YAAY;QACZ,kBAAkB,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE;QACtC,0BAA0B,MAAM,CAAC,KAAK,CAAC,iBAAiB,EAAE;QAC1D,kBAAkB,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE;QACzC,cAAc,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE;QACzC,0BAA0B,MAAM,CAAC,KAAK,CAAC,aAAa,EAAE;QACtD,EAAE;QACF,KAAK;QACL,EAAE;QACF,MAAM,CAAC,IAAI;KACZ,CAAC;IAEF,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,iBAAiB,EAAE;YACjB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAsB;IAC3D,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAE7D,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EACF,mDAAmD;wBACnD,mCAAmC;iBACtC;aACF;YACD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,mBAAmB,CAAC;IAC/C,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,qBAAqB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAElD,MAAM,UAAU,GAAG,kBAAkB,EAAE,CAAC;IACxC,MAAM,QAAQ,GAAmB;QAC/B,EAAE,EAAE,UAAU;QACd,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAChC,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC;QAC3B,QAAQ,CAAC,KAAK,GAAG,MAAM,CAAC;QACxB,MAAM,cAAc,CAAC,KAAK,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAClD,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,2BAA2B,MAAM,EAAE,EAAE,CAAC;YACtE,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QAC/B,QAAQ,CAAC,MAAM,GAAG,OAAO,CAAC;IAC5B,CAAC;IAED,MAAM,cAAc,CAAC,KAAK,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAElD,MAAM,aAAa,GACjB,MAAM,CAAC,QAAQ,KAAK,MAAM;QACxB,CAAC,CAAC,+BAA+B,UAAU,GAAG;QAC9C,CAAC,CAAC,YAAY,MAAM,CAAC,QAAQ,kBAAkB,UAAU,GAAG,CAAC;IAEjE,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE;oBACJ,UAAU,aAAa,GAAG;oBAC1B,EAAE;oBACF,gBAAgB,IAAI,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE;oBAClD,eAAe,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,6BAA6B,EAAE;oBAC9E,UAAU,MAAM,CAAC,KAAK,CAAC,iBAAiB,eAAe,MAAM,CAAC,KAAK,CAAC,QAAQ,iBAAiB,MAAM,CAAC,KAAK,CAAC,YAAY,UAAU;iBACjI,CAAC,IAAI,CAAC,IAAI,CAAC;aACb;SACF;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,KAA6B;IACzE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACtC,oBAAoB,CAAC,KAAK,CAAC,WAAW,CAAC;QACvC,cAAc,CAAC,KAAK,CAAC,WAAW,CAAC;KAClC,CAAC,CAAC;IAEH,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EACF,uCAAuC;wBACvC,gEAAgE;iBACnE;aACF;SACF,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAa;QACtB,gCAAgC;QAChC,EAAE;QACF,mBAAmB;QACnB,mBAAmB;QACnB,gBAAgB,MAAM,CAAC,QAAQ,IAAI;QACnC,iBAAiB,MAAM,CAAC,SAAS,IAAI;QACrC,kBAAkB,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,IAAI;QAC9D,kBAAkB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI;QACnD,EAAE;QACF,0BAA0B,GAAG,CAAC,MAAM,GAAG;KACxC,CAAC;IAEF,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,oBAAoB,CAAC,CAAC;IACvC,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,mCAAmC,EAAE,mCAAmC,CAAC,CAAC;QACzF,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;YACpB,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5D,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,OAAO,MAAM,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,iBAAiB,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE;KAC/C,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,IAAI,gBAAgB,GAAG,CAAC,CAAC;AAEzB,SAAS,kBAAkB;IACzB,gBAAgB,IAAI,CAAC,CAAC;IACtB,OAAO,OAAO,MAAM,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,MAAqB,EACrB,MAAyB,EACzB,WAAmB;IAEnB,MAAM,QAAQ,GAAwB,MAAM,CAAC,QAAQ,CAAC;IAEtD,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,MAAM,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACvC,OAAO;IACT,CAAC;IAED,IAAI,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC5B,MAAM,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,OAAO;IACT,CAAC;IAED,sBAAsB;IACtB,MAAM,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC"}

package/dist/tools/estimate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"estimate.d.ts","sourceRoot":"","sources":["../../src/tools/estimate.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEnE,wBAAsB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CA6F7E"}
+{"version":3,"file":"estimate.d.ts","sourceRoot":"","sources":["../../src/tools/estimate.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEnE,wBAAsB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAoH7E"}

package/dist/tools/estimate.js

@@ -1,6 +1,8 @@
 // tools/estimate.ts — Estimate difficulty, hours, tokens, costs for a spec
 // Uses the estimator engine with historical metrics for calibration.
 import { specStore, metricsStore, globalStore, knowledgeStore } from '../storage/index.js';
+import { getCalibration } from '../storage/actuals-store.js';
+import { applyCalibration } from '../engine/estimation-calibrator.js';
 import { estimateSpec } from '../engine/estimator.js';
 import { classifyOperation, recommendModel } from '../engine/token-tracker.js';
 import { ti } from '../i18n/index.js';
@@ -32,6 +34,25 @@ export async function handleEstimate(args) {
     const metricsHistory = await metricsStore.getMetricsHistory(projectId);
     // 5. Run estimation engine
     const result = estimateSpec(spec, configOverrides, metricsHistory.entries);
+    // 5a. SPEC-287: Apply SPEC-287 calibration factors on top of existing estimation
+    const calibrationFactors = await getCalibration(projectId).catch(() => null);
+    let calibrationNote = null;
+    if (calibrationFactors) {
+        const rawHours = result.estimation.devHours + result.estimation.reviewHours;
+        const calibratedHours = applyCalibration(rawHours, spec.scope, spec.type, calibrationFactors);
+        if (calibratedHours !== rawHours) {
+            const ratio = calibratedHours / rawHours;
+            result.estimation.devHours = Math.round(result.estimation.devHours * ratio * 10) / 10;
+            result.estimation.reviewHours = Math.round(result.estimation.reviewHours * ratio * 10) / 10;
+            result.estimation.humanCostUsd =
+                Math.round((result.estimation.devHours + result.estimation.reviewHours) *
+                    result.estimation.hourlyRate *
+                    100) / 100;
+            result.estimation.totalCostUsd =
+                Math.round((result.estimation.apiCostUsd + result.estimation.humanCostUsd) * 100) / 100;
+            calibrationNote = `Calibration applied (${spec.scope}/${spec.type}): ${String(rawHours)}h → ${String(calibratedHours)}h`;
+        }
+    }
     // 6. Update spec with estimation data
     await specStore.updateSpec(projectId, specId, {
         estimation: result.estimation,
@@ -66,6 +87,7 @@ export async function handleEstimate(args) {
         reasoning: result.reasoning,
         similarSpecs: result.similarSpecs,
         historyUsed: metricsHistory.entries.length > 0,
+        calibrationApplied: calibrationNote,
     };
     const level = knowledge?.experienceLevel ?? 'intermediate';
     const summary = formatByLevel(ti('tools.estimate.success', {

package/dist/tools/estimate.js.map

@@ -1 +1 @@
-{"version":3,"file":"estimate.js","sourceRoot":"","sources":["../../src/tools/estimate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"estimate.js","sourceRoot":"","sources":["../../src/tools/estimate.ts"],"names":[],"mappings":"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"}

package/dist/tools/estimation-accuracy-handler.d.ts

@@ -0,0 +1,5 @@
+import type { ToolResult, RecordActualInput, AccuracyReportInput, CalibrateInput } from '../types/index.js';
+export declare function handleRecordActual(input: RecordActualInput): Promise<ToolResult>;
+export declare function handleEstimationAccuracyReport(input: AccuracyReportInput): Promise<ToolResult>;
+export declare function handleCalibrateEstimates(input: CalibrateInput): Promise<ToolResult>;
+//# sourceMappingURL=estimation-accuracy-handler.d.ts.map

package/dist/tools/estimation-accuracy-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimation-accuracy-handler.d.ts","sourceRoot":"","sources":["../../src/tools/estimation-accuracy-handler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EAIf,MAAM,mBAAmB,CAAC;AA4B3B,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAqEtF;AAMD,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,UAAU,CAAC,CAuDrB;AAMD,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA6CzF"}

package/dist/tools/estimation-accuracy-handler.js

@@ -0,0 +1,171 @@
+import { hashProjectPath } from '../storage/base-store.js';
+import { specStore } from '../storage/index.js';
+import { saveActual, listActuals, saveCalibration } from '../storage/actuals-store.js';
+import { computeDeviationPct, generateAccuracyReport, computeCalibrationFactors, } from '../engine/estimation-calibrator.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function resolveProjectId(params) {
+    if (params.projectId) {
+        return params.projectId;
+    }
+    if (params.projectPath) {
+        return hashProjectPath(params.projectPath);
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// record_actual handler
+// ---------------------------------------------------------------------------
+export async function handleRecordActual(input) {
+    const { specId, actualHours, notes } = input;
+    const projectId = resolveProjectId(input);
+    if (!projectId) {
+        return {
+            content: [{ type: 'text', text: 'Provide projectId or projectPath.' }],
+            isError: true,
+        };
+    }
+    if (actualHours < 0) {
+        return {
+            content: [{ type: 'text', text: 'actualHours must be a non-negative number.' }],
+            isError: true,
+        };
+    }
+    const spec = await specStore.getSpec(projectId, specId);
+    if (!spec) {
+        return {
+            content: [{ type: 'text', text: `Spec '${specId}' not found.` }],
+            isError: true,
+        };
+    }
+    const estimatedHours = spec.estimation.devHours + spec.estimation.reviewHours;
+    const deviationPct = computeDeviationPct(estimatedHours, actualHours);
+    const specType = spec.type ?? 'feature';
+    const specScope = spec.scope ?? 'feature';
+    const record = {
+        specId,
+        estimatedHours,
+        actualHours,
+        deviationPct,
+        specType,
+        specScope,
+        recordedAt: new Date().toISOString(),
+        ...(notes !== undefined ? { notes } : {}),
+    };
+    await saveActual(projectId, record);
+    const deviationLabel = deviationPct > 0 ? `+${deviationPct.toFixed(1)}%` : `${deviationPct.toFixed(1)}%`;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: [
+                    `Actual recorded for ${specId}.`,
+                    `Estimated: ${String(estimatedHours)}h | Actual: ${String(actualHours)}h | Deviation: ${deviationLabel}`,
+                    notes ? `Notes: ${notes}` : '',
+                ]
+                    .filter(Boolean)
+                    .join('\n'),
+            },
+        ],
+        structuredContent: {
+            specId,
+            estimatedHours,
+            actualHours,
+            deviationPct,
+            recordedAt: record.recordedAt,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// estimation_accuracy_report handler
+// ---------------------------------------------------------------------------
+export async function handleEstimationAccuracyReport(input) {
+    const projectId = resolveProjectId(input);
+    if (!projectId) {
+        return {
+            content: [{ type: 'text', text: 'Provide projectId or projectPath.' }],
+            isError: true,
+        };
+    }
+    let records = await listActuals(projectId);
+    if (input.scope !== undefined) {
+        records = records.filter((r) => r.specScope === input.scope);
+    }
+    if (input.type !== undefined) {
+        records = records.filter((r) => r.specType === input.type);
+    }
+    if (input.limit !== undefined && input.limit > 0) {
+        records = records.slice(-input.limit);
+    }
+    if (records.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'No actuals recorded yet. Use record_actual after completing specs.',
+                },
+            ],
+        };
+    }
+    const report = generateAccuracyReport(projectId, records);
+    const lines = [
+        `Estimation Accuracy Report — ${String(report.totalRecords)} specs`,
+        `Avg deviation: ${String(report.aggregate.avgDeviationPct)}% | Median: ${String(report.aggregate.medianDeviationPct)}%`,
+        `Outliers (>50% deviation): ${String(report.aggregate.outlierCount)}`,
+        '',
+        'By scope:',
+        ...report.byScope.map((s) => `  ${s.scope}: avg ${String(s.avgDeviationPct)}% (${String(s.count)} specs, multiplier: ${String(s.suggestedMultiplier)}x)`),
+        '',
+        'By type:',
+        ...report.byType.map((t) => `  ${t.type}: avg ${String(t.avgDeviationPct)}% (${String(t.count)} specs)`),
+    ];
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        structuredContent: report,
+    };
+}
+// ---------------------------------------------------------------------------
+// calibrate_estimates handler
+// ---------------------------------------------------------------------------
+export async function handleCalibrateEstimates(input) {
+    const projectId = resolveProjectId(input);
+    if (!projectId) {
+        return {
+            content: [{ type: 'text', text: 'Provide projectId or projectPath.' }],
+            isError: true,
+        };
+    }
+    const minSamples = input.minSamples ?? 3;
+    const records = await listActuals(projectId);
+    if (records.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'No actuals recorded yet. Cannot calibrate without historical data.',
+                },
+            ],
+        };
+    }
+    const factors = computeCalibrationFactors(projectId, records, minSamples);
+    await saveCalibration(projectId, factors);
+    const scopeEntries = Object.entries(factors.scopeMultipliers);
+    const typeEntries = Object.entries(factors.typeMultipliers);
+    const lines = [
+        `Calibration updated — based on ${String(records.length)} actuals (min samples: ${String(minSamples)}).`,
+        '',
+        scopeEntries.length > 0
+            ? `Scope multipliers updated:\n${scopeEntries.map(([k, v]) => `  ${k}: ${String(v)}x`).join('\n')}`
+            : 'No scope multipliers updated (insufficient samples or deviation <20%).',
+        '',
+        typeEntries.length > 0
+            ? `Type multipliers updated:\n${typeEntries.map(([k, v]) => `  ${k}: ${String(v)}x`).join('\n')}`
+            : 'No type multipliers updated (insufficient samples or deviation <20%).',
+    ];
+    return {
+        content: [{ type: 'text', text: lines.filter(Boolean).join('\n') }],
+        structuredContent: factors,
+    };
+}
+//# sourceMappingURL=estimation-accuracy-handler.js.map

package/dist/tools/estimation-accuracy-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimation-accuracy-handler.js","sourceRoot":"","sources":["../../src/tools/estimation-accuracy-handler.ts"],"names":[],"mappings":"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"}

package/dist/tools/facilitate.d.ts

@@ -1,8 +1,4 @@
 import type { ToolResult, FacilitateInput, ParadigmReport } from '../types/index.js';
-/**
- * Builds paradigm expert voice observations from a pre-computed ParadigmReport.
- * Degrades gracefully when no detection data is available.
- */
 export declare function buildParadigmObservations(paradigmReport: ParadigmReport | null | undefined): string;
-export declare function handleFacilitate(params: FacilitateInput): ToolResult;
+export declare function handleFacilitate(params: FacilitateInput): Promise<ToolResult>;
 //# sourceMappingURL=facilitate.d.ts.map

package/dist/tools/facilitate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facilitate.d.ts","sourceRoot":"","sources":["../../src/tools/facilitate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EAEV,eAAe,EAGf,cAAc,EACf,MAAM,mBAAmB,CAAC;AAwI3B;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAChD,MAAM,CAMR;AAiDD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU,CAsIpE"}
+{"version":3,"file":"facilitate.d.ts","sourceRoot":"","sources":["../../src/tools/facilitate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EAEV,eAAe,EAGf,cAAc,EAEf,MAAM,mBAAmB,CAAC;AAwI3B,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAChD,MAAM,CAMR;AA2HD,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CA+JnF"}