claude-code-autoconfig 1.0.197 → 1.0.199

package/.claude/commands/disable-arcade-beeps.md

@@ -0,0 +1,10 @@
+---
+description: Turn OFF Pole Position tab status beeps
+allowed-tools: Bash
+---
+
+Run exactly this command, then reply with a single confirmation line and nothing else:
+
+```
+rm -f ~/.claude/sounds/arcade-beeps.enabled && echo "arcade beeps DISABLED."
+```

package/.claude/commands/enable-arcade-beeps.md

@@ -0,0 +1,10 @@
+---
+description: Turn ON Pole Position tab status beeps (awaiting = low tone, complete = high tone)
+allowed-tools: Bash
+---
+
+Run exactly this command, then reply with a single confirmation line and nothing else:
+
+```
+mkdir -p ~/.claude/sounds && touch ~/.claude/sounds/arcade-beeps.enabled && echo "arcade beeps ENABLED (every turn-end beeps: awaiting=low, complete=high). Disable with /disable-arcade-beeps."
+```

package/.claude/docs/autoconfig.docs.html

@@ -878,6 +878,16 @@
                                 <span class="tree-file-icon">📄</span>
                                 <span class="file">commit-and-push.md</span>
                             </div>
+                            <div class="tree-item indent-3 hidden" data-info="disable-arcade-beeps" data-parent="commands">
+                                <span class="tree-spacer"></span>
+                                <span class="tree-file-icon">📄</span>
+                                <span class="file">disable-arcade-beeps.md</span>
+                            </div>
+                            <div class="tree-item indent-3 hidden" data-info="enable-arcade-beeps" data-parent="commands">
+                                <span class="tree-spacer"></span>
+                                <span class="tree-file-icon">📄</span>
+                                <span class="file">enable-arcade-beeps.md</span>
+                            </div>
                             <div class="tree-item indent-3 hidden" data-info="extract-rules" data-parent="commands">
                                 <span class="tree-spacer"></span>
                                 <span class="tree-file-icon">📄</span>
@@ -933,6 +943,11 @@
                                 <span class="tree-folder-icon">📁</span>
                                 <span class="folder">hooks</span>
                             </div>
+                            <div class="tree-item indent-3 hidden" data-info="arcade-beeps-hook" data-parent="hooks">
+                                <span class="tree-spacer"></span>
+                                <span class="tree-file-icon">📄</span>
+                                <span class="file">arcade-beeps.js</span>
+                            </div>
                             <div class="tree-item indent-3 hidden" data-info="feedback-rule-check-hook" data-parent="hooks">
                                 <span class="tree-spacer"></span>
                                 <span class="tree-file-icon">📄</span>
@@ -1263,7 +1278,7 @@
                 title: '.claude/ Directory',
                 desc: 'Commands, rules, settings, and these docs. Keeps configuration organized as your project grows.'
             },
-                                                                                                                                                                                                                                                                                                                                                                                                            'rules': {
+                                                                                                                                                                                                                                                                                                                                                                                                                        'rules': {
                 title: 'rules/',
                 desc: 'Path-scoped context that loads when Claude works on matching files.'
             },
@@ -1298,6 +1313,16 @@
                 desc: 'Runs tests, then stages all changes, generates a conventional commit message, commits, and pushes.<div style="margin-top: 12px;"><strong>Parameters</strong><div style="margin-top: 4px; opacity: 0.6;">None</div></div><div style="margin-top: 12px;"><strong>Responses</strong><table style="margin-top: 6px; border-collapse: collapse; font-size: 0.9em; text-align: left;"><tr style="text-align: left; border-bottom: 1px solid var(--border);"><th style="padding: 4px 8px 4px 0; white-space: nowrap;">Status</th><th style="padding: 4px 8px 4px 0;">Description</th></tr><tr style="border-bottom: 1px solid var(--border);"><td style="padding: 4px 8px 4px 0; vertical-align: top; white-space: nowrap;"><code>success</code></td><td style="padding: 4px 8px 4px 0; vertical-align: top;">Changes committed and pushed to current branch.</td></tr><tr style="border-bottom: 1px solid var(--border);"><td style="padding: 4px 8px 4px 0; vertical-align: top; white-space: nowrap;"><code>test-failure</code></td><td style="padding: 4px 8px 4px 0; vertical-align: top;">Tests failed — no commit made.</td></tr></table></div><div style="margin-top: 12px;"><strong>Side Effects</strong><div style="margin-top: 4px; font-size: 0.9em;">Runs test suite, stages all changes, creates git commit, pushes to remote</div></div><div style="margin-top: 12px;"><strong>Examples</strong><div style="margin-top: 6px; background: var(--bg-elevated); border-radius: 6px; padding: 8px 12px; font-family: monospace; font-size: 0.85em;"><div><code>/commit-and-push</code> <span style="opacity: 0.6;">— Run tests, commit, and push</span></div></div></div>',
                 trigger: '/commit-and-push'
             },
