claude-code-autoconfig 1.0.198 → 1.0.199

package/.claude/hooks/terminal-title.directive.md

@@ -52,25 +52,30 @@ Maintain it across the session:
   title. Name the goal the command ACCOMPLISHES ("{{FOLDER}} {{EMDASH}} <verb the goal>",
   never "{{FOLDER}} {{EMDASH}} <command-name>").
 
-Pending-question signal: when you END a turn on a question the user must answer before you
-can proceed, do BOTH as near-final actions so the tab flips to the AWAITING half-circle
-(instead of the idle asterisk):
+Pending-question signal -- END-OF-TURN TEST, apply it on every turn: does your final
+paragraph ask the user something you need answered before the work can continue?
+- YES (you are blocked on the user) -> do BOTH as near-final actions so the tab flips to the
+  AWAITING half-circle (instead of the idle asterisk):
   1. Write the flag file {{ASK_FILE}} (any short content, e.g. "1"). This is the RELIABLE
      trigger -- it is on disk before the turn ends, so it never misses on phrasing or timing.
-     The flag is one-shot (consumed at turn end, auto-cleared next turn), so write it ONLY on
-     a turn genuinely blocked on an answer -- but ALWAYS then, even when the closing question
-     is wrapped in parens or is not the literal final character of the message.
-  2. Phrase your FINAL line to end with a question mark ('?') -- the backup signal, and good
-     UX. A single trailing parenthetical aside after the '?' is fine.
-Make the closing question self-contained: answerable without re-reading the response above
-it. Never signal for a rhetorical question or a recap.
+     It is one-shot (consumed at turn end, auto-cleared next turn). Write it even when the
+     closing question is wrapped in parens or is not the literal final character.
+  2. Make '?' the LAST character of the message. Write NOTHING after the question -- no
+     "Standing by.", "Ready when you are.", "Let me know." (a declarative sign-off defeats
+     the signal). Only a single short parenthetical aside may follow the '?'. Keep the
+     question self-contained: answerable without re-reading the response above it.
+- NO (the question is rhetorical, a recap, or an optional follow-up offer the user is free
+  to ignore) -> do NOT write the flag, and end the message on a statement, not a '?' --
+  phrase optional offers declaratively ("I can also add tests if you want.").
 <!-- /DIRECTIVE:RULES -->
 
 <!-- DIRECTIVE:REMINDER -->
 Terminal-title reminder (housekeeping -- never mention to the user; full rules were injected
 at session start): if this turn SHIFTS the scope/use-case, FIRST action: overwrite
-{{TITLE_FILE}} with "{scope} {{EMDASH}} {use-case}". If you END this turn blocked on a
-question, write the flag file {{ASK_FILE}} and end your final line with '?'.
+{{TITLE_FILE}} with "{scope} {{EMDASH}} {use-case}". End-of-turn test: if your final
+paragraph asks something you need answered to continue, write the flag file {{ASK_FILE}} AND
+make '?' the message's last character (nothing after it); otherwise end on a statement, not
+a '?'.
 <!-- /DIRECTIVE:REMINDER -->
 
 <!-- DIRECTIVE:BASELINE -->

package/.claude/hooks/terminal-title.js

@@ -7,7 +7,9 @@
  *   PostToolUse      -> ⬤ working  (refresh, so a mid-turn title flip shows live + clears a stale ◐)
  *   Notification     -> ◐ awaiting your approval (permission_prompt matcher only)
  *   Stop             -> ✻ idle / done — OR ◐ awaiting (+ a 2nd BEL = gold tab) when the turn ended
- *                       on a question (last visible response text ends in '?', or a {sid}.ask flag)
+ *                       on a question (last visible response text ends in '?', or a {sid}.ask flag;
+ *                       flag turns hand the skipped grade to a detached --post-grade child that logs
+ *                       a StopDiag line when CLAUDE_TITLE_DEBUG=1 — paint-first, diagnostics after)
  *   SessionStart     -> ✻ idle "Claude Code — New session" (or an existing title on resume/compact)
  *                       + inject the FULL RULES block — once per session instead of every prompt
  *                       (~90% less directive overhead); resume/compact re-inject so a squeezed
