# Sparse Mode: ANSI Bold Headers Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Convert `## headers` to ANSI bold text (instead of stripping them) in sparse render mode, giving readable section separation at ~3 tokens/header instead of 0 (stripped) or ~12 (colored badge).

**Architecture:** Modify `stripMarkdown()` in `ansi-renderer.ts` to accept an options parameter. When `boldHeaders: true`, headers get `\x1b[1m` ANSI bold wrapping instead of being stripped to plain text. The sparse case in `renderOutput()` calls `stripMarkdown` with this option enabled.

**Tech Stack:** TypeScript, raw ANSI escape codes (`\x1b[1m`, `\x1b[0m`)

---

### Task 1: Add ANSI Bold Header Support to stripMarkdown

**Files:**
- Modify: `src/utils/ansi-renderer.ts:552-592` (stripMarkdown function)
- Test: `src/utils/__tests__/strip-markdown.test.ts`

- [ ] **Step 1: Write the failing test**

```typescript
// src/utils/__tests__/strip-markdown.test.ts
import { describe, it, expect } from 'vitest';
import { stripMarkdown } from '../ansi-renderer.js';

describe('stripMarkdown', () => {
  it('strips headers to plain text by default', () => {
    expect(stripMarkdown('## Analysis')).toBe('Analysis');
    expect(stripMarkdown('### Summary')).toBe('Summary');
  });

  it('converts headers to ANSI bold when boldHeaders is true', () => {
    const result = stripMarkdown('## Analysis', { boldHeaders: true });
    expect(result).toBe('\x1b[1mAnalysis\x1b[0m');
  });

  it('handles h1-h6 with ANSI bold', () => {
    const result = stripMarkdown('# Title\n## Section\n### Sub', { boldHeaders: true });
    expect(result).toContain('\x1b[1mTitle\x1b[0m');
    expect(result).toContain('\x1b[1mSection\x1b[0m');
    expect(result).toContain('\x1b[1mSub\x1b[0m');
  });

  it('strips bold/italic/strikethrough normally', () => {
    expect(stripMarkdown('**bold** and *italic* and ~~strike~~')).toBe('bold and italic and strike');
  });

  it('preserves bullets and indentation', () => {
    const input = '- Item 1\n  - Sub item\n    - Deep';
    expect(stripMarkdown(input)).toBe(input);
  });

  it('preserves code blocks untouched', () => {
    const input = '```js\nconst x = 1;\n```';
    expect(stripMarkdown(input)).toContain('const x = 1;');
  });

  it('strips horizontal rules', () => {
    expect(stripMarkdown('---')).toBe('');
    expect(stripMarkdown('***')).toBe('');
  });

  it('adds blank line after bold header for readability', () => {
    const result = stripMarkdown('## Analysis\nSome text', { boldHeaders: true });
    expect(result).toBe('\x1b[1mAnalysis\x1b[0m\nSome text');
  });
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npx vitest run src/utils/__tests__/strip-markdown.test.ts`
Expected: FAIL — `stripMarkdown` does not accept options parameter

- [ ] **Step 3: Add options parameter to stripMarkdown**

In `src/utils/ansi-renderer.ts`, change the `stripMarkdown` signature and header regex:

```typescript
export interface StripMarkdownOptions {
  /** Convert ## headers to ANSI bold instead of stripping # prefix */
  boldHeaders?: boolean;
}

export function stripMarkdown(md: string, options?: StripMarkdownOptions): string {
  const { boldHeaders = false } = options || {};

  // ... existing code block extraction ...

  // 2. Strip decorative formatting on non-code text
  text = text
    // Headers — ANSI bold or strip # prefix
    .replace(/^#{1,6}\s+(.+)$/gm, boldHeaders ? '\x1b[1m$1\x1b[0m' : '$1')
    // ... rest of existing regexes unchanged ...
```

- [ ] **Step 4: Run test to verify it passes**

Run: `npx vitest run src/utils/__tests__/strip-markdown.test.ts`
Expected: ALL PASS

- [ ] **Step 5: Commit**

```bash
git add src/utils/__tests__/strip-markdown.test.ts src/utils/ansi-renderer.ts
git commit -m "feat(sparse): convert headers to ANSI bold in stripMarkdown"
```

---

### Task 2: Wire Sparse Mode to Use Bold Headers

**Files:**
- Modify: `src/utils/ansi-renderer.ts:240-253` (sparse case in renderOutput)

- [ ] **Step 1: Update sparse case to pass boldHeaders option**