+            'disable-arcade-beeps': {
+                title: 'disable-arcade-beeps.md',
+                desc: 'disable-arcade-beeps.md in commands/<div style="margin-top: 12px;"><strong>Parameters</strong><div style="margin-top: 4px; opacity: 0.6;">None</div></div>',
+                trigger: '/disable-arcade-beeps'
+            },
+            'enable-arcade-beeps': {
+                title: 'enable-arcade-beeps.md',
+                desc: 'enable-arcade-beeps.md in commands/<div style="margin-top: 12px;"><strong>Parameters</strong><div style="margin-top: 4px; opacity: 0.6;">None</div></div>',
+                trigger: '/enable-arcade-beeps'
+            },
             'extract-rules': {
                 title: 'extract-rules.md',
                 desc: 'Scan Claude artifacts and extract structured rules into .claude/rules/<div style="margin-top: 12px;"><strong>Parameters</strong><table style="margin-top: 6px; border-collapse: collapse; font-size: 0.9em; text-align: left;"><tr style="text-align: left; border-bottom: 1px solid var(--border);"><th style="padding: 4px 8px 4px 0; white-space: nowrap;">Name</th><th style="padding: 4px 8px 4px 0; white-space: nowrap;">Type</th><th style="padding: 4px 8px 4px 0; white-space: nowrap;">Required</th><th style="padding: 4px 8px 4px 0;">Description</th></tr><tr style="border-bottom: 1px solid var(--border);"><td style="padding: 4px 8px 4px 0; vertical-align: top; white-space: nowrap;"><code>select</code></td><td style="padding: 4px 8px 4px 0; vertical-align: top; white-space: nowrap;"><code>string</code></td><td style="padding: 4px 8px 4px 0; vertical-align: top;">optional</td><td style="padding: 4px 8px 4px 0; vertical-align: top;">Write only specific rules by number: "1,3,5". Default: all.</td></tr><tr style="border-bottom: 1px solid var(--border);"><td style="padding: 4px 8px 4px 0; vertical-align: top; white-space: nowrap;"><code>keep-sources</code></td><td style="padding: 4px 8px 4px 0; vertical-align: top; white-space: nowrap;"><code>boolean</code></td><td style="padding: 4px 8px 4px 0; vertical-align: top;">optional</td><td style="padding: 4px 8px 4px 0; vertical-align: top;">Write rules but skip source cleanup (Step 8)</td></tr></table></div><div style="margin-top: 12px;"><strong>Responses</strong><table style="margin-top: 6px; border-collapse: collapse; font-size: 0.9em; text-align: left;"><tr style="text-align: left; border-bottom: 1px solid var(--border);"><th style="padding: 4px 8px 4px 0; white-space: nowrap;">Status</th><th style="padding: 4px 8px 4px 0;">Description</th></tr><tr style="border-bottom: 1px solid var(--border);"><td style="padding: 4px 8px 4px 0; vertical-align: top; white-space: nowrap;"><code>success</code></td><td style="padding: 4px 8px 4px 0; vertical-align: top;">Rules extracted, written, and sources cleaned up.</td></tr><tr style="border-bottom: 1px solid var(--border);"><td style="padding: 4px 8px 4px 0; vertical-align: top; white-space: nowrap;"><code>no-rules</code></td><td style="padding: 4px 8px 4px 0; vertical-align: top;">No extractable rules found in scanned sources.</td></tr></table></div><div style="margin-top: 12px;"><strong>Side Effects</strong><div style="margin-top: 4px; font-size: 0.9em;">Creates .claude/rules/ files and removes extracted content from source files</div></div><div style="margin-top: 12px;"><strong>Examples</strong><div style="margin-top: 6px; background: var(--bg-elevated); border-radius: 6px; padding: 8px 12px; font-family: monospace; font-size: 0.85em;"><div><code>/extract-rules</code> <span style="opacity: 0.6;">— Scan, propose, prompt for approval, write, and clean up</span></div><div><code>/extract-rules --keep-sources</code> <span style="opacity: 0.6;">— Write rules without modifying source files</span></div><div><code>/extract-rules --select 1,3</code> <span style="opacity: 0.6;">— Write only rules #1 and #3</span></div></div></div>',
@@ -1333,6 +1358,11 @@
                 desc: 'Placeholder — drop your project\'s custom subagent definitions in this directory.',
                 trigger: 'Background agent'
             },
