ai-gains 1.3.5 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-gains",
-  "version": "1.3.5",
+  "version": "1.5.0",
   "description": "Interactive browser dashboard for AI development session tracking",
   "main": "src/server.js",
   "bin": {

package/src/dashboard.html

@@ -182,6 +182,7 @@
     .chart-wrap {
       position: relative;
       height: 240px;
+      cursor: pointer;
     }
 
     /* ── Session cards ── */
@@ -407,6 +408,93 @@
     }
     .placeholder-icon { font-size: 44px; margin-bottom: 14px; }
 
+    /* ── Category breakdown ── */
+    .cat-layout {
+      display: flex;
+      align-items: center;
+      gap: 32px;
+    }
+
+    .cat-donut-wrap {
+      position: relative;
+      width: 180px;
+      height: 180px;
+      flex-shrink: 0;
+    }
+
+    .cat-legend {
+      flex: 1;
+      min-width: 0;
+    }
+
+    .cat-legend-row {
+      display: grid;
+      grid-template-columns: 10px 1fr auto auto;
+      align-items: center;
+      gap: 8px 12px;
+      padding: 6px 0;
+      border-bottom: 1px solid var(--border);
+      cursor: default;
+      transition: background 0.1s;
+      border-radius: 4px;
+    }
+
+    .cat-legend-row:last-child { border-bottom: none; }
+    .cat-legend-row:hover { background: var(--surface-2); }
+
+    .cat-dot {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      flex-shrink: 0;
+      justify-self: center;
+    }
+
+    .cat-legend-name {
+      font-size: 13px;
+      font-weight: 500;
+    }
+
+    .cat-legend-time {
+      font-size: 13px;
+      font-weight: 700;
+      text-align: right;
+      white-space: nowrap;
+    }
+
+    .cat-legend-meta {
+      font-size: 11px;
+      color: var(--muted);
+      text-align: right;
+      white-space: nowrap;
+    }
+
+    @media (max-width: 600px) {
+      .cat-layout { flex-direction: column; align-items: flex-start; }
+      .cat-donut-wrap { width: 150px; height: 150px; }
+    }
+
+    /* ── Category badge ── */
+    .cat-badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+      border-radius: 4px;
+      padding: 2px 7px;
+      font-size: 10px;
+      font-weight: 600;
+      letter-spacing: 0.05em;
+      text-transform: uppercase;
+      white-space: nowrap;
+    }
+
+    .cat-summary {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 6px;
+      margin-bottom: 18px;
+    }
+
     /* ── Scrollbar ── */
     ::-webkit-scrollbar { width: 7px; }
     ::-webkit-scrollbar-track { background: var(--bg); }
@@ -431,7 +519,6 @@
       </select>
       <div class="filter-divider"></div>
       <div class="period-pills" id="period-pills">
-        <button class="period-pill active" data-period="all"  onclick="setPeriod(this)">All time</button>
         <button class="period-pill" data-period="today" onclick="setPeriod(this)">Today</button>
         <button class="period-pill" data-period="3d"    onclick="setPeriod(this)">3 days</button>
         <button class="period-pill" data-period="week"  onclick="setPeriod(this)">Week</button>
@@ -439,8 +526,10 @@
         <button class="period-pill" data-period="3m"    onclick="setPeriod(this)">3 months</button>
         <button class="period-pill" data-period="6m"    onclick="setPeriod(this)">6 months</button>
         <button class="period-pill" data-period="year"  onclick="setPeriod(this)">Year</button>
+        <button class="period-pill" data-period="all"   onclick="setPeriod(this)">All time</button>
       </div>
     </div>
+    <div id="last-session-note" style="font-size:12px;color:var(--muted);margin-bottom:20px;min-height:16px"></div>
 
     <!-- Stats -->
     <div class="stats-grid">
@@ -458,18 +547,34 @@
       </div>
       <div class="stat-card">
         <div class="stat-label">Avg Speedup</div>
-        <div class="stat-value c-orange" id="stat-speedup">—</div>
+        <div class="stat-value c-orange" style="display:flex;align-items:baseline;gap:8px">
+          <span id="stat-speedup">—</span>
+          <span id="stat-speedup-trend" style="font-size:14px;font-weight:600;letter-spacing:0"></span>
+        </div>
       </div>
     </div>
 
     <!-- Chart -->
     <div class="section">
-      <div class="section-label">AI Time vs Estimated Human Time (minutes per session)</div>
+      <div class="section-label">Cumulative Time Saved</div>
       <div class="chart-wrap">
         <canvas id="main-chart"></canvas>
       </div>
     </div>
 
