@auto-engineer/server-implementer 1.119.0 → 1.120.0

package/ketchup-plan.md

@@ -1,4 +1,4 @@
-# Ketchup Plan: Fix implementer context/prompt gaps
+# Ketchup Plan: Fix Server-Implementer Prompt Engineering
 
 ## TODO
 
@@ -6,10 +6,15 @@
 
 ## DONE
 
+- [x] Burst 6: Update runSlice.ts to use shared utilities (782660f2)
+- [x] Burst 5: Update implement-slice.ts to use shared utilities (b31e9c45)
+- [x] Burst 4: Rewrite systemPrompt.ts with emmett patterns and import rules (e619ec01)
+- [x] Burst 3: Extract shared buildContextSections utility + tests (ad51e08f)
+- [x] Burst 2: Extract shared loadContextFiles utility + tests (987b9f8b)
+- [x] Burst 1: Change loadSharedContext return type to Record<string, string> + update tests (09ebc833)
 - [x] Burst 10: Add strict array/object typing rules to implementer prompts
 - [x] Burst 9: Add discriminated union narrowing guidance to prompts (f43a84c9)
 - [x] Burst 8: Load full shared directory into implementer context (e8f42abf)
-
 - [x] Burst 7: Add implementer prompt guardrails for phantom enums and hardcoded projections (14d8cbda)
 - [x] Burst 6: Fix `_state` reference in decide.ts.ejs instruction comment (dff8f329)
 - [x] Burst 5: Fix singleton projection instructions in projection.ts.ejs (3271cfe4)

package/package.json

@@ -18,8 +18,8 @@
     "debug": "^4.3.4",
     "fast-glob": "^3.3.3",
     "vite": "^5.4.1",
-    "@auto-engineer/model-factory": "1.119.0",
-    "@auto-engineer/message-bus": "1.119.0"
+    "@auto-engineer/model-factory": "1.120.0",
+    "@auto-engineer/message-bus": "1.120.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
@@ -29,9 +29,9 @@
     "glob": "^11.0.3",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
-    "@auto-engineer/cli": "1.119.0"
+    "@auto-engineer/cli": "1.120.0"
   },