+            'arcade-beeps-hook': {
+                title: 'arcade-beeps.js',
+                desc: 'arcade-beeps.js in hooks/',
+                trigger: 'PostToolUse hook'
+            },
             'feedback-rule-check-hook': {
                 title: 'feedback-rule-check.js',
                 desc: 'After FEEDBACK.md is edited, notifies Claude to evaluate',
@@ -1569,7 +1599,7 @@ CRITICAL: A plausible-looking cause from code reading is NOT confirmed evidence.
 
 > Run \`/autoconfig\` to populate this based on your project.`
             },
-                                                                                                                                                                                                                                                                                                                                                                                                            'autoconfig-update': {
+                                                                                                                                                                                                                                                                                                                                                                                                                        'autoconfig-update': {
                 filename: 'autoconfig-update.md',
                 content: `<!-- @applied
 -->
@@ -1656,6 +1686,32 @@ Use conventional commits: \`type(scope): description\`
 Types: feat, fix, docs, style, refactor, test, chore
 
 Keep the subject line under 50 chars. Add body if the change needs explanation.`
+            },
+            'disable-arcade-beeps': {
+                filename: 'disable-arcade-beeps.md',
+                content: `---
+description: Turn OFF Pole Position tab status beeps
+allowed-tools: Bash
+---
+
+Run exactly this command, then reply with a single confirmation line and nothing else:
+
+\`\`\`
+rm -f ~/.claude/sounds/arcade-beeps.enabled && echo "arcade beeps DISABLED."
+\`\`\``
+            },
+            'enable-arcade-beeps': {
+                filename: 'enable-arcade-beeps.md',
+                content: `---
+description: Turn ON Pole Position tab status beeps (awaiting = low tone, complete = high tone)
+allowed-tools: Bash
+---
+
+Run exactly this command, then reply with a single confirmation line and nothing else:
+
+\`\`\`
+mkdir -p ~/.claude/sounds && touch ~/.claude/sounds/arcade-beeps.enabled && echo "arcade beeps ENABLED (every turn-end beeps: awaiting=low, complete=high). Disable with /disable-arcade-beeps."
+\`\`\``
             },
             'extract-rules': {
                 filename: 'extract-rules.md',
@@ -1837,6 +1893,39 @@ claude-code-autoconfig ships this folder empty so you can populate it with agent
 
 See Anthropic's subagents docs for the file format:
 https://docs.anthropic.com/en/docs/claude-code/sub-agents`
+            },
+            'arcade-beeps-hook': {
+                filename: 'arcade-beeps.js',
+                content: `#!/usr/bin/env node
+/**
+ * arcade-beeps — optional Pole-Position status cues for the Claude Code tab.
+ * Companion to terminal-title.js. Registered (settings.json) on Stop + Notification.
+ *
+ * OFF unless the enable flag exists:  ~/.claude/sounds/arcade-beeps.enabled
+ *   toggle via  /enable-arcade-beeps   /disable-arcade-beeps
+ * The flag is GLOBAL (homedir), so one toggle covers every project you've installed into.
+ *
+ * Mapping (matches the ◐/✻ tab glyph that terminal-title.js paints on the SAME event):
+ *   Stop, turn ended on a question   -> ◐ awaiting  -> get-ready tick (pp3-getready-G4.wav, G4/384Hz)
+ *   Stop, turn ended normally         -> ✻ complete  -> GO beep        (pp3-go-F#5.wav, F#5/759Hz)
+ *   Notification (permission_prompt) -> ◐ awaiting  -> get-ready tick
+ *
+ * Tones are an extracted+smoothed take on the Pole Position race-start cue (arcade-ping
+ * envelope). LOWER tick = awaiting, HIGHER GO = complete.
+ *
+ * Assets resolve relative to THIS file (../sounds) so a per-project CCA install finds its own
+ * copy at <project>/.claude/sounds — no dependency on a global sounds dir.
+ *
+ * Playback is cross-platform and best-effort: PowerShell SoundPlayer on Windows, afplay on
+ * macOS, paplay||aplay on Linux. If none is present the hook simply stays silent — never errors.
+ *
+ * Playback BLOCKS (spawnSync) so the sound finishes inside the hook's lifetime — a detached
+ * fire-and-forget child can be killed by the hook runner's job/process-group cleanup before it
+ * plays. Blocking costs ~0.5s on turn-end but is reliable. Still fail-safe: wrapped so it never
+ * throws into the turn, and every path ends in exit(0).
+ *
+ * State detection reuses terminal-title.js's exported inspectLastResponse (lazy-required only
+ * when enabled) so sound and glyph agree. A tiny inline '?' check is the fallback.`
             },
             'feedback-rule-check-hook': {
                 filename: 'feedback-rule-check.js',
@@ -2082,6 +2171,10 @@ Claude reads this file but must never write to it. When Claude discovers project
           {
             "type": "command",
             "command": "node .claude/hooks/terminal-title.js"
+          },
+          {
+            "type": "command",
+            "command": "node .claude/hooks/arcade-beeps.js"
           }
         ]
       }