In the `renderOutput` function's sparse case:

```typescript
    case 'sparse': {
      // Sparse mode: ANSI badge header + clean text with bold section headers
      if (options.model) {
        const badge = renderModelBadge(options.model);
        if (options.summary) {
          output = badge + renderSummaryBadge(options.summary, options.model) + '\n';
        } else {
          output = badge + '\n';
        }
      }
      output += stripMarkdown(content, { boldHeaders: true });
      break;
    }
```

- [ ] **Step 2: Verify plain mode still strips headers (no bold)**

The `plain` case should remain unchanged:
```typescript
    case 'plain':
      output += stripMarkdown(content);  // no options = headers stripped flat
      break;
```

- [ ] **Step 3: Build and test end-to-end**

Run: `npm run build && node -e "
import { renderOutput } from './dist/src/utils/ansi-renderer.js';
const md = '## Analysis\n\n**Critical bug** in server.ts:\n- Missing null check\n\n### Summary\nLooks good.';
console.log('--- sparse ---');
console.log(renderOutput(md, { model: 'gemini', summary: 'gemini_analyze_code', mode: 'sparse' }));
console.log('--- plain ---');
console.log(renderOutput(md, { model: 'gemini', mode: 'plain' }));
"`

Expected:
- sparse: badge + `\x1b[1mAnalysis\x1b[0m` (bold) + stripped body
- plain: `Analysis` (no bold) + stripped body

- [ ] **Step 4: Commit**

```bash
git add src/utils/ansi-renderer.ts
git commit -m "feat(sparse): wire bold headers in sparse render mode"
```

---

### Task 3: Fix TS Unused Import Warnings in server.ts

**Files:**
- Modify: `src/server.ts:34,63,67,71,73,78,84,339,342`

- [ ] **Step 1: Remove unused imports and variables**

Lines to fix (from TS diagnostics):
- Line 34: `envResult` — prefix with `void` or remove assignment: `dotenvConfig({ path: envPath, override: true });`
- Line 63: `stripMarkdown` — already removed in this session
- Line 67: `getUpdateStatus` — remove from import
- Line 71: `TechnicalDomain` — remove import
- Line 73: `getUnifiedAITools` — remove from import
- Line 78: `createFocusDeepPlan`, `generateFocusDeepVisualization` — remove from import
- Line 84: `getAllOpenRouterTools` — remove from import
- Line 339: `executeNow` — remove or prefix unused destructure
- Line 342: `saveSession` — remove or prefix unused destructure

- [ ] **Step 2: Build to verify no errors**

Run: `npm run build`
Expected: Clean build, no warnings

- [ ] **Step 3: Run existing tests**

Run: `npm test`
Expected: ALL PASS

- [ ] **Step 4: Commit**

```bash
git add src/server.ts
git commit -m "chore: remove unused imports in server.ts"
```

---

### Task 4: Set RENDER_OUTPUT=sparse as Default

**Files:**
- Modify: `.env` (add `RENDER_OUTPUT=sparse`)
- Modify: `src/utils/ansi-renderer.ts:113` (optional: change default from `markdown` to `sparse`)

- [ ] **Step 1: Add to .env**

```bash
echo 'RENDER_OUTPUT=sparse' >> .env
```

- [ ] **Step 2: Decide on code default**

Option A: Keep `markdown` as code default, override in `.env` only (safer, no behavior change for other users)
Option B: Change code default to `sparse` (all users get badges by default)

Recommend: Option A — set in `.env`, keep code default as `markdown`.

- [ ] **Step 3: Restart MCP server and test with a real tool call**

Call any tachibot tool (e.g., `gemini_analyze_code`) and verify:
- Colored badge appears at top
- Summary badge next to it
- Headers are bold
- Body is clean (no `**`, `##`, `~~`)

- [ ] **Step 4: Commit**

```bash
git add .env
git commit -m "feat: enable sparse render mode in .env"
```

---

### Token Cost Summary

| Element | Tokens per instance | Instances/response | Total |
|---------|-------------------:|-------------------:|------:|
| Model badge (ANSI) | ~12 | 1 | 12 |
| Summary badge (ANSI) | ~8 | 1 | 8 |
| Bold header (ANSI) | ~3-4 | 2-4 | 8-16 |
| Stripped `**`/`##`/`~~` | -2 each | 10-15 | -20 to -30 |
| **Net per response** | | | **~0 to +6** |

Sparse mode with bold headers is token-neutral vs raw markdown. You get visual readability for free.
