popeye-cli 1.10.0 → 2.1.0

package/src/types/index.ts

@@ -58,6 +58,7 @@ export {
   DEFAULT_GROK_MODEL,
   AIProviderSchema,
   KNOWN_GEMINI_MODELS,
+  KNOWN_GROK_MODELS,
   GeminiModelSchema,
   GrokModelSchema,
   type AIProvider,

package/src/types/project.ts

@@ -242,7 +242,12 @@ export interface WebsiteSpec {
 /**
  * Known OpenAI models (used for suggestions and display, not strict validation)
  */
-export const KNOWN_OPENAI_MODELS = ['gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', 'o1-preview', 'o1-mini'] as const;
+export const KNOWN_OPENAI_MODELS = [
+  'gpt-4.1', 'gpt-4.1-mini', 'gpt-4.1-nano',
+  'o3', 'o3-mini', 'o4-mini',
+  'gpt-4o', 'gpt-4o-mini',
+  'gpt-4-turbo', 'o1-preview', 'o1-mini',
+] as const;
 
 /**
  * OpenAI model schema - accepts any non-empty string to support new models
@@ -289,24 +294,48 @@ export interface GenerationOptions {
  * Available OpenAI models with descriptions
  */
 export const OPENAI_MODELS: Record<OpenAIModel, { description: string; recommended: string }> = {
-  'gpt-4o': {
-    description: 'Most capable, best reasoning',
+  'gpt-4.1': {
+    description: 'Smartest non-reasoning model, 1M context',
     recommended: 'Complex projects',
   },
+  'gpt-4.1-mini': {
+    description: 'Fast, strong instruction following',
+    recommended: 'Medium complexity',
+  },
+  'gpt-4.1-nano': {
+    description: 'Fastest, most cost-efficient',
+    recommended: 'Simple projects',
+  },
+  'o3': {
+    description: 'Strongest reasoning model',
+    recommended: 'Architectural decisions',
+  },
+  'o3-mini': {
+    description: 'Efficient reasoning',
+    recommended: 'Code review',
+  },
+  'o4-mini': {
+    description: 'Fast reasoning, best on STEM',
+    recommended: 'Technical analysis',
+  },
+  'gpt-4o': {
+    description: 'Multimodal, strong all-rounder',
+    recommended: 'General purpose',
+  },
   'gpt-4o-mini': {
     description: 'Fast, cost-effective',
-    recommended: 'Simple projects',
+    recommended: 'Simple tasks',
   },
   'gpt-4-turbo': {
-    description: 'High capability, faster',
-    recommended: 'Medium complexity',
+    description: 'High capability, legacy',
+    recommended: 'Backward compatibility',
   },
   'o1-preview': {
-    description: 'Advanced reasoning',
-    recommended: 'Architectural decisions',
+    description: 'Advanced reasoning (legacy)',
+    recommended: 'Legacy reasoning tasks',
   },
   'o1-mini': {
-    description: 'Efficient reasoning',
-    recommended: 'Code review',
+    description: 'Efficient reasoning (legacy)',
+    recommended: 'Legacy reasoning tasks',
   },
 };

package/src/types/workflow.ts

@@ -254,7 +254,7 @@ export const ProjectStateSchema = z.object({
   name: z.string(),
   idea: z.string(),
   language: OutputLanguageSchema,
-  openaiModel: z.enum(['gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', 'o1-preview', 'o1-mini']),
+  openaiModel: z.string().min(1),
   phase: WorkflowPhaseSchema,
   status: ProjectStatusSchema,
   specification: z.string().optional(),

package/src/upgrade/handlers.ts

@@ -349,7 +349,7 @@ export async function upgradeFullstackToAll(
       idea: 'Marketing website',
       name: projectName,
       language: 'all',
-      openaiModel: 'gpt-4o',
+      openaiModel: 'gpt-4.1',
     };
 
     // Build content context from user docs, brand assets, and strategy
@@ -421,7 +421,7 @@ export async function upgradeSingleToFullstack(
     if (!(await pathExists(frontendDir))) {
       const spec: ProjectSpec = {
         idea: 'Frontend application', name: projectName,
-        language: 'fullstack', openaiModel: 'gpt-4o',
+        language: 'fullstack', openaiModel: 'gpt-4.1',
       };
       const result = await generateTypeScriptProject(spec, path.join(projectDir, 'apps'), {
         baseDir: frontendDir,
@@ -439,7 +439,7 @@ export async function upgradeSingleToFullstack(
     if (!(await pathExists(backendDir))) {
       const spec: ProjectSpec = {
         idea: 'Backend API', name: projectName,
-        language: 'fullstack', openaiModel: 'gpt-4o',
+        language: 'fullstack', openaiModel: 'gpt-4.1',
       };
       const result = await generatePythonProject(spec, path.join(projectDir, 'apps'), {
         baseDir: backendDir,
@@ -508,7 +508,7 @@ export async function upgradeWebsiteToAll(
   if (!(await pathExists(frontendDir))) {
     const spec: ProjectSpec = {
       idea: 'Frontend application', name: projectName,
-      language: 'all', openaiModel: 'gpt-4o',
+      language: 'all', openaiModel: 'gpt-4.1',
     };
     const result = await generateTypeScriptProject(spec, path.join(projectDir, 'apps'), {
       baseDir: frontendDir,
@@ -520,7 +520,7 @@ export async function upgradeWebsiteToAll(
   if (!(await pathExists(backendDir))) {
     const spec: ProjectSpec = {
       idea: 'Backend API', name: projectName,
-      language: 'all', openaiModel: 'gpt-4o',
+      language: 'all', openaiModel: 'gpt-4.1',
     };
     const result = await generatePythonProject(spec, path.join(projectDir, 'apps'), {
       baseDir: backendDir,

package/src/workflow/index.ts

@@ -28,6 +28,7 @@ import {
   type TaskExecutionResult,
 } from './execution-mode.js';
 import { getWorkflowLogger } from './workflow-logger.js';
+import { runPipeline, resumePipeline } from '../pipeline/orchestrator.js';
 // Types are re-exported via export * from statements below
 
 // Re-export submodules
@@ -99,6 +100,34 @@ export async function runWorkflow(
 ): Promise<WorkflowResult> {
   const { projectDir, consensusConfig, maxRetries, onProgress } = options;
 
+  // P0-5: Pipeline mode check — use full autonomy pipeline unless legacy mode
+  const useLegacy = process.env.POPEYE_LEGACY_WORKFLOW === '1' || process.env.POPEYE_LEGACY_WORKFLOW === 'true';
+  if (!useLegacy) {
+    try {
+      // Bootstrap state if it doesn't exist yet (new projects)
+      let state = await loadProject(projectDir).catch(() => null);
+      if (!state) {
+        const { createProject } = await import('../state/index.js');
+        state = await createProject(spec, projectDir);
+      }
+      const result = await runPipeline({
+        projectDir,
+        state,
+        consensusConfig,
+        onPhaseStart: (phase) => onProgress?.('pipeline', `Starting phase: ${phase}`),
+        onProgress: (msg) => onProgress?.('pipeline', msg),
+      });
+      return {
+        success: result.success,
+        state: await loadProject(projectDir).catch(() => ({} as ProjectState)),
+        error: result.error,
+      };
+    } catch {
+      // Fall through to legacy workflow on pipeline error
+      onProgress?.('workflow', 'Pipeline mode failed, falling back to legacy workflow...');
+    }
+  }
+
   // Initialize workflow logger
   const logger = getWorkflowLogger(projectDir);
 
@@ -206,6 +235,29 @@ export async function resumeWorkflow(
 ): Promise<WorkflowResult> {
   const { consensusConfig, maxRetries, onProgress, additionalContext } = options;
 
+  // P0-5: Pipeline mode check
+  const useLegacy = process.env.POPEYE_LEGACY_WORKFLOW === '1' || process.env.POPEYE_LEGACY_WORKFLOW === 'true';
+  if (!useLegacy) {
+    try {
+      const state = await loadProject(projectDir);
+      const result = await resumePipeline({
+        projectDir,
+        state,
+        consensusConfig,
+        additionalContext,
+        onPhaseStart: (phase) => onProgress?.('pipeline', `Resuming phase: ${phase}`),
+        onProgress: (msg) => onProgress?.('pipeline', msg),
+      });
+      return {
+        success: result.success,
+        state: await loadProject(projectDir).catch(() => ({} as ProjectState)),
+        error: result.error,
+      };
+    } catch {
+      onProgress?.('workflow', 'Pipeline resume failed, falling back to legacy workflow...');
+    }
+  }
+
   // Initialize workflow logger
   const logger = getWorkflowLogger(projectDir);
 

package/src/workflow/website-strategy.ts

@@ -142,7 +142,7 @@ Respond with ONLY valid JSON, no markdown code fences or explanation.`;
   onProgress?.('Generating website strategy via AI...');
 
   const completion = await client.chat.completions.create({
-    model: 'gpt-4o',
+    model: 'gpt-4.1',
     messages: [{ role: 'user', content: prompt }],
     temperature: 0.4,
     max_tokens: 4096,

package/tests/cli/model-command.test.ts

@@ -5,7 +5,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { OpenAIModelSchema, KNOWN_OPENAI_MODELS } from '../../src/types/project.js';
-import { GeminiModelSchema, GrokModelSchema, KNOWN_GEMINI_MODELS } from '../../src/types/consensus.js';
+import { GeminiModelSchema, GrokModelSchema, KNOWN_GEMINI_MODELS, KNOWN_GROK_MODELS } from '../../src/types/consensus.js';
 
 describe('OpenAI model validation', () => {
   it('should accept known OpenAI models', () => {
@@ -17,7 +17,7 @@ describe('OpenAI model validation', () => {
   it('should accept unknown/new OpenAI models (flexible)', () => {
     expect(OpenAIModelSchema.safeParse('gpt-5').success).toBe(true);
     expect(OpenAIModelSchema.safeParse('gpt-5.2-turbo').success).toBe(true);
-    expect(OpenAIModelSchema.safeParse('o3-mini').success).toBe(true);
+    expect(OpenAIModelSchema.safeParse('some-future-model').success).toBe(true);
   });
 
   it('should reject empty string', () => {
@@ -33,8 +33,8 @@ describe('Gemini model validation', () => {
   });
 
   it('should accept unknown/new Gemini models (flexible)', () => {
-    expect(GeminiModelSchema.safeParse('gemini-2.5-pro').success).toBe(true);
     expect(GeminiModelSchema.safeParse('gemini-3.0-ultra').success).toBe(true);
+    expect(GeminiModelSchema.safeParse('gemini-4.0-flash').success).toBe(true);
   });
 
   it('should reject empty string', () => {
@@ -44,9 +44,9 @@ describe('Gemini model validation', () => {
 
 describe('Grok model validation', () => {
   it('should accept any non-empty string as Grok model', () => {
+    expect(GrokModelSchema.safeParse('grok-4-0709').success).toBe(true);
     expect(GrokModelSchema.safeParse('grok-3').success).toBe(true);
     expect(GrokModelSchema.safeParse('grok-3-mini').success).toBe(true);
-    expect(GrokModelSchema.safeParse('grok-2').success).toBe(true);
     expect(GrokModelSchema.safeParse('some-future-model').success).toBe(true);
   });
 
@@ -62,15 +62,25 @@ describe('Grok model validation', () => {
 
 describe('known models lists', () => {
   it('should have known OpenAI models', () => {
+    expect(KNOWN_OPENAI_MODELS).toContain('gpt-4.1');
     expect(KNOWN_OPENAI_MODELS).toContain('gpt-4o');
-    expect(KNOWN_OPENAI_MODELS).toContain('gpt-4o-mini');
-    expect(KNOWN_OPENAI_MODELS.length).toBeGreaterThanOrEqual(5);
+    expect(KNOWN_OPENAI_MODELS).toContain('o3');
+    expect(KNOWN_OPENAI_MODELS).toContain('o4-mini');
+    expect(KNOWN_OPENAI_MODELS.length).toBeGreaterThanOrEqual(8);
   });
 
   it('should have known Gemini models', () => {
+    expect(KNOWN_GEMINI_MODELS).toContain('gemini-2.5-flash');
+    expect(KNOWN_GEMINI_MODELS).toContain('gemini-2.5-pro');
     expect(KNOWN_GEMINI_MODELS).toContain('gemini-2.0-flash');
-    expect(KNOWN_GEMINI_MODELS).toContain('gemini-1.5-pro');
-    expect(KNOWN_GEMINI_MODELS.length).toBeGreaterThanOrEqual(3);
+    expect(KNOWN_GEMINI_MODELS.length).toBeGreaterThanOrEqual(5);
+  });
+
+  it('should have known Grok models', () => {
+    expect(KNOWN_GROK_MODELS).toContain('grok-4-0709');
+    expect(KNOWN_GROK_MODELS).toContain('grok-3');
+    expect(KNOWN_GROK_MODELS).toContain('grok-3-mini');
+    expect(KNOWN_GROK_MODELS.length).toBeGreaterThanOrEqual(4);
   });
 });
 
@@ -84,7 +94,7 @@ describe('backward compatibility', () => {
   });
 
   it('should not auto-detect non-OpenAI models as known OpenAI', () => {
-    const nonOpenAI = ['gemini-2.0-flash', 'grok-3'];
+    const nonOpenAI = ['gemini-2.5-flash', 'grok-3', 'grok-4-0709'];
     for (const model of nonOpenAI) {
       const isKnown = (KNOWN_OPENAI_MODELS as readonly string[]).includes(model);
       expect(isKnown).toBe(false);

package/tests/config/config.test.ts

@@ -23,7 +23,7 @@ describe('DEFAULT_CONFIG', () => {
   });
 
   it('should have valid API defaults', () => {
-    expect(DEFAULT_CONFIG.apis.openai.model).toBe('gpt-4o');
+    expect(DEFAULT_CONFIG.apis.openai.model).toBe('gpt-4.1');
     expect(DEFAULT_CONFIG.apis.openai.temperature).toBe(0.3);
     expect(DEFAULT_CONFIG.apis.openai.max_tokens).toBe(4096);
   });
@@ -122,11 +122,11 @@ describe('ConfigSchema', () => {
     expect(result.success).toBe(false);
   });
 
-  it('should reject invalid model', () => {
+  it('should reject empty model string', () => {
     const config = {
       apis: {
         openai: {
-          model: 'gpt-5',
+          model: '',
         },
       },
     };

package/tests/config/popeye-md.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Fix C tests — readPopeyeMdConfig shared config reader.
+ * Verifies popeye.md parsing for CLI commands.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { readPopeyeMdConfig } from '../../src/config/popeye-md.js';
+
+describe('Fix C: readPopeyeMdConfig', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'popeye-md-test-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('should return null when popeye.md does not exist', async () => {
+    const config = await readPopeyeMdConfig(tmpDir);
+    expect(config).toBeNull();
+  });
+
+  it('should parse basic config with reviewer and language', async () => {
+    await fs.writeFile(
+      path.join(tmpDir, 'popeye.md'),
+      [
+        '---',
+        'language: python',
+        'reviewer: openai',
+        'arbitrator: gemini',
+        '---',
+        '',
+        '# Project Config',
+      ].join('\n'),
+    );
+
+    const config = await readPopeyeMdConfig(tmpDir);
+    expect(config).not.toBeNull();
+    expect(config!.language).toBe('python');
+    expect(config!.reviewer).toBe('openai');
+    expect(config!.arbitrator).toBe('gemini');
+    expect(config!.enableArbitration).toBe(true);
+  });
+
+  it('should parse model fields from popeye.md', async () => {
+    await fs.writeFile(
+      path.join(tmpDir, 'popeye.md'),
+      [
+        '---',
+        'language: typescript',
+        'reviewer: gemini',
+        'arbitrator: grok',
+        'openaiModel: gpt-4o-mini',
+        'geminiModel: gemini-2.0-flash',
+        'grokModel: grok-3',
+        '---',
+      ].join('\n'),
+    );
+
+    const config = await readPopeyeMdConfig(tmpDir);
+    expect(config).not.toBeNull();
+    expect(config!.openaiModel).toBe('gpt-4o-mini');
+    expect(config!.geminiModel).toBe('gemini-2.0-flash');
+    expect(config!.grokModel).toBe('grok-3');
+  });
+
+  it('should handle arbitrator: off', async () => {
+    await fs.writeFile(
+      path.join(tmpDir, 'popeye.md'),
+      [
+        '---',
+        'language: fullstack',
+        'reviewer: openai',
+        'arbitrator: off',
+        '---',
+      ].join('\n'),
+    );
+
+    const config = await readPopeyeMdConfig(tmpDir);
+    expect(config).not.toBeNull();
+    expect(config!.enableArbitration).toBe(false);
+  });
+
+  it('should return null when frontmatter is missing', async () => {
+    await fs.writeFile(
+      path.join(tmpDir, 'popeye.md'),
+      '# Just a markdown file\n\nNo frontmatter here.',
+    );
+
+    const config = await readPopeyeMdConfig(tmpDir);
+    expect(config).toBeNull();
+  });
+
+  it('should return null when essential fields are missing', async () => {
+    await fs.writeFile(
+      path.join(tmpDir, 'popeye.md'),
+      [
+        '---',
+        'projectName: my-app',
+        'created: 2024-01-01',
+        '---',
+      ].join('\n'),
+    );
+
+    const config = await readPopeyeMdConfig(tmpDir);
+    // Missing language and reviewer -> null
+    expect(config).toBeNull();
+  });
+
+  it('should extract notes section', async () => {
+    await fs.writeFile(
+      path.join(tmpDir, 'popeye.md'),
+      [
+        '---',
+        'language: website',
+        'reviewer: openai',
+        '---',
+        '',
+        '## Notes',
+        'This project uses Tailwind CSS.',
+        'Deploy to Vercel.',
+      ].join('\n'),
+    );
+
+    const config = await readPopeyeMdConfig(tmpDir);
+    expect(config).not.toBeNull();
+    expect(config!.notes).toContain('Tailwind CSS');
+  });
+
+  it('should reject invalid language values', async () => {
+    await fs.writeFile(
+      path.join(tmpDir, 'popeye.md'),
+      [
+        '---',
+        'language: rust',
+        'reviewer: openai',
+        '---',
+      ].join('\n'),
+    );
+
+    const config = await readPopeyeMdConfig(tmpDir);
+    // Invalid language means essential field is missing
+    expect(config).toBeNull();
+  });
+
+  it('should return model fields as undefined when not specified', async () => {
+    await fs.writeFile(
+      path.join(tmpDir, 'popeye.md'),
+      [
+        '---',
+        'language: python',
+        'reviewer: openai',
+        '---',
+      ].join('\n'),
+    );
+
+    const config = await readPopeyeMdConfig(tmpDir);
+    expect(config).not.toBeNull();
+    expect(config!.openaiModel).toBeUndefined();
+    expect(config!.geminiModel).toBeUndefined();
+    expect(config!.grokModel).toBeUndefined();
+  });
+});

package/tests/pipeline/artifact-manager.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Artifact Manager tests — create, version, verify, index.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createArtifactManager } from '../../src/pipeline/artifact-manager.js';
+
+const TEST_DIR = join(process.cwd(), '.test-artifact-manager');
+
+describe('ArtifactManager', () => {
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+  });
+
+  describe('ensureDocsStructure', () => {
+    it('should create all required subdirectories', () => {
+      const manager = createArtifactManager(TEST_DIR);
+      manager.ensureDocsStructure();
+
+      expect(existsSync(join(TEST_DIR, 'docs'))).toBe(true);
+      expect(existsSync(join(TEST_DIR, 'docs', 'master-plan'))).toBe(true);
+      expect(existsSync(join(TEST_DIR, 'docs', 'architecture'))).toBe(true);
+      expect(existsSync(join(TEST_DIR, 'docs', 'consensus'))).toBe(true);
+      expect(existsSync(join(TEST_DIR, 'docs', 'audit'))).toBe(true);
+      expect(existsSync(join(TEST_DIR, 'docs', 'release'))).toBe(true);
+    });
+  });
+
+  describe('createArtifactText', () => {
+    it('should create a markdown artifact file', () => {
+      const manager = createArtifactManager(TEST_DIR);
+      const entry = manager.createArtifactText(
+        'master_plan',
+        '# Master Plan\n\nThe plan.',
+        'INTAKE',
+      );
+
+      expect(entry.type).toBe('master_plan');
+      expect(entry.phase).toBe('INTAKE');
+      expect(entry.version).toBe(1);
+      expect(entry.content_type).toBe('markdown');
+      expect(entry.immutable).toBe(true);
+      expect(entry.path).toContain('master-plan');
+      expect(entry.path).toContain('.md');
+
+      // File should exist on disk
+      const fullPath = join(TEST_DIR, entry.path);
+      expect(existsSync(fullPath)).toBe(true);
+      expect(readFileSync(fullPath, 'utf-8')).toBe('# Master Plan\n\nThe plan.');
+    });
+  });
+
+  describe('createArtifactJson', () => {
+    it('should create a JSON artifact file', () => {
+      const manager = createArtifactManager(TEST_DIR);
+      const data = { key: 'value', count: 42 };
+      const entry = manager.createArtifactJson(
+        'repo_snapshot',
+        data,
+        'INTAKE',
+      );
+
+      expect(entry.content_type).toBe('json');
+      expect(entry.path).toContain('.json');
+
+      const fullPath = join(TEST_DIR, entry.path);
+      expect(existsSync(fullPath)).toBe(true);
+
+      const parsed = JSON.parse(readFileSync(fullPath, 'utf-8'));
+      expect(parsed.key).toBe('value');
+      expect(parsed.count).toBe(42);
+    });
+  });
+
+  describe('verifyArtifact', () => {
+    it('should verify intact artifacts', () => {
+      const manager = createArtifactManager(TEST_DIR);
+      const entry = manager.createArtifactText(
+        'master_plan',
+        'Content here',
+        'INTAKE',
+      );
+
+      expect(manager.verifyArtifact(entry)).toBe(true);
+    });
+
+    it('should detect missing artifacts', () => {
+      const manager = createArtifactManager(TEST_DIR);
+      const entry = manager.createArtifactText(
+        'master_plan',
+        'Content',
+        'INTAKE',
+      );
+
+      // Remove the file
+      rmSync(join(TEST_DIR, entry.path));
+      expect(manager.verifyArtifact(entry)).toBe(false);
+    });
+  });
+
+  describe('version chains', () => {
+    it('should auto-increment versions within a group', () => {
+      const manager = createArtifactManager(TEST_DIR);
+      const groupId = 'test-group';
+
+      const v1 = manager.createAndStoreText('master_plan', 'v1 content', 'INTAKE', groupId);
+      const v2 = manager.createAndStoreText('master_plan', 'v2 content', 'INTAKE', groupId);
+      const v3 = manager.createAndStoreText('master_plan', 'v3 content', 'INTAKE', groupId);
+
+      expect(v1.version).toBe(1);
+      expect(v2.version).toBe(2);
+      expect(v3.version).toBe(3);
+
+      expect(v1.group_id).toBe(groupId);
+      expect(v2.group_id).toBe(groupId);
+      expect(v3.group_id).toBe(groupId);
+
+      expect(v2.previous_id).toBe(v1.id);
+      expect(v3.previous_id).toBe(v2.id);
+    });
+
+    it('should start at v1 for a new group', () => {
+      const manager = createArtifactManager(TEST_DIR);
+      const entry = manager.createAndStoreText('architecture', 'content', 'ARCHITECTURE');
+      expect(entry.version).toBe(1);
+      expect(entry.previous_id).toBeUndefined();
+    });
+  });
+
+  describe('toArtifactRef', () => {
+    it('should convert entry to ref', () => {
+      const manager = createArtifactManager(TEST_DIR);
+      const entry = manager.createArtifactText('master_plan', 'content', 'INTAKE');
+      const ref = manager.toArtifactRef(entry);
+
+      expect(ref.artifact_id).toBe(entry.id);
+      expect(ref.path).toBe(entry.path);
+      expect(ref.sha256).toBe(entry.sha256);
+      expect(ref.version).toBe(entry.version);
+      expect(ref.type).toBe(entry.type);
+    });
+  });
+
+  describe('updateIndex', () => {
+    it('should create INDEX.md with artifact listing', () => {
+      const manager = createArtifactManager(TEST_DIR);
+      const entry = manager.createArtifactText('master_plan', 'content', 'INTAKE');
+
+      manager.updateIndex([entry]);
+
+      const indexPath = join(TEST_DIR, 'docs', 'INDEX.md');
+      expect(existsSync(indexPath)).toBe(true);
+
+      const indexContent = readFileSync(indexPath, 'utf-8');
+      expect(indexContent).toContain('Documentation Index');
+      expect(indexContent).toContain('master_plan');
+      expect(indexContent).toContain('INTAKE');
+    });
+  });
+
+  describe('storeArtifactMetadata', () => {
+    it('should store and retrieve metadata', () => {
+      const manager = createArtifactManager(TEST_DIR);
+      const entry = manager.createArtifactText('master_plan', 'content', 'INTAKE');
+      manager.storeArtifactMetadata(entry);
+
+      const listed = manager.listArtifacts('master_plan');
+      expect(listed).toHaveLength(1);
+      expect(listed[0].id).toBe(entry.id);
+    });
+  });
+});