@@ -2093,6 +2186,10 @@ Claude reads this file but must never write to it. When Claude discovers project
           {
             "type": "command",
             "command": "node .claude/hooks/terminal-title.js"
+          },
+          {
+            "type": "command",
+            "command": "node .claude/hooks/arcade-beeps.js"
           }
         ]
       }

package/.claude/hooks/arcade-beeps.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * arcade-beeps — optional Pole-Position status cues for the Claude Code tab.
+ * Companion to terminal-title.js. Registered (settings.json) on Stop + Notification.
+ *
+ * OFF unless the enable flag exists:  ~/.claude/sounds/arcade-beeps.enabled
+ *   toggle via  /enable-arcade-beeps   /disable-arcade-beeps
+ * The flag is GLOBAL (homedir), so one toggle covers every project you've installed into.
+ *
+ * Mapping (matches the ◐/✻ tab glyph that terminal-title.js paints on the SAME event):
+ *   Stop, turn ended on a question   -> ◐ awaiting  -> get-ready tick (pp3-getready-G4.wav, G4/384Hz)
+ *   Stop, turn ended normally         -> ✻ complete  -> GO beep        (pp3-go-F#5.wav, F#5/759Hz)
+ *   Notification (permission_prompt) -> ◐ awaiting  -> get-ready tick
+ *
+ * Tones are an extracted+smoothed take on the Pole Position race-start cue (arcade-ping
+ * envelope). LOWER tick = awaiting, HIGHER GO = complete.
+ *
+ * Assets resolve relative to THIS file (../sounds) so a per-project CCA install finds its own
+ * copy at <project>/.claude/sounds — no dependency on a global sounds dir.
+ *
+ * Playback is cross-platform and best-effort: PowerShell SoundPlayer on Windows, afplay on
+ * macOS, paplay||aplay on Linux. If none is present the hook simply stays silent — never errors.
+ *
+ * Playback BLOCKS (spawnSync) so the sound finishes inside the hook's lifetime — a detached
+ * fire-and-forget child can be killed by the hook runner's job/process-group cleanup before it
+ * plays. Blocking costs ~0.5s on turn-end but is reliable. Still fail-safe: wrapped so it never
+ * throws into the turn, and every path ends in exit(0).
+ *
+ * State detection reuses terminal-title.js's exported inspectLastResponse (lazy-required only
+ * when enabled) so sound and glyph agree. A tiny inline '?' check is the fallback.
+ *
+ * Diagnostic log (bounded ~64KB) at ~/.claude/hooks/.titles/arcade-beeps.log records every
+ * invocation + choice, so we can prove whether the hook fires on a real Stop.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ASSET_DIR = path.join(__dirname, '..', 'sounds');           // wavs ship beside the hook
+const FLAG = path.join(os.homedir(), '.claude', 'sounds', 'arcade-beeps.enabled'); // global toggle
+const LOG = path.join(os.homedir(), '.claude', 'hooks', '.titles', 'arcade-beeps.log');
+const DEBUG = process.env.ARCADE_BEEPS_DEBUG === '1';
+
+function logLine(msg) {
+  try {
+    try { if (fs.statSync(LOG).size > 64 * 1024) fs.renameSync(LOG, `${LOG}.1`); } catch (_) { /* none yet */ }
+    fs.appendFileSync(LOG, `${new Date().toISOString()}  ${msg}\n`);
+  } catch (_) { /* logging must never throw */ }
+}
+
+function enabled() { try { return fs.existsSync(FLAG); } catch (_) { return false; } }
+function delay(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+// Pick a blocking audio player for the current OS. Returns [cmd, args].
+function playerFor(wav) {
+  if (process.platform === 'win32') {
+    return ['powershell', ['-NoProfile', '-Command', `(New-Object Media.SoundPlayer '${wav}').PlaySync()`]];
+  }
+  if (process.platform === 'darwin') {
+    return ['afplay', [wav]];
+  }
+  // linux / other: prefer paplay (PulseAudio/PipeWire), fall back to aplay (ALSA)
+  return ['sh', ['-c', `paplay "${wav}" 2>/dev/null || aplay "${wav}" 2>/dev/null`]];
+}
+
+function play(wavName, why) {
+  if (DEBUG) process.stderr.write(`arcade-beeps: chose ${wavName} (${why})\n`);
+  logLine(`play ${wavName} (${why})`);
+  try {
+    const wav = path.join(ASSET_DIR, wavName);
+    if (!fs.existsSync(wav)) { logLine(`MISSING ${wav}`); return; }
+    // Block until the sound finishes so it can't be reaped with the hook process.
+    const [cmd, cmdArgs] = playerFor(wav);
+    spawnSync(cmd, cmdArgs, { stdio: 'ignore', windowsHide: true });
+  } catch (e) { logLine(`play-error ${e && e.message}`); }
+}
+
+// Fallback: does the last visible assistant text end on a question? (Mirrors terminal-title.js's regex.)
+function endsOnQuestionInline(transcriptPath) {
+  try {
+    const lines = fs.readFileSync(transcriptPath, 'utf8').split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const l = lines[i].trim(); if (!l) continue;
+      let o; try { o = JSON.parse(l); } catch (_) { continue; }
+      if (!o || o.type !== 'assistant' || !o.message) continue;
+      const c = o.message.content; let t = '';
+      if (typeof c === 'string') t = c;
+      else if (Array.isArray(c)) t = c.filter(b => b && b.type === 'text' && typeof b.text === 'string').map(b => b.text).join('\n');
+      if (t.trim()) return /\?[\s)*_"]*(\([^()]*\)[\s.*_"]*)?$/.test(t);
+    }
+  } catch (_) { /* ignore */ }
+  return false;
+}
+
+async function main(input) {
+  let data = {};
+  try { data = JSON.parse(input); } catch (_) { /* ignore */ }
+  const event = data.hook_event_name || '?';
+  const en = enabled();
+  logLine(`invoked event=${event} enabled=${en ? 1 : 0}`);
+  if (!en) return;                               // opt-in only
+
+  if (event === 'Notification') { play('pp3-getready-G4.wav', 'notification'); return; }
+  if (event !== 'Stop') return;
+
+  // awaiting (question) vs complete — same signals terminal-title.js uses, so the tone matches the glyph.
+  const sid = data.session_id || '';
+  const askFile = path.join(os.homedir(), '.claude', 'hooks', '.titles', `${sid}.ask`);
+  let pending = false;
+  try { pending = fs.existsSync(askFile); } catch (_) { /* ignore */ }
+
+  if (!pending) {
+    let inspect = null;
+    try { ({ inspectLastResponse: inspect } = require('./terminal-title.js')); } catch (_) { /* fallback below */ }
+    if (inspect) {
+      let q = inspect(data.transcript_path);
+      let n = 0;
+      while (!q.ends && (q.suspectRace || !q.found) && n < 5) { await delay(120); q = inspect(data.transcript_path); n++; }
+      pending = q.ends;
+    } else {
+      pending = endsOnQuestionInline(data.transcript_path);
+    }
+  }
+
+  play(pending ? 'pp3-getready-G4.wav' : 'pp3-go-F#5.wav', pending ? 'awaiting' : 'complete');
+}
+
+if (require.main === module) {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', c => (input += c));
+  process.stdin.on('end', async () => { try { await main(input); } catch (_) { /* ignore */ } process.exit(0); });
+}
+
+module.exports = { endsOnQuestionInline };

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/.claude/settings.json