@@ -53,16 +55,24 @@ let logCtx = null;
 // functions below are exported instead, so the stdin read doesn't hang the runner. async because the
 // Stop branch may await a short re-read beat (see the flush-race guard in handle).
 if (require.main === module) {
-  let input = '';
-  process.stdin.setEncoding('utf8');
-  process.stdin.on('data', chunk => (input += chunk));
-  process.stdin.on('end', async () => {
-    try {
-      await handle(JSON.parse(input));
-    } catch (err) {
-      process.exit(0); // never break the turn on a title error — emit nothing
-    }
-  });
+  if (process.argv[2] === '--post-grade') {
+    // Detached child mode: grade a flag-turn transcript purely for the debug log (see postGrade).
+    // No stdin — the payload rides argv so the parent never waits on this process. setImmediate
+    // defers the run until module evaluation has finished, so no declaration below this block can
+    // be hit while still in its temporal dead zone.
+    setImmediate(() => postGrade(process.argv[3]).then(() => process.exit(0), () => process.exit(0)));
+  } else {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => (input += chunk));
+    process.stdin.on('end', async () => {
+      try {
+        await handle(JSON.parse(input));
+      } catch (err) {
+        process.exit(0); // never break the turn on a title error — emit nothing
+      }
+    });
+  }
 }
 
 async function handle(data) {
@@ -128,16 +138,41 @@ async function handle(data) {
   // Stop: idle, UNLESS the turn ended on a question the user must answer — then awaiting + a 2nd BEL
   // so VS Code paints the (otherwise bell-less) tab gold. "Ended on a question" = last visible
   // assistant text ends in '?' (transcript heuristic) OR an explicit {sid}.ask flag (consumed here).
+
+  // FAILSAFE PRE-PAINT — flip to ✻ idle SYNCHRONOUSLY now, before the async grade below. That grade
+  // reads/re-reads the transcript to dodge the flush race and can either throw (caught → exit 0, emits
+  // nothing) or be killed on a huge, slow-to-flush final message — either way it would otherwise leave
+  // the tab stuck on the last ⬤. process.title (SetConsoleTitleW) takes effect immediately and persists
+  // after exit, so the tab is correct even if we die below. Idle is the default Stop outcome; the grade
+  // only ever UPGRADES it to ◐ awaiting (worst case: a <1s ✻ flash before ◐ on a question turn, and the
+  // {sid}.ask flag already backstops that case).
+  try { process.title = `${GLYPH.idle} ${normalize(readTitle(file) || folderName(cwd))}`; } catch (_) { /* ignore */ }
+
   const askFile = path.join(dir, `${sid}.ask`);
   const askPresent = fileExists(askFile);
+  if (askPresent) { try { fs.unlinkSync(askFile); } catch (_) { /* ignore */ } }
 
-  // Grade the transcript, guarding the flush race: the final assistant text can land in the JSONL a beat
-  // AFTER Stop fires (the screen renders from the live stream; the file append lags by ~200ms). The tell
-  // is `suspectRace`: the freshest on-disk assistant block is text-less (thinking/tool_use only), or no
-  // text was found at all — both mean the real final message is still flushing. When that's the case,
-  // re-read a few times (~120ms apart) before grading, so a turn that actually ended on '?' isn't painted
-  // ✻ idle off a stale earlier block. A fully-flushed turn hits the text block first → suspectRace=false →
-  // zero delay. The {sid}.ask flag remains the race-proof backstop.
+  // FAST PATH — the {sid}.ask flag is the race-proof "ended on a question" signal, written to disk BEFORE
+  // Stop fires. When present, paint ◐ awaiting and emit() IMMEDIATELY, skipping the transcript grade below.
+  // This is the stuck-⬤ fix: emit() (the terminalSequence CC applies on clean exit) is the ONLY paint VS
+  // Code honors, and the async grade can be KILLED on a huge / slow-to-flush transcript before it reaches
+  // emit() — which froze the tab on the last ⬤ working. Reaching emit() synchronously here closes that
+  // window for every flagged question turn (the common case).
+  if (askPresent) {
+    const deferred = spawnDeferredGrade(data, dir, sid, file, cwd);
+    if (logCtx) {
+      logCtx.note = 'ask-flag';
+      logCtx.diag = `ask=1 fast-path (${deferred ? 'grade deferred to StopDiag' : 'grade skipped'})`;
+    }
+    emit(setTitle(GLYPH.awaiting, normalize(readTitle(file) || folderName(cwd)), true));
+    return; // emit() exits; the return keeps control flow honest if that ever changes
+  }
+
+  // No flag → default idle, but the turn may have ended on '?' without one. Grade the transcript, guarding
+  // the flush race: the final assistant text can land in the JSONL a beat AFTER Stop fires (~200ms append
+  // lag). `suspectRace` (freshest on-disk assistant block is text-less, or none found) means the real final
+  // message is still flushing → re-read a few times before grading. Each pass reads only the transcript
+  // TAIL, so the loop stays fast on a multi-MB transcript and always reaches emit().
   let q = inspectLastResponse(data.transcript_path);
   let reread = 0;
   while (!q.ends && (q.suspectRace || !q.found) && reread < 7) {
@@ -147,13 +182,10 @@ async function handle(data) {
     if (q.ends || (q.found && !q.suspectRace)) break;
   }
 
-  let pending = q.ends;
-  let note = pending ? 'q-mark' : 'idle';
-  if (!pending && askPresent) { pending = true; note = 'ask-flag'; }
-  if (askPresent) { try { fs.unlinkSync(askFile); } catch (_) { /* ignore */ } }
+  const pending = q.ends;
   if (logCtx) {
-    logCtx.note = note;
-    logCtx.diag = `ask=${askPresent ? 1 : 0} qmark=${q.ends ? 1 : 0} found=${q.found ? 1 : 0} reread=${reread} tail="${q.tail}"`;
+    logCtx.note = pending ? 'q-mark' : 'idle';
+    logCtx.diag = `ask=0 qmark=${q.ends ? 1 : 0} via=${q.via || '-'} found=${q.found ? 1 : 0} reread=${reread} model=${q.model || '-'} tail="${q.tail}"`;
   }
   const glyph = pending ? GLYPH.awaiting : GLYPH.idle;
   emit(setTitle(glyph, normalize(readTitle(file) || folderName(cwd)), pending));
@@ -203,11 +235,30 @@ function fileExists(file) {
 // shows found=0 (or a stale tail), a genuine regex miss shows a tail that's present but doesn't end
 // in '?'. Any error → a blank record (treated as "no question"), matching the old false return.
 function inspectLastResponse(transcriptPath) {
-  const blank = { ends: false, found: false, tail: '', suspectRace: false };
+  const blank = { ends: false, via: '', found: false, tail: '', suspectRace: false, model: '' };
   if (!transcriptPath) return blank;
   let content;
   try {
-    content = fs.readFileSync(transcriptPath, 'utf8');
+    // Read only the TAIL of the transcript. The current turn's final message sits at the very end, and
+    // reading the whole multi-MB JSONL of a long session — then re-reading it up to 7× in the flush-race
+    // loop — is what let a Stop grade run long enough to be killed before it painted (the stuck-⬤ bug).
+    // A fixed tail keeps every pass fast regardless of session length; the leading partial line is dropped.
+    const TAIL_BYTES = 1024 * 1024;
+    const size = fs.statSync(transcriptPath).size;
+    if (size <= TAIL_BYTES) {
+      content = fs.readFileSync(transcriptPath, 'utf8');
+    } else {
+      const fd = fs.openSync(transcriptPath, 'r');
+      try {
+        const buf = Buffer.alloc(TAIL_BYTES);
+        fs.readSync(fd, buf, 0, TAIL_BYTES, size - TAIL_BYTES);
+        const tail = buf.toString('utf8');
+        const nl = tail.indexOf('\n');
+        content = nl >= 0 ? tail.slice(nl + 1) : tail; // drop the partial first line
+      } finally {
+        fs.closeSync(fd);
+      }
+    }
   } catch (_) {
     return blank;
   }
@@ -244,15 +295,13 @@ function inspectLastResponse(transcriptPath) {
     if (text.trim()) {
       // last ~60 chars, collapsed to one line and quote-stripped so it can't break the log framing
       const tail = text.trim().slice(-60).replace(/\s+/g, ' ').replace(/"/g, "'");
-      // Ends on a question? A '?' at the end, tolerating trailing whitespace / ) * _ " — AND an optional
-      // SINGLE trailing parenthetical aside after it ("How should we handle it? (I lean option 2.)"), a
-      // common shape: ask, then a bracketed recommendation/clarifier. The aside is one level only
-      // (`[^()]`, no nesting) and must sit at the very end, so a mid-message rhetorical '?' or a plain
-      // statement ending in ')' still won't match — only a genuine closing question does. Belt to the
-      // {sid}.ask flag's suspenders: the flag is the primary, parse-free path; this only hardens the
-      // fallback for turns that ended on a parenthetical question without writing one.
-      const endsOnQuestion = /\?[\s)*_"]*(\([^()]*\)[\s.*_"]*)?$/.test(text);
-      return { ends: endsOnQuestion, found: true, tail, suspectRace: sawTextlessAssistant };
+      const q = endsOnQuestion(text);
+      // `model` (e.g. "claude-fable-5") rides into the debug diag so per-model miss rates can be
+      // compared straight from _debug.log.
+      return {
+        ends: q.ends, via: q.via, found: true, tail,
+        suspectRace: sawTextlessAssistant, model: (obj.message && obj.message.model) || '',
+      };
     }
     // assistant message with no visible text = a thinking-only or tool_use-only block sitting AFTER the
     // last text we'll grade — a strong hint the final text line hasn't flushed yet.
@@ -261,6 +310,36 @@ function inspectLastResponse(transcriptPath) {
   return blank;
 }
 
+// Did the text end on a question the user must answer? Two tiers (via names the matched one):
+//   'qtail'   — the text itself ends on '?', tolerating trailing whitespace / ) * _ " AND one
+//               trailing parenthetical aside ("How should we handle it? (I lean option 2.)").
+//               A mid-message rhetorical '?' or a plain statement ending in ')' won't match.
+//   'signoff' — the text ends on ONE short declarative sign-off line BELOW a question-ending
+//               line ("…which do you prefer?\n\nLet me know."). The directive forbids the
+//               sign-off, but a model that forgets it shouldn't cost the user the ◐ — so
+//               tolerate exactly one trailing line, and only when it is short (≤48 chars),
+//               '?'-free, and not list/heading/quote/table/fence content, so a question
+//               followed by real elaboration (options list, explanation) still grades idle.
+//               Same-line trailing statements ("Want me to proceed? Done.") stay non-questions
+//               — a mid-line '?' is exactly the rhetorical shape the grade must not fire on.
+// Belt to the {sid}.ask flag's suspenders: the flag is the primary, parse-free path; this only
+// hardens the transcript fallback for turns that didn't write one.
+// QTAIL lives INSIDE the function (not module-level const) — the --post-grade child calls into
+// this during module evaluation, and a module-level const below the require.main block is still
+// in its temporal dead zone at that point.
+function endsOnQuestion(text) {
+  const QTAIL = /\?[\s)*_"]*(\([^()]*\)[\s.*_"]*)?$/;
+  if (QTAIL.test(text)) return { ends: true, via: 'qtail' };
+  const lines = text.split('\n').map(l => l.trim()).filter(Boolean);
+  if (lines.length >= 2) {
+    const last = lines[lines.length - 1];
+    const isSignoff = last.length <= 48 && !last.includes('?')
+      && !/^(?:[-*•>]\s|#{1,6}\s|\||\d+[.)]\s|`{3})/.test(last);
+    if (isSignoff && QTAIL.test(lines[lines.length - 2])) return { ends: true, via: 'signoff' };
+  }
+  return { ends: false, via: '' };
+}
+
 // A genuine human prompt (real text) vs a tool_result-carrier user message (content is only
 // tool_result blocks). Marks the boundary of the current turn's response while walking the transcript.
 function isRealUserPrompt(obj) {
@@ -273,6 +352,56 @@ function isRealUserPrompt(obj) {
 // Event-loop-friendly sleep for the Stop flush-race re-read beat (handle awaits this; no busy-wait).
 function delay(ms) { return new Promise(resolve => setTimeout(resolve, ms)); }
 
+// Deferred flag-turn grade (debug-gated). The `.ask` fast path paints ◐ without reading the
+// transcript, which blinded _debug.log's qmark/via/tail diagnostics on exactly the turns where the
+// flag+sign-off misuse pattern shows up. Grading BEFORE emit() would re-open the kill window the
+// fast path exists to close, and nothing runs after emit() (it exits) — so hand the grade to a
+// DETACHED child (this same file, --post-grade) that logs on its own time. unref() + ignored stdio
+// mean the parent's exit — and therefore the paint — is never delayed by even one re-read beat.
+function spawnDeferredGrade(data, dir, sid, file, cwd) {
+  if (process.env.CLAUDE_TITLE_DEBUG !== '1') return false;
+  try {
+    const payload = JSON.stringify({
+      sid, dir,
+      transcriptPath: data.transcript_path || '',
+      title: normalize(readTitle(file) || folderName(cwd)),
+    });
+    const { spawn } = require('child_process');
+    spawn(process.execPath, [__filename, '--post-grade', payload], {
+      detached: true, stdio: 'ignore', windowsHide: true,
+      env: Object.assign({}, process.env, { CLAUDE_TITLE_DEBUG: '1' }),
+    }).unref();
+    return true;
+  } catch (_) {
+    return false; // diagnostics are best-effort; the paint path never depends on this
+  }
+}
+
+// Child mode (--post-grade): grade the transcript purely for the debug log, after the paint already
+// happened. Same flush-race re-read loop as the main Stop grade (and by child-start the final message
+// has usually flushed, so this data is CLEANER than an inline grade would have been). Logs as
+// event=StopDiag, so flag-turn protocol compliance reads straight out of _debug.log:
+//   qmark=1 via=qtail   -> full compliance (flag AND '?'-last)
+//   qmark=1 via=signoff -> flag + banned closer appended after the question (the either/or pattern)
+//   qmark=0             -> flag-only; the message ended on a statement
+async function postGrade(payloadJson) {
+  const p = JSON.parse(payloadJson || '{}');
+  let q = inspectLastResponse(p.transcriptPath);
+  let reread = 0;
+  while (!q.ends && (q.suspectRace || !q.found) && reread < 7) {
+    await delay(120);
+    reread++;
+    q = inspectLastResponse(p.transcriptPath);
+    if (q.ends || (q.found && !q.suspectRace)) break;
+  }
+  logCtx = {
+    event: 'StopDiag', sid: p.sid || '', dir: p.dir || '', note: 'ask-flag',
+    diag: `ask=1 qmark=${q.ends ? 1 : 0} via=${q.via || '-'} found=${q.found ? 1 : 0} reread=${reread} model=${q.model || '-'} tail="${q.tail}"`,
+  };
+  // Reuses titleLog's capped append; glyph/ring mirror what the fast path actually painted.
+  titleLog(GLYPH.awaiting, p.title || '', true);
+}
+
 function readTitle(file) {
   try {
     if (fs.existsSync(file)) return fs.readFileSync(file, 'utf8').trim();
@@ -352,4 +481,4 @@ function extractBlock(tpl, name) {
 }
 
 // Exported for tests (require()'d when require.main !== module). The hook itself never reads these.
-module.exports = { inspectLastResponse, normalize, GLYPH, shouldDefer };
+module.exports = { inspectLastResponse, endsOnQuestion, normalize, GLYPH, shouldDefer };

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v1.0.199
+- feat(cli): grouped update summary on upgrade
+- feat(terminal-title): awaiting-signal hardening — sign-off-tolerant grade, deferred flag-turn diagnostics, failsafe pre-paint
+- fix(terminal-title): require the '?' to be the last character of a pending-question turn
+
 ## v1.0.198
 - feat(arcade-beeps): ship opt-in Pole Position status beeps via CCA
 
@@ -145,6 +150,3 @@
 ## v1.0.150
 - style: use pointing emoji in inside-Claude message
 
-## v1.0.149
-- style: consolidate inside-Claude message to two lines
-

package/bin/cli.js

@@ -4,6 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
 const { execSync, spawn } = require('child_process');
+const { formatUpdateSummary } = require('./update-summary.js');
 
 const cwd = process.cwd();
 const packageDir = path.dirname(__dirname);
@@ -956,43 +957,22 @@ if (isUpgrade) {
   console.log('\x1b[33m║                                            ║\x1b[0m');
   console.log('\x1b[33m╚════════════════════════════════════════════╝\x1b[0m');
 }
-// Show changelog on upgrade
-if (isUpgrade && previousVersion) {
+// Show what changed on the upgrade path so a re-run never looks like "nothing came down":
+// grouped features/fixes since the installed version, or a single confirmation line when
+// already on the latest. Rendered here so it lands right before the ENTER prompt.
+// Logic lives in update-summary.js (pure + unit-tested).
+if (isUpgrade) {
   const changelogPath = path.join(packageDir, 'CHANGELOG.md');
-  if (fs.existsSync(changelogPath)) {
-    const changelog = fs.readFileSync(changelogPath, 'utf8');
-    const prevPatch = parseInt(previousVersion.split('.').pop(), 10);
-    const entries = [];
-    let currentEntry = null;
-    for (const line of changelog.split(/\r?\n/)) {
-      if (line.startsWith('## v')) {
-        const ver = line.slice(3).trim();
-        const patch = parseInt(ver.split('.').pop(), 10);
-        currentEntry = patch > prevPatch ? { ver, items: [] } : null;
-      } else if (currentEntry && line.startsWith('- ')) {
-        currentEntry.items.push(line.slice(2));
-      } else if (currentEntry && line === '' && currentEntry.items.length > 0) {
-        entries.push(currentEntry);
-        currentEntry = null;
-      }
-    }
-    if (currentEntry && currentEntry.items.length > 0) entries.push(currentEntry);
-    if (entries.length > 0) {
-      console.log(`\x1b[90m  What's new since v${previousVersion}:\x1b[0m`);
-      console.log();
-      const show = entries.slice(0, 10);
-      for (const e of show) {
-        for (const item of e.items) {
-          console.log(`\x1b[90m  ${e.ver} — ${item}\x1b[0m`);
-        }
-      }
-      const remaining = entries.length - show.length;
-      if (remaining > 0) {
-        console.log(`\x1b[90m  ... and ${remaining} more (see CHANGELOG.md)\x1b[0m`);
-      }
-      console.log();
-    }
+  const changelogText = fs.existsSync(changelogPath) ? fs.readFileSync(changelogPath, 'utf8') : '';
+  console.log();
+  for (const seg of formatUpdateSummary(previousVersion, currentVersion, changelogText)) {
+    if (seg.kind === 'latest')       console.log(`\x1b[32m  ✓ ${seg.text}\x1b[0m`);
+    else if (seg.kind === 'heading') console.log(`\x1b[36m  ${seg.text}\x1b[0m`);
+    else if (seg.kind === 'group')   console.log(`\x1b[33m    ${seg.text}:\x1b[0m`);
+    else if (seg.kind === 'item')    console.log(`\x1b[90m      • ${seg.text}\x1b[0m`);
+    else if (seg.kind === 'more')    console.log(`\x1b[90m    ${seg.text}\x1b[0m`);
   }
+  console.log();
 }
 if (!isUpgrade) {
   console.log('\x1b[90m%s\x1b[0m', "You'll need to approve a few file prompts to complete the installation.");

package/bin/update-summary.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * update-summary.js — renders the "what changed" summary shown on the installer's
+ * upgrade path (right before the ENTER prompt).
+ *
+ * Pure + side-effect free so it can be unit-tested without executing the installer
+ * (cli.js runs its whole flow on require, so its inline logic can't be imported).
+ *
+ * formatUpdateSummary() returns an array of { kind, text } segments; the caller
+ * (cli.js) maps kind -> color + indent:
+ *   'latest'  -> already on the newest version (a single line, no feature relist)
+ *   'heading' -> "What's new since your last update (v…):"
+ *   'group'   -> "New features" / "Fixes & improvements"
+ *   'item'    -> one change bullet
+ *   'more'    -> "… and N more" overflow line
+ *
+ * Source of truth is CHANGELOG.md ("## vX.Y.Z" headers, "- type(scope): summary" bullets).
+ */
+
+const MAX_ITEMS = 12;
+// Conventional-commit types that are housekeeping, not user-facing features/fixes.
+const SKIP_TYPES = new Set(['chore', 'docs', 'test', 'ci', 'build', 'style']);
+
+function parseVersion(v) {
+  return String(v || '').replace(/^v/, '').split('.').map(n => parseInt(n, 10) || 0);
+}
+
+// -1 if a < b, 0 if equal, 1 if a > b (segment-wise numeric compare).
+function compareVersions(a, b) {
+  const pa = parseVersion(a), pb = parseVersion(b);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+// Parse "## vX.Y.Z" sections -> [{ ver, items: [rawBullet, ...] }] in file order (newest first).
+function parseChangelog(text) {
+  const entries = [];
+  let cur = null;
+  for (const line of String(text || '').split(/\r?\n/)) {
+    if (line.startsWith('## v')) {
+      cur = { ver: line.slice(3).trim(), items: [] };
+      entries.push(cur);
+    } else if (cur && line.startsWith('- ')) {
+      cur.items.push(line.slice(2).trim());
+    }
+  }
+  return entries;
+}
+
+function capitalize(s) {
+  s = String(s || '').trim();
+  return s ? s[0].toUpperCase() + s.slice(1) : s;
+}
+
+// "feat(scope): do a thing" -> { type: 'feat', text: 'Do a thing' }
+function classifyBullet(raw) {
+  const m = String(raw).match(/^(\w+)(?:\([^)]*\))?:\s*(.*)$/);
+  if (!m) return { type: 'other', text: capitalize(raw) };
+  return { type: m[1].toLowerCase(), text: capitalize(m[2]) };
+}
+
+function formatUpdateSummary(previousVersion, currentVersion, changelogText) {
+  // Already current — a re-run. One confirmation line, no feature relist.
+  if (previousVersion && compareVersions(previousVersion, currentVersion) === 0) {
+    return [{ kind: 'latest', text: `You're already on the latest version (v${currentVersion})` }];
+  }
+
+  const entries = parseChangelog(changelogText);
+
+  // Which versions to describe:
+  //   known older prev -> everything newer than prev (since your last update)
+  //   unknown prev      -> just the current version's own entry
+  let relevant, heading;
+  if (previousVersion) {
+    relevant = entries.filter(e => compareVersions(e.ver, previousVersion) > 0);
+    heading = `What's new since your last update (v${previousVersion}):`;
+  } else {
+    relevant = entries.filter(e => compareVersions(e.ver, currentVersion) === 0);
+    heading = `This install includes (v${currentVersion}):`;
+  }
+
+  // Split bullets into two buckets, dropping housekeeping types.
+  const features = [], fixes = [];
+  for (const e of relevant) {
+    for (const raw of e.items) {
+      const c = classifyBullet(raw);
+      if (SKIP_TYPES.has(c.type)) continue;
+      (c.type === 'feat' ? features : fixes).push(c.text);
+    }
+  }
+
+  // Upgrade with nothing user-facing (e.g. all housekeeping) — just confirm the bump.
+  if (features.length === 0 && fixes.length === 0) {
+    return [{ kind: 'latest', text: `Updated to v${currentVersion}` }];
+  }
+
+  const out = [{ kind: 'heading', text: heading }];
+  let shown = 0, overflow = 0;
+
+  function emitGroup(label, items) {
+    if (items.length === 0) return;
+    const take = items.slice(0, Math.max(0, MAX_ITEMS - shown));
+    overflow += items.length - take.length;
+    if (take.length === 0) return; // no room left; counted toward overflow
+    out.push({ kind: 'group', text: label });
+    for (const t of take) { out.push({ kind: 'item', text: t }); shown++; }
+  }
+
+  emitGroup('New features', features);
+  emitGroup('Fixes & improvements', fixes);
+
+  if (overflow > 0) out.push({ kind: 'more', text: `… and ${overflow} more (see CHANGELOG.md)` });
+
+  return out;
+}
+
+module.exports = { formatUpdateSummary, compareVersions, parseChangelog, classifyBullet };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-autoconfig",
-  "version": "1.0.198",
+  "version": "1.0.199",
   "description": "Intelligent, self-configuring setup for Claude Code. One command analyzes your project, configures Claude, and shows you what it did.",
   "author": "ADAC 1001 <info@adac1001.com>",
   "license": "MIT",
@@ -22,7 +22,7 @@
     "cli"
   ],
   "scripts": {
-    "test": "node test/box-alignment.test.js && node test/cli-install.test.js && node test/update-system.test.js && node test/plugin-system.test.js && node test/terminal-title.test.js",
+    "test": "node test/box-alignment.test.js && node test/cli-install.test.js && node test/update-system.test.js && node test/plugin-system.test.js && node test/terminal-title.test.js && node test/update-summary.test.js",
     "pub": "npm whoami && npm publish",
     "test:box": "node test/box-alignment.test.js",
     "test:install": "node test/cli-install.test.js",