claudeup 6.2.1 → 6.3.0

package/src/__tests__/conventions-integration.test.ts

@@ -23,30 +23,30 @@
  *   the actual .missing property. This is a minor API deviation (richer return).
  */
 
-import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
-import { mkdtemp, rm, mkdir, writeFile, readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 import {
-  // Gitignore operations
-  ensureGitignoreEntries,
-  checkGitignoreEntries,
-  // CLAUDE.md operations
-  parseClaudeMdSections,
-  injectClaudeMdSection,
-  removeClaudeMdSection,
-  listClaudeMdSections,
-  // Convention resolution
-  resolvePluginConventions,
-  readConventionTemplate,
-  // End-to-end convention application
-  applyConventions,
-  removeConventions,
-  // Types
-  type ParseResult,
-} from '../services/conventions-manager.js';
+	// Types
+	type ParseResult,
+	// End-to-end convention application
+	applyConventions,
+	checkGitignoreEntries,
+	// Gitignore operations
+	ensureGitignoreEntries,
+	injectClaudeMdSection,
+	listClaudeMdSections,
+	// CLAUDE.md operations
+	parseClaudeMdSections,
+	readConventionTemplate,
+	removeClaudeMdSection,
+	removeConventions,
+	// Convention resolution
+	resolvePluginConventions,
+} from "../services/conventions-manager.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -54,67 +54,67 @@ import {
 
 /** Create an isolated temp directory for test operations */
 async function createTempDir(): Promise<string> {
-  return mkdtemp(join(tmpdir(), 'conventions-integ-'));
+	return mkdtemp(join(tmpdir(), "conventions-integ-"));
 }
 
 /** Create a mock plugin directory with plugin.json and optional template */
 async function createMockPlugin(
-  baseDir: string,
-  pluginName: string,
-  opts: {
-    gitignoreProject?: string[];
-    gitignoreGlobal?: string[];
-    claudemdSection?: string;
-    claudemdVersion?: string;
-    templateContent?: string;
-  },
+	baseDir: string,
+	pluginName: string,
+	opts: {
+		gitignoreProject?: string[];
+		gitignoreGlobal?: string[];
+		claudemdSection?: string;
+		claudemdVersion?: string;
+		templateContent?: string;
+	},
 ): Promise<string> {
-  const pluginDir = join(baseDir, pluginName);
-  await mkdir(pluginDir, { recursive: true });
-
-  const manifest: Record<string, unknown> = {
-    name: pluginName,
-    version: '1.0.0',
-    description: `Test plugin ${pluginName}`,
-  };
-
-  const conventions: Record<string, unknown> = {};
-
-  if (opts.gitignoreProject || opts.gitignoreGlobal) {
-    const gitignore: Record<string, string[]> = {};
-    if (opts.gitignoreProject) gitignore.project = opts.gitignoreProject;
-    if (opts.gitignoreGlobal) gitignore.global = opts.gitignoreGlobal;
-    conventions.gitignore = gitignore;
-  }
-
-  if (opts.claudemdSection && opts.claudemdVersion && opts.templateContent) {
-    conventions.claudemd = {
-      section: opts.claudemdSection,
-      template: './templates/claude-md-conventions.md',
-      version: opts.claudemdVersion,
-    };
-
-    // Create the template file
-    const templateDir = join(pluginDir, 'templates');
-    await mkdir(templateDir, { recursive: true });
-    await writeFile(
-      join(templateDir, 'claude-md-conventions.md'),
-      opts.templateContent,
-      'utf-8',
-    );
-  }
-
-  if (Object.keys(conventions).length > 0) {
-    manifest.conventions = conventions;
-  }
-
-  await writeFile(
-    join(pluginDir, 'plugin.json'),
-    JSON.stringify(manifest, null, 2),
-    'utf-8',
-  );
-
-  return pluginDir;
+	const pluginDir = join(baseDir, pluginName);
+	await mkdir(pluginDir, { recursive: true });
+
+	const manifest: Record<string, unknown> = {
+		name: pluginName,
+		version: "1.0.0",
+		description: `Test plugin ${pluginName}`,
+	};
+
+	const conventions: Record<string, unknown> = {};
+
+	if (opts.gitignoreProject || opts.gitignoreGlobal) {
+		const gitignore: Record<string, string[]> = {};
+		if (opts.gitignoreProject) gitignore.project = opts.gitignoreProject;
+		if (opts.gitignoreGlobal) gitignore.global = opts.gitignoreGlobal;
+		conventions.gitignore = gitignore;
+	}
+
+	if (opts.claudemdSection && opts.claudemdVersion && opts.templateContent) {
+		conventions.claudemd = {
+			section: opts.claudemdSection,
+			template: "./templates/claude-md-conventions.md",
+			version: opts.claudemdVersion,
+		};
+
+		// Create the template file
+		const templateDir = join(pluginDir, "templates");
+		await mkdir(templateDir, { recursive: true });
+		await writeFile(
+			join(templateDir, "claude-md-conventions.md"),
+			opts.templateContent,
+			"utf-8",
+		);
+	}
+
+	if (Object.keys(conventions).length > 0) {
+		manifest.conventions = conventions;
+	}
+
+	await writeFile(
+		join(pluginDir, "plugin.json"),
+		JSON.stringify(manifest, null, 2),
+		"utf-8",
+	);
+
+	return pluginDir;
 }
 
 /**
@@ -123,623 +123,708 @@ async function createMockPlugin(
  * has a bug (see IMPLEMENTATION ISSUES above).
  */
 async function applyConventionsManually(
-  pluginDir: string,
-  projectDir: string,
+	pluginDir: string,
+	projectDir: string,
 ): Promise<{
-  gitignore: { added: string[]; modified: boolean };
-  claudemd: { action: string; section?: string };
+	gitignore: { added: string[]; modified: boolean };
+	claudemd: { action: string; section?: string };
 }> {
-  const conventions = await resolvePluginConventions(pluginDir);
-  if (!conventions) {
-    return { gitignore: { added: [], modified: false }, claudemd: { action: 'skipped' } };
-  }
-
-  let gitignoreResult = { added: [] as string[], modified: false };
-  if (conventions.gitignore?.project && conventions.gitignore.project.length > 0) {
-    const gitignorePath = join(projectDir, '.gitignore');
-    gitignoreResult = await ensureGitignoreEntries(gitignorePath, conventions.gitignore.project);
-  }
-
-  let claudemdResult: { action: string; section?: string } = { action: 'skipped' };
-  if (conventions.claudemd) {
-    const claudeMdPath = join(projectDir, 'CLAUDE.md');
-    const template = await readConventionTemplate(pluginDir, conventions.claudemd.template);
-    const injectResult = await injectClaudeMdSection(
-      claudeMdPath,
-      conventions.claudemd.section,
-      conventions.claudemd.version,
-      template,
-    );
-    claudemdResult = { action: injectResult.action, section: conventions.claudemd.section };
-  }
-
-  return { gitignore: gitignoreResult, claudemd: claudemdResult };
+	const conventions = await resolvePluginConventions(pluginDir);
+	if (!conventions) {
+		return {
+			gitignore: { added: [], modified: false },
+			claudemd: { action: "skipped" },
+		};
+	}
+
+	let gitignoreResult = { added: [] as string[], modified: false };
+	if (
+		conventions.gitignore?.project &&
+		conventions.gitignore.project.length > 0
+	) {
+		const gitignorePath = join(projectDir, ".gitignore");
+		gitignoreResult = await ensureGitignoreEntries(
+			gitignorePath,
+			conventions.gitignore.project,
+		);
+	}
+
+	let claudemdResult: { action: string; section?: string } = {
+		action: "skipped",
+	};
+	if (conventions.claudemd) {
+		const claudeMdPath = join(projectDir, "CLAUDE.md");
+		const template = await readConventionTemplate(
+			pluginDir,
+			conventions.claudemd.template,
+		);
+		const injectResult = await injectClaudeMdSection(
+			claudeMdPath,
+			conventions.claudemd.section,
+			conventions.claudemd.version,
+			template,
+		);
+		claudemdResult = {
+			action: injectResult.action,
+			section: conventions.claudemd.section,
+		};
+	}
+
+	return { gitignore: gitignoreResult, claudemd: claudemdResult };
 }
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('Convention System Integration', () => {
-  let tempDir: string;
-  let projectDir: string;
-
-  beforeEach(async () => {
-    tempDir = await createTempDir();
-    projectDir = join(tempDir, 'project');
-    await mkdir(projectDir, { recursive: true });
-  });
-
-  afterEach(async () => {
-    if (existsSync(tempDir)) {
-      await rm(tempDir, { recursive: true, force: true });
-    }
-  });
-
-  // =========================================================================
-  // Category 1: End-to-End Convention Lifecycle
-  // =========================================================================
-
-  describe('End-to-End Convention Lifecycle', () => {
-    it('TEST-1: install plugin with conventions updates .gitignore', async () => {
-      const pluginDir = await createMockPlugin(tempDir, 'test-plugin', {
-        gitignoreProject: ['.mnemex/', '.claude/sessions/'],
-        claudemdSection: 'test-plugin',
-        claudemdVersion: '1.0.0',
-        templateContent: '## Test Plugin\n\nSome conventions here.\n',
-      });
-
-      const result = await applyConventionsManually(pluginDir, projectDir);
-
-      // Gitignore should have been modified
-      expect(result.gitignore.modified).toBe(true);
-      expect(result.gitignore.added).toContain('.mnemex/');
-      expect(result.gitignore.added).toContain('.claude/sessions/');
-
-      // Verify file on disk
-      const gitignorePath = join(projectDir, '.gitignore');
-      expect(existsSync(gitignorePath)).toBe(true);
-      const gitignoreContent = await readFile(gitignorePath, 'utf-8');
-      expect(gitignoreContent).toContain('.mnemex/');
-      expect(gitignoreContent).toContain('.claude/sessions/');
-    });
-
-    it('TEST-2: install plugin with conventions injects CLAUDE.md section', async () => {
-      const pluginDir = await createMockPlugin(tempDir, 'test-plugin', {
-        gitignoreProject: ['.mnemex/'],
-        claudemdSection: 'test-plugin',
-        claudemdVersion: '1.0.0',
-        templateContent: '## Test Plugin Conventions\n\nDo not commit `.mnemex/`.\n',
-      });
-
-      const result = await applyConventionsManually(pluginDir, projectDir);
-
-      // CLAUDE.md should have been injected
-      expect(result.claudemd.action).toBe('inserted');
-
-      // Verify file on disk
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-      expect(existsSync(claudeMdPath)).toBe(true);
-      const claudeMdContent = await readFile(claudeMdPath, 'utf-8');
-      expect(claudeMdContent).toContain('<!-- BEGIN magus:test-plugin v1.0.0 -->');
-      expect(claudeMdContent).toContain('<!-- END magus:test-plugin -->');
-      expect(claudeMdContent).toContain('Test Plugin Conventions');
-      expect(claudeMdContent).toContain('Do not commit `.mnemex/`.');
-    });
-
-    it('TEST-3: uninstall removes CLAUDE.md section but keeps gitignore entries', async () => {
-      const pluginDir = await createMockPlugin(tempDir, 'test-plugin', {
-        gitignoreProject: ['.mnemex/', '.claude/sessions/'],
-        claudemdSection: 'test-plugin',
-        claudemdVersion: '1.0.0',
-        templateContent: '## Test Plugin Conventions\n\nContent here.\n',
-      });
-
-      // Apply conventions manually (since applyConventions has a bug)
-      await applyConventionsManually(pluginDir, projectDir);
-
-      // Verify both files exist
-      const gitignorePath = join(projectDir, '.gitignore');
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-      expect(existsSync(gitignorePath)).toBe(true);
-      expect(existsSync(claudeMdPath)).toBe(true);
-
-      // Remove CLAUDE.md section directly (removeConventions has same bug as applyConventions)
-      const removeResult = await removeClaudeMdSection(claudeMdPath, 'test-plugin');
-      expect(removeResult.removed).toBe(true);
-
-      // CLAUDE.md section should be gone
-      const claudeMdContent = await readFile(claudeMdPath, 'utf-8');
-      expect(claudeMdContent).not.toContain('<!-- BEGIN magus:test-plugin');
-      expect(claudeMdContent).not.toContain('<!-- END magus:test-plugin -->');
-      expect(claudeMdContent).not.toContain('Test Plugin Conventions');
-
-      // .gitignore entries MUST still be present (by design)
-      const gitignoreContent = await readFile(gitignorePath, 'utf-8');
-      expect(gitignoreContent).toContain('.mnemex/');
-      expect(gitignoreContent).toContain('.claude/sessions/');
-    });
-  });
-
-  // =========================================================================
-  // Category 2: Idempotency
-  // =========================================================================
-
-  describe('Idempotency', () => {
-    it('TEST-4: applying conventions twice produces identical result', async () => {
-      const pluginDir = await createMockPlugin(tempDir, 'test-plugin', {
-        gitignoreProject: ['.mnemex/'],
-        claudemdSection: 'test-plugin',
-        claudemdVersion: '1.0.0',
-        templateContent: '## Test Conventions\n\nContent.\n',
-      });
-
-      // First apply (using manual helper)
-      const result1 = await applyConventionsManually(pluginDir, projectDir);
-      expect(result1.gitignore.modified).toBe(true);
-      expect(result1.claudemd.action).toBe('inserted');
-
-      // Snapshot file contents after first apply
-      const gitignorePath = join(projectDir, '.gitignore');
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-      const gitignoreAfterFirst = await readFile(gitignorePath, 'utf-8');
-      const claudeMdAfterFirst = await readFile(claudeMdPath, 'utf-8');
-
-      // Second apply
-      const result2 = await applyConventionsManually(pluginDir, projectDir);
-      expect(result2.gitignore.modified).toBe(false);
-      expect(result2.claudemd.action).toBe('unchanged');
-
-      // File contents must be identical
-      const gitignoreAfterSecond = await readFile(gitignorePath, 'utf-8');
-      const claudeMdAfterSecond = await readFile(claudeMdPath, 'utf-8');
-      expect(gitignoreAfterSecond).toBe(gitignoreAfterFirst);
-      expect(claudeMdAfterSecond).toBe(claudeMdAfterFirst);
-    });
-
-    it('TEST-5: ensureGitignoreEntries is idempotent', async () => {
-      const gitignorePath = join(projectDir, '.gitignore');
-
-      // First call
-      const result1 = await ensureGitignoreEntries(gitignorePath, ['.mnemex/', '.claudemem/']);
-      expect(result1.modified).toBe(true);
-      expect(result1.added.length).toBe(2);
-
-      const contentAfterFirst = await readFile(gitignorePath, 'utf-8');
-
-      // Second call with same entries
-      const result2 = await ensureGitignoreEntries(gitignorePath, ['.mnemex/', '.claudemem/']);
-      expect(result2.modified).toBe(false);
-      expect(result2.added.length).toBe(0);
-
-      const contentAfterSecond = await readFile(gitignorePath, 'utf-8');
-      expect(contentAfterSecond).toBe(contentAfterFirst);
-    });
-
-    it('TEST-6: injectClaudeMdSection with same version is idempotent', async () => {
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-      const content = '## Test Section\n\nSome content.\n';
-
-      // First inject
-      const result1 = await injectClaudeMdSection(claudeMdPath, 'test-plugin', '1.0.0', content);
-      expect(result1.action).toBe('inserted');
-
-      // Second inject with same version and content
-      const result2 = await injectClaudeMdSection(claudeMdPath, 'test-plugin', '1.0.0', content);
-      expect(result2.action).toBe('unchanged');
-    });
-  });
-
-  // =========================================================================
-  // Category 3: Version Upgrade
-  // =========================================================================
-
-  describe('Version Upgrade', () => {
-    it('TEST-7: applying v2.0.0 over v1.0.0 updates CLAUDE.md content', async () => {
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-      const v1Content = '## V1 Content\n\nOriginal version.\n';
-      const v2Content = '## V2 Content\n\nUpdated version with new features.\n';
-
-      // Inject v1
-      const result1 = await injectClaudeMdSection(claudeMdPath, 'test-plugin', '1.0.0', v1Content);
-      expect(result1.action).toBe('inserted');
-
-      // Inject v2
-      const result2 = await injectClaudeMdSection(claudeMdPath, 'test-plugin', '2.0.0', v2Content);
-      expect(result2.action).toBe('updated');
-      expect(result2.previousVersion).toBe('1.0.0');
-    });
-
-    it('TEST-8: version marker is updated in BEGIN tag after upgrade', async () => {
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-      const v1Content = '## V1 Content\n\nOriginal.\n';
-      const v2Content = '## V2 Content\n\nNew stuff.\n';
-
-      await injectClaudeMdSection(claudeMdPath, 'test-plugin', '1.0.0', v1Content);
-      await injectClaudeMdSection(claudeMdPath, 'test-plugin', '2.0.0', v2Content);
-
-      const fileContent = await readFile(claudeMdPath, 'utf-8');
-
-      // Should have v2 marker, not v1
-      expect(fileContent).toContain('<!-- BEGIN magus:test-plugin v2.0.0 -->');
-      expect(fileContent).not.toContain('<!-- BEGIN magus:test-plugin v1.0.0 -->');
-
-      // Should have v2 content, not v1
-      expect(fileContent).toContain('V2 Content');
-      expect(fileContent).toContain('New stuff.');
-      expect(fileContent).not.toContain('V1 Content');
-      expect(fileContent).not.toContain('Original.');
-    });
-  });
-
-  // =========================================================================
-  // Category 4: Multiple Plugins
-  // =========================================================================
-
-  describe('Multiple Plugins', () => {
-    it('TEST-9: two plugins can coexist in CLAUDE.md', async () => {
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-
-      const contentA = '## Plugin A Conventions\n\nPlugin A content.\n';
-      const contentB = '## Plugin B Conventions\n\nPlugin B content.\n';
-
-      await injectClaudeMdSection(claudeMdPath, 'plugin-a', '1.0.0', contentA);
-      await injectClaudeMdSection(claudeMdPath, 'plugin-b', '1.0.0', contentB);
-
-      const fileContent = await readFile(claudeMdPath, 'utf-8');
-
-      // Both sections present
-      expect(fileContent).toContain('<!-- BEGIN magus:plugin-a v1.0.0 -->');
-      expect(fileContent).toContain('<!-- END magus:plugin-a -->');
-      expect(fileContent).toContain('Plugin A content.');
-
-      expect(fileContent).toContain('<!-- BEGIN magus:plugin-b v1.0.0 -->');
-      expect(fileContent).toContain('<!-- END magus:plugin-b -->');
-      expect(fileContent).toContain('Plugin B content.');
-
-      // List should show both
-      const sections = await listClaudeMdSections(claudeMdPath);
-      expect(sections.length).toBe(2);
-      const sectionNames = sections.map((s) => s.section);
-      expect(sectionNames).toContain('plugin-a');
-      expect(sectionNames).toContain('plugin-b');
-    });
-
-    it('TEST-10: removing one plugin leaves the other intact', async () => {
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-
-      const contentA = '## Plugin A Conventions\n\nPlugin A content.\n';
-      const contentB = '## Plugin B Conventions\n\nPlugin B content.\n';
-
-      await injectClaudeMdSection(claudeMdPath, 'plugin-a', '1.0.0', contentA);
-      await injectClaudeMdSection(claudeMdPath, 'plugin-b', '1.0.0', contentB);
-
-      // Remove plugin-a
-      const removeResult = await removeClaudeMdSection(claudeMdPath, 'plugin-a');
-      expect(removeResult.removed).toBe(true);
-
-      const fileContent = await readFile(claudeMdPath, 'utf-8');
-
-      // Plugin A should be gone
-      expect(fileContent).not.toContain('<!-- BEGIN magus:plugin-a');
-      expect(fileContent).not.toContain('Plugin A content.');
-
-      // Plugin B should still be there
-      expect(fileContent).toContain('<!-- BEGIN magus:plugin-b v1.0.0 -->');
-      expect(fileContent).toContain('<!-- END magus:plugin-b -->');
-      expect(fileContent).toContain('Plugin B content.');
-    });
-
-    it('TEST-11: two plugins with different gitignore entries both present', async () => {
-      const gitignorePath = join(projectDir, '.gitignore');
-
-      await ensureGitignoreEntries(gitignorePath, ['.mnemex/'], '# Plugin A');
-      await ensureGitignoreEntries(gitignorePath, ['.claudemem/'], '# Plugin B');
-
-      const content = await readFile(gitignorePath, 'utf-8');
-      expect(content).toContain('.mnemex/');
-      expect(content).toContain('.claudemem/');
-
-      // No duplicates -- adding same entries again should not duplicate
-      await ensureGitignoreEntries(gitignorePath, ['.mnemex/']);
-      const contentAfter = await readFile(gitignorePath, 'utf-8');
-      const mnemexOccurrences = contentAfter.split('.mnemex/').length - 1;
-      expect(mnemexOccurrences).toBe(1);
-    });
-  });
-
-  // =========================================================================
-  // Category 5: Doctor Detection
-  // =========================================================================
-
-  describe('Doctor Detection', () => {
-    // Note: checkGitignoreEntries returns { present: string[], missing: string[] }
-    // instead of string[] as documented in the architecture. This is an
-    // IMPLEMENTATION_ISSUE (API deviation), but the richer return type is a
-    // superset. Tests use .missing property to access the missing entries.
-
-    it('TEST-12: checkGitignoreEntries detects missing entries', async () => {
-      const gitignorePath = join(projectDir, '.gitignore');
-      // Create gitignore with only one entry
-      await writeFile(gitignorePath, '.mnemex/\n', 'utf-8');
-
-      const result = await checkGitignoreEntries(gitignorePath, [
-        '.mnemex/',
-        '.claudemem/',
-        '.claude/sessions/',
-      ]);
-
-      // API returns { present, missing } object instead of string[] per contract
-      const resultObj = result as unknown as { present: string[]; missing: string[] };
-
-      expect(resultObj.missing).toContain('.claudemem/');
-      expect(resultObj.missing).toContain('.claude/sessions/');
-      expect(resultObj.missing).not.toContain('.mnemex/');
-      expect(resultObj.missing.length).toBe(2);
-
-      // Also verify present entries
-      expect(resultObj.present).toContain('.mnemex/');
-      expect(resultObj.present.length).toBe(1);
-    });
-
-    it('TEST-13: missing CLAUDE.md section is detectable via listClaudeMdSections', async () => {
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-      // Create CLAUDE.md with existing content but no managed sections
-      await writeFile(claudeMdPath, '# Project CLAUDE.md\n\nSome existing content.\n', 'utf-8');
-
-      const sections = await listClaudeMdSections(claudeMdPath);
-      expect(sections.length).toBe(0);
-    });
-
-    it('TEST-14: ensureGitignoreEntries fixes missing entries detected by check', async () => {
-      const gitignorePath = join(projectDir, '.gitignore');
-      await writeFile(gitignorePath, '.mnemex/\n', 'utf-8');
-
-      // Detect missing using the actual return type
-      const checkResult = await checkGitignoreEntries(gitignorePath, [
-        '.mnemex/',
-        '.claudemem/',
-        '.claude/sessions/',
-      ]);
-      const missing = (checkResult as unknown as { missing: string[] }).missing;
-      expect(missing.length).toBe(2);
-
-      // Fix by adding missing entries
-      const fixResult = await ensureGitignoreEntries(gitignorePath, missing);
-      expect(fixResult.modified).toBe(true);
-      expect(fixResult.added.length).toBe(2);
-
-      // Re-check: should now all be present
-      const recheck = await checkGitignoreEntries(gitignorePath, [
-        '.mnemex/',
-        '.claudemem/',
-        '.claude/sessions/',
-      ]);
-      const stillMissing = (recheck as unknown as { missing: string[] }).missing;
-      expect(stillMissing.length).toBe(0);
-    });
-  });
-
-  // =========================================================================
-  // Category 6: Malformed CLAUDE.md Handling
-  // =========================================================================
-
-  describe('Malformed CLAUDE.md Handling', () => {
-    it('TEST-15: inject refuses when CLAUDE.md has missing END marker', async () => {
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-      // Write a malformed file: BEGIN without END
-      const malformedContent = [
-        '# Project Notes',
-        '',
-        '<!-- BEGIN magus:broken-plugin v1.0.0 -->',
-        '## Broken Plugin',
-        '',
-        'This section has no END marker.',
-        '',
-        '# More content below',
-        '',
-      ].join('\n');
-      await writeFile(claudeMdPath, malformedContent, 'utf-8');
-
-      // Attempting to inject a NEW section should be refused
-      const result = await injectClaudeMdSection(
-        claudeMdPath,
-        'new-plugin',
-        '1.0.0',
-        '## New Plugin\n\nContent.\n',
-      );
-      expect(result.action).toBe('error');
-      expect(result.error).toBeDefined();
-      expect(typeof result.error).toBe('string');
-    });
-
-    it('TEST-16: parse detects duplicate sections', async () => {
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-      const duplicateContent = [
-        '# Project',
-        '',
-        '<!-- BEGIN magus:test-plugin v1.0.0 -->',
-        '## First instance',
-        '<!-- END magus:test-plugin -->',
-        '',
-        '<!-- BEGIN magus:test-plugin v1.0.0 -->',
-        '## Second instance (duplicate!)',
-        '<!-- END magus:test-plugin -->',
-        '',
-      ].join('\n');
-      await writeFile(claudeMdPath, duplicateContent, 'utf-8');
-
-      const parseResult: ParseResult = await parseClaudeMdSections(claudeMdPath);
-      expect(parseResult.errors.length).toBeGreaterThan(0);
-
-      const duplicateError = parseResult.errors.find(
-        (e) => e.type === 'duplicate_section',
-      );
-      expect(duplicateError).toBeDefined();
-      if (duplicateError) {
-        expect(duplicateError.section).toBe('test-plugin');
-      }
-    });
-
-    it('TEST-17: parse ignores markers inside code blocks', async () => {
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-      const contentWithCodeBlock = [
-        '# Documentation',
-        '',
-        'Here is an example of markers:',
-        '',
-        '```markdown',
-        '<!-- BEGIN magus:example v1.0.0 -->',
-        '## Example section',
-        '<!-- END magus:example -->',
-        '```',
-        '',
-        'The above markers are inside a code block and should be ignored.',
-        '',
-      ].join('\n');
-      await writeFile(claudeMdPath, contentWithCodeBlock, 'utf-8');
-
-      const parseResult = await parseClaudeMdSections(claudeMdPath);
-
-      // Markers inside code blocks should NOT be treated as real sections
-      const realSections = parseResult.sections.filter(
-        (s) => !s.insideCodeBlock,
-      );
-      expect(realSections.length).toBe(0);
-
-      // If the parser reports code-block markers, check the error type
-      if (parseResult.errors.length > 0) {
-        const codeBlockErrors = parseResult.errors.filter(
-          (e) => e.type === 'marker_in_code_block',
-        );
-        // It's valid for the parser to either:
-        // 1. Report marker_in_code_block errors, OR
-        // 2. Simply ignore them (no sections, no errors)
-        // Both behaviors comply with the architecture spec.
-        if (codeBlockErrors.length > 0) {
-          expect(codeBlockErrors[0].section).toBe('example');
-        }
-      }
-    });
-  });
-
-  // =========================================================================
-  // Category 7: Path Classification (Gitignore Entries)
-  // =========================================================================
-
-  describe('Path Classification', () => {
-    it('TEST-18: all standard private paths can be added to gitignore', async () => {
-      const gitignorePath = join(projectDir, '.gitignore');
-      const privatePaths = [
-        '.mnemex/',
-        '.claudemem/',
-        '.claude/sessions/',
-        '.claude/worktrees/',
-      ];
-
-      const result = await ensureGitignoreEntries(
-        gitignorePath,
-        privatePaths,
-        '# Claude Code ephemeral/machine-specific data',
-      );
-
-      expect(result.modified).toBe(true);
-      expect(result.added.length).toBe(4);
-
-      const content = await readFile(gitignorePath, 'utf-8');
-      for (const path of privatePaths) {
-        expect(content).toContain(path);
-      }
-    });
-
-    it('TEST-19: checkGitignoreEntries reports correct missing set', async () => {
-      const gitignorePath = join(projectDir, '.gitignore');
-      // Only .mnemex/ exists
-      await writeFile(gitignorePath, '.mnemex/\n', 'utf-8');
-
-      const allPaths = [
-        '.mnemex/',
-        '.claudemem/',
-        '.claude/sessions/',
-        '.claude/worktrees/',
-      ];
-
-      const result = await checkGitignoreEntries(gitignorePath, allPaths);
-      // API returns { present, missing } instead of string[] (see IMPLEMENTATION_ISSUE note)
-      const resultObj = result as unknown as { present: string[]; missing: string[] };
-
-      expect(resultObj.missing.length).toBe(3);
-      expect(resultObj.missing).toContain('.claudemem/');
-      expect(resultObj.missing).toContain('.claude/sessions/');
-      expect(resultObj.missing).toContain('.claude/worktrees/');
-      expect(resultObj.missing).not.toContain('.mnemex/');
-    });
-
-    it('TEST-20: gitignore entries survive plugin uninstall', async () => {
-      const pluginDir = await createMockPlugin(tempDir, 'test-plugin', {
-        gitignoreProject: ['.mnemex/', '.claude/sessions/'],
-        claudemdSection: 'test-plugin',
-        claudemdVersion: '1.0.0',
-        templateContent: '## Test\n\nContent.\n',
-      });
-
-      // Apply conventions manually (since applyConventions has a bug)
-      await applyConventionsManually(pluginDir, projectDir);
-
-      const gitignorePath = join(projectDir, '.gitignore');
-      const gitignoreBefore = await readFile(gitignorePath, 'utf-8');
-      expect(gitignoreBefore).toContain('.mnemex/');
-      expect(gitignoreBefore).toContain('.claude/sessions/');
-
-      // Remove conventions via public API
-      await removeConventions('test-plugin', projectDir);
-
-      // Gitignore entries MUST still be there (by design)
-      const gitignoreAfter = await readFile(gitignorePath, 'utf-8');
-      expect(gitignoreAfter).toContain('.mnemex/');
-      expect(gitignoreAfter).toContain('.claude/sessions/');
-    });
-  });
-
-  // =========================================================================
-  // IMPLEMENTATION_ISSUE: applyConventions() regression tests
-  // These tests SHOULD pass when the bug in applyConventions() is fixed.
-  // They currently fail because applyConventions() silently skips all work.
-  // =========================================================================
-
-  describe('applyConventions orchestration (IMPLEMENTATION_ISSUE)', () => {
-    it('TEST-1-A: applyConventions should apply gitignore entries', async () => {
-      const pluginDir = await createMockPlugin(tempDir, 'apply-test', {
-        gitignoreProject: ['.mnemex/', '.claude/sessions/'],
-        claudemdSection: 'apply-test',
-        claudemdVersion: '1.0.0',
-        templateContent: '## Test Plugin\n\nConventions.\n',
-      });
-
-      const result = await applyConventions(pluginDir, projectDir);
-      expect(result.gitignore.modified).toBe(true);
-      expect(result.gitignore.added).toContain('.mnemex/');
-    });
-
-    it('TEST-2-A: applyConventions should inject CLAUDE.md section', async () => {
-      const pluginDir = await createMockPlugin(tempDir, 'apply-test', {
-        claudemdSection: 'apply-test',
-        claudemdVersion: '1.0.0',
-        templateContent: '## Test Plugin\n\nConventions.\n',
-      });
-
-      const result = await applyConventions(pluginDir, projectDir);
-      expect(result.claudemd.action).toBe('inserted');
-    });
-
-    it('TEST-3-A: removeConventions should remove CLAUDE.md section', async () => {
-      // First create a CLAUDE.md with a section using the working low-level API
-      const claudeMdPath = join(projectDir, 'CLAUDE.md');
-      await injectClaudeMdSection(claudeMdPath, 'test-plugin', '1.0.0', '## Test\n\nContent.\n');
-
-      // removeConventions should find and remove the section
-      const result = await removeConventions('test-plugin', projectDir);
-      expect(result.claudemd.removed).toBe(true);
-    });
-  });
+describe("Convention System Integration", () => {
+	let tempDir: string;
+	let projectDir: string;
+
+	beforeEach(async () => {
+		tempDir = await createTempDir();
+		projectDir = join(tempDir, "project");
+		await mkdir(projectDir, { recursive: true });
+	});
+
+	afterEach(async () => {
+		if (existsSync(tempDir)) {
+			await rm(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	// =========================================================================
+	// Category 1: End-to-End Convention Lifecycle
+	// =========================================================================
+
+	describe("End-to-End Convention Lifecycle", () => {
+		it("TEST-1: install plugin with conventions updates .gitignore", async () => {
+			const pluginDir = await createMockPlugin(tempDir, "test-plugin", {
+				gitignoreProject: [".mnemex/", ".claude/sessions/"],
+				claudemdSection: "test-plugin",
+				claudemdVersion: "1.0.0",
+				templateContent: "## Test Plugin\n\nSome conventions here.\n",
+			});
+
+			const result = await applyConventionsManually(pluginDir, projectDir);
+
+			// Gitignore should have been modified
+			expect(result.gitignore.modified).toBe(true);
+			expect(result.gitignore.added).toContain(".mnemex/");
+			expect(result.gitignore.added).toContain(".claude/sessions/");
+
+			// Verify file on disk
+			const gitignorePath = join(projectDir, ".gitignore");
+			expect(existsSync(gitignorePath)).toBe(true);
+			const gitignoreContent = await readFile(gitignorePath, "utf-8");
+			expect(gitignoreContent).toContain(".mnemex/");
+			expect(gitignoreContent).toContain(".claude/sessions/");
+		});
+
+		it("TEST-2: install plugin with conventions injects CLAUDE.md section", async () => {
+			const pluginDir = await createMockPlugin(tempDir, "test-plugin", {
+				gitignoreProject: [".mnemex/"],
+				claudemdSection: "test-plugin",
+				claudemdVersion: "1.0.0",
+				templateContent:
+					"## Test Plugin Conventions\n\nDo not commit `.mnemex/`.\n",
+			});
+
+			const result = await applyConventionsManually(pluginDir, projectDir);
+
+			// CLAUDE.md should have been injected
+			expect(result.claudemd.action).toBe("inserted");
+
+			// Verify file on disk
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+			expect(existsSync(claudeMdPath)).toBe(true);
+			const claudeMdContent = await readFile(claudeMdPath, "utf-8");
+			expect(claudeMdContent).toContain(
+				"<!-- BEGIN magus:test-plugin v1.0.0 -->",
+			);
+			expect(claudeMdContent).toContain("<!-- END magus:test-plugin -->");
+			expect(claudeMdContent).toContain("Test Plugin Conventions");
+			expect(claudeMdContent).toContain("Do not commit `.mnemex/`.");
+		});
+
+		it("TEST-3: uninstall removes CLAUDE.md section but keeps gitignore entries", async () => {
+			const pluginDir = await createMockPlugin(tempDir, "test-plugin", {
+				gitignoreProject: [".mnemex/", ".claude/sessions/"],
+				claudemdSection: "test-plugin",
+				claudemdVersion: "1.0.0",
+				templateContent: "## Test Plugin Conventions\n\nContent here.\n",
+			});
+
+			// Apply conventions manually (since applyConventions has a bug)
+			await applyConventionsManually(pluginDir, projectDir);
+
+			// Verify both files exist
+			const gitignorePath = join(projectDir, ".gitignore");
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+			expect(existsSync(gitignorePath)).toBe(true);
+			expect(existsSync(claudeMdPath)).toBe(true);
+
+			// Remove CLAUDE.md section directly (removeConventions has same bug as applyConventions)
+			const removeResult = await removeClaudeMdSection(
+				claudeMdPath,
+				"test-plugin",
+			);
+			expect(removeResult.removed).toBe(true);
+
+			// CLAUDE.md section should be gone
+			const claudeMdContent = await readFile(claudeMdPath, "utf-8");
+			expect(claudeMdContent).not.toContain("<!-- BEGIN magus:test-plugin");
+			expect(claudeMdContent).not.toContain("<!-- END magus:test-plugin -->");
+			expect(claudeMdContent).not.toContain("Test Plugin Conventions");
+
+			// .gitignore entries MUST still be present (by design)
+			const gitignoreContent = await readFile(gitignorePath, "utf-8");
+			expect(gitignoreContent).toContain(".mnemex/");
+			expect(gitignoreContent).toContain(".claude/sessions/");
+		});
+	});
+
+	// =========================================================================
+	// Category 2: Idempotency
+	// =========================================================================
+
+	describe("Idempotency", () => {
+		it("TEST-4: applying conventions twice produces identical result", async () => {
+			const pluginDir = await createMockPlugin(tempDir, "test-plugin", {
+				gitignoreProject: [".mnemex/"],
+				claudemdSection: "test-plugin",
+				claudemdVersion: "1.0.0",
+				templateContent: "## Test Conventions\n\nContent.\n",
+			});
+
+			// First apply (using manual helper)
+			const result1 = await applyConventionsManually(pluginDir, projectDir);
+			expect(result1.gitignore.modified).toBe(true);
+			expect(result1.claudemd.action).toBe("inserted");
+
+			// Snapshot file contents after first apply
+			const gitignorePath = join(projectDir, ".gitignore");
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+			const gitignoreAfterFirst = await readFile(gitignorePath, "utf-8");
+			const claudeMdAfterFirst = await readFile(claudeMdPath, "utf-8");
+
+			// Second apply
+			const result2 = await applyConventionsManually(pluginDir, projectDir);
+			expect(result2.gitignore.modified).toBe(false);
+			expect(result2.claudemd.action).toBe("unchanged");
+
+			// File contents must be identical
+			const gitignoreAfterSecond = await readFile(gitignorePath, "utf-8");
+			const claudeMdAfterSecond = await readFile(claudeMdPath, "utf-8");
+			expect(gitignoreAfterSecond).toBe(gitignoreAfterFirst);
+			expect(claudeMdAfterSecond).toBe(claudeMdAfterFirst);
+		});
+
+		it("TEST-5: ensureGitignoreEntries is idempotent", async () => {
+			const gitignorePath = join(projectDir, ".gitignore");
+
+			// First call
+			const result1 = await ensureGitignoreEntries(gitignorePath, [
+				".mnemex/",
+				".claudemem/",
+			]);
+			expect(result1.modified).toBe(true);
+			expect(result1.added.length).toBe(2);
+
+			const contentAfterFirst = await readFile(gitignorePath, "utf-8");
+
+			// Second call with same entries
+			const result2 = await ensureGitignoreEntries(gitignorePath, [
+				".mnemex/",
+				".claudemem/",
+			]);
+			expect(result2.modified).toBe(false);
+			expect(result2.added.length).toBe(0);
+
+			const contentAfterSecond = await readFile(gitignorePath, "utf-8");
+			expect(contentAfterSecond).toBe(contentAfterFirst);
+		});
+
+		it("TEST-6: injectClaudeMdSection with same version is idempotent", async () => {
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+			const content = "## Test Section\n\nSome content.\n";
+
+			// First inject
+			const result1 = await injectClaudeMdSection(
+				claudeMdPath,
+				"test-plugin",
+				"1.0.0",
+				content,
+			);
+			expect(result1.action).toBe("inserted");
+
+			// Second inject with same version and content
+			const result2 = await injectClaudeMdSection(
+				claudeMdPath,
+				"test-plugin",
+				"1.0.0",
+				content,
+			);
+			expect(result2.action).toBe("unchanged");
+		});
+	});
+
+	// =========================================================================
+	// Category 3: Version Upgrade
+	// =========================================================================
+
+	describe("Version Upgrade", () => {
+		it("TEST-7: applying v2.0.0 over v1.0.0 updates CLAUDE.md content", async () => {
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+			const v1Content = "## V1 Content\n\nOriginal version.\n";
+			const v2Content = "## V2 Content\n\nUpdated version with new features.\n";
+
+			// Inject v1
+			const result1 = await injectClaudeMdSection(
+				claudeMdPath,
+				"test-plugin",
+				"1.0.0",
+				v1Content,
+			);
+			expect(result1.action).toBe("inserted");
+
+			// Inject v2
+			const result2 = await injectClaudeMdSection(
+				claudeMdPath,
+				"test-plugin",
+				"2.0.0",
+				v2Content,
+			);
+			expect(result2.action).toBe("updated");
+			expect(result2.previousVersion).toBe("1.0.0");
+		});
+
+		it("TEST-8: version marker is updated in BEGIN tag after upgrade", async () => {
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+			const v1Content = "## V1 Content\n\nOriginal.\n";
+			const v2Content = "## V2 Content\n\nNew stuff.\n";
+
+			await injectClaudeMdSection(
+				claudeMdPath,
+				"test-plugin",
+				"1.0.0",
+				v1Content,
+			);
+			await injectClaudeMdSection(
+				claudeMdPath,
+				"test-plugin",
+				"2.0.0",
+				v2Content,
+			);
+
+			const fileContent = await readFile(claudeMdPath, "utf-8");
+
+			// Should have v2 marker, not v1
+			expect(fileContent).toContain("<!-- BEGIN magus:test-plugin v2.0.0 -->");
+			expect(fileContent).not.toContain(
+				"<!-- BEGIN magus:test-plugin v1.0.0 -->",
+			);
+
+			// Should have v2 content, not v1
+			expect(fileContent).toContain("V2 Content");
+			expect(fileContent).toContain("New stuff.");
+			expect(fileContent).not.toContain("V1 Content");
+			expect(fileContent).not.toContain("Original.");
+		});
+	});
+
+	// =========================================================================
+	// Category 4: Multiple Plugins
+	// =========================================================================
+
+	describe("Multiple Plugins", () => {
+		it("TEST-9: two plugins can coexist in CLAUDE.md", async () => {
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+
+			const contentA = "## Plugin A Conventions\n\nPlugin A content.\n";
+			const contentB = "## Plugin B Conventions\n\nPlugin B content.\n";
+
+			await injectClaudeMdSection(claudeMdPath, "plugin-a", "1.0.0", contentA);
+			await injectClaudeMdSection(claudeMdPath, "plugin-b", "1.0.0", contentB);
+
+			const fileContent = await readFile(claudeMdPath, "utf-8");
+
+			// Both sections present
+			expect(fileContent).toContain("<!-- BEGIN magus:plugin-a v1.0.0 -->");
+			expect(fileContent).toContain("<!-- END magus:plugin-a -->");
+			expect(fileContent).toContain("Plugin A content.");
+
+			expect(fileContent).toContain("<!-- BEGIN magus:plugin-b v1.0.0 -->");
+			expect(fileContent).toContain("<!-- END magus:plugin-b -->");
+			expect(fileContent).toContain("Plugin B content.");
+
+			// List should show both
+			const sections = await listClaudeMdSections(claudeMdPath);
+			expect(sections.length).toBe(2);
+			const sectionNames = sections.map((s) => s.section);
+			expect(sectionNames).toContain("plugin-a");
+			expect(sectionNames).toContain("plugin-b");
+		});
+
+		it("TEST-10: removing one plugin leaves the other intact", async () => {
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+
+			const contentA = "## Plugin A Conventions\n\nPlugin A content.\n";
+			const contentB = "## Plugin B Conventions\n\nPlugin B content.\n";
+
+			await injectClaudeMdSection(claudeMdPath, "plugin-a", "1.0.0", contentA);
+			await injectClaudeMdSection(claudeMdPath, "plugin-b", "1.0.0", contentB);
+
+			// Remove plugin-a
+			const removeResult = await removeClaudeMdSection(
+				claudeMdPath,
+				"plugin-a",
+			);
+			expect(removeResult.removed).toBe(true);
+
+			const fileContent = await readFile(claudeMdPath, "utf-8");
+
+			// Plugin A should be gone
+			expect(fileContent).not.toContain("<!-- BEGIN magus:plugin-a");
+			expect(fileContent).not.toContain("Plugin A content.");
+
+			// Plugin B should still be there
+			expect(fileContent).toContain("<!-- BEGIN magus:plugin-b v1.0.0 -->");
+			expect(fileContent).toContain("<!-- END magus:plugin-b -->");
+			expect(fileContent).toContain("Plugin B content.");
+		});
+
+		it("TEST-11: two plugins with different gitignore entries both present", async () => {
+			const gitignorePath = join(projectDir, ".gitignore");
+
+			await ensureGitignoreEntries(gitignorePath, [".mnemex/"], "# Plugin A");
+			await ensureGitignoreEntries(
+				gitignorePath,
+				[".claudemem/"],
+				"# Plugin B",
+			);
+
+			const content = await readFile(gitignorePath, "utf-8");
+			expect(content).toContain(".mnemex/");
+			expect(content).toContain(".claudemem/");
+
+			// No duplicates -- adding same entries again should not duplicate
+			await ensureGitignoreEntries(gitignorePath, [".mnemex/"]);
+			const contentAfter = await readFile(gitignorePath, "utf-8");
+			const mnemexOccurrences = contentAfter.split(".mnemex/").length - 1;
+			expect(mnemexOccurrences).toBe(1);
+		});
+	});
+
+	// =========================================================================
+	// Category 5: Doctor Detection
+	// =========================================================================
+
+	describe("Doctor Detection", () => {
+		// Note: checkGitignoreEntries returns { present: string[], missing: string[] }
+		// instead of string[] as documented in the architecture. This is an
+		// IMPLEMENTATION_ISSUE (API deviation), but the richer return type is a
+		// superset. Tests use .missing property to access the missing entries.
+
+		it("TEST-12: checkGitignoreEntries detects missing entries", async () => {
+			const gitignorePath = join(projectDir, ".gitignore");
+			// Create gitignore with only one entry
+			await writeFile(gitignorePath, ".mnemex/\n", "utf-8");
+
+			const result = await checkGitignoreEntries(gitignorePath, [
+				".mnemex/",
+				".claudemem/",
+				".claude/sessions/",
+			]);
+
+			// API returns { present, missing } object instead of string[] per contract
+			const resultObj = result as unknown as {
+				present: string[];
+				missing: string[];
+			};
+
+			expect(resultObj.missing).toContain(".claudemem/");
+			expect(resultObj.missing).toContain(".claude/sessions/");
+			expect(resultObj.missing).not.toContain(".mnemex/");
+			expect(resultObj.missing.length).toBe(2);
+
+			// Also verify present entries
+			expect(resultObj.present).toContain(".mnemex/");
+			expect(resultObj.present.length).toBe(1);
+		});
+
+		it("TEST-13: missing CLAUDE.md section is detectable via listClaudeMdSections", async () => {
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+			// Create CLAUDE.md with existing content but no managed sections
+			await writeFile(
+				claudeMdPath,
+				"# Project CLAUDE.md\n\nSome existing content.\n",
+				"utf-8",
+			);
+
+			const sections = await listClaudeMdSections(claudeMdPath);
+			expect(sections.length).toBe(0);
+		});
+
+		it("TEST-14: ensureGitignoreEntries fixes missing entries detected by check", async () => {
+			const gitignorePath = join(projectDir, ".gitignore");
+			await writeFile(gitignorePath, ".mnemex/\n", "utf-8");
+
+			// Detect missing using the actual return type
+			const checkResult = await checkGitignoreEntries(gitignorePath, [
+				".mnemex/",
+				".claudemem/",
+				".claude/sessions/",
+			]);
+			const missing = (checkResult as unknown as { missing: string[] }).missing;
+			expect(missing.length).toBe(2);
+
+			// Fix by adding missing entries
+			const fixResult = await ensureGitignoreEntries(gitignorePath, missing);
+			expect(fixResult.modified).toBe(true);
+			expect(fixResult.added.length).toBe(2);
+
+			// Re-check: should now all be present
+			const recheck = await checkGitignoreEntries(gitignorePath, [
+				".mnemex/",
+				".claudemem/",
+				".claude/sessions/",
+			]);
+			const stillMissing = (recheck as unknown as { missing: string[] })
+				.missing;
+			expect(stillMissing.length).toBe(0);
+		});
+	});
+
+	// =========================================================================
+	// Category 6: Malformed CLAUDE.md Handling
+	// =========================================================================
+
+	describe("Malformed CLAUDE.md Handling", () => {
+		it("TEST-15: inject refuses when CLAUDE.md has missing END marker", async () => {
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+			// Write a malformed file: BEGIN without END
+			const malformedContent = [
+				"# Project Notes",
+				"",
+				"<!-- BEGIN magus:broken-plugin v1.0.0 -->",
+				"## Broken Plugin",
+				"",
+				"This section has no END marker.",
+				"",
+				"# More content below",
+				"",
+			].join("\n");
+			await writeFile(claudeMdPath, malformedContent, "utf-8");
+
+			// Attempting to inject a NEW section should be refused
+			const result = await injectClaudeMdSection(
+				claudeMdPath,
+				"new-plugin",
+				"1.0.0",
+				"## New Plugin\n\nContent.\n",
+			);
+			expect(result.action).toBe("error");
+			expect(result.error).toBeDefined();
+			expect(typeof result.error).toBe("string");
+		});
+
+		it("TEST-16: parse detects duplicate sections", async () => {
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+			const duplicateContent = [
+				"# Project",
+				"",
+				"<!-- BEGIN magus:test-plugin v1.0.0 -->",
+				"## First instance",
+				"<!-- END magus:test-plugin -->",
+				"",
+				"<!-- BEGIN magus:test-plugin v1.0.0 -->",
+				"## Second instance (duplicate!)",
+				"<!-- END magus:test-plugin -->",
+				"",
+			].join("\n");
+			await writeFile(claudeMdPath, duplicateContent, "utf-8");
+
+			const parseResult: ParseResult =
+				await parseClaudeMdSections(claudeMdPath);
+			expect(parseResult.errors.length).toBeGreaterThan(0);
+
+			const duplicateError = parseResult.errors.find(
+				(e) => e.type === "duplicate_section",
+			);
+			expect(duplicateError).toBeDefined();
+			if (duplicateError) {
+				expect(duplicateError.section).toBe("test-plugin");
+			}
+		});
+
+		it("TEST-17: parse ignores markers inside code blocks", async () => {
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+			const contentWithCodeBlock = [
+				"# Documentation",
+				"",
+				"Here is an example of markers:",
+				"",
+				"```markdown",
+				"<!-- BEGIN magus:example v1.0.0 -->",
+				"## Example section",
+				"<!-- END magus:example -->",
+				"```",
+				"",
+				"The above markers are inside a code block and should be ignored.",
+				"",
+			].join("\n");
+			await writeFile(claudeMdPath, contentWithCodeBlock, "utf-8");
+
+			const parseResult = await parseClaudeMdSections(claudeMdPath);
+
+			// Markers inside code blocks should NOT be treated as real sections
+			const realSections = parseResult.sections.filter(
+				(s) => !s.insideCodeBlock,
+			);
+			expect(realSections.length).toBe(0);
+
+			// If the parser reports code-block markers, check the error type
+			if (parseResult.errors.length > 0) {
+				const codeBlockErrors = parseResult.errors.filter(
+					(e) => e.type === "marker_in_code_block",
+				);
+				// It's valid for the parser to either:
+				// 1. Report marker_in_code_block errors, OR
+				// 2. Simply ignore them (no sections, no errors)
+				// Both behaviors comply with the architecture spec.
+				if (codeBlockErrors.length > 0) {
+					expect(codeBlockErrors[0].section).toBe("example");
+				}
+			}
+		});
+	});
+
+	// =========================================================================
+	// Category 7: Path Classification (Gitignore Entries)
+	// =========================================================================
+
+	describe("Path Classification", () => {
+		it("TEST-18: all standard private paths can be added to gitignore", async () => {
+			const gitignorePath = join(projectDir, ".gitignore");
+			const privatePaths = [
+				".mnemex/",
+				".claudemem/",
+				".claude/sessions/",
+				".claude/worktrees/",
+			];
+
+			const result = await ensureGitignoreEntries(
+				gitignorePath,
+				privatePaths,
+				"# Claude Code ephemeral/machine-specific data",
+			);
+
+			expect(result.modified).toBe(true);
+			expect(result.added.length).toBe(4);
+
+			const content = await readFile(gitignorePath, "utf-8");
+			for (const path of privatePaths) {
+				expect(content).toContain(path);
+			}
+		});
+
+		it("TEST-19: checkGitignoreEntries reports correct missing set", async () => {
+			const gitignorePath = join(projectDir, ".gitignore");
+			// Only .mnemex/ exists
+			await writeFile(gitignorePath, ".mnemex/\n", "utf-8");
+
+			const allPaths = [
+				".mnemex/",
+				".claudemem/",
+				".claude/sessions/",
+				".claude/worktrees/",
+			];
+
+			const result = await checkGitignoreEntries(gitignorePath, allPaths);
+			// API returns { present, missing } instead of string[] (see IMPLEMENTATION_ISSUE note)
+			const resultObj = result as unknown as {
+				present: string[];
+				missing: string[];
+			};
+
+			expect(resultObj.missing.length).toBe(3);
+			expect(resultObj.missing).toContain(".claudemem/");
+			expect(resultObj.missing).toContain(".claude/sessions/");
+			expect(resultObj.missing).toContain(".claude/worktrees/");
+			expect(resultObj.missing).not.toContain(".mnemex/");
+		});
+
+		it("TEST-20: gitignore entries survive plugin uninstall", async () => {
+			const pluginDir = await createMockPlugin(tempDir, "test-plugin", {
+				gitignoreProject: [".mnemex/", ".claude/sessions/"],
+				claudemdSection: "test-plugin",
+				claudemdVersion: "1.0.0",
+				templateContent: "## Test\n\nContent.\n",
+			});
+
+			// Apply conventions manually (since applyConventions has a bug)
+			await applyConventionsManually(pluginDir, projectDir);
+
+			const gitignorePath = join(projectDir, ".gitignore");
+			const gitignoreBefore = await readFile(gitignorePath, "utf-8");
+			expect(gitignoreBefore).toContain(".mnemex/");
+			expect(gitignoreBefore).toContain(".claude/sessions/");
+
+			// Remove conventions via public API
+			await removeConventions("test-plugin", projectDir);
+
+			// Gitignore entries MUST still be there (by design)
+			const gitignoreAfter = await readFile(gitignorePath, "utf-8");
+			expect(gitignoreAfter).toContain(".mnemex/");
+			expect(gitignoreAfter).toContain(".claude/sessions/");
+		});
+	});
+
+	// =========================================================================
+	// IMPLEMENTATION_ISSUE: applyConventions() regression tests
+	// These tests SHOULD pass when the bug in applyConventions() is fixed.
+	// They currently fail because applyConventions() silently skips all work.
+	// =========================================================================
+
+	describe("applyConventions orchestration (IMPLEMENTATION_ISSUE)", () => {
+		it("TEST-1-A: applyConventions should apply gitignore entries", async () => {
+			const pluginDir = await createMockPlugin(tempDir, "apply-test", {
+				gitignoreProject: [".mnemex/", ".claude/sessions/"],
+				claudemdSection: "apply-test",
+				claudemdVersion: "1.0.0",
+				templateContent: "## Test Plugin\n\nConventions.\n",
+			});
+
+			const result = await applyConventions(pluginDir, projectDir);
+			expect(result.gitignore.modified).toBe(true);
+			expect(result.gitignore.added).toContain(".mnemex/");
+		});
+
+		it("TEST-2-A: applyConventions should inject CLAUDE.md section", async () => {
+			const pluginDir = await createMockPlugin(tempDir, "apply-test", {
+				claudemdSection: "apply-test",
+				claudemdVersion: "1.0.0",
+				templateContent: "## Test Plugin\n\nConventions.\n",
+			});
+
+			const result = await applyConventions(pluginDir, projectDir);
+			expect(result.claudemd.action).toBe("inserted");
+		});
+
+		it("TEST-3-A: removeConventions should remove CLAUDE.md section", async () => {
+			// First create a CLAUDE.md with a section using the working low-level API
+			const claudeMdPath = join(projectDir, "CLAUDE.md");
+			await injectClaudeMdSection(
+				claudeMdPath,
+				"test-plugin",
+				"1.0.0",
+				"## Test\n\nContent.\n",
+			);
+
+			// removeConventions should find and remove the section
+			const result = await removeConventions("test-plugin", projectDir);
+			expect(result.claudemd.removed).toBe(true);
+		});
+	});
 });