@@ -42,6 +42,10 @@
           {
             "type": "command",
             "command": "node .claude/hooks/terminal-title.js"
+          },
+          {
+            "type": "command",
+            "command": "node .claude/hooks/arcade-beeps.js"
           }
         ]
       }
@@ -53,6 +57,10 @@
           {
             "type": "command",
             "command": "node .claude/hooks/terminal-title.js"
+          },
+          {
+            "type": "command",
+            "command": "node .claude/hooks/arcade-beeps.js"
           }
         ]
       }

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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
+
 ## v1.0.197
 - perf(terminal-title): deliver the directive once per session; dedupe user/project hooks
 
@@ -142,9 +150,3 @@
 ## v1.0.150
 - style: use pointing emoji in inside-Claude message
 
-## v1.0.149
-- style: consolidate inside-Claude message to two lines
-
-## v1.0.148
-- fix: refine inside-Claude error wording
-

package/README.md

@@ -61,7 +61,8 @@ your-project/
     ├── hooks/                         # Hook scripts
     │   ├── format.js                  #   Auto-format on Write/Edit
     │   ├── terminal-title.js          #   Use-case terminal tab titles + live state
-    │   └── terminal-title.directive.md # Injected title directive (tunable wording)
+    │   ├── terminal-title.directive.md # Injected title directive (tunable wording)
+    │   └── arcade-beeps.js            #   Optional Pole Position status beeps (opt-in)
     ├── docs/                          # Interactive documentation
     │   └── autoconfig.docs.html       #   Open with /show-docs
     ├── updates/                       # Pending config updates
