@monoes/monograph 1.1.0 → 1.2.0

package/.monomind/data/ranked-context.json

@@ -1,5 +1,5 @@
 {
   "version": 1,
-  "computedAt": 1777578175217,
+  "computedAt": 1778102154767,
   "entries": []
 }

package/.monomind/sessions/session-1777578175215.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1777578175215",
+  "startedAt": "2026-04-30T19:42:55.215Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 42,
+    "commands": 0,
+    "tasks": 10,
+    "errors": 0
+  },
+  "endedAt": "2026-05-03T15:52:50.959Z",
+  "duration": 245395745
+}

package/.monomind/sessions/session-1777823684507.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1777823684507",
+  "startedAt": "2026-05-03T15:54:44.507Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 34,
+    "commands": 0,
+    "tasks": 0,
+    "errors": 0
+  },
+  "endedAt": "2026-05-04T21:07:59.511Z",
+  "duration": 105195004
+}

package/.monomind/sessions/session-1777928944749.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1777928944749",
+  "startedAt": "2026-05-04T21:09:04.749Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 18,
+    "commands": 0,
+    "tasks": 3,
+    "errors": 0
+  },
+  "endedAt": "2026-05-06T07:32:36.650Z",
+  "duration": 123811901
+}

package/.monomind/sessions/session-1778052902210.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1778052902210",
+  "startedAt": "2026-05-06T07:35:02.210Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 29,
+    "commands": 0,
+    "tasks": 2,
+    "errors": 0
+  },
+  "endedAt": "2026-05-06T08:37:15.370Z",
+  "duration": 3733161
+}

package/.monomind/sessions/session-1778056744636.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1778056744636",
+  "startedAt": "2026-05-06T08:39:04.636Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 30,
+    "commands": 0,
+    "tasks": 2,
+    "errors": 0
+  },
+  "endedAt": "2026-05-06T09:49:21.825Z",
+  "duration": 4217190
+}

package/.monomind/sessions/session-1778061077599.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1778061077599",
+  "startedAt": "2026-05-06T09:51:17.599Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 11,
+    "commands": 0,
+    "tasks": 0,
+    "errors": 0
+  },
+  "endedAt": "2026-05-06T21:13:36.832Z",
+  "duration": 40939234
+}

package/.monomind/sessions/session-1778102154764.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1778102154764",
+  "startedAt": "2026-05-06T21:15:54.764Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 12,
+    "commands": 0,
+    "tasks": 0,
+    "errors": 0
+  },
+  "endedAt": "2026-05-09T05:42:40.302Z",
+  "duration": 203205539
+}

