@devflow-tools/database 0.16.0 → 0.16.3

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.16.3](https://github.com/shilongfeicool/dev-flow/compare/v0.16.2...v0.16.3) (2026-07-22)
+
+
+### Bug Fixes
+
+* **telemetry:** measure required MCP obligations ([f7e976c](https://github.com/shilongfeicool/dev-flow/commit/f7e976c28bf1629cf4c05c2ba6a49f569bf882d7))
+
+
+
+
+
+## [0.16.2](https://github.com/shilongfeicool/dev-flow/compare/v0.16.1...v0.16.2) (2026-07-22)
+
+
+### Bug Fixes
+
+* harden Claude plugin lifecycle ([992e74f](https://github.com/shilongfeicool/dev-flow/commit/992e74ff0a37cdb5132736eba3926be7639ac806))
+
+
+
+
+
 # [0.16.0](https://github.com/shilongfeicool/dev-flow/compare/v0.15.0...v0.16.0) (2026-07-22)
 
 

package/__tests__/database.skill-executions.test.ts

@@ -142,14 +142,20 @@ describe('DevFlowDatabase - Skill Executions', () => {
     expect(reactExecs[0].skillName).toBe('devflow:react');
   });
 
-  it('should compute MCP compliance rate', () => {
-    // Execution 1: 2 MCP, 1 direct = 66.7%
+  it('computes required MCP obligation compliance independently of direct calls', () => {
+    // React requires successful context plus at least one React domain tool.
     db.insertSkillExecution({
       executionId: 'exec_001',
       skillName: 'devflow:react',
       startedAt: Date.now(),
       status: 'completed',
     });
+    db.insertToolCallEvent({
+      eventId: 'evt_context_1', executionId: 'exec_001', timestamp: Date.now(),
+      toolName: 'mcp__devflow__get_project_context', toolType: 'mcp',
+      isMcpTool: true, mcpToolName: 'get_project_context', mcpEnforced: true,
+      mcpFallback: false, input: {}, duration: 20, blocked: false,
+    });
     db.insertToolCallEvent({
       eventId: 'evt_001', executionId: 'exec_001', timestamp: Date.now(),
       toolName: 'mcp__devflow__react_diagnose_bug', toolType: 'mcp',
@@ -165,17 +171,23 @@ describe('DevFlowDatabase - Skill Executions', () => {
     db.insertToolCallEvent({
       eventId: 'evt_003', executionId: 'exec_001', timestamp: Date.now(),
       toolName: 'Read', toolType: 'direct',
-      isMcpTool: false, mcpEnforced: false, mcpFallback: true,
+      isMcpTool: false, mcpEnforced: false, mcpFallback: false,
       input: {}, tokensUsed: 50, duration: 100, blocked: false,
     });
 
-    // Execution 2: 1 MCP, 0 direct = 100%
+    // Vue has the same context + domain obligations.
     db.insertSkillExecution({
       executionId: 'exec_002',
       skillName: 'devflow:vue',
       startedAt: Date.now(),
       status: 'completed',
     });
+    db.insertToolCallEvent({
+      eventId: 'evt_context_2', executionId: 'exec_002', timestamp: Date.now(),
+      toolName: 'mcp__devflow__get_project_context', toolType: 'mcp',
+      isMcpTool: true, mcpToolName: 'get_project_context', mcpEnforced: true,
+      mcpFallback: false, input: {}, duration: 20, blocked: false,
+    });
     db.insertToolCallEvent({
       eventId: 'evt_004', executionId: 'exec_002', timestamp: Date.now(),
       toolName: 'mcp__devflow__vue_diagnose_bug', toolType: 'mcp',
@@ -184,8 +196,11 @@ describe('DevFlowDatabase - Skill Executions', () => {
     });
 
     const compliance = db.getMcpCompliance();
-    expect(compliance.overall).toBeCloseTo(75, 0); // 3 MCP / 4 total = 75%
-    expect(compliance.bySkill['devflow:react']).toBeCloseTo(66.7, 0);
+    expect(compliance.overall).toBe(100);
+    expect(compliance.bySkill['devflow:react']).toBe(100);
     expect(compliance.bySkill['devflow:vue']).toBeCloseTo(100, 0);
+    expect(compliance.applicableObligations).toBe(4);
+    expect(compliance.satisfiedObligations).toBe(4);
+    expect(compliance.mcpCallShare).toBeCloseTo(83.33, 1);
   });
 });

package/dist/database.d.ts

@@ -66,6 +66,14 @@ export interface HookReceiptRecord {
     bypassCount?: number;
     updatedAt: number;
 }
+export interface ContextReceiptRecord {
+    projectRoot: string;
+    sessionId: string;
+    executionId: string;
+    contextHash: string;
+    issuedAt: number;
+    expiresAt: number;
+}
 export interface MemoryDistillCheckpointRecord {
     id: string;
     projectRoot: string;
@@ -105,6 +113,12 @@ export declare class DevFlowDatabase {
         label?: string;
         startedAt: number;
     }): void;
+    ensureSession(params: {
+        id: string;
+        projectRoot: string;
+        label?: string;
+        startedAt?: number;
+    }): void;
     getSession(id: string): any | null;
     listSessions(limit: number, offset: number, projectRoot?: string): any[];
     closeSession(id: string, finishedAt?: number): void;
@@ -130,6 +144,7 @@ export declare class DevFlowDatabase {
         mcpToolCalls?: number;
         directToolCalls?: number;
         subagentCount?: number;
+        metadata?: Record<string, unknown>;
     }): void;
     listSkillExecutions(limit: number, skillName?: string): any[];
     insertToolCallEvent(params: {
@@ -155,6 +170,7 @@ export declare class DevFlowDatabase {
         workflowRunId?: string;
         failureCategory?: string;
         tokensUsed?: number;
+        toolUseId?: string;
     }): boolean;
     listToolCallEvents(executionId: string): any[];
     updateToolCallEvent(eventId: string, updates: {
@@ -162,10 +178,22 @@ export declare class DevFlowDatabase {
         error?: string;
         duration?: number;
     }): boolean;
+    markToolCallBlocked(eventId: string, reason: string): boolean;
+    reconcileSkillExecution(executionId: string, status: 'completed' | 'failed', finishedAt?: number, metadata?: Record<string, unknown>): void;
+    getExecutionObligationCompliance(executionId: string): {
+        rate: number;
+        applicable: number;
+        satisfied: number;
+        missedTools: string[];
+        mcpCallShare: number;
+    };
     getMcpCompliance(): {
         overall: number;
         bySkill: Record<string, number>;
         missedTools: string[];
+        applicableObligations: number;
+        satisfiedObligations: number;
+        mcpCallShare: number;
     };
     cleanupStaleRecords(): void;
     insertToolMetric(metric: {
@@ -238,6 +266,10 @@ export declare class DevFlowDatabase {
     getHookReceipt(projectRoot: string): HookReceiptRecord | null;
     updateHookReceipt(projectRoot: string, updater: (current: HookReceiptRecord | null) => Omit<HookReceiptRecord, 'projectRoot' | 'updatedAt'>): HookReceiptRecord;
     deleteHookReceipt(projectRoot: string): boolean;
+    upsertContextReceipt(receipt: ContextReceiptRecord): void;
+    getContextReceipt(projectRoot: string, sessionId: string, executionId: string): ContextReceiptRecord | null;
+    deleteContextReceipt(projectRoot: string, sessionId: string, executionId?: string): number;
+    purgeExpiredContextReceipts(now?: number): number;
     recordMemoryDistillCheckpoint(checkpoint: MemoryDistillCheckpointRecord): void;
     listMemoryDistillCheckpoints(projectRoot: string, limit?: number): MemoryDistillCheckpointRecord[];
     all(sql: string, ...params: unknown[]): unknown[];

package/dist/database.js

@@ -7,6 +7,36 @@ const node_sqlite_1 = require("./node-sqlite");
 const path_1 = require("path");
 const fs_1 = require("fs");
 const os_1 = require("os");
+const CONTEXT_REQUIRED_SKILLS = new Set([
+    'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
+]);
+function toolNameMatches(event, expected) {
+    if (event.blocked || event.error)
+        return false;
+    const name = String(event.mcpToolName ?? event.toolName ?? '')
+        .replace(/^mcp__[^_]+__/, '');
+    return name === expected;
+}
+function obligationsForSkill(skillName, configured) {
+    const configuredTools = Array.isArray(configured)
+        ? configured.filter((tool) => typeof tool === 'string' && tool.length > 0)
+        : [];
+    const family = skillName.split(':').pop() ?? skillName;
+    if (CONTEXT_REQUIRED_SKILLS.has(family)) {
+        return [`${family}:context`, `${family}:domain`];
+    }
+    if (family === 'context')
+        return ['get_project_context'];
+    if (family === 'graph')
+        return ['get_dependency_graph'];
+    if (family === 'knowledge')
+        return ['get_knowledge'];
+    if (family === 'memory')
+        return ['get_memory'];
+    if (family === 'workflow')
+        return ['run_workflow'];
+    return configuredTools.slice(0, 1);
+}
 function getGlobalDevFlowDbPath(home = (0, os_1.homedir)()) {
     const stateDir = process.env.DEVFLOW_STATE_DIR ?? (0, path_1.join)(home, '.devflow', 'global');
     return (0, path_1.join)(stateDir, 'devflow.db');
@@ -137,7 +167,8 @@ class DevFlowDatabase {
         error TEXT,
         blocked INTEGER DEFAULT 0 CHECK (blocked IN (0, 1)),
         block_reason TEXT,
-        failure_category TEXT
+        failure_category TEXT,
+        tool_use_id TEXT
       );
 
       CREATE INDEX IF NOT EXISTS idx_executions_skill ON skill_executions(skill_name);
@@ -160,7 +191,8 @@ class DevFlowDatabase {
         mcp_tool_calls INTEGER DEFAULT 0,
         direct_tool_calls INTEGER DEFAULT 0,
         subagent_count INTEGER DEFAULT 0,
-        status TEXT NOT NULL DEFAULT 'running' CHECK (status IN ('running', 'completed', 'failed'))
+        status TEXT NOT NULL DEFAULT 'running' CHECK (status IN ('running', 'completed', 'failed')),
+        metadata TEXT
       );
 
       CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_root);
@@ -227,6 +259,19 @@ class DevFlowDatabase {
         updated_at INTEGER NOT NULL
       );
 
+      CREATE TABLE IF NOT EXISTS devflow_context_receipts (
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        execution_id TEXT NOT NULL,
+        context_hash TEXT NOT NULL,
+        issued_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL,
+        PRIMARY KEY (project_root, session_id, execution_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_context_receipts_expiry
+        ON devflow_context_receipts(expires_at);
+
       CREATE TABLE IF NOT EXISTS devflow_memory_distill_checkpoints (
         id TEXT PRIMARY KEY,
         project_root TEXT NOT NULL,
@@ -269,6 +314,23 @@ class DevFlowDatabase {
             this.db.exec('ALTER TABLE tool_call_events ADD COLUMN failure_category TEXT');
         }
         catch { }
+        try {
+            this.db.exec('ALTER TABLE tool_call_events ADD COLUMN tool_use_id TEXT');
+        }
+        catch { }
+        try {
+            this.db.exec('ALTER TABLE sessions ADD COLUMN metadata TEXT');
+        }
+        catch { }
+        try {
+            this.db.exec('ALTER TABLE skill_executions ADD COLUMN metadata TEXT');
+        }
+        catch { }
+        try {
+            this.db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_events_session_tool_use
+        ON tool_call_events(session_id, tool_use_id) WHERE tool_use_id IS NOT NULL`);
+        }
+        catch { }
         try {
             this.db.exec('ALTER TABLE devflow_rules ADD COLUMN gate INTEGER NOT NULL DEFAULT 1');
         }
@@ -507,6 +569,22 @@ class DevFlowDatabase {
       VALUES (?, ?, ?, ?, 'running')
     `).run(params.id, params.projectRoot, params.label ?? null, params.startedAt);
     }
+    ensureSession(params) {
+        if (!params.id.trim())
+            throw new Error('Canonical session ID is required');
+        const startedAt = params.startedAt ?? Date.now();
+        this.db.prepare(`
+      INSERT INTO sessions (id, project_root, label, started_at, status)
+      VALUES (?, ?, ?, ?, 'running')
+      ON CONFLICT(id) DO UPDATE SET
+        project_root = CASE
+          WHEN sessions.project_root = '' OR sessions.project_root = 'unknown' THEN excluded.project_root
+          ELSE sessions.project_root
+        END,
+        label = COALESCE(sessions.label, excluded.label),
+        started_at = MIN(sessions.started_at, excluded.started_at)
+    `).run(params.id, params.projectRoot || 'unknown', params.label ?? null, startedAt);
+    }
     getSession(id) {
         const row = this.db.prepare('SELECT * FROM sessions WHERE id = ?').get(id);
         if (!row)
@@ -523,6 +601,7 @@ class DevFlowDatabase {
             directToolCalls: row.direct_tool_calls,
             subagentCount: row.subagent_count,
             status: row.status,
+            metadata: row.metadata ? JSON.parse(row.metadata) : null,
         };
     }
     listSessions(limit, offset, projectRoot) {
@@ -547,6 +626,7 @@ class DevFlowDatabase {
             directToolCalls: row.direct_tool_calls,
             subagentCount: row.subagent_count,
             status: row.status,
+            metadata: row.metadata ? JSON.parse(row.metadata) : null,
         }));
     }
     closeSession(id, finishedAt) {
@@ -601,6 +681,7 @@ class DevFlowDatabase {
             blocked: row.blocked === 1,
             blockReason: row.block_reason,
             failureCategory: row.failure_category,
+            toolUseId: row.tool_use_id,
             tokensUsed: row.tokens_used ?? 0,
         }));
     }
@@ -635,6 +716,7 @@ class DevFlowDatabase {
                 blocked: row.blocked === 1,
                 blockReason: row.block_reason,
                 failureCategory: row.failure_category,
+                toolUseId: row.tool_use_id,
                 tokensUsed: row.tokens_used ?? 0,
             });
         }
@@ -669,6 +751,7 @@ class DevFlowDatabase {
             mcpComplianceRate: row.mcp_compliance_rate,
             missedMcpTools: row.missed_mcp_tools ? JSON.parse(row.missed_mcp_tools) : null,
             createdAt: row.created_at,
+            metadata: row.metadata ? JSON.parse(row.metadata) : null,
         };
     }
     updateSkillExecution(executionId, updates) {
@@ -710,6 +793,10 @@ class DevFlowDatabase {
             sets.push('subagent_count = ?');
             values.push(updates.subagentCount);
         }
+        if (updates.metadata !== undefined) {
+            sets.push('metadata = ?');
+            values.push(JSON.stringify(updates.metadata));
+        }
         if (sets.length > 0) {
             values.push(executionId);
             this.db.prepare(`UPDATE skill_executions SET ${sets.join(', ')} WHERE execution_id = ?`).run(...values);
@@ -738,6 +825,7 @@ class DevFlowDatabase {
             subagentCount: row.subagent_count,
             totalDuration: row.total_duration,
             mcpComplianceRate: row.mcp_compliance_rate,
+            metadata: row.metadata ? JSON.parse(row.metadata) : null,
         }));
     }
     // ---- Tool Call Events ----
@@ -748,9 +836,9 @@ class DevFlowDatabase {
         (event_id, execution_id, session_id, timestamp, tool_name, tool_type, is_mcp_tool,
          mcp_tool_name, mcp_enforced, mcp_fallback, kind, input, output, tokens_used, duration,
          parent_tool_call_id, subagent_id, error, blocked, block_reason, workflow_run_id,
-         failure_category)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(params.eventId, params.executionId || '', params.sessionId ?? null, params.timestamp, params.toolName, params.toolType, params.isMcpTool ? 1 : 0, params.mcpToolName || null, params.mcpEnforced ? 1 : 0, params.mcpFallback ? 1 : 0, params.kind ?? 'tool_use', JSON.stringify(params.input) ?? null, params.output !== undefined ? JSON.stringify(params.output) : null, params.tokensUsed ?? 0, params.duration, params.parentToolCallId || null, params.subagentId || null, params.error || null, params.blocked ? 1 : 0, params.blockReason || null, params.workflowRunId || null, params.failureCategory || null);
+         failure_category, tool_use_id)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(params.eventId, params.executionId || '', params.sessionId ?? null, params.timestamp, params.toolName, params.toolType, params.isMcpTool ? 1 : 0, params.mcpToolName || null, params.mcpEnforced ? 1 : 0, params.mcpFallback ? 1 : 0, params.kind ?? 'tool_use', JSON.stringify(params.input) ?? null, params.output !== undefined ? JSON.stringify(params.output) : null, params.tokensUsed ?? 0, params.duration, params.parentToolCallId || null, params.subagentId || null, params.error || null, params.blocked ? 1 : 0, params.blockReason || null, params.workflowRunId || null, params.failureCategory || null, params.toolUseId || null);
             if (result.changes === 0)
                 return false;
             this.db.prepare(`
@@ -758,9 +846,24 @@ class DevFlowDatabase {
         SET total_tool_calls = total_tool_calls + 1,
             mcp_tool_calls = mcp_tool_calls + ?,
             direct_tool_calls = direct_tool_calls + ?,
-            subagent_count = subagent_count + ?
+            subagent_count = subagent_count + ?,
+            total_duration = MAX(total_duration, ? - started_at),
+            mcp_compliance_rate = ROUND(
+              100.0 * (mcp_tool_calls + ?) / NULLIF(total_tool_calls + 1, 0), 2
+            )
         WHERE execution_id = ?
-      `).run(params.isMcpTool ? 1 : 0, params.isMcpTool ? 0 : 1, params.toolType === 'subagent' ? 1 : 0, params.executionId);
+      `).run(params.isMcpTool ? 1 : 0, params.isMcpTool ? 0 : 1, params.toolType === 'subagent' ? 1 : 0, params.timestamp, params.isMcpTool ? 1 : 0, params.executionId);
+            if (params.sessionId) {
+                this.db.prepare(`
+          UPDATE sessions
+          SET total_tool_calls = total_tool_calls + 1,
+              mcp_tool_calls = mcp_tool_calls + ?,
+              direct_tool_calls = direct_tool_calls + ?,
+              subagent_count = subagent_count + ?,
+              duration_ms = MAX(duration_ms, ? - started_at)
+          WHERE id = ?
+        `).run(params.isMcpTool ? 1 : 0, params.isMcpTool ? 0 : 1, params.toolType === 'subagent' ? 1 : 0, params.timestamp, params.sessionId);
+            }
             return true;
         });
     }
@@ -787,6 +890,7 @@ class DevFlowDatabase {
             blocked: row.blocked === 1,
             blockReason: row.block_reason,
             failureCategory: row.failure_category,
+            toolUseId: row.tool_use_id,
         }));
     }
     updateToolCallEvent(eventId, updates) {
@@ -811,49 +915,121 @@ class DevFlowDatabase {
         }
         return false;
     }
+    markToolCallBlocked(eventId, reason) {
+        return this.db.prepare(`
+      UPDATE tool_call_events
+      SET blocked = 1, block_reason = ?, error = COALESCE(error, ?)
+      WHERE event_id = ?
+    `).run(reason, reason, eventId).changes > 0;
+    }
+    reconcileSkillExecution(executionId, status, finishedAt = Date.now(), metadata) {
+        const row = this.db.prepare(`
+      SELECT COUNT(*) AS total,
+        SUM(CASE WHEN is_mcp_tool = 1 THEN 1 ELSE 0 END) AS mcp,
+        SUM(CASE WHEN is_mcp_tool = 0 THEN 1 ELSE 0 END) AS direct,
+        SUM(CASE WHEN tool_type = 'subagent' THEN 1 ELSE 0 END) AS subagents,
+        MIN(timestamp) AS first_at,
+        MAX(timestamp) AS last_at
+      FROM tool_call_events WHERE execution_id = ?
+    `).get(executionId);
+        const total = Number(row?.total ?? 0);
+        const mcp = Number(row?.mcp ?? 0);
+        const obligation = this.getExecutionObligationCompliance(executionId);
+        this.updateSkillExecution(executionId, {
+            status,
+            finishedAt,
+            totalToolCalls: total,
+            mcpToolCalls: mcp,
+            directToolCalls: Number(row?.direct ?? 0),
+            subagentCount: Number(row?.subagents ?? 0),
+            totalDuration: row?.first_at != null && row?.last_at != null ? row.last_at - row.first_at : 0,
+            mcpComplianceRate: obligation.rate,
+            metadata,
+        });
+    }
+    getExecutionObligationCompliance(executionId) {
+        const execution = this.getSkillExecution(executionId);
+        const events = this.listToolCallEvents(executionId);
+        if (!execution) {
+            return { rate: 0, applicable: 0, satisfied: 0, missedTools: [], mcpCallShare: 0 };
+        }
+        const obligations = obligationsForSkill(execution.skillName, execution.requiredMcpTools);
+        const satisfied = obligations.filter((obligation) => {
+            if (obligation.endsWith(':context')) {
+                return events.some((event) => toolNameMatches(event, 'get_project_context'));
+            }
+            if (obligation.endsWith(':domain')) {
+                const family = obligation.slice(0, -':domain'.length);
+                return events.some((event) => {
+                    if (event.blocked || event.error || !event.isMcpTool)
+                        return false;
+                    const name = String(event.mcpToolName ?? event.toolName ?? '')
+                        .replace(/^mcp__[^_]+__/, '');
+                    return name.startsWith(`${family}_`);
+                });
+            }
+            return events.some((event) => toolNameMatches(event, obligation));
+        });
+        const missedTools = obligations.filter((obligation) => !satisfied.includes(obligation));
+        const total = events.length;
+        const mcp = events.filter((event) => event.isMcpTool).length;
+        return {
+            rate: obligations.length > 0
+                ? Math.round((satisfied.length / obligations.length) * 10000) / 100
+                : 0,
+            applicable: obligations.length,
+            satisfied: satisfied.length,
+            missedTools,
+            mcpCallShare: total > 0 ? Math.round((mcp / total) * 10000) / 100 : 0,
+        };
+    }
     // ---- MCP Compliance ----
     getMcpCompliance() {
-        // Overall compliance (include all executions, not just completed)
-        const overallRow = this.db.prepare(`
-      SELECT
-        SUM(mcp_tool_calls) as mcp_calls,
-        SUM(total_tool_calls) as total_calls
-      FROM skill_executions
-    `).get();
-        const overall = overallRow?.total_calls > 0
-            ? Math.round((overallRow.mcp_calls / overallRow.total_calls) * 10000) / 100
-            : 0;
-        // By skill
-        const bySkillRows = this.db.prepare(`
-      SELECT
-        skill_name,
-        SUM(mcp_tool_calls) as mcp_calls,
-        SUM(total_tool_calls) as total_calls
-      FROM skill_executions
-      GROUP BY skill_name
-    `).all();
+        const executions = this.db.prepare('SELECT execution_id, skill_name FROM skill_executions').all();
         const bySkill = {};
-        for (const row of bySkillRows) {
-            bySkill[row.skill_name] = row.total_calls > 0
-                ? Math.round((row.mcp_calls / row.total_calls) * 10000) / 100
+        const bySkillCounts = new Map();
+        let applicableObligations = 0;
+        let satisfiedObligations = 0;
+        let totalCalls = 0;
+        let mcpCalls = 0;
+        const missedTools = new Set();
+        for (const execution of executions) {
+            const result = this.getExecutionObligationCompliance(execution.execution_id);
+            const skill = String(execution.skill_name ?? 'unknown');
+            const skillCounts = bySkillCounts.get(skill) ?? { applicable: 0, satisfied: 0 };
+            skillCounts.applicable += result.applicable;
+            skillCounts.satisfied += result.satisfied;
+            bySkillCounts.set(skill, skillCounts);
+            applicableObligations += result.applicable;
+            satisfiedObligations += result.satisfied;
+            result.missedTools.forEach((tool) => missedTools.add(tool));
+            const events = this.listToolCallEvents(execution.execution_id);
+            totalCalls += events.length;
+            mcpCalls += events.filter((event) => event.isMcpTool).length;
+        }
+        for (const [skill, counts] of bySkillCounts) {
+            bySkill[skill] = counts.applicable > 0
+                ? Math.round((counts.satisfied / counts.applicable) * 10000) / 100
                 : 0;
         }
-        // Missed tools: tools that were required but fell back to direct
-        const missedRows = this.db.prepare(`
-      SELECT DISTINCT mcp_tool_name
-      FROM tool_call_events
-      WHERE mcp_fallback = 1 AND mcp_tool_name IS NOT NULL
-      ORDER BY timestamp DESC
-      LIMIT 10
-    `).all();
-        const missedTools = missedRows.map((row) => row.mcp_tool_name);
-        return { overall, bySkill, missedTools };
+        return {
+            overall: applicableObligations > 0
+                ? Math.round((satisfiedObligations / applicableObligations) * 10000) / 100
+                : 0,
+            bySkill,
+            missedTools: [...missedTools].slice(0, 10),
+            applicableObligations,
+            satisfiedObligations,
+            mcpCallShare: totalCalls > 0 ? Math.round((mcpCalls / totalCalls) * 10000) / 100 : 0,
+        };
     }
     cleanupStaleRecords() {
         const cutoff = Date.now() - 30 * 60 * 1000;
         try {
-            this.db.prepare(`UPDATE skill_executions SET status = 'failed', finished_at = ? WHERE status = 'running' AND started_at < ?`).run(Date.now(), cutoff);
-            this.db.prepare(`UPDATE sessions SET status = 'failed', finished_at = ? WHERE status = 'running' AND started_at < ?`).run(Date.now(), cutoff);
+            this.db.prepare(`UPDATE skill_executions SET status = 'failed', finished_at = ?, metadata = ?
+         WHERE status = 'running' AND started_at < ?`).run(Date.now(), JSON.stringify({ closureReason: 'abandoned' }), cutoff);
+            this.db.prepare(`UPDATE sessions SET status = 'failed', finished_at = ?, metadata = ?
+         WHERE status = 'running' AND started_at < ?`).run(Date.now(), JSON.stringify({ closureReason: 'abandoned' }), cutoff);
         }
         catch { /* best-effort */ }
     }
@@ -1240,6 +1416,45 @@ class DevFlowDatabase {
         return this.db.prepare('DELETE FROM devflow_hook_receipts WHERE project_root = ?')
             .run(projectRoot).changes > 0;
     }
+    upsertContextReceipt(receipt) {
+        this.db.prepare(`
+      INSERT INTO devflow_context_receipts
+        (project_root, session_id, execution_id, context_hash, issued_at, expires_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_root, session_id, execution_id) DO UPDATE SET
+        context_hash = excluded.context_hash,
+        issued_at = excluded.issued_at,
+        expires_at = excluded.expires_at
+    `).run(receipt.projectRoot, receipt.sessionId, receipt.executionId, receipt.contextHash, receipt.issuedAt, receipt.expiresAt);
+    }
+    getContextReceipt(projectRoot, sessionId, executionId) {
+        const row = this.db.prepare(`
+      SELECT project_root, session_id, execution_id, context_hash, issued_at, expires_at
+      FROM devflow_context_receipts
+      WHERE project_root = ? AND session_id = ? AND execution_id = ?
+    `).get(projectRoot, sessionId, executionId);
+        return row ? {
+            projectRoot: row.project_root,
+            sessionId: row.session_id,
+            executionId: row.execution_id,
+            contextHash: row.context_hash,
+            issuedAt: row.issued_at,
+            expiresAt: row.expires_at,
+        } : null;
+    }
+    deleteContextReceipt(projectRoot, sessionId, executionId) {
+        return executionId
+            ? this.db.prepare(`DELETE FROM devflow_context_receipts
+          WHERE project_root = ? AND session_id = ? AND execution_id = ?`)
+                .run(projectRoot, sessionId, executionId).changes
+            : this.db.prepare(`DELETE FROM devflow_context_receipts
+          WHERE project_root = ? AND session_id = ?`)
+                .run(projectRoot, sessionId).changes;
+    }
+    purgeExpiredContextReceipts(now = Date.now()) {
+        return this.db.prepare('DELETE FROM devflow_context_receipts WHERE expires_at <= ?')
+            .run(now).changes;
+    }
     recordMemoryDistillCheckpoint(checkpoint) {
         this.db.prepare(`
       INSERT INTO devflow_memory_distill_checkpoints

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-tools/database",
-  "version": "0.16.0",
+  "version": "0.16.3",
   "description": "DevFlow SQLite database package",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,5 +13,5 @@
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"
   },
-  "gitHead": "2f52776bda72517354d44453756cccb9e8de9afa"
+  "gitHead": "5f49cf58702ee94ad9e4ab585e58f824e8633721"
 }