@@ -70,6 +71,9 @@ your-project/
     │   └── readme-sync.md             #   Sync README & docs before publish
     ├── scripts/                       # Utility scripts
     │   └── sync-docs.js               #   Regenerate interactive HTML docs
+    ├── sounds/                        # Status-cue audio for arcade-beeps
+    │   ├── pp3-getready-G4.wav        #   Awaiting tone (get-ready tick)
+    │   └── pp3-go-F#5.wav             #   Complete tone (GO beep)
     ├── .mcp.json                      # MCP server configs (empty placeholder)
     └── settings.json                  # Permissions & security
 ```
@@ -110,6 +114,8 @@ Autoconfig is **self-configuring**. Run `/autoconfig` and Claude:
 | `/gls` | Views latest screenshot for visual context |
 | `/validate-cca-install` | Validates installation against latest published version |
 | `/extract-rules` | Scan Claude artifacts and extract structured rules |
+| `/enable-arcade-beeps` | Turn on opt-in Pole Position status beeps |
+| `/disable-arcade-beeps` | Turn off the status beeps |
 
 ### Updates
 
@@ -135,6 +141,10 @@ Autoconfig writes a debug methodology to Claude's persistent memory (`MEMORY.md`
 
 Run several Claude Code sessions at once and the tabs all look alike. Autoconfig retitles each tab as `{scope} — {what you're working on}` with a live state indicator — ⬤ working, ◐ waiting on you, ✻ idle — so you can tell sessions apart at a glance. Claude updates the title itself as the work shifts; nothing to configure.
 
+### Status Beeps (opt-in)
+
+Prefer your ears to your eyes? Run `/enable-arcade-beeps` for Pole Position–style tab cues that mirror the title glyph: a low get-ready tick when a session is **waiting on you** and a higher GO tone when it **finishes**. Cross-platform (Windows / macOS / Linux) and off by default — toggle back off any time with `/disable-arcade-beeps`.
+
 ### Team Feedback
 
 When Claude makes a mistake, add an entry to `.claude/feedback/FEEDBACK.md`:

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);
@@ -27,7 +28,7 @@ const WINDOWS_RESERVED = ['CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'C
   'LPT6', 'LPT7', 'LPT8', 'LPT9'];
 
 // Files/folders installed by autoconfig - don't backup these