package/__tests__/analysis/shape-extractor.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from 'vitest';
+import {
+  extractHandlerReturnKeys,
+  extractAccessedKeys,
+  compareShapes,
+} from '../../src/analysis/shape-extractor.js';
+
+describe('extractHandlerReturnKeys', () => {
+  it('extracts keys from .json({ id, name })', () => {
+    const src = `res.json({ id: user.id, name: user.name })`;
+    expect(extractHandlerReturnKeys(src)).toEqual(['id', 'name']);
+  });
+
+  it('extracts keys from return { status, data } sorted alphabetically', () => {
+    const src = `return { status: 'ok', data: [] }`;
+    expect(extractHandlerReturnKeys(src)).toEqual(['data', 'status']);
+  });
+
+  it('extracts keys from NextResponse.json({ key })', () => {
+    const src = `return NextResponse.json({ success: true, token: jwt })`;
+    expect(extractHandlerReturnKeys(src)).toEqual(['success', 'token']);
+  });
+
+  it('returns empty array when no pattern is found', () => {
+    const src = `const x = 1; console.log(x);`;
+    expect(extractHandlerReturnKeys(src)).toEqual([]);
+  });
+
+  it('deduplicates keys across multiple occurrences', () => {
+    const src = `
+      if (error) return res.json({ message: 'fail' });
+      return res.json({ message: 'ok', id: 1 });
+    `;
+    expect(extractHandlerReturnKeys(src)).toEqual(['id', 'message']);
+  });
+
+  it('ignores spread properties', () => {
+    const src = `res.json({ ...user, extra: true })`;
+    const keys = extractHandlerReturnKeys(src);
+    expect(keys).toContain('extra');
+    expect(keys).not.toContain('...user');
+  });
+});
+
+describe('extractAccessedKeys', () => {
+  it('extracts dot-access keys from response variable', () => {
+    const src = `const email = data.email;`;
+    expect(extractAccessedKeys(src, ['data'])).toContain('email');
+  });
+
+  it('extracts destructured keys from response variable', () => {
+    const src = `const { id, name } = result;`;
+    expect(extractAccessedKeys(src, ['result'])).toEqual(
+      expect.arrayContaining(['id', 'name']),
+    );
+  });
+
+  it('extracts keys from both dot-access and destructuring', () => {
+    const src = `
+      const { id, name } = result;
+      console.log(data.email);
+    `;
+    const keys = extractAccessedKeys(src, ['data', 'result']);
+    expect(keys).toEqual(expect.arrayContaining(['email', 'id', 'name']));
+  });
+
+  it('excludes method calls (data.json() should not add json)', () => {
+    const src = `data.json().then(r => r)`;
+    const keys = extractAccessedKeys(src, ['data']);
+    expect(keys).not.toContain('json');
+  });
+
+  it('returns sorted unique keys', () => {
+    const src = `
+      const z = data.z;
+      const a = data.a;
+      const z2 = data.z;
+    `;
+    const keys = extractAccessedKeys(src, ['data']);
+    expect(keys).toEqual(['a', 'z']);
+  });
+
+  it('uses default var names when not provided', () => {
+    const src = `const x = response.userId;`;
+    const keys = extractAccessedKeys(src);
+    expect(keys).toContain('userId');
+  });
+});
+
+describe('compareShapes', () => {
+  it('returns MATCH when all accessed keys are returned', () => {
+    const shape = compareShapes(['id', 'name', 'email'], ['id', 'name']);
+    expect(shape.status).toBe('MATCH');
+    expect(shape.mismatches).toHaveLength(0);
+    expect(shape.extra).toEqual(['email']);
+  });
+
+  it('returns MISMATCH when an accessed key is not returned', () => {
+    const shape = compareShapes(['id', 'name'], ['id', 'name', 'token']);
+    expect(shape.status).toBe('MISMATCH');
+    expect(shape.mismatches).toEqual(['token']);
+  });
+
+  it('returns UNKNOWN when returnedKeys is empty', () => {
+    const shape = compareShapes([], ['id']);
+    expect(shape.status).toBe('UNKNOWN');
+  });
+
+  it('returns UNKNOWN when accessedKeys is empty', () => {
+    const shape = compareShapes(['id', 'name'], []);
+    expect(shape.status).toBe('UNKNOWN');
+  });
+
+  it('returns UNKNOWN when both sets are empty', () => {
+    const shape = compareShapes([], []);
+    expect(shape.status).toBe('UNKNOWN');
+  });
+
+  it('populates returnedKeys and accessedKeys on result', () => {
+    const shape = compareShapes(['id'], ['id']);
+    expect(shape.returnedKeys).toEqual(['id']);
+    expect(shape.accessedKeys).toEqual(['id']);
+  });
+});