+    <!-- Category breakdown -->
+    <div id="cat-section" style="display:none">
+      <div class="section">
+        <div class="section-label">By Category</div>
+        <div class="cat-layout">
+          <div class="cat-donut-wrap">
+            <canvas id="cat-chart"></canvas>
+          </div>
+          <div class="cat-legend" id="cat-legend"></div>
+        </div>
+      </div>
+    </div>
+
     <!-- Sessions list -->
     <div class="sessions-label">Sessions</div>
     <div id="sessions-list">
@@ -496,9 +601,94 @@
   'use strict';
 
   let sessions = [];
-  let chart = null;
+  let chart    = null;
+  let catChart = null;
   let filterAuthor = '';
-  let filterPeriod = 'all';
+  let filterPeriod = 'all'; // overwritten by pickDefaultPeriod() after load
+
+  // ── Categories ───────────────────────────────────────────────────────────────
+
+  const CATEGORIES = [
+    {
+      id: 'bug-fix',
+      label: 'Bug Fix',
+      color: '#ef4444',
+      dim: 'rgba(239,68,68,0.15)',
+      keywords: ['fixed', 'fix ', 'bug', 'broken', 'regression', 'incorrect', 'wrong', 'invalid',
+                 'failure', 'failed', 'http 4', 'http 5', '410', '400', '500',
+                 'error', 'always showing', 'not working', 'deprecated', 'corrupt'],
+    },
+    {
+      id: 'debugging',
+      label: 'Debugging',
+      color: '#f59e0b',
+      dim: 'rgba(245,158,11,0.15)',
+      keywords: ['debug', 'diagnos', 'root cause', 'traced', 'reproduc', 'pinpoint',
+                 'found the issue', 'found issue', 'identified the bug'],
+    },
+    {
+      id: 'enhancement',
+      label: 'Enhancement',
+      color: '#3b82f6',
+      dim: 'rgba(59,130,246,0.15)',
+      keywords: ['added', 'implemented', 'built', 'created', 'feature', 'improved', 'enhanced',
+                 'redesigned', 'extended', 'upgraded', 'integrated', 'new '],
+    },
+    {
+      id: 'research',
+      label: 'Research',
+      color: '#a855f7',
+      dim: 'rgba(168,85,247,0.15)',
+      keywords: ['research', 'analyz', 'review', 'explor', 'compar', 'evaluat', 'audit',
+                 'investigat', 'survey', 'visual review', 'assess', 'benchmark'],
+    },
+    {
+      id: 'documentation',
+      label: 'Documentation',
+      color: '#14b8a6',
+      dim: 'rgba(20,184,166,0.15)',
+      keywords: ['doc', 'readme', 'comment', 'wrote', 'written', 'document', 'spec', 'guide', 'changelog'],
+    },
+    {
+      id: 'testing',
+      label: 'Testing',
+      color: '#06b6d4',
+      dim: 'rgba(6,182,212,0.15)',
+      keywords: ['test', 'spec', 'unit test', 'integration test', 'e2e', 'assert', 'coverage', 'validat'],
+    },
+    {
+      id: 'refactoring',
+      label: 'Refactoring',
+      color: '#8b5cf6',
+      dim: 'rgba(139,92,246,0.15)',
+      keywords: ['refactor', 'restructur', 'clean up', 'cleanup', 'simplif', 'consolidat', 'reorganiz', 'dedup'],
+    },
+    {
+      id: 'ui-ux',
+      label: 'UI/UX',
+      color: '#ec4899',
+      dim: 'rgba(236,72,153,0.15)',
+      keywords: ['ui', 'ux', 'design', 'layout', 'style', 'css', 'component', 'visual', 'interface', 'responsive'],
+    },
+  ];
+
+  const CAT_OTHER = { id: 'other', label: 'Other', color: '#94a3b8', dim: 'rgba(148,163,184,0.15)' };
+  const CAT_MAP   = Object.fromEntries([...CATEGORIES, CAT_OTHER].map(c => [c.id, c]));
+
+  function classifyByKeywords(description) {
+    const lower = description.toLowerCase();
+    let best = CAT_OTHER, bestScore = 0;
+    for (const cat of CATEGORIES) {
+      const score = cat.keywords.filter(k => lower.includes(k)).length;
+      if (score > bestScore) { bestScore = score; best = cat; }
+    }
+    return best;
+  }
+
+  function getCategory(achievement) {
+    if (achievement.category) return CAT_MAP[achievement.category] || CAT_OTHER;
+    return classifyByKeywords(achievement.description);
+  }
 
   // ── Filters ──────────────────────────────────────────────────────────────────
 
@@ -539,7 +729,9 @@
 
   function applyFilters() {
     filterAuthor = document.getElementById('filter-author').value;
+    renderLastSessionNote();
     renderStats();
+    renderCategories();
     renderChart();
     renderSessions();
   }