-  "version": "1.119.0",
+  "version": "1.120.0",
   "scripts": {
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts",
     "test": "vitest run --reporter=dot",

package/src/agent/runSlice.ts

@@ -5,9 +5,10 @@ import { generateText } from 'ai';
 import { execa } from 'execa';
 import fg from 'fast-glob';
 import { SYSTEM_PROMPT } from '../prompts/systemPrompt';
+import { buildContextSections } from '../utils/buildContextSections';
 import { buildShadowWarning } from '../utils/detectImportedTypeShadowing';
 import { extractCodeBlock } from '../utils/extractCodeBlock';
-import { loadSharedContext } from '../utils/loadSharedContext';
+import { loadContextFiles } from '../utils/loadContextFiles';
 import { runTests } from './runTests';
 
 type TestAndTypecheckResult = {
@@ -102,22 +103,6 @@ async function retryFailedFiles(
   return result;
 }
 
-async function loadContextFiles(sliceDir: string): Promise<Record<string, string>> {
-  const files = await fg(['*.ts'], { cwd: sliceDir });
-  const context: Record<string, string> = {};
-  for (const file of files) {
-    const absPath = path.join(sliceDir, file);
-    context[file] = await readFile(absPath, 'utf-8');
-  }
-
-  const sharedContent = await loadSharedContext(sliceDir);
-  if (sharedContent) {
-    context['domain-shared-types.ts'] = sharedContent;
-  }
-
-  return context;
-}
-
 function findFilesToImplement(contextFiles: Record<string, string>) {
   return Object.entries(contextFiles).filter(
     ([, content]) => content.includes('TODO:') || content.includes('IMPLEMENTATION INSTRUCTIONS'),
@@ -133,12 +118,7 @@ ${SYSTEM_PROMPT}
 
 ${context[targetFile]}
 
----
-🧠 Other files in the same slice:
-${Object.entries(context)
-  .filter(([name]) => name !== targetFile)
-  .map(([name, content]) => `// File: ${name}\n${content}`)
-  .join('\n\n')}
+${buildContextSections(targetFile, context)}
 
 ---
 Return only the whole updated file of ${targetFile}. Do not remove existing imports or types that are still referenced or required in the file. The file returned has to be production ready.
@@ -161,11 +141,7 @@ The previous implementation of ${targetFile} caused test or type-check failures.
 
 ${context[targetFile]}
 
-🧠 Other files in the same slice:
-${Object.entries(context)
-  .filter(([name]) => name !== targetFile)
-  .map(([name, content]) => `// File: ${name}\n${content}`)
-  .join('\n\n')}
+${buildContextSections(targetFile, context)}
 
 🧪 Test errors:
 ${testErrors || 'None'}

package/src/commands/implement-slice.ts

@@ -1,13 +1,14 @@
 import { existsSync } from 'node:fs';
-import { readFile, writeFile } from 'node:fs/promises';
+import { writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { type Command, defineCommandHandler, type Event } from '@auto-engineer/message-bus';
 import { createModelFromEnv } from '@auto-engineer/model-factory';
 import { generateText } from 'ai';
 import createDebug from 'debug';
-import fg from 'fast-glob';
+import { SYSTEM_PROMPT } from '../prompts/systemPrompt';
+import { buildContextSections } from '../utils/buildContextSections';
 import { buildShadowWarning } from '../utils/detectImportedTypeShadowing';
-import { loadSharedContext } from '../utils/loadSharedContext';
+import { loadContextFiles } from '../utils/loadContextFiles';
 
 const debug = createDebug('auto:server-implementer:slice');
 const debugHandler = createDebug('auto:server-implementer:slice:handler');
@@ -102,22 +103,6 @@ function extractCodeBlock(text: string): string {
     .trim();
 }
 
-async function loadContextFiles(sliceDir: string): Promise<Record<string, string>> {
-  const files = await fg(['*.ts', '!*.specs.ts'], { cwd: sliceDir });
-  const context: Record<string, string> = {};
-  for (const file of files) {
-    const absPath = path.join(sliceDir, file);
-    context[file] = await readFile(absPath, 'utf-8');
-  }
-
-  const sharedContent = await loadSharedContext(sliceDir);
-  if (sharedContent) {
-    context['domain-shared-types.ts'] = sharedContent;
-  }
-
-  return context;
-}
-
 const IMPLEMENTATION_MARKER = '// @auto-implement';
 
 function hasImplementationMarker(content: string): boolean {
@@ -141,96 +126,7 @@ function findFilesToImplement(contextFiles: Record<string, string>): Array<[stri
   return Object.entries(contextFiles).filter(([, content]) => hasImplementationMarker(content));
 }
 
-const SYSTEM_PROMPT = `
-You are a software engineer implementing missing logic in a sliced event-driven TypeScript server. Each slice contains partially scaffolded code, and your task is to complete the logic following implementation instructions embedded in each file.
-
-Project Characteristics:
-- Architecture: sliced event-sourced CQRS (Command, Query, Reaction slices)
-- Language: TypeScript with type-graphql and @event-driven-io/emmett
-- Each slice has scaffolded files with implementation instructions clearly marked with comments (e.g., '## IMPLEMENTATION INSTRUCTIONS ##') or TODOs.
-- Tests (e.g., *.specs.ts) must pass.
-- Type errors are not allowed.
-- The domain uses shared enums defined in domain/shared/types.ts for type-safe values. When a field type is an enum (e.g., Status), you MUST use enum constants (e.g., Status.IN_PROGRESS) instead of string literals (e.g., 'in_progress').
-
-Your Goal:
-- Read the implementation instructions from the provided file.
-- Generate only the code needed to fulfill the instructions, nothing extra and provide back the whole file without the instructions.
-- Maintain immutability and adhere to functional best practices.
-- Use only the types and domain constructs already present in the slice.
-- CRITICAL: When a field has an enum type (e.g., status: Status), you MUST use the enum constant (e.g., Status.IN_PROGRESS) NOT a string literal (e.g., 'in_progress'). Check domain-shared-types.ts for the exact enum constant names.
-- Do not remove existing imports or types that are still referenced or required in the file.
-- Preserve index signatures like [key: string]: unknown as they are required for TypeScript compatibility.
-- Return the entire updated file, not just the modified parts and remove any TODO comments or instructions after implementing the logic
-
-Key rules:
-- Never modify code outside the TODO or instruction areas.
-- Ensure the code is production-ready and type-safe.
-- Follow the slice type conventions:
-  - **Command slice**: validate command, inspect state, emit events, never mutate state. Uses graphql mutations.
-  - **Reaction slice**: respond to events with commands.
-  - **Query slice**: maintain projections based on events, do not emit or throw. Uses graphql queries.
-- All code must be TypeScript compliant and follow functional patterns.
-- If a test exists, make it pass.
-- Keep implementations minimal and idiomatic.
-- CRITICAL: When assigning values to enum-typed fields, use the enum constant name from domain-shared-types.ts. For example, if Status enum has IN_PROGRESS = 'in_progress', use Status.IN_PROGRESS not 'in_progress'.
-- Derive all output values from inputs (event.data, command.data, state) or generate at runtime. Never reproduce literal values from test examples.
-- Always annotate array literals with explicit types: \`const items: SomeType[] = []\`, never \`const items = []\`.
-- When mapping objects to a typed array, include ALL required fields in each object literal. TypeScript requires every field — omitting one and assigning it later causes a type error.
-
-Avoid:
-- Adding new dependencies.
-- Refactoring unrelated code.
-- Changing the structure of already scaffolded files unless instructed.
-- Using string literals for enum-typed fields. ALWAYS use the enum constant from domain-shared-types.ts (e.g., if status field type is Status and Status enum defines IN_PROGRESS = 'in_progress', use Status.IN_PROGRESS not the string 'in_progress').
-- Importing enum types that do not appear in domain-shared-types.ts. If a field type is plain \`string\` (not an enum type), use a string literal.
-
-You will receive:
-- The path of the file to implement.
-- The current contents of the file, with instruction comments.
-- Other relevant files from the same slice (e.g., types, test, state, etc.).
-- Shared domain types including enum definitions (domain-shared-types.ts).
-
-You must:
--  Return the entire updated file (no commentary and remove all implementation instructions).
-- Ensure the output is valid TypeScript.
-- Use enum constants from domain-shared-types.ts when appropriate.
-`;
-
-function extractEnumExamples(sharedTypesContent: string): string {
-  const enumMatches = sharedTypesContent.matchAll(/export enum (\w+) \{([^}]+)\}/g);
-  const examples: string[] = [];
-
-  for (const match of enumMatches) {
-    const enumName = match[1];
-    const enumBody = match[2];
-    const firstConstant = enumBody.match(/\s*(\w+)\s*=\s*['"]([^'"]+)['"]/);
-
-    if (firstConstant !== null) {
-      const constantName = firstConstant[1];
-      const constantValue = firstConstant[2];
-      examples.push(`  - ${enumName}.${constantName} (NOT '${constantValue}')`);
-    }
-  }
-
-  if (examples.length === 0) {
-    return '';
-  }
-
-  return `
-📌 CRITICAL: Enum Usage Examples from Your Context:
-${examples.join('\n')}
-
-Pattern: Always use EnumName.CONSTANT_NAME for enum-typed fields.
-Never use string literals like 'pending' or 'Pending' when an enum constant exists.
-`;
-}
-
 function buildInitialPrompt(targetFile: string, context: Record<string, string>): string {
-  const sharedTypes = context['domain-shared-types.ts'];
-  const sliceFiles = Object.entries(context).filter(
-    ([name]) => name !== targetFile && name !== 'domain-shared-types.ts',
-  );
-
   return `
 ${SYSTEM_PROMPT}
 
@@ -239,31 +135,14 @@ ${SYSTEM_PROMPT}
 
 ${context[targetFile]}
 
-${
-  sharedTypes !== undefined
-    ? `---
-📦 Shared domain types (available via import from '../../../shared'):
-${sharedTypes}
-
-${extractEnumExamples(sharedTypes)}
-IMPORTANT: Use enum constants (e.g., Status.PENDING) instead of string literals (e.g., 'pending') when working with enum types.
-
-`
-    : ''
-}---
-🧠 Other files in the same slice:
-${sliceFiles.map(([name, content]) => `// File: ${name}\n${content}`).join('\n\n')}
+${buildContextSections(targetFile, context)}
 
 ---
-Return only the whole updated file of ${targetFile}. Do not remove existing imports or types that are still referenced or required in the file. The file returned has to be production ready. Remember to use enum constants from domain-shared-types.ts instead of string literals.
+Return only the whole updated file of ${targetFile}. Do not remove existing imports or types that are still referenced or required in the file. The file returned has to be production ready.
 `.trim();
 }
 
 function buildRetryPrompt(targetFile: string, context: Record<string, string>, previousOutputs: string): string {
-  const sharedTypes = context['domain-shared-types.ts'];
-  const sliceFiles = Object.entries(context).filter(
-    ([name]) => name !== targetFile && name !== 'domain-shared-types.ts',
-  );
   const shadowWarning = buildShadowWarning(context[targetFile], targetFile);
 
   return `
@@ -279,23 +158,10 @@ ${shadowWarning.length > 0 ? `\n🚨 ${shadowWarning}\n` : ''}
 
 ${context[targetFile]}
 
-${
-  sharedTypes !== undefined
-    ? `---
-📦 Shared domain types (available via import from '../../../shared'):
-${sharedTypes}
-
-${extractEnumExamples(sharedTypes)}
-IMPORTANT: Use enum constants (e.g., Status.PENDING) instead of string literals (e.g., 'pending') when working with enum types.
-
-`
-    : ''
-}---
-🧠 Other files in the same slice:
-${sliceFiles.map(([name, content]) => `// File: ${name}\n${content}`).join('\n\n')}
+${buildContextSections(targetFile, context)}
 
 ---
-Return only the corrected full contents of ${targetFile}, no commentary, no markdown. Remember to use enum constants from domain-shared-types.ts instead of string literals.
+Return only the corrected full contents of ${targetFile}, no commentary, no markdown.
 `.trim();
 }
 

package/src/prompts/systemPrompt.ts

@@ -1,48 +1,84 @@
 export const SYSTEM_PROMPT = `
-You are a software engineer implementing missing logic in a sliced event-driven TypeScript server. Each slice contains partially scaffolded code, and your task is to complete the logic following implementation instructions embedded in each file.
-
-Project Characteristics:
-- Architecture: sliced event-sourced CQRS (Command, Query, Reaction slices)
-- Language: TypeScript with type-graphql and Emmett
-- Each slice has scaffolded files with implementation instructions clearly marked with comments (e.g., '## IMPLEMENTATION INSTRUCTIONS ##') or TODOs.
-- Tests (e.g., *.specs.ts) must pass.
-- Type errors are not allowed.
-
-Your Goal:
-- Read the implementation instructions from the provided file.
-- Generate only the code needed to fulfill the instructions, nothing extra and provide back the whole file without the instructions.
-- Maintain immutability and adhere to functional best practices.
-- Use only the types and domain constructs already present in the slice.
-- Do not remove existing imports or types that are still referenced or required in the file.
-- Return the entire updated file, not just the modified parts and remove any TODO comments or instructions after implementing the logic
-
-Key rules:
-- Never modify code outside the TODO or instruction areas.
-- Ensure the code is production-ready and type-safe.
-- Follow the slice type conventions:
-  - **Command slice**: validate command, inspect state, emit events, never mutate state. Uses graphql mutations.
-  - **Reaction slice**: respond to events with commands.
-  - **Query slice**: maintain projections based on events, do not emit or throw. Uses graphql queries.
-- All code must be TypeScript compliant and follow functional patterns.
-- If a test exists, make it pass.
-- Keep implementations minimal and idiomatic.
-- Derive all output values from inputs (event.data, command.data, state) or generate at runtime. Never reproduce literal values from test examples.
-- Always annotate array literals with explicit types: \`const items: SomeType[] = []\`, never \`const items = []\`.
-- When mapping objects to a typed array, include ALL required fields in each object literal. TypeScript requires every field — omitting one and assigning it later causes a type error.
-
-Avoid:
-- Adding new dependencies.
-- Refactoring unrelated code.
-- Changing the structure of already scaffolded files unless instructed.
-- Inventing or importing types (e.g. enums) not already present in the provided files. If a field type is \`string\`, use a string literal.
-- Hardcoding constant values (IDs, numbers, strings, arrays) that should be dynamically generated or computed from inputs.
-
-You will receive:
-- The path of the file to implement.
-- The current contents of the file, with instruction comments.
-- Other relevant files from the same slice (e.g., types, test, state, etc.).
-
-You must:
--  Return the entire updated file (no commentary and remove all implementation instructions).
-- Ensure the output is valid TypeScript.
+## 1. ROLE & CONTEXT
+
+You are a software engineer implementing @auto-implement files in a sliced event-driven TypeScript server.
+
+- Architecture: event-sourced CQRS with @event-driven-io/emmett
+- Language: TypeScript with type-graphql
+- Sliced structure: Command, Reaction, Query slices
+- Each slice has scaffolded files with implementation instructions marked with comments or TODOs
+
+## 2. TASK
+
+- Complete the logic in the target file following embedded instructions
+- Return the entire updated file, production-ready
+- Remove all TODO/instruction comments after implementing
+
+## 3. EMMETT FRAMEWORK PATTERNS
+
+decide(command, state) returns only { type, data }:
+  CORRECT:
+    return { type: 'OrderPlaced', data: { orderId: command.data.id } };
+  WRONG — framework adds kind/metadata internally:
+    return { type: 'OrderPlaced', data: {...}, kind: 'Event', metadata: {...} };
+
+evolve(state, event) returns new state derived from event data:
+  CORRECT:
+    return { ...state, status: event.data.status, updatedAt: event.data.timestamp };
+
+react(context) returns void — queries eventStore, sends commands:
+  CORRECT:
+    const { state } = await eventStore.aggregateStream(streamId, { evolve, initialState });
+    await commandSender.send({ type: 'ProcessItem', kind: 'Command', data: {...} });
+
+Projection evolve(document, event) returns updated document.
+
+## 4. IMPORT RULES
+
+- The provided context files are the COMPLETE set of available modules.
+  If a module or type does not appear in any provided file, it does not exist.
+- Only import from: sibling files (./), shared directory ('../../../shared'),
+  or packages already imported in the scaffolded code.
+- Never create imports to modules not shown in the provided context.
+- If you need a type that doesn't exist in any provided file,
+  use inline types or primitive values instead.
+
+## 5. TEST SPECIFICATIONS GUIDANCE
+
+- .specs.ts files show expected behavior via Given/When/Then patterns
+- given([events]) = initial state, when({input}) = trigger, then({output}) = expected result
+- Match the exact field names, types, and value derivations in assertions
+- Pay attention to which values come from state vs. command/event data
+- If a spec queries eventStore before testing, the implementation must too
+- Derive values from inputs — never hardcode test literals
+
+## 6. CONSTRAINTS
+
+- Type safety: no type errors, annotate array literals with explicit types
+- Enums: if shared types define enums, use constants (e.g., Status.ACTIVE) not string literals ('active')
+- Immutability: functional patterns, never mutate state
+- Include ALL required fields in object literals
+- Preserve index signatures ([key: string]: unknown)
+- Do not remove existing imports still referenced
+- When mapping objects to a typed array, include ALL required fields in each object literal
+
+## 7. SLICE CONVENTIONS
+
+- Command slice: validate command, inspect state, emit events, never mutate state. Uses graphql mutations.
+- Reaction slice: respond to events with commands.
+- Query slice: maintain projections based on events, do not emit or throw. Uses graphql queries.
+
+## 8. AVOID
+
+- Adding dependencies
+- Refactoring unrelated code
+- Inventing types, enums, or modules not present in provided files
+- String literals for enum-typed fields
+- Hardcoding values that should be computed from inputs
+- Reproducing literal values from test examples
+
+## 9. OUTPUT
+
+Return only the entire updated file. No commentary, no markdown fences.
+Ensure the output is valid TypeScript.
 `;

package/src/utils/buildContextSections.specs.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import { buildContextSections } from './buildContextSections';
+
+describe('buildContextSections', () => {
+  it('separates shared files, slice files, and spec files into labeled sections', () => {
+    const context: Record<string, string> = {
+      'decide.ts': 'export function decide() {}',
+      'state.ts': 'export type State = {}',
+      'decide.specs.ts': 'it("works", () => {})',
+      'shared/types.ts': 'export type Foo = string;',
+    };
+
+    const result = buildContextSections('decide.ts', context);
+
+    expect(result).toBe(
+      [
+        '---',
+        "📦 Shared domain types (importable from '../../../shared'):",
+        '// File: shared/types.ts',
+        'export type Foo = string;',
+        '',
+        '---',
+        '🧠 Other files in the same slice:',
+        '// File: state.ts',
+        'export type State = {}',
+        '',
+        '---',
+        '🧪 Test specifications (READ-ONLY reference):',
+        '// File: decide.specs.ts',
+        'it("works", () => {})',
+      ].join('\n'),
+    );
+  });
+
+  it('omits shared section when no shared files exist', () => {
+    const context: Record<string, string> = {
+      'decide.ts': 'export function decide() {}',
+      'state.ts': 'export type State = {}',
+    };
+
+    const result = buildContextSections('decide.ts', context);
+
+    expect(result).toBe(
+      ['---', '🧠 Other files in the same slice:', '// File: state.ts', 'export type State = {}'].join('\n'),
+    );
+  });
+
+  it('omits spec section when no spec files exist', () => {
+    const context: Record<string, string> = {
+      'decide.ts': 'export function decide() {}',
+      'evolve.ts': 'export function evolve() {}',
+      'shared/types.ts': 'export type Foo = string;',
+    };
+
+    const result = buildContextSections('decide.ts', context);
+
+    expect(result).toBe(
+      [
+        '---',
+        "📦 Shared domain types (importable from '../../../shared'):",
+        '// File: shared/types.ts',
+        'export type Foo = string;',
+        '',
+        '---',
+        '🧠 Other files in the same slice:',
+        '// File: evolve.ts',
+        'export function evolve() {}',
+      ].join('\n'),
+    );
+  });
+
+  it('appends enum examples to shared section when provided', () => {
+    const context: Record<string, string> = {
+      'decide.ts': 'export function decide() {}',
+      'evolve.ts': 'export function evolve() {}',
+      'shared/types.ts': 'export enum Status { ACTIVE = "active" }',
+    };
+
+    const result = buildContextSections('decide.ts', context, { enumExamples: 'Use Status.ACTIVE not "active"' });
+
+    expect(result).toBe(
+      [
+        '---',
+        "📦 Shared domain types (importable from '../../../shared'):",
+        '// File: shared/types.ts',
+        'export enum Status { ACTIVE = "active" }',
+        '',
+        'Use Status.ACTIVE not "active"',
+        '',
+        '---',
+        '🧠 Other files in the same slice:',
+        '// File: evolve.ts',
+        'export function evolve() {}',
+      ].join('\n'),
+    );
+  });
+
+  it('excludes target file from slice files section', () => {
+    const context: Record<string, string> = {
+      'decide.ts': 'export function decide() {}',
+      'evolve.ts': 'export function evolve() {}',
+    };
+
+    const result = buildContextSections('decide.ts', context);
+
+    expect(result).not.toContain('decide.ts');
+    expect(result).toContain('// File: evolve.ts');
+  });
+});

package/src/utils/buildContextSections.ts

@@ -0,0 +1,30 @@
+export function buildContextSections(
+  targetFile: string,
+  context: Record<string, string>,
+  options?: { enumExamples?: string },
+): string {
+  const sharedFiles = Object.entries(context).filter(([name]) => name.startsWith('shared/'));
+  const specs = Object.entries(context).filter(([name]) => name.endsWith('.specs.ts'));
+  const sliceFiles = Object.entries(context).filter(
+    ([name]) => name !== targetFile && !name.startsWith('shared/') && !name.endsWith('.specs.ts'),
+  );
+
+  let result = '';
+
+  if (sharedFiles.length > 0) {
+    result += `---\n📦 Shared domain types (importable from '../../../shared'):\n`;
+    result += sharedFiles.map(([name, content]) => `// File: ${name}\n${content}`).join('\n\n');
+    if (options?.enumExamples) result += `\n\n${options.enumExamples}`;
+    result += '\n\n';
+  }
+
+  result += `---\n🧠 Other files in the same slice:\n`;
+  result += sliceFiles.map(([name, content]) => `// File: ${name}\n${content}`).join('\n\n');
+
+  if (specs.length > 0) {
+    result += `\n\n---\n🧪 Test specifications (READ-ONLY reference):\n`;
+    result += specs.map(([name, content]) => `// File: ${name}\n${content}`).join('\n\n');
+  }
+
+  return result;
+}

package/src/utils/loadContextFiles.specs.ts

@@ -0,0 +1,54 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { loadContextFiles } from './loadContextFiles';
+
+describe('loadContextFiles', () => {
+  let tmpDir: string;
+  let sliceDir: string;
+  let sharedDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(import.meta.dirname, '.tmp-'));
+    sharedDir = path.join(tmpDir, 'shared');
+    sliceDir = path.join(tmpDir, 'src', 'slices', 'some-slice');
+    await fs.mkdir(sliceDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('loads all .ts files from slice directory including specs', async () => {
+    await fs.writeFile(path.join(sliceDir, 'decide.ts'), 'export function decide() {}');
+    await fs.writeFile(path.join(sliceDir, 'state.ts'), 'export type State = {}');
+    await fs.writeFile(path.join(sliceDir, 'decide.specs.ts'), 'it("works", () => {})');
+
+    const result = await loadContextFiles(sliceDir);
+
+    expect(result).toEqual({
+      'decide.ts': 'export function decide() {}',
+      'state.ts': 'export type State = {}',
+      'decide.specs.ts': 'it("works", () => {})',
+    });
+  });
+
+  it('integrates shared context files with real filenames', async () => {
+    await fs.mkdir(sharedDir, { recursive: true });
+    await fs.writeFile(path.join(sliceDir, 'decide.ts'), 'export function decide() {}');
+    await fs.writeFile(path.join(sharedDir, 'types.ts'), 'export type Foo = string;');
+
+    const result = await loadContextFiles(sliceDir);
+
+    expect(result).toEqual({
+      'decide.ts': 'export function decide() {}',
+      'shared/types.ts': 'export type Foo = string;',
+    });
+  });
+
+  it('returns empty record for empty slice directory', async () => {
+    const result = await loadContextFiles(sliceDir);
+
+    expect(result).toEqual({});
+  });
+});

package/src/utils/loadContextFiles.ts

@@ -0,0 +1,15 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { loadSharedContext } from './loadSharedContext';
+
+export async function loadContextFiles(sliceDir: string): Promise<Record<string, string>> {
+  const files = await fg(['*.ts'], { cwd: sliceDir });
+  const context: Record<string, string> = {};
+  for (const file of files) {
+    context[file] = await readFile(path.join(sliceDir, file), 'utf-8');
+  }
+  const sharedFiles = await loadSharedContext(sliceDir);
+  Object.assign(context, sharedFiles);
+  return context;
+}