package/__tests__/analysis/surprise-scorer.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from 'vitest';
+import { computeSurpriseScore, scoreNodes } from '../../src/analysis/surprise-scorer.js';
+import type { ScoredNode } from '../../src/analysis/surprise-scorer.js';
+
+function makeNode(overrides: Partial<ScoredNode> = {}): ScoredNode {
+  return {
+    id: 'node-1',
+    degree: 5,
+    avgDegree: 5,
+    crossCommunityEdges: 0,
+    totalEdges: 10,
+    stalenessScore: 0,
+    ...overrides,
+  };
+}
+
+describe('computeSurpriseScore', () => {
+  it('average node with no anomalies scores near 0', () => {
+    const node = makeNode({
+      degree: 5,
+      avgDegree: 5,
+      crossCommunityEdges: 0,
+      totalEdges: 10,
+      stalenessScore: 0,
+    });
+    const score = computeSurpriseScore(node);
+    expect(score).toBeCloseTo(0, 5);
+  });
+
+  it('hub node with very high degree scores high on degree anomaly', () => {
+    const node = makeNode({
+      degree: 100,
+      avgDegree: 5,
+      crossCommunityEdges: 0,
+      totalEdges: 100,
+      stalenessScore: 0,
+    });
+    const score = computeSurpriseScore(node);
+    // degreeAnomaly = clamp(|100-5|/(5+1), 0, 1) = clamp(15.83, 0, 1) = 1
+    // score = 0.4 * 1 + 0.4 * 0 + 0.2 * 0 = 0.4
+    expect(score).toBeCloseTo(0.4, 5);
+  });
+
+  it('node with all cross-community edges scores high on that factor', () => {
+    const node = makeNode({
+      degree: 5,
+      avgDegree: 5,
+      crossCommunityEdges: 10,
+      totalEdges: 10,
+      stalenessScore: 0,
+    });
+    const score = computeSurpriseScore(node);
+    // crossCommunityRatio = 10/10 = 1
+    // score = 0.4 * 0 + 0.4 * 1 + 0.2 * 0 = 0.4
+    expect(score).toBeCloseTo(0.4, 5);
+  });
+
+  it('stale node scores higher than fresh node with same degree', () => {
+    const base = { degree: 5, avgDegree: 5, crossCommunityEdges: 0, totalEdges: 10 };
+    const freshScore = computeSurpriseScore(makeNode({ ...base, stalenessScore: 0 }));
+    const staleScore = computeSurpriseScore(makeNode({ ...base, stalenessScore: 1 }));
+    expect(staleScore).toBeGreaterThan(freshScore);
+    // staleScore should be 0.2 (0.4*0 + 0.4*0 + 0.2*1)
+    expect(staleScore).toBeCloseTo(0.2, 5);
+  });
+
+  it('fully anomalous node (high degree + all cross-community + fully stale) scores 1', () => {
+    const node = makeNode({
+      degree: 1000,
+      avgDegree: 5,
+      crossCommunityEdges: 10,
+      totalEdges: 10,
+      stalenessScore: 1,
+    });
+    const score = computeSurpriseScore(node);
+    // degreeAnomaly clamped to 1, crossCommunityRatio = 1, staleness = 1
+    // score = 0.4*1 + 0.4*1 + 0.2*1 = 1.0
+    expect(score).toBeCloseTo(1.0, 5);
+  });
+
+  it('returns 0 cross-community ratio when totalEdges is 0', () => {
+    const node = makeNode({
+      degree: 0,
+      avgDegree: 5,
+      crossCommunityEdges: 0,
+      totalEdges: 0,
+      stalenessScore: 0,
+    });
+    // Should not throw, cross-community factor should be 0
+    const score = computeSurpriseScore(node);
+    expect(score).toBeGreaterThanOrEqual(0);
+    expect(score).toBeLessThanOrEqual(1);
+  });
+
+  it('respects custom weights', () => {
+    const node = makeNode({
+      degree: 1000,
+      avgDegree: 5,
+      crossCommunityEdges: 0,
+      totalEdges: 10,
+      stalenessScore: 0,
+    });
+    // Only degree weight active, set to 1.0
+    const score = computeSurpriseScore(node, {
+      degreeWeight: 1.0,
+      crossCommunityWeight: 0,
+      stalenessWeight: 0,
+    });
+    expect(score).toBeCloseTo(1.0, 5);
+  });
+});
+
+describe('scoreNodes', () => {
+  it('returns nodes sorted by surprise score descending', () => {
+    const nodes: ScoredNode[] = [
+      makeNode({ id: 'low', degree: 5, avgDegree: 5, crossCommunityEdges: 0, totalEdges: 10, stalenessScore: 0 }),
+      makeNode({ id: 'high', degree: 100, avgDegree: 5, crossCommunityEdges: 10, totalEdges: 10, stalenessScore: 1 }),
+      makeNode({ id: 'mid', degree: 5, avgDegree: 5, crossCommunityEdges: 5, totalEdges: 10, stalenessScore: 0.5 }),
+    ];
+
+    const scored = scoreNodes(nodes);
+    expect(scored[0].id).toBe('high');
+    expect(scored[scored.length - 1].id).toBe('low');
+  });
+
+  it('attaches surpriseScore to each node', () => {
+    const nodes = [makeNode({ id: 'a' }), makeNode({ id: 'b' })];
+    const scored = scoreNodes(nodes);
+    expect(scored).toHaveLength(2);
+    for (const node of scored) {
+      expect(typeof node.surpriseScore).toBe('number');
+      expect(node.surpriseScore).toBeGreaterThanOrEqual(0);
+      expect(node.surpriseScore).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it('preserves all original node properties', () => {
+    const node = makeNode({ id: 'test-node', communityId: 'community-A' });
+    const [scored] = scoreNodes([node]);
+    expect(scored.id).toBe('test-node');
+    expect(scored.communityId).toBe('community-A');
+  });
+
+  it('default weights sum to 1.0 (0.4 + 0.4 + 0.2)', () => {
+    const degreeWeight = 0.4;
+    const crossCommunityWeight = 0.4;
+    const stalenessWeight = 0.2;
+    expect(degreeWeight + crossCommunityWeight + stalenessWeight).toBeCloseTo(1.0, 10);
+  });
+
+  it('returns empty array for empty input', () => {
+    expect(scoreNodes([])).toEqual([]);
+  });
+});

package/__tests__/cache/extraction-cache.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { ExtractionCache } from '../../src/cache/extraction-cache.js';
+import type { MonographNode } from '../../src/types.js';
+
+const sampleNodes: MonographNode[] = [
+  { id: 'n1', label: 'Function', name: 'fn', normLabel: 'fn', isExported: false },
+];
+
+let cacheDir: string;
+beforeEach(() => { cacheDir = mkdtempSync(join(tmpdir(), 'monograph-cache-')); });
+afterEach(() => { rmSync(cacheDir, { recursive: true, force: true }); });
+
+describe('ExtractionCache', () => {
+  it('returns null for unknown file', () => {
+    const cache = new ExtractionCache(cacheDir);
+    expect(cache.get('some/file.ts', 'abc123')).toBeNull();
+  });
+
+  it('stores and retrieves nodes for a file hash', () => {
+    const cache = new ExtractionCache(cacheDir);
+    cache.set('src/foo.ts', 'deadbeef', sampleNodes, []);
+    const hit = cache.get('src/foo.ts', 'deadbeef');
+    expect(hit).not.toBeNull();
+    expect(hit!.nodes[0].name).toBe('fn');
+  });
+
+  it('returns null when hash has changed (cache miss)', () => {
+    const cache = new ExtractionCache(cacheDir);
+    cache.set('src/foo.ts', 'hash1', sampleNodes, []);
+    expect(cache.get('src/foo.ts', 'hash2')).toBeNull();
+  });
+
+  it('computes file hash deterministically', () => {
+    const cache = new ExtractionCache(cacheDir);
+    const tmpFile = join(cacheDir, 'test.ts');
+    writeFileSync(tmpFile, 'const x = 1;');
+    const h1 = cache.hashFile(tmpFile);
+    const h2 = cache.hashFile(tmpFile);
+    expect(h1).toBe(h2);
+    expect(h1).toHaveLength(64); // sha256 hex
+  });
+});

package/__tests__/cli/ai-context.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { injectAiContext } from '../../src/cli/ai-context.js';
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'monograph-ai-context-'));
+});
+
+afterEach(async () => {
+  await fs.rm(tempDir, { recursive: true, force: true });
+});
+
+// ─── CLAUDE.md ────────────────────────────────────────────────────────────────
+
+describe('injectAiContext — CLAUDE.md', () => {
+  it('creates CLAUDE.md when it does not exist', async () => {
+    const result = await injectAiContext({ repoPath: tempDir, targets: ['claude'] });
+
+    const content = await fs.readFile(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('monograph:context:start');
+    expect(content).toContain('Monograph');
+    expect(result.updated).toContain('CLAUDE.md');
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('appends to existing CLAUDE.md without overwriting existing content', async () => {
+    const existing = '# My Project\n\nSome instructions here.\n';
+    await fs.writeFile(path.join(tempDir, 'CLAUDE.md'), existing, 'utf-8');
+
+    await injectAiContext({ repoPath: tempDir, targets: ['claude'] });
+
+    const content = await fs.readFile(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('# My Project');
+    expect(content).toContain('Some instructions here.');
+    expect(content).toContain('monograph:context:start');
+  });
+
+  it('is idempotent — running twice does not duplicate the block', async () => {
+    await injectAiContext({ repoPath: tempDir, targets: ['claude'] });
+    await injectAiContext({ repoPath: tempDir, targets: ['claude'] });
+
+    const content = await fs.readFile(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+    const occurrences = (content.match(/monograph:context:start/g) ?? []).length;
+    expect(occurrences).toBe(1);
+  });
+
+  it('marks file as skipped on second run when content is unchanged', async () => {
+    await injectAiContext({ repoPath: tempDir, targets: ['claude'] });
+    const result = await injectAiContext({ repoPath: tempDir, targets: ['claude'] });
+
+    expect(result.skipped).toContain('CLAUDE.md');
+    expect(result.updated).not.toContain('CLAUDE.md');
+  });
+
+  it('contains imperative rules (MUST/NEVER)', async () => {
+    await injectAiContext({ repoPath: tempDir, targets: ['claude'] });
+    const content = await fs.readFile(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('MUST');
+    expect(content).toContain('NEVER');
+  });
+
+  it('contains start and end markers', async () => {
+    await injectAiContext({ repoPath: tempDir, targets: ['claude'] });
+    const content = await fs.readFile(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('<!-- monograph:context:start -->');
+    expect(content).toContain('<!-- monograph:context:end -->');
+  });
+
+  it('contains tool usage guidance', async () => {
+    await injectAiContext({ repoPath: tempDir, targets: ['claude'] });
+    const content = await fs.readFile(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('monograph_impact');
+    expect(content).toContain('monograph_query');
+    expect(content).toContain('monograph_context');
+  });
+});
+
+// ─── AGENTS.md ────────────────────────────────────────────────────────────────
+
+describe('injectAiContext — AGENTS.md', () => {
+  it('creates AGENTS.md when it does not exist', async () => {
+    const result = await injectAiContext({ repoPath: tempDir, targets: ['agents-md'] });
+
+    const content = await fs.readFile(path.join(tempDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toContain('monograph:context:start');
+    expect(result.updated).toContain('AGENTS.md');
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('appends to existing AGENTS.md without overwriting existing content', async () => {
+    const existing = '# Agent Instructions\n\nExisting content.\n';
+    await fs.writeFile(path.join(tempDir, 'AGENTS.md'), existing, 'utf-8');
+
+    await injectAiContext({ repoPath: tempDir, targets: ['agents-md'] });
+
+    const content = await fs.readFile(path.join(tempDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toContain('# Agent Instructions');
+    expect(content).toContain('Existing content.');
+    expect(content).toContain('monograph:context:start');
+  });
+
+  it('is idempotent — running twice does not duplicate the block', async () => {
+    await injectAiContext({ repoPath: tempDir, targets: ['agents-md'] });
+    await injectAiContext({ repoPath: tempDir, targets: ['agents-md'] });
+
+    const content = await fs.readFile(path.join(tempDir, 'AGENTS.md'), 'utf-8');
+    const occurrences = (content.match(/monograph:context:start/g) ?? []).length;
+    expect(occurrences).toBe(1);
+  });
+
+  it('marks file as skipped on second run', async () => {
+    await injectAiContext({ repoPath: tempDir, targets: ['agents-md'] });
+    const result = await injectAiContext({ repoPath: tempDir, targets: ['agents-md'] });
+
+    expect(result.skipped).toContain('AGENTS.md');
+    expect(result.updated).not.toContain('AGENTS.md');
+  });
+});
+
+// ─── Both targets (default) ───────────────────────────────────────────────────
+
+describe('injectAiContext — both targets (default)', () => {
+  it('updates both files when no targets option is provided', async () => {
+    const result = await injectAiContext({ repoPath: tempDir });
+
+    expect(result.updated).toContain('CLAUDE.md');
+    expect(result.updated).toContain('AGENTS.md');
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('returns empty updated array when all targets are already present', async () => {
+    await injectAiContext({ repoPath: tempDir });
+    const result = await injectAiContext({ repoPath: tempDir });
+
+    expect(result.updated).toHaveLength(0);
+    expect(result.skipped).toHaveLength(2);
+  });
+
+  it('CLAUDE.md and AGENTS.md contain the same monograph block', async () => {
+    await injectAiContext({ repoPath: tempDir });
+
+    const claude = await fs.readFile(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+    const agents = await fs.readFile(path.join(tempDir, 'AGENTS.md'), 'utf-8');
+
+    // Both must contain the start and end markers
+    expect(claude).toContain('<!-- monograph:context:start -->');
+    expect(agents).toContain('<!-- monograph:context:start -->');
+    expect(claude).toContain('<!-- monograph:context:end -->');
+    expect(agents).toContain('<!-- monograph:context:end -->');
+  });
+});
+
+// ─── Natural-language content (not MCP config) ────────────────────────────────
+
+describe('injectAiContext — content character', () => {
+  it('does not inject a raw JSON MCP server config block', async () => {
+    await injectAiContext({ repoPath: tempDir, targets: ['claude'] });
+    const content = await fs.readFile(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+    // setup.ts injects {"mcpServers": ...} JSON — ai-context.ts must NOT
+    expect(content).not.toContain('"mcpServers"');
+  });
+
+  it('provides prose guidance aimed at AI agents', async () => {
+    await injectAiContext({ repoPath: tempDir, targets: ['claude'] });
+    const content = await fs.readFile(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+    // Should have human-readable section heading
+    expect(content).toContain('Monograph');
+    // Should describe tool use in natural language
+    expect(content).toContain('impact');
+  });
+});