@@ -601,6 +793,33 @@
       .replace(/"/g, '&quot;');
   }
 
+  // ── Last session note ────────────────────────────────────────────────────────
+
+  function renderLastSessionNote() {
+    const el = document.getElementById('last-session-note');
+    if (!sessions.length) { el.textContent = ''; return; }
+
+    const latest = sessions.reduce((a, b) =>
+      new Date(a.start_time) > new Date(b.start_time) ? a : b);
+    const diff = Date.now() - new Date(latest.start_time);
+    const mins  = Math.floor(diff / 60000);
+    const hours = Math.floor(diff / 3600000);
+    const days  = Math.floor(diff / 86400000);
+
+    let ago;
+    if      (mins  <  1)  ago = 'just now';
+    else if (mins  < 60)  ago = `${mins} minute${mins !== 1 ? 's' : ''} ago`;
+    else if (hours < 24)  ago = `${hours} hour${hours !== 1 ? 's' : ''} ago`;
+    else if (days  === 1) ago = 'yesterday';
+    else                  ago = `${days} days ago`;
+
+    if (filterPeriod === 'today' && days === 0) {
+      el.textContent = '';
+    } else {
+      el.textContent = `Most recent session ${ago}`;
+    }
+  }
+
   // ── Render stats ────────────────────────────────────────────────────────────
 
   function renderStats() {
@@ -615,58 +834,205 @@
     document.getElementById('stat-achievements').textContent = ach;
     document.getElementById('stat-saved').textContent        = fmtDur(saved);
     document.getElementById('stat-speedup').textContent      = sp.toFixed(1) + '×';
+
+    // Trend: compare avg speedup of most recent 3 sessions vs prior 3
+    const trendEl = document.getElementById('stat-speedup-trend');
+    const sorted  = [...data].sort((a, b) => new Date(a.start_time) - new Date(b.start_time));
+    const avgSp   = arr => arr.reduce((s, x) => s + speedup(x), 0) / arr.length;
+    if (sorted.length >= 4) {
+      const recent = sorted.slice(-3);
+      const prior  = sorted.slice(-6, -3);
+      const diff   = avgSp(recent) - avgSp(prior);
+      if (diff > 0.1) {
+        trendEl.textContent = '↑';
+        trendEl.style.color = 'var(--green)';
+        trendEl.title = `Recent avg ${avgSp(recent).toFixed(1)}× vs prior ${avgSp(prior).toFixed(1)}×`;
+      } else if (diff < -0.1) {
+        trendEl.textContent = '↓';
+        trendEl.style.color = '#f87171';
+        trendEl.title = `Recent avg ${avgSp(recent).toFixed(1)}× vs prior ${avgSp(prior).toFixed(1)}×`;
+      } else {
+        trendEl.textContent = '→';
+        trendEl.style.color = 'var(--muted)';
+        trendEl.title = `Recent avg ${avgSp(recent).toFixed(1)}× vs prior ${avgSp(prior).toFixed(1)}×`;
+      }
+    } else {
+      trendEl.textContent = '';
+      trendEl.title = '';
+    }
+  }
+
+  // ── Render category breakdown ────────────────────────────────────────────────
+
+  function renderCategories() {
+    const data    = getFiltered();
+    const section = document.getElementById('cat-section');
+    if (catChart) { catChart.destroy(); catChart = null; }
+    if (!data.length) { section.style.display = 'none'; return; }
+
+    const tally = {};
+    let totalSaved = 0;
+    for (const s of data) {
+      for (const a of s.achievements) {
+        const cat  = getCategory(a);
+        const mins = a.estimated_human_time_minutes || 0;
+        if (!tally[cat.id]) tally[cat.id] = { cat, saved: 0, count: 0 };
+        tally[cat.id].saved += mins;
+        tally[cat.id].count += 1;
+        totalSaved += mins;
+      }
+    }
+
+    const sorted = Object.values(tally).sort((a, b) => b.saved - a.saved);
+    if (!sorted.length) { section.style.display = 'none'; return; }
+
+    section.style.display = '';
+
+    // Centre-text plugin — draws total time saved + label inside the donut hole
+    const centerTextPlugin = {
+      id: 'centerText',
+      afterDatasetsDraw(ch) {
+        const { ctx, chartArea: { top, bottom, left, right } } = ch;
+        const cx = (left + right) / 2, cy = (top + bottom) / 2;
+        ctx.save();
+        ctx.textAlign = 'center';
+        ctx.fillStyle = '#f1f5f9';
+        ctx.font = 'bold 16px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif';
+        ctx.fillText(fmtDur(totalSaved), cx, cy - 9);
+        ctx.fillStyle = '#64748b';
+        ctx.font = '10px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif';
+        ctx.fillText('TIME SAVED', cx, cy + 10);
+        ctx.restore();
+      }
+    };
+
+    catChart = new Chart(document.getElementById('cat-chart').getContext('2d'), {
+      type: 'doughnut',
+      plugins: [centerTextPlugin],
+      data: {
+        labels:   sorted.map(r => r.cat.label),
+        datasets: [{
+          data:            sorted.map(r => r.saved),
+          backgroundColor: sorted.map(r => r.cat.color),
+          borderColor:     '#1e293b',
+          borderWidth:     3,
+          hoverOffset:     6,
+        }]
+      },
+      options: {
+        responsive: true,
+        maintainAspectRatio: false,
+        cutout: '68%',
+        plugins: {
+          legend: { display: false },
+          tooltip: {
+            backgroundColor: '#1e293b',
+            borderColor: '#334155',
+            borderWidth: 1,
+            titleColor: '#f1f5f9',
+            bodyColor: '#94a3b8',
+            padding: 10,
+            callbacks: {
+              label(ctx) {
+                const { saved, count } = sorted[ctx.dataIndex];
+                const pct = totalSaved > 0 ? ((saved / totalSaved) * 100).toFixed(1) : 0;
+                return [
+                  `  ${fmtDur(saved)} saved (${pct}%)`,
+                  `  ${count} achievement${count !== 1 ? 's' : ''}`,
+                ];
+              }
+            }
+          }
+        }
+      }
+    });
+
+    // Legend table
+    document.getElementById('cat-legend').innerHTML = sorted.map(({ cat, saved, count }) => {
+      const pct = totalSaved > 0 ? Math.round((saved / totalSaved) * 100) : 0;
+      return `
+        <div class="cat-legend-row">
+          <span class="cat-dot" style="background:${cat.color}"></span>
+          <span class="cat-legend-name">${esc(cat.label)}</span>
+          <span class="cat-legend-time" style="color:${cat.color}">${esc(fmtDur(saved))}</span>
+          <span class="cat-legend-meta">${count} achievement${count !== 1 ? 's' : ''} · ${pct}%</span>
+        </div>`;
+    }).join('');
   }
 
   // ── Render chart ────────────────────────────────────────────────────────────
 
   function renderChart() {
-    const sorted     = [...getFiltered()].sort((a, b) => new Date(a.start_time) - new Date(b.start_time));
-    const labels     = sorted.map(s => fmtDateShort(s.start_time));
-    const aiTimes    = sorted.map(s => s.duration_minutes);
-    const humanTimes = sorted.map(s => humanTime(s));
+    const sorted = [...getFiltered()].sort((a, b) => new Date(a.start_time) - new Date(b.start_time));
 
     if (chart) chart.destroy();
 
-    chart = new Chart(document.getElementById('main-chart').getContext('2d'), {
-      type: 'bar',
+    if (!sorted.length) return;
+
+    // Build cumulative time-saved values, keeping session reference per point
+    let cumulative = 0;
+    const points = sorted.map(s => {
+      cumulative += (humanTime(s) - s.duration_minutes);
+      return { x: fmtDateShort(s.start_time), y: cumulative, session: s };
+    });
+
+    const canvas = document.getElementById('main-chart');
+
+    chart = new Chart(canvas.getContext('2d'), {
+      type: 'line',
       data: {
-        labels,
-        datasets: [
-          {
-            label: 'AI Time (min)',
-            data: aiTimes,
-            backgroundColor: 'rgba(59,130,246,0.75)',
-            borderColor: 'rgb(59,130,246)',
-            borderWidth: 1,
-            borderRadius: 5,
-            borderSkipped: false,
-          },
-          {
-            label: 'Human Estimate (min)',
-            data: humanTimes,
-            backgroundColor: 'rgba(34,197,94,0.45)',
-            borderColor: 'rgb(34,197,94)',
-            borderWidth: 1,
-            borderRadius: 5,
-            borderSkipped: false,
-          }
-        ]
+        labels: points.map(p => p.x),
+        datasets: [{
+          label: 'Time Saved (min)',
+          data: points.map(p => p.y),
+          borderColor: 'rgb(34,197,94)',
+          backgroundColor: 'rgba(34,197,94,0.08)',
+          borderWidth: 2.5,
+          pointBackgroundColor: 'rgb(34,197,94)',
+          pointBorderColor: '#0f172a',
+          pointBorderWidth: 2,
+          pointRadius: 5,
+          pointHoverRadius: 7,
+          fill: true,
+          tension: 0.35,
+        }]
       },
       options: {
         responsive: true,
         maintainAspectRatio: false,
+        onClick(_evt, elements) {
+          if (elements.length) {
+            const s = points[elements[0].index].session;
+            showSession(s.uuid || s.session_id);
+          }
+        },
         plugins: {
-          legend: {
-            labels: { color: '#94a3b8', font: { size: 12 }, boxWidth: 13, padding: 18 }
-          },
+          legend: { display: false },
           tooltip: {
             backgroundColor: '#1e293b',
             borderColor: '#334155',
             borderWidth: 1,
             titleColor: '#f1f5f9',
             bodyColor: '#94a3b8',
+            padding: 12,
             callbacks: {
-              label: ctx => ` ${ctx.dataset.label}: ${ctx.parsed.y} min`
+              title(items) {
+                const s = points[items[0].dataIndex].session;
+                return fmtDate(s.start_time);
+              },
+              label(ctx) {
+                const s = points[ctx.dataIndex].session;
+                const saved = humanTime(s) - s.duration_minutes;
+                const sp    = speedup(s);
+                return [
+                  ` Cumulative saved: ${fmtDur(ctx.parsed.y)}`,
+                  ` This session: +${fmtDur(saved)}`,
+                  ` AI time: ${fmtDur(s.duration_minutes)}  ·  Human est: ${fmtDur(humanTime(s))}`,
+                  ` Speedup: ${sp.toFixed(1)}×  ·  ${s.achievements.length} achievement${s.achievements.length !== 1 ? 's' : ''}`,
+                  ...(s.author ? [` Author: ${s.author}`] : []),
+                ];
+              },
+              afterBody() { return ['', ' Click to open session ↗']; }
             }
           }
         },
@@ -677,7 +1043,7 @@
           },
           y: {
             grid: { color: 'rgba(51,65,85,0.5)' },
-            ticks: { color: '#94a3b8', font: { size: 11 }, callback: v => v + ' min' },
+            ticks: { color: '#94a3b8', font: { size: 11 }, callback: v => fmtDur(v) },
             beginAtZero: true
           }
         }
@@ -731,14 +1097,34 @@
     const ht = humanTime(s);
     const sv = ht - s.duration_minutes;
 
+    // Build category summary for this session
+    const catTally = {};
+    for (const a of s.achievements) {
+      const cat = getCategory(a);
+      if (!catTally[cat.id]) catTally[cat.id] = { cat, saved: 0, count: 0 };
+      catTally[cat.id].saved += a.estimated_human_time_minutes || 0;
+      catTally[cat.id].count += 1;
+    }
+    const catSummaryHTML = Object.values(catTally)
+      .sort((a, b) => b.saved - a.saved)
+      .map(({ cat, saved, count }) =>
+        `<span class="cat-badge" style="background:${cat.dim};color:${cat.color}">
+           ● ${esc(cat.label)} · ${esc(fmtDur(saved))}
+         </span>`)
+      .join('');
+
     const achievementsHTML = s.achievements.map((a, i) => {
+      const cat      = getCategory(a);
       const created  = (a.files_created  || []).map(f => `<span class="file-chip created">+ ${esc(f)}</span>`).join('');
       const modified = (a.files_modified || []).map(f => `<span class="file-chip modified">~ ${esc(f)}</span>`).join('');
       const hasFiles = created || modified;
 
       return `
         <div class="achievement-card">
-          <div class="achievement-num">Achievement ${i + 1} of ${s.achievements.length}</div>
+          <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:10px">
+            <div class="achievement-num" style="margin-bottom:0">Achievement ${i + 1} of ${s.achievements.length}</div>
+            <span class="cat-badge" style="background:${cat.dim};color:${cat.color}">● ${esc(cat.label)}</span>
+          </div>
           <div class="achievement-desc">${esc(a.description)}</div>
           <div class="achievement-footer">
             ${hasFiles ? `<div class="files-row">${created}${modified}</div>` : ''}
@@ -789,6 +1175,9 @@
 
       <div class="speedup-banner">⚡ ${esc(s.ai_speedup)}</div>
 
+      <div class="section-label" style="margin-bottom:10px;">By Category</div>
+      <div class="cat-summary" style="margin-bottom:24px">${catSummaryHTML}</div>
+
       <div class="section-label" style="margin-bottom:14px;">Achievements</div>
       ${achievementsHTML}
     `;
@@ -806,13 +1195,44 @@
 
   // ── Init ────────────────────────────────────────────────────────────────────
 
+  function pickDefaultPeriod() {
+    const ORDER = ['today', '3d', 'week', 'month', '3m', '6m', 'year', 'all'];
+    const DAY   = 86400000;
+    const cutoffs = {
+      today: () => { const d = new Date(); d.setHours(0,0,0,0); return d; },
+      '3d':  () => new Date(Date.now() - 3   * DAY),
+      week:  () => new Date(Date.now() - 7   * DAY),
+      month: () => new Date(Date.now() - 30  * DAY),
+      '3m':  () => new Date(Date.now() - 90  * DAY),
+      '6m':  () => new Date(Date.now() - 180 * DAY),
+      year:  () => new Date(Date.now() - 365 * DAY),
+      all:   () => null,
+    };
+    for (const period of ORDER) {
+      const cutoff = cutoffs[period]();
+      const hasData = cutoff
+        ? sessions.some(s => new Date(s.start_time) >= cutoff)
+        : sessions.length > 0;
+      if (hasData) {
+        filterPeriod = period;
+        const btn = document.querySelector(`.period-pill[data-period="${period}"]`);
+        document.querySelectorAll('.period-pill').forEach(b => b.classList.remove('active'));
+        if (btn) btn.classList.add('active');
+        return;
+      }
+    }
+  }
+
   async function init() {
     try {
       const res = await fetch('/api/sessions');
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       sessions = await res.json();
       populateAuthors();
+      pickDefaultPeriod();
+      renderLastSessionNote();
       renderStats();
+      renderCategories();
       renderChart();
       renderSessions();
     } catch (err) {

package/src/init.js

@@ -5,10 +5,25 @@ const path = require('path');
 
 const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
 
+const STALE_HOOK_TYPES = ['SessionStart', 'Stop'];
+const AI_GAINS_LABEL = 'ai-gains';
+
 function mergeSettings(existing, template) {
   const result = JSON.parse(JSON.stringify(existing));
   if (!result.hooks) result.hooks = {};
 
+  // Remove stale ai-gains hooks that no longer exist in the template
+  for (const hookType of STALE_HOOK_TYPES) {
+    if (!result.hooks[hookType]) continue;
+    result.hooks[hookType] = result.hooks[hookType]
+      .map(entry => ({
+        ...entry,
+        hooks: (entry.hooks || []).filter(h => h.label !== AI_GAINS_LABEL)
+      }))
+      .filter(entry => (entry.hooks || []).length > 0);
+    if (result.hooks[hookType].length === 0) delete result.hooks[hookType];
+  }
+
   for (const [hookType, templateEntries] of Object.entries(template.hooks || {})) {
     if (!result.hooks[hookType]) {
       result.hooks[hookType] = templateEntries;
@@ -89,6 +104,16 @@ function initProject(targetDir) {
   fs.copyFileSync(skillSrc, skillDst);
   console.log(`  ${skillExisted ? 'updated' : 'created'} .claude/skills/ai-gains/SKILL.md`);
 
+  // Remove stale hook scripts that no longer exist in the template
+  const staleScripts = ['session-start.cjs', 'stop.cjs'];
+  for (const name of staleScripts) {
+    const stalePath = path.join(scriptsDst, name);
+    if (fs.existsSync(stalePath)) {
+      fs.rmSync(stalePath);
+      console.log(`  removed  .claude/scripts/ai-gains/${name}`);
+    }
+  }
+
   // Copy hook scripts (safe to overwrite)
   const scriptsExisted = fs.existsSync(scriptsDst);
   copyDir(scriptsSrc, scriptsDst);

package/template/.claude/scripts/ai-gains/get-session-times.cjs

@@ -0,0 +1,81 @@
+'use strict';
+const fs = require('fs');
+
+const transcriptPath = process.argv[2];
+if (!transcriptPath) {
+  console.error('Usage: get-session-times.cjs <transcript_path>');
+  process.exit(1);
+}
+
+const CHUNK_SIZE = 4096;
+const fd = fs.openSync(transcriptPath, 'r');
+const { size } = fs.fstatSync(fd);
+
+// Scan from the start for the first entry with a timestamp
+function findFirstTimestamp() {
+  const rl = require('readline').createInterface({
+    input: fs.createReadStream(transcriptPath),
+    crlfDelay: Infinity
+  });
+  return new Promise(resolve => {
+    rl.on('line', line => {
+      if (!line.trim()) return;
+      try {
+        const entry = JSON.parse(line);
+        if (entry.timestamp) {
+          rl.close();
+          resolve(entry.timestamp);
+        }
+      } catch {}
+    });
+    rl.on('close', () => resolve(null));
+  });
+}
+
+// Scan from the end for the last entry with a timestamp
+function findLastTimestamp() {
+  let offset = size;
+  let remainder = '';
+  let lastTimestamp = null;
+
+  while (offset > 0) {
+    const readSize = Math.min(CHUNK_SIZE, offset);
+    offset -= readSize;
+    const buf = Buffer.alloc(readSize);
+    fs.readSync(fd, buf, 0, readSize, offset);
+    const chunk = buf.toString('utf8') + remainder;
+    const lines = chunk.split('\n');
+    remainder = lines.shift(); // incomplete line at chunk boundary
+
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      try {
+        const entry = JSON.parse(line);
+        if (entry.timestamp) {
+          lastTimestamp = entry.timestamp;
+          break;
+        }
+      } catch {}
+    }
+    if (lastTimestamp) break;
+  }
+
+  fs.closeSync(fd);
+  return lastTimestamp;
+}
+
+(async () => {
+  const [start_time, end_time] = await Promise.all([
+    findFirstTimestamp(),
+    Promise.resolve(findLastTimestamp())
+  ]);
+
+  if (!start_time || !end_time) {
+    console.error('Could not extract timestamps from transcript');
+    process.exit(1);
+  }
+
+  const duration_minutes = Math.round((new Date(end_time) - new Date(start_time)) / 60000);
+  console.log(JSON.stringify({ start_time, end_time, duration_minutes }));
+})();

package/template/.claude/scripts/ai-gains/user-prompt-submit.cjs

@@ -4,8 +4,8 @@ let raw = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => { raw += chunk; });
 process.stdin.on('end', () => {
-  const { session_id } = JSON.parse(raw);
+  const { session_id, transcript_path } = JSON.parse(raw);
   process.stdout.write(
-    `Session ID: ${session_id}. IMPORTANT: In your final response, remind the user to update the ai-gains session log (the /ai-gains skill).`
+    `Session ID: ${session_id}. Transcript: ${transcript_path}. IMPORTANT: In your final response, remind the user to update the ai-gains session log (the /ai-gains skill).`
   );
 });

package/template/.claude/settings.json

@@ -1,16 +1,5 @@
 {
   "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "label": "ai-gains",
-            "command": "node .claude/scripts/ai-gains/session-start.cjs"
-          }
-        ]
-      }
-    ],
     "UserPromptSubmit": [
       {
         "hooks": [
@@ -21,17 +10,6 @@
           }
         ]
       }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "label": "ai-gains",
-            "command": "node .claude/scripts/ai-gains/stop.cjs"
-          }
-        ]
-      }
     ]
   }
 }

package/template/.claude/skills/ai-gains/SKILL.md

@@ -7,17 +7,11 @@ description: Manages the AI gains session log. Session initialization and user p
 
 ## Context
 
-Session tracking is managed automatically via hooks configured in `.claude/settings.json`:
+Session tracking is managed automatically via a hook configured in `.claude/settings.json`:
 
-- **SessionStart hook**: Reads Claude Code's `session_id` from stdin and creates `.ai-gains/<start_time>_<session_id>.json` with `start_time` and `author`. The timestamp uses `-` instead of `:` for cross-platform filename compatibility (e.g. `2026-03-02T09-00-00Z_<session_id>.json`).
-- **UserPromptSubmit hook**: Reads the `session_id` from stdin and echoes it into context with a lightweight reminder for Claude to prompt the user to update the log at the end of each response. The skill itself is not loaded automatically — only when the user invokes `/ai-gains`.
-- **Stop hook**: Reads the `session_id` from stdin, locates the matching `.ai-gains/*_<session_id>.json` file, and updates `end_time` after every Claude response.
+- **UserPromptSubmit hook**: Reads `session_id` and `transcript_path` from stdin and echoes both into context, along with a lightweight reminder for Claude to prompt the user to update the log at the end of each response. The skill itself is not loaded automatically — only when the user invokes `/ai-gains`.
 
-`duration_minutes` is the wall-clock time from `start_time` to `end_time`. This intentionally includes human review time, approval of actions, reading diffs, etc. — giving a true picture of total time spent with AI vs. without.
-
-Files are named `<start_time>_<session_id>.json` so they sort chronologically and concurrent sessions never conflict.
-
-Claude should note the Session ID echoed by each UserPromptSubmit hook and use it to locate the session file.
+`duration_minutes` is derived from the first and last timestamped entries in the session transcript. This reflects actual conversation activity from first message to last response, and intentionally includes human review time, approval of actions, reading diffs, etc. — giving a true picture of total time spent with AI vs. without.
 
 ## Proactive Log Reminders
 
@@ -31,41 +25,60 @@ Claude should use judgment about what counts as "meaningful" -- a single quick a
 
 When the user invokes `/ai-gains` or confirms they want to update the log:
 
-1. Get the current UTC time:
+1. Get `session_id` and `transcript_path` from the context echoed by the UserPromptSubmit hook.
+
+2. Run `get-session-times.cjs` with the transcript path to get accurate start/end times and duration:
+   ```bash
+   node .claude/scripts/ai-gains/get-session-times.cjs <transcript_path>
+   ```
+   This outputs `{ start_time, end_time, duration_minutes }` derived from the first and last timestamped entries in the transcript.
+
+3. Get the author from git config:
    ```bash
-   node -e "console.log(new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'))"
+   git config user.email
    ```
 
-2. Use the Session ID echoed by the UserPromptSubmit hook (present in context) to locate the session file:
+4. Check if a session file already exists for this session:
    ```
    .ai-gains/*_<session_id>.json
    ```
-
-3. Read the session file to get `start_time` and `end_time`.
-
-4. Calculate `duration_minutes` as the difference between `end_time` and `start_time` in minutes (wall-clock time). This includes all time spent in the session — AI working, human reviewing, approving actions, reading output, etc.
+   If it exists, read the existing `achievements` array to use as a starting point for merging.
 
 5. Reflect on all work done this session: research done, features built, bugs fixed, problems solved, code reviewed, debugging done, documentation updated, etc.
 
 6. For each achievement, estimate how long a human developer would take to do the same work without AI assistance.
 
-7. Write the updated JSON back to `.ai-gains/<start_utc_timestamp>_<uuid>.json`, preserving existing fields. The JSON structure should look like this:
+7. For each achievement, assign a `category` from this list — pick the one that best describes the primary nature of the work:
+   - `bug-fix` — fixing a broken or incorrect behaviour
+   - `debugging` — diagnosing, tracing or reproducing a problem (without necessarily fixing it yet)
+   - `enhancement` — adding or improving a feature, refactoring, or extending functionality
+   - `research` — investigating options, reviewing code/docs, evaluating approaches, visual review
+   - `documentation` — writing or updating docs, comments, specs, READMEs
+   - `testing` — writing or executing tests, validating functionality
+   - `refactoring` — restructuring existing code without changing its external behavior
+   - `ui-ux` — designing or improving user interfaces and user experiences
+   - `other` — anything that doesn't fit the above
+
+8. Merge new achievements with any existing ones from step 4. If a prior achievement is superseded or refined by new work in the same area, update it in place rather than duplicating it.
+
+9. Write the session file to `.ai-gains/<start_time_with_colons_replaced>_<session_id>.json`. The filename uses `-` instead of `:` in the timestamp for cross-platform compatibility. The JSON structure should look like this:
 
 ```json
 {
-  "uuid": "<session-uuid>",
+  "session_id": "<session-id>",
   "start_time": "<ISO start time>",
+  "end_time": "<ISO end time>",
   "author": "<git user email>",
-  "end_time": "<ISO current time>",
   "duration_minutes": "<number>",
   "achievements": [
     {
       "description": "<what was done>",
-      "estimated_human_time_minutes": "<number>"
+      "estimated_human_time_minutes": "<number>",
+      "category": "<bug-fix | debugging | enhancement | research | documentation | testing | refactoring | ui-ux | other>"
     }
   ],
   "ai_speedup": "<summary of time saved vs human>"
 }
 ```
 
-8. Confirm to the user that the log has been updated and summarize the key achievements.
+10. Confirm to the user that the log has been updated and summarize the key achievements.

package/template/.claude/scripts/ai-gains/session-start.cjs

@@ -1,24 +0,0 @@
-'use strict';
-const fs = require('fs');
-const { execSync } = require('child_process');
-
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => { raw += chunk; });
-process.stdin.on('end', () => {
-  const { session_id } = JSON.parse(raw);
-  const start_time = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
-
-  let author = 'unknown';
-  try {
-    author = execSync('git config user.email', { stdio: ['pipe', 'pipe', 'pipe'] })
-      .toString().trim();
-  } catch {}
-
-  const safeTs = start_time.replace(/:/g, '-');
-  fs.mkdirSync('.ai-gains', { recursive: true });
-  fs.writeFileSync(
-    `.ai-gains/${safeTs}_${session_id}.json`,
-    JSON.stringify({ session_id, start_time, author }, null, 2) + '\n'
-  );
-});

package/template/.claude/scripts/ai-gains/stop.cjs

@@ -1,16 +0,0 @@
-'use strict';
-const fs = require('fs');
-
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => { raw += chunk; });
-process.stdin.on('end', () => {
-  const { session_id } = JSON.parse(raw);
-  const match = fs.readdirSync('.ai-gains').find(f => f.endsWith(`_${session_id}.json`));
-  if (!match) return;
-  const file = `.ai-gains/${match}`;
-
-  const session = JSON.parse(fs.readFileSync(file, 'utf8'));
-  session.end_time = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
-  fs.writeFileSync(file, JSON.stringify(session, null, 2) + '\n');
-});