-const AUTOCONFIG_FILES = ['commands', 'docs', 'agents', 'migration', 'hooks', 'scripts', 'rules', 'feedback', 'settings.json', 'settings.local.json', '.mcp.json', '.autoconfig-version', '.autoconfig-plugins.json'];
+const AUTOCONFIG_FILES = ['commands', 'docs', 'agents', 'migration', 'hooks', 'scripts', 'sounds', 'rules', 'feedback', 'settings.json', 'settings.local.json', '.mcp.json', '.autoconfig-version', '.autoconfig-plugins.json'];
 
 function isReservedName(name) {
   const baseName = name.replace(/\.[^.]*$/, '').toUpperCase();
@@ -775,7 +776,7 @@ if (fs.existsSync(feedbackSrc)) {
 // (copyDirIfMissing), BUT the cca-managed title-hook files are ALWAYS refreshed so bug-fixes
 // reach existing installs — without this, copyDirIfMissing leaves stale hooks in place forever
 // (same always-overwrite rationale as scripts/ below). --force already overwrites everything.
-const MANAGED_HOOKS = ['terminal-title.js', 'terminal-title.directive.md'];
+const MANAGED_HOOKS = ['terminal-title.js', 'terminal-title.directive.md', 'arcade-beeps.js'];
 if (fs.existsSync(hooksSrc)) {
   const copyFn = forceMode ? copyDir : copyDirIfMissing;
   copyFn(hooksSrc, path.join(claudeDest, 'hooks'));
@@ -793,6 +794,12 @@ if (fs.existsSync(scriptsSrc)) {
   copyDir(scriptsSrc, path.join(claudeDest, 'scripts'));
 }
 
+// Copy sounds directory (binary status-cue assets for arcade-beeps; always overwrite)
+const soundsSrc = path.join(packageDir, '.claude', 'sounds');
+if (fs.existsSync(soundsSrc)) {
+  copyDir(soundsSrc, path.join(claudeDest, 'sounds'));
+}
+
 // Note: updates directory is no longer copied to user projects.
 // Update files are only used by --pull-updates (for /autoconfig-update).
 // On fresh install, all updates are pre-marked as applied and the content
@@ -950,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.197",